diff --git a/pl_PL.ISO8859-2/books/Makefile b/pl_PL.ISO8859-2/books/Makefile new file mode 100644 index 0000000000..9860667d73 --- /dev/null +++ b/pl_PL.ISO8859-2/books/Makefile @@ -0,0 +1,18 @@ +# $FreeBSD$ +# Original revision: 1.14 + +#SUBDIR+= arch-handbook +#SUBDIR+= corp-net-guide +#SUBDIR+= design-44bsd +#SUBDIR+= dev-model +#SUBDIR+= developers-handbook +#SUBDIR+= faq +#SUBDIR+= fdp-primer +SUBDIR = handbook +#SUBDIR+= pmake +#SUBDIR+= porters-handbook + +ROOT_SYMLINKS= faq handbook + +DOC_PREFIX?= ${.CURDIR}/../.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/pl_PL.ISO8859-2/books/Makefile.inc b/pl_PL.ISO8859-2/books/Makefile.inc new file mode 100644 index 0000000000..9b0603ff02 --- /dev/null +++ b/pl_PL.ISO8859-2/books/Makefile.inc @@ -0,0 +1,6 @@ +# +# $FreeBSD$ +# Original revision: 1.4 +# + +DESTDIR?= ${DOCDIR}/pl_PL.ISO8859-2/books/${.CURDIR:T} diff --git a/pl_PL.ISO8859-2/books/handbook/Makefile b/pl_PL.ISO8859-2/books/handbook/Makefile new file mode 100644 index 0000000000..505f8e1c82 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/Makefile @@ -0,0 +1,256 @@ +# The FreeBSD Polish Documentation Project +# +# $FreeBSD$ +# Original revision: 1.100 +# +# Build the FreeBSD Handbook. +# + +# ------------------------------------------------------------------------ +# +# Handbook-specific variables +# +# WITH_PGPKEYS The print version of the handbook only prints PGP +# fingerprints by default. If you would like for the +# entire key to be displayed, then set this variable. +# This option has no affect on the HTML formats. +# +# Handbook-specific targets +# +# pgpkeyring This target will read the contents of +# pgpkeys/chapter.sgml and will extract all of +# the pgpkeys to standard out. This output can then +# be redirected into a file and distributed as a +# public keyring of FreeBSD developers that can +# easily be imported into PGP/GPG. +# +# ------------------------------------------------------------------------ + +.PATH: ${.CURDIR}/../../share/sgml/glossary + +MAINTAINER= doc@FreeBSD.org + +DOC?= book + +FORMATS?= html-split + +HAS_INDEX= true +USE_PS2PDF= yes + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +IMAGES_EN = advanced-networking/isdn-bus.eps +IMAGES_EN+= advanced-networking/isdn-twisted-pair.eps +IMAGES_EN+= advanced-networking/natd.eps +IMAGES_EN+= advanced-networking/net-routing.pic +IMAGES_EN+= advanced-networking/static-routes.pic +IMAGES_EN+= geom/striping.pic +IMAGES_EN+= install/adduser1.scr +IMAGES_EN+= install/adduser2.scr +IMAGES_EN+= install/adduser3.scr +IMAGES_EN+= install/boot-mgr.scr +IMAGES_EN+= install/console-saver1.scr +IMAGES_EN+= install/console-saver2.scr +IMAGES_EN+= install/console-saver3.scr +IMAGES_EN+= install/console-saver4.scr +IMAGES_EN+= install/desktop.scr +IMAGES_EN+= install/disklabel-auto.scr +IMAGES_EN+= install/disklabel-ed1.scr +IMAGES_EN+= install/disklabel-ed2.scr +IMAGES_EN+= install/disklabel-fs.scr +IMAGES_EN+= install/disklabel-root1.scr +IMAGES_EN+= install/disklabel-root2.scr +IMAGES_EN+= install/disklabel-root3.scr +IMAGES_EN+= install/disk-layout.eps +IMAGES_EN+= install/dist-set.scr +IMAGES_EN+= install/dist-set2.scr +IMAGES_EN+= install/docmenu1.scr +IMAGES_EN+= install/ed0-conf.scr +IMAGES_EN+= install/ed0-conf2.scr +IMAGES_EN+= install/edit-inetd-conf.scr +IMAGES_EN+= install/fdisk-drive1.scr +IMAGES_EN+= install/fdisk-drive2.scr +IMAGES_EN+= install/fdisk-edit1.scr +IMAGES_EN+= install/fdisk-edit2.scr +IMAGES_EN+= install/ftp-anon1.scr +IMAGES_EN+= install/ftp-anon2.scr +IMAGES_EN+= install/hdwrconf.scr +IMAGES_EN+= install/keymap.scr +IMAGES_EN+= install/main1.scr +IMAGES_EN+= install/mainexit.scr +IMAGES_EN+= install/main-std.scr +IMAGES_EN+= install/main-options.scr +IMAGES_EN+= install/main-doc.scr +IMAGES_EN+= install/main-keymap.scr +IMAGES_EN+= install/media.scr +IMAGES_EN+= install/mouse1.scr +IMAGES_EN+= install/mouse2.scr +IMAGES_EN+= install/mouse3.scr +IMAGES_EN+= install/mouse4.scr +IMAGES_EN+= install/mouse5.scr +IMAGES_EN+= install/mouse6.scr +IMAGES_EN+= install/mta-main.scr +IMAGES_EN+= install/net-config-menu1.scr +IMAGES_EN+= install/net-config-menu2.scr +IMAGES_EN+= install/nfs-server-edit.scr +IMAGES_EN+= install/ntp-config.scr +IMAGES_EN+= install/options.scr +IMAGES_EN+= install/pkg-cat.scr +IMAGES_EN+= install/pkg-confirm.scr +IMAGES_EN+= install/pkg-install.scr +IMAGES_EN+= install/pkg-sel.scr +IMAGES_EN+= install/probstart.scr +IMAGES_EN+= install/routed.scr +IMAGES_EN+= install/security.scr +IMAGES_EN+= install/sysinstall-exit.scr +IMAGES_EN+= install/timezone1.scr +IMAGES_EN+= install/timezone2.scr +IMAGES_EN+= install/timezone3.scr +IMAGES_EN+= install/userconfig.scr +IMAGES_EN+= install/userconfig2.scr +IMAGES_EN+= install/xf86setup.scr +IMAGES_EN+= mail/mutt1.scr +IMAGES_EN+= mail/mutt2.scr +IMAGES_EN+= mail/mutt3.scr +IMAGES_EN+= mail/pine1.scr +IMAGES_EN+= mail/pine2.scr +IMAGES_EN+= mail/pine3.scr +IMAGES_EN+= mail/pine4.scr +IMAGES_EN+= mail/pine5.scr + +IMAGES_EN+= install/example-dir1.eps +IMAGES_EN+= install/example-dir2.eps +IMAGES_EN+= install/example-dir3.eps +IMAGES_EN+= install/example-dir4.eps +IMAGES_EN+= install/example-dir5.eps +IMAGES_EN+= security/ipsec-network.pic +IMAGES_EN+= security/ipsec-crypt-pkt.pic +IMAGES_EN+= security/ipsec-encap-pkt.pic +IMAGES_EN+= security/ipsec-out-pkt.pic +IMAGES_EN+= vinum/vinum-concat.pic +IMAGES_EN+= vinum/vinum-mirrored-vol.pic +IMAGES_EN+= vinum/vinum-raid10-vol.pic +IMAGES_EN+= vinum/vinum-raid5-org.pic +IMAGES_EN+= vinum/vinum-simple-vol.pic +IMAGES_EN+= vinum/vinum-striped-vol.pic +IMAGES_EN+= vinum/vinum-striped.pic + +# Images from the cross-document image library +IMAGES_LIB= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png +IMAGES_LIB+= callouts/4.png +IMAGES_LIB+= callouts/5.png +IMAGES_LIB+= callouts/6.png +IMAGES_LIB+= callouts/7.png +IMAGES_LIB+= callouts/8.png +IMAGES_LIB+= callouts/9.png +IMAGES_LIB+= callouts/10.png + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS+= audit/chapter.sgml +SRCS+= book.sgml +SRCS+= colophon.sgml +SRCS+= freebsd-glossary.sgml +SRCS+= advanced-networking/chapter.sgml +SRCS+= basics/chapter.sgml +SRCS+= bibliography/chapter.sgml +SRCS+= boot/chapter.sgml +SRCS+= config/chapter.sgml +SRCS+= cutting-edge/chapter.sgml +SRCS+= desktop/chapter.sgml +SRCS+= disks/chapter.sgml +SRCS+= eresources/chapter.sgml +SRCS+= firewalls/chapter.sgml +SRCS+= geom/chapter.sgml +SRCS+= install/chapter.sgml +SRCS+= introduction/chapter.sgml +SRCS+= kernelconfig/chapter.sgml +SRCS+= l10n/chapter.sgml +SRCS+= linuxemu/chapter.sgml +SRCS+= mac/chapter.sgml +SRCS+= mail/chapter.sgml +SRCS+= mirrors/chapter.sgml +SRCS+= multimedia/chapter.sgml +SRCS+= network-servers/chapter.sgml +SRCS+= pgpkeys/chapter.sgml +SRCS+= ports/chapter.sgml +SRCS+= ppp-and-slip/chapter.sgml +SRCS+= preface/preface.sgml +SRCS+= printing/chapter.sgml +SRCS+= security/chapter.sgml +SRCS+= serialcomms/chapter.sgml +SRCS+= users/chapter.sgml +SRCS+= vinum/chapter.sgml +SRCS+= x11/chapter.sgml + +# Entities +SRCS+= chapters.ent + +SYMLINKS= ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?= ${SRCS:M*chapter.sgml} + +SGMLFLAGS+= ${CHAPTERS:S/\/chapter.sgml//:S/^/-i chap./} +SGMLFLAGS+= -i chap.freebsd-glossary + +pgpkeyring: pgpkeys/chapter.sgml + @${JADE} -V nochunks ${OTHERFLAGS} ${JADEOPTS} -d ${DSLPGP} -t sgml ${MASTERDOC} + +# +# Handbook-specific variables +# +.if defined(WITH_PGPKEYS) +JADEFLAGS+= -V withpgpkeys +.endif + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +# +# rules generating lists of mirror site from XML database. +# +XMLDOCS= mirrors-ftp:::mirrors.sgml.ftp.inc.tmp \ + mirrors-cvsup:::mirrors.sgml.cvsup.inc.tmp \ + eresources:::eresources.sgml.www.inc.tmp +DEPENDSET.DEFAULT= transtable mirror +XSLT.DEFAULT= ${XSL_MIRRORS} +XML.DEFAULT= ${XML_MIRRORS} +NO_TIDY.DEFAULT= yes + +PARAMS.mirrors-ftp+= --param 'type' "'ftp'" \ + --param 'proto' "'ftp'" \ + --param 'target' "'handbook/mirrors/chapter.sgml'" +PARAMS.mirrors-cvsup+= --param 'type' "'cvsup'" \ + --param 'proto' "'cvsup'" \ + --param 'target' "'handbook/mirrors/chapter.sgml'" +PARAMS.eresources+= --param 'type' "'www'" \ + --param 'proto' "'http'" \ + --param 'target' "'handbook/eresources/chapter.sgml'" + +SRCS+= mirrors.sgml.ftp.inc \ + mirrors.sgml.cvsup.inc \ + eresources.sgml.www.inc + +CLEANFILES+= mirrors.sgml.ftp.inc mirrors.sgml.ftp.inc.tmp \ + mirrors.sgml.cvsup.inc mirrors.sgml.cvsup.inc.tmp \ + eresources.sgml.www.inc eresources.sgml.www.inc.tmp + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" + +.for p in ftp cvsup +mirrors.sgml.${p}.inc: mirrors.sgml.${p}.inc.tmp + ${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2>,;s,,,'\ + < $@.tmp > $@ || (${RM} -f $@ && false) +.endfor + +eresources.sgml.www.inc: eresources.sgml.www.inc.tmp + ${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2>,;s,,,'\ + < $@.tmp > $@ || (${RM} -f $@ && false) diff --git a/pl_PL.ISO8859-2/books/handbook/advanced-networking/Makefile b/pl_PL.ISO8859-2/books/handbook/advanced-networking/Makefile new file mode 100644 index 0000000000..eb62e4335c --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/advanced-networking/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= advanced-networking/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/advanced-networking/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/advanced-networking/chapter.sgml new file mode 100644 index 0000000000..e8d3947de3 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/advanced-networking/chapter.sgml @@ -0,0 +1,4707 @@ + + + + Advanced Networking + + + Synopsis + + This chapter will cover a number of advanced networking + topics. + + After reading this chapter, you will know: + + + + The basics of gateways and routes. + + + + How to set up IEEE 802.11 and &bluetooth; devices. + + + + How to make FreeBSD act as a bridge. + + + + How to set up network booting on a diskless machine. + + + + How to set up network address translation. + + + + How to connect two computers via PLIP. + + + + How to set up IPv6 on a FreeBSD machine. + + + + How to configure ATM. + + + + Before reading this chapter, you should: + + + + Understand the basics of the /etc/rc scripts. + + + + Be familiar with basic network terminology. + + + + Know how to configure and install a new FreeBSD kernel + (). + + + + Know how to install additional third-party + software (). + + + + + + + + + + Coranth + Gryphon + Contributed by + + + + Gateways and Routes + + routing + gateway + subnet + For one machine to be able to find another over a network, + there must be a mechanism in place to describe how to get from + one to the other. This is called + routing. A route is a + defined pair of addresses: a destination and a + gateway. The pair indicates that if you are + trying to get to this destination, + communicate through this gateway. There + are three types of destinations: individual hosts, subnets, and + default. The default route is + used if none of the other routes apply. We will talk a little + bit more about default routes later on. There are also three + types of gateways: individual hosts, interfaces (also called + links), and Ethernet hardware addresses (MAC + addresses). + + + + An Example + + To illustrate different aspects of routing, we will use the + following example from netstat: + + &prompt.user; netstat -r +Routing tables + +Destination Gateway Flags Refs Use Netif Expire + +default outside-gw UGSc 37 418 ppp0 +localhost localhost UH 0 181 lo0 +test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 +10.20.30.255 link#1 UHLW 1 2421 +example.com link#1 UC 0 0 +host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 +host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => +host2.example.com link#1 UC 0 0 +224 link#1 UC 0 0 + + default route + The first two lines specify the default route (which we + will cover in the next + section) and the localhost route. + + loopback device + The interface (Netif column) that this + routing table specifies to use for + localhost is lo0, + also known as the loopback device. This says to keep all + traffic for this destination internal, rather than sending it + out over the LAN, since it will only end up back where it + started. + + + Ethernet + MAC address + + The next thing that stands out are the addresses beginning + with 0:e0:. These are Ethernet + hardware addresses, which are also known as MAC addresses. + FreeBSD will automatically identify any hosts + (test0 in the example) on the local Ethernet + and add a route for that host, directly to it over the + Ethernet interface, ed0. There is + also a timeout (Expire column) associated + with this type of route, which is used if we fail to hear from + the host in a specific amount of time. When this happens, the + route to this host will be automatically deleted. These hosts + are identified using a mechanism known as RIP (Routing + Information Protocol), which figures out routes to local hosts + based upon a shortest path determination. + + subnet + FreeBSD will also add subnet routes for the local subnet (10.20.30.255 is the broadcast address for the + subnet 10.20.30, and example.com is the domain name associated + with that subnet). The designation link#1 refers + to the first Ethernet card in the machine. You will notice no + additional interface is specified for those. + + Both of these groups (local network hosts and local subnets) have + their routes automatically configured by a daemon called + routed. If this is not run, then only + routes which are statically defined (i.e. entered explicitly) will + exist. + + The host1 line refers to our host, which it + knows by Ethernet address. Since we are the sending host, FreeBSD + knows to use the loopback interface (lo0) + rather than sending it out over the Ethernet interface. + + The two host2 lines are an example of + what happens when we use an &man.ifconfig.8; alias (see the + section on Ethernet for reasons why we would do this). The + => symbol after the + lo0 interface says that not only are + we using the loopback (since this address also refers to the + local host), but specifically it is an alias. Such routes + only show up on the host that supports the alias; all other + hosts on the local network will simply have a + link#1 line for such routes. + + The final line (destination subnet 224) deals + with multicasting, which will be covered in another section. + + Finally, various attributes of each route can be seen in + the Flags column. Below is a short table + of some of these flags and their meanings: + + + + + + + + + U + Up: The route is active. + + + + H + Host: The route destination is a single host. + + + + G + Gateway: Send anything for this destination on to this + remote system, which will figure out from there where to send + it. + + + + S + Static: This route was configured manually, not + automatically generated by the system. + + + + C + Clone: Generates a new route based upon this route for + machines we connect to. This type of route is normally used + for local networks. + + + + W + WasCloned: Indicated a route that was auto-configured + based upon a local area network (Clone) route. + + + + L + Link: Route involves references to Ethernet + hardware. + + + + + + + + Default Routes + + default route + When the local system needs to make a connection to a remote host, + it checks the routing table to determine if a known path exists. If + the remote host falls into a subnet that we know how to reach (Cloned + routes), then the system checks to see if it can connect along that + interface. + + If all known paths fail, the system has one last option: the + default route. This route is a special type of gateway + route (usually the only one present in the system), and is always + marked with a c in the flags field. For hosts on a + local area network, this gateway is set to whatever machine has a + direct connection to the outside world (whether via PPP link, + DSL, cable modem, T1, or another network interface). + + If you are configuring the default route for a machine which + itself is functioning as the gateway to the outside world, then the + default route will be the gateway machine at your Internet Service + Provider's (ISP) site. + + Let us look at an example of default routes. This is a common + configuration: + + + + + + + + +[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] + + + + + The hosts Local1 and + Local2 are at your site. + Local1 is connected to an ISP via a dial up + PPP connection. This PPP server computer is connected through + a local area network to another gateway computer through an + external interface to the ISPs Internet feed. + + The default routes for each of your machines will be: + + + + + + Host + Default Gateway + Interface + + + + + + Local2 + Local1 + Ethernet + + + + Local1 + T1-GW + PPP + + + + + + A common question is Why (or how) would we set + the T1-GW to be the default gateway for + Local1, rather than the ISP server it is + connected to?. + + Remember, since the PPP interface is using an address on the ISP's + local network for your side of the connection, routes for any other + machines on the ISP's local network will be automatically generated. + Hence, you will already know how to reach the T1-GW + machine, so there is no need for the intermediate step + of sending traffic to the ISP server. + + It is common to use the address X.X.X.1 as the gateway address for your local + network. So (using the same example), if your local class-C address + space was 10.20.30 and your ISP was + using 10.9.9 then the default routes + would be: + + + + + + Host + Default Route + + + + + Local2 (10.20.30.2) + Local1 (10.20.30.1) + + + Local1 (10.20.30.1, 10.9.9.30) + T1-GW (10.9.9.1) + + + + + + You can easily define the default route via the + /etc/rc.conf file. In our example, on the + Local2 machine, we added the following line + in /etc/rc.conf: + + defaultrouter="10.20.30.1" + + It is also possible to do it directly from the command + line with the &man.route.8; command: + + &prompt.root; route add default 10.20.30.1 + + For more information on manual manipulation of network + routing tables, consult &man.route.8; manual page. + + + + Dual Homed Hosts + dual homed hosts + There is one other type of configuration that we should cover, and + that is a host that sits on two different networks. Technically, any + machine functioning as a gateway (in the example above, using a PPP + connection) counts as a dual-homed host. But the term is really only + used to refer to a machine that sits on two local-area + networks. + + In one case, the machine has two Ethernet cards, each + having an address on the separate subnets. Alternately, the + machine may only have one Ethernet card, and be using + &man.ifconfig.8; aliasing. The former is used if two + physically separate Ethernet networks are in use, the latter + if there is one physical network segment, but two logically + separate subnets. + + Either way, routing tables are set up so that each subnet knows + that this machine is the defined gateway (inbound route) to the other + subnet. This configuration, with the machine acting as a router + between the two subnets, is often used when we need to implement + packet filtering or firewall security in either or both + directions. + + If you want this machine to actually forward packets + between the two interfaces, you need to tell FreeBSD to enable + this ability. See the next section for more details on how + to do this. + + + + Building a Router + + router + + A network router is simply a system that forwards packets + from one interface to another. Internet standards and good + engineering practice prevent the FreeBSD Project from enabling + this by default in FreeBSD. You can 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 gateway + + This option will set the &man.sysctl.8; variable + net.inet.ip.forwarding to + 1. If you should need to stop routing + temporarily, you can reset this to 0 temporarily. + + Your new router will need routes to know where to send the + traffic. If your network is simple enough you can use static + routes. FreeBSD also comes with the standard BSD routing + daemon &man.routed.8;, which speaks RIP (both version 1 and + version 2) and IRDP. Support for BGP v4, OSPF v2, and other + sophisticated routing protocols is available with the + net/zebra package. + Commercial products such as &gated; are also available for more + complex network routing solutions. + +BGP +RIP +OSPF + + + + + + + Al + Hoang + Contributed by + + + + + Setting Up Static Routes + + + Manual Configuration + + Let us assume we have a network as follows: + + + + + + + + + INTERNET + | (10.0.0.1/24) Default Router to Internet + | + |Interface xl0 + |10.0.0.10/24 + +------+ + | | RouterA + | | (FreeBSD gateway) + +------+ + | Interface xl1 + | 192.168.1.1/24 + | + +--------------------------------+ + Internal Net 1 | 192.168.1.2/24 + | + +------+ + | | RouterB + | | + +------+ + | 192.168.2.1/24 + | + Internal Net 2 + + + + + In this scenario, RouterA is our &os; + machine that is acting as a router to the rest of the + Internet. It has a default route set to 10.0.0.1 which allows it to connect + with the outside world. We will assume that + RouterB is already configured properly and + knows how to get wherever it needs to go. (This is simple + in this picture. Just add a default route on + RouterB using 192.168.1.1 as the gateway.) + + If we look at the routing table for + RouterA we would see something like the + following: + + &prompt.user; netstat -nr +Routing tables + +Internet: +Destination Gateway Flags Refs Use Netif Expire +default 10.0.0.1 UGS 0 49378 xl0 +127.0.0.1 127.0.0.1 UH 0 6 lo0 +10.0.0/24 link#1 UC 0 0 xl0 +192.168.1/24 link#2 UC 0 0 xl1 + + With the current routing table RouterA + will not be able to reach our Internal Net 2. It does not + have a route for 192.168.2.0/24. One way to alleviate + this is to manually add the route. The following command + would add the Internal Net 2 network to + RouterA's routing table using 192.168.1.2 as the next hop: + + &prompt.root; route add -net 192.168.2.0/24 192.168.1.2 + + Now RouterA can reach any hosts on the + 192.168.2.0/24 + network. + + + + Persistent Configuration + + The above example is perfect for configuring a static + route on a running system. However, one problem is that the + routing information will not persist if you reboot your &os; + machine. The way to handle the addition of a static route + is to put it in your /etc/rc.conf + file: + + # Add Internal Net 2 as a static route +static_routes="internalnet2" +route_internalnet2="-net 192.168.2.0/24 192.168.1.2" + + The static_routes configuration + variable is a list of strings separated by a space. Each + string references to a route name. In our above example we + only have one string in static_routes. + This string is internalnet2. We + then add a configuration variable called + route_internalnet2 + where we put all of the configuration parameters we would + give to the &man.route.8; command. For our example above we + would have used the command: + + &prompt.root; route add -net 192.168.2.0/24 192.168.1.2 + + so we need "-net 192.168.2.0/24 192.168.1.2". + + As said above, we can have more than one string in + static_routes. This allows us to + create multiple static routes. The following lines shows + an example of adding static routes for the 192.168.0.0/24 and 192.168.1.0/24 networks on an imaginary + router: + + static_routes="net1 net2" +route_net1="-net 192.168.0.0/24 192.168.0.1" +route_net2="-net 192.168.1.0/24 192.168.1.1" + + + + + Routing Propagation + routing propagation + We have already talked about how we define our routes to the + outside world, but not about how the outside world finds us. + + We already know that routing tables can be set up so that all + traffic for a particular address space (in our examples, a class-C + subnet) can be sent to a particular host on that network, which will + forward the packets inbound. + + When you get an address space assigned to your site, your service + provider will set up their routing tables so that all traffic for your + subnet will be sent down your PPP link to your site. But how do sites + across the country know to send to your ISP? + + There is a system (much like the distributed DNS information) that + keeps track of all assigned address-spaces, and defines their point of + connection to the Internet Backbone. The Backbone are + the main trunk lines that carry Internet traffic across the country, + and around the world. Each backbone machine has a copy of a master + set of tables, which direct traffic for a particular network to a + specific backbone carrier, and from there down the chain of service + providers until it reaches your network. + + It is the task of your service provider to advertise to the + backbone sites that they are the point of connection (and thus the + path inward) for your site. This is known as route + propagation. + + + + Troubleshooting + + traceroute + + Sometimes, there is a problem with routing propagation, and some + sites are unable to connect to you. Perhaps the most useful command + for trying to figure out where routing is breaking down is the + &man.traceroute.8; command. It is equally useful if you cannot seem + to make a connection to a remote machine (i.e. &man.ping.8; + fails). + + The &man.traceroute.8; command is run with the name of the remote + host you are trying to connect to. It will show the gateway hosts + along the path of the attempt, eventually either reaching the target + host, or terminating because of a lack of connection. + + For more information, see the manual page for + &man.traceroute.8;. + + + + Multicast Routing + + multicast routing + + + kernel options + MROUTING + + FreeBSD supports both multicast applications and multicast + routing natively. Multicast applications do not require any + special configuration of FreeBSD; applications will generally + run out of the box. Multicast routing + requires that support be compiled into the kernel: + + options MROUTING + + In addition, the multicast routing daemon, &man.mrouted.8; + must be configured to set up tunnels and DVMRP via + /etc/mrouted.conf. More details on + multicast configuration may be found in the manual page for + &man.mrouted.8;. + + + + + + + + Loader + + + + Marc + Fonvieille + + + + Murray + Stokely + + + + Wireless Networking + + wireless networking + + 802.11 + wireless networking + + + + Wireless Networking Basics + + Most wireless networks are based on the IEEE 802.11 + standards. A basic wireless network consists of multiple + stations communicating with radios that broadcast in either + the 2.4GHz or 5GHz band (though this varies according to the + locale and is also changing to enable communication in the + 2.3GHz and 4.9GHz ranges). + + 802.11 networks are organized in two ways: in + infrastructure mode one station acts as a + master with all the other stations associating to it; the + network is known as a BSS and the master station is termed an + access point (AP). In a BSS all communication passes through + the AP; even when one station wants to communicate with + another wireless station messages must go through the AP. In + the second form of network there is no master and stations + communicate directly. This form of network is termed an IBSS + and is commonly known as an ad-hoc + network. + + 802.11 networks were first deployed in the 2.4GHz band + using protocols defined by the IEEE 802.11 and 802.11b + standard. These specifications include the operating + frequencies, MAC layer characteristics including framing and + transmission rates (communication can be done at various + rates). Later the 802.11a standard defined operation in the + 5GHz band, including different signalling mechanisms and + higher transmission rates. Still later the 802.11g standard + was defined to enable use of 802.11a signalling and + transmission mechanisms in the 2.4GHz band in such a way as to + be backwards compatible with 802.11b networks. + + Separate from the underlying transmission techniques + 802.11 networks have a variety of security mechanisms. The + original 802.11 specifications defined a simple security + protocol called WEP. This protocol uses a fixed pre-shared key + and the RC4 cryptographic cipher to encode data transmitted on + a network. Stations must all agree on the fixed key in order + to communicate. This scheme was shown to be easily broken and + is now rarely used except to discourage transient users from + joining networks. Current security practice is given by the + IEEE 802.11i specification that defines new cryptographic + ciphers and an additional protocol to authenticate stations to + an access point and exchange keys for doing data + communication. Further, cryptographic keys are periodically + refreshed and there are mechanisms for detecting intrusion + attempts (and for countering intrusion attempts). Another + security protocol specification commonly used in wireless + networks is termed WPA. This was a precursor to 802.11i + defined by an industry group as an interim measure while + waiting for 802.11i to be ratified. WPA specifies a subset of + the requirements found in 802.11i and is designed for + implementation on legacy hardware. Specifically WPA requires + only the TKIP cipher that is derived from the original WEP + cipher. 802.11i permits use of TKIP but also requires support + for a stronger cipher, AES-CCM, for encrypting data. (The AES + cipher was not required in WPA because it was deemed too + computationally costly to be implemented on legacy + hardware.) + + Other than the above protocol standards the other + important standard to be aware of is 802.11e. This defines + protocols for deploying multi-media applications such as + streaming video and voice over IP (VoIP) in an 802.11 network. + Like 802.11i, 802.11e also has a precursor specification + termed WME (later renamed WMM) that has been defined by an + industry group as a subset of 802.11e that can be deployed now + to enable multi-media applications while waiting for the final + ratification of 802.11e. The most important thing to know + about 802.11e and WME/WMM is that it enables prioritized + traffic use of a wireless network through Quality of Service + (QoS) protocols and enhanced media access protocols. Proper + implementation of these protocols enable high speed bursting + of data and prioritized traffic flow. + + Since the 6.0 version, &os; supports networks that operate + using 802.11a, 802.11b, and 802.11g. The WPA and 802.11i + security protocols are likewise supported (in conjunction with + any of 11a, 11b, and 11g) and QoS and traffic prioritization + required by the WME/WMM protocols are supported for a limited + set of wireless devices. + + + + Basic Setup + + + Kernel Configuration + + To use wireless networking you need a wireless + networking card and to configure the kernel with the + appropriate wireless networking support. The latter is + separated into multiple modules so that you only need to + configure the software you are actually going to use. + + The first thing you need is a wireless device. The most + commonly used devices are those that use parts made by + Atheros. These devices are supported by the &man.ath.4; + driver and require the following line to be added to the + /boot/loader.conf file: + + if_ath_load="YES" + + The Atheros driver is split up into three separate + pieces: the driver proper (&man.ath.4;), the hardware + support layer that handles chip-specific functions + (&man.ath.hal.4;), and an algorithm for selecting which of + several possible rates for transmitting frames + (ath_rate_sample here). When you load this support as + modules these dependencies are automatically handled for + you. If instead of an Atheros device you had another device + you would select the module for that device; e.g.: + + if_wi_load="YES" + + for devices based on the Intersil Prism parts + (&man.wi.4; driver). + + + In the rest of this document, we will use an + &man.ath.4; device, the device name in the examples must + be changed according to your configuration. A list of + available wireless drivers can be found at the beginning + of the &man.wlan.4; manual page. If a native &os; driver + for your wireless device does not exist, it may be + possible to directly use the &windows; driver with the + help of the NDIS driver + wrapper. + + + With a device driver configured you need to also bring + in the 802.11 networking support required by the driver. + For the &man.ath.4; driver this is at least the &man.wlan.4; + module; this module is automatically loaded with the + wireless device driver. With that you will need the modules + that implement cryptographic support for the security + protocols you intend to use. These are intended to be + dynamically loaded on demand by the &man.wlan.4; module but + for now they must be manually configured. The following + modules are available: &man.wlan.wep.4;, &man.wlan.ccmp.4; + and &man.wlan.tkip.4;. Both &man.wlan.ccmp.4; and + &man.wlan.tkip.4; drivers are only needed if you intend to + use the WPA and/or 802.11i security protocols. If your + network is to run totally open (i.e., with no encryption) + then you do not even need the &man.wlan.wep.4; support. To + load these modules at boot time, add the following lines to + /boot/loader.conf: + + wlan_wep_load="YES" +wlan_ccmp_load="YES" +wlan_tkip_load="YES" + + With this information in the system bootstrap + configuration file (i.e., + /boot/loader.conf), you have to reboot + your &os; box. If you do not want to reboot your machine + for the moment, you can just load the modules by hand using + &man.kldload.8;. + + + If you do not want to use modules, it is possible to + compile these drivers into the kernel by adding the + following lines to your kernel configuration file: + + device ath # Atheros IEEE 802.11 wireless network driver +device ath_hal # Atheros Hardware Access Layer +device ath_rate_sample # John Bicket's SampleRate control algorithm. +device wlan # 802.11 support (Required) +device wlan_wep # WEP crypto support for 802.11 devices +device wlan_ccmp # AES-CCMP crypto support for 802.11 devices +device wlan_tkip # TKIP and Michael crypto support for 802.11 devices + + With this information in the kernel configuration + file, recompile the kernel and reboot your &os; + machine. + + + When the system is up, we could find some information + about the wireless device in the boot messages, like + this: + + ath0: <Atheros 5212> mem 0xff9f0000-0xff9fffff irq 17 at device 2.0 on pci2 +ath0: Ethernet address: 00:11:95:d5:43:62 +ath0: mac 7.9 phy 4.5 radio 5.6 + + + + + Infrastructure Mode + + The infrastructure mode or BSS mode is the mode that is + typically used. In this mode, a number of wireless access + points are connected to a wired network. Each wireless + network has its own name, this name is called the SSID of the + network. Wireless clients connect to the wireless access + points. + + + &os; Clients + + + How to Find Access Points + + To scan for networks, use the + ifconfig command. This request may + take a few moments to complete as it requires that the + system switches to each available wireless frequency and + probes for available access points. Only the super-user + can initiate such a scan: + + &prompt.root; ifconfig ath0 up scan +SSID BSSID CHAN RATE S:N INT CAPS +dlinkap 00:13:46:49:41:76 6 54M 29:0 100 EPS WPA WME +freebsdap 00:11:95:c3:0d:ac 1 54M 22:0 100 EPS WPA + + + You must mark the interface + before you can scan. Subsequent scan requests do not + require you to mark the interface up again. + + + The output of a scan request lists each BSS/IBSS + network found. Beside the name of the network, + SSID, we find the + BSSID which is the MAC address of the + access point. The CAPS field + identifies the type of each network and the capabilities + of the stations operating there: + + + + E + + + Extended Service Set (ESS). Indicates that the + station is part of an infrastructure network (in + contrast to an IBSS/ad-hoc network). + + + + + I + + + IBSS/ad-hoc network. Indicates that the station + is part of an ad-hoc network (in contrast to an ESS + network). + + + + + P + + + Privacy. Data confidentiality is required for + all data frames exchanged within the BSS. This means + that this BSS requires the station to use + cryptographic means such as WEP, TKIP or AES-CCMP to + encrypt/decrypt data frames being exchanged with + others. + + + + + S + + + Short Preamble. Indicates that the network is + using short preambles (defined in 802.11b High + Rate/DSSS PHY, short preamble utilizes a 56 bit sync + field in contrast to a 128 bit field used in long + preamble mode). + + + + + s + + + Short slot time. Indicates that the 802.11g + network is using a short slot time because there are + no legacy (802.11b) stations present. + + + + + One can also display the current list of known + networks with: + + &prompt.root; ifconfig ath0 list scan + + This information may be updated automatically by the + adapter or manually with a request. + Old data is automatically removed from the cache, so over + time this list may shrink unless more scans are + done. + + + + Basic Settings + + This section provides a simple example of how to make + the wireless network adapter work in &os; without + encryption. After you are familiar with these concepts, + we strongly recommend using WPA to set up your + wireless network. + + There are three basic steps to configure a wireless + network: selecting an access point, authenticating your + station, and configuring an IP address. The following + sections discuss each step. + + + Selecting an Access Point + + Most of time it is sufficient to let the system + choose an access point using the builtin heuristics. + This is the default behaviour when you mark an interface + up or otherwise configure an interface by listing it in + /etc/rc.conf, e.g.: + + ifconfig_ath0="DHCP" + + If there are multiple access points and you want to + select a specific one, you can select it by its + SSID: + + ifconfig_ath0="ssid your_ssid_here DHCP" + + In an environment where there are multiple access + points with the same SSID (often done to simplify + roaming) it may be necessary to associate to one + specific device. In this case you can also specify the + BSSID of the access point (you can also leave off the + SSID): + + ifconfig_ath0="ssid your_ssid_here bssid xx:xx:xx:xx:xx:xx DHCP" + + There are other ways to constrain the choice of an + access point such as limiting the set of frequencies the + system will scan on. This may be useful if you have a + multi-band wireless card as scanning all the possible + channels can be time-consuming. To limit operation to a + specific band you can use the + parameter; e.g.: + + ifconfig_ath0="mode 11g ssid your_ssid_here DHCP" + + will force the card to operate in 802.11g which is + defined only for 2.4GHz frequencies so any 5GHz channels + will not be considered. Other ways to do this are the + parameter, to lock operation to + one specific frequency, and the + parameter, to specify a list + of channels for scanning. More information about these + parameters can be found in the &man.ifconfig.8; manual + page. + + + + Authentication + + Once you have selected an access point your station + needs to authenticate before it can pass data. + Authentication can happen in several ways. The most + common scheme used is termed open authentication and + allows any station to join the network and communicate. + This is the authentication you should use for test + purpose the first time you set up a wireless network. + Other schemes require cryptographic handshakes be + completed before data traffic can flow; either using + pre-shared keys or secrets, or more complex schemes that + involve backend services such as RADIUS. Most users + will use open authentication which is the default + setting. Next most common setup is WPA-PSK, also known + as WPA Personal, which is described below. + + + If you have an &apple; &airport; Extreme base + station for an access point you may need to configure + shared-key authentication together with a WEP key. + This can be done in the + /etc/rc.conf file or using the + &man.wpa.supplicant.8; program. If you have a single + &airport; base station you can setup access with + something like: + + ifconfig_ath0="authmode shared wepmode on weptxkey 1 wepkey 01234567 DHCP" + + In general shared key authentication is to be + avoided because it uses the WEP key material in a + highly-constrained manner making it even easier to + crack the key. If WEP must be used (e.g., for + compatibility with legacy devices) it is better to use + WEP with open authentication. More + information regarding WEP can be found in the . + + + + + Getting an IP Address with DHCP + + Once you have selected an access point and set the + authentication parameters, you will have to get an IP + address to communicate. Most of time you will obtain + your wireless IP address via DHCP. To achieve that, + simply edit /etc/rc.conf and add + DHCP to the configuration for your + device as shown in various examples above: + + ifconfig_ath0="DHCP" + + At this point, you are ready to bring up the + wireless interface: + + &prompt.root; /etc/rc.d/netif start + + Once the interface is running, use + ifconfig to see the status of the + interface ath0: + + &prompt.root; ifconfig ath0 +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps) + status: associated + ssid dlinkap channel 6 bssid 00:13:46:49:41:76 + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100 + + The status: associated means you + are connected to the wireless network (to the + dlinkap network in our case). The + bssid 00:13:46:49:41:76 part is the + MAC address of your access point; the + authmode line informs you that the + communication is not encrypted + (OPEN). + + + + Static IP Address + + In the case you cannot obtain an IP address from a + DHCP server, you can set a fixed IP address. Replace + the DHCP keyword shown above with the + address information. Be sure to retain any other + parameters you have set up for selecting an access + point: + + ifconfig_ath0="inet 192.168.1.100 netmask 255.255.255.0 ssid your_ssid_here" + + + + WPA + + WPA (Wi-Fi Protected Access) is a security protocol + used together with 802.11 networks to address the lack of + proper authentication and the weakness of WEP. WPA leverages + the 802.1X authentication protocol and uses one of several + ciphers instead of WEP for data integrity. The only + cipher required by WPA is TKIP (Temporary Key Integrity + Protocol) which is a cipher that extends the basic RC4 + cipher used by WEP by adding integrity checking, tamper + detection, and measures for responding to any detected + intrusions. TKIP is designed to work on legacy hardware + with only software modification; it represents a + compromise that improves security but is still not + entirely immune to attack. WPA also specifies the + AES-CCMP cipher as an alternative to TKIP and that is + preferred when possible; for this specification the term + WPA2 (or RSN) is commonly used. + + WPA defines authentication and encryption protocols. + Authentication is most commonly done using one of two + techniques: by 802.1X and a backend authentication service + such as RADIUS, or by a minimal handshake between the + station and the access point using a pre-shared secret. + The former is commonly termed WPA Enterprise with the + latter known as WPA Personal. Since most people will not + set up a RADIUS backend server for wireless network, + WPA-PSK is by far the most commonly encountered + configuration for WPA. + + The control of the wireless connection and the + authentication (key negotiation or authentication with a + server) is done with the &man.wpa.supplicant.8; utility. + This program requires a configuration file, + /etc/wpa_supplicant.conf, to run. + More information regarding this file can be found in the + &man.wpa.supplicant.conf.5; manual page. + + + WPA-PSK + + WPA-PSK also known as WPA-Personal is based on a + pre-shared key (PSK) generated from a given password and + that will be used as the master key in the wireless + network. This means every wireless user will share the + same key. WPA-PSK is intended for small networks where + the use of an authentication server is not possible or + desired. + + + Always use strong passwords that are + sufficiently long and made from a rich alphabet so + they will not be guessed and/or attacked. + + + The first step is the configuration of the + /etc/wpa_supplicant.conf file with + the SSID and the pre-shared key of your network: + + network={ + ssid="freebsdap" + psk="freebsdmall" +} + + Then, in /etc/rc.conf, we + indicate that the wireless device configuration will be + done with WPA and the IP address will be obtained with + DHCP: + + ifconfig_ath0="WPA DHCP" + + Then, we can bring up the interface: + + &prompt.root; /etc/rc.d/netif start +Starting wpa_supplicant. +DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 5 +DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 6 +DHCPOFFER from 192.168.0.1 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100 + + Or you can try to configure it manually using the + same /etc/wpa_supplicant.conf above, and + run: + + &prompt.root; wpa_supplicant -i ath0 -c /etc/wpa_supplicant.conf +Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz) +Associated with 00:11:95:c3:0d:ac +WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=TKIP GTK=TKIP] + + The next operation is the launch of the + dhclient command to get the IP + address from the DHCP server: + + &prompt.root; dhclient ath0 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +&prompt.root; ifconfig ath0 +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/48Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100 + + + If the /etc/rc.conf is set up + with the line ifconfig_ath0="DHCP" + then it is no need to run the + dhclient command manually, + dhclient will be launched after + wpa_supplicant plumbs the + keys. + + + In the case where the use of DHCP is not possible, + you can set a static IP address after + wpa_supplicant has authenticated the + station: + + &prompt.root; ifconfig ath0 inet 192.168.0.100 netmask 255.255.255.0 +&prompt.root; ifconfig ath0 +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100 + + When DHCP is not used, you also have to manually set + up the default gateway and the nameserver: + + &prompt.root; route add default your_default_router +&prompt.root; echo "nameserver your_DNS_server" >> /etc/resolv.conf + + + + WPA with EAP-TLS + + The second way to use WPA is with an 802.1X backend + authentication server, in this case WPA is called + WPA-Enterprise to make difference with the less secure + WPA-Personal with its pre-shared key. The + authentication in WPA-Enterprise is based on EAP + (Extensible Authentication Protocol). + + EAP does not come with an encryption method, it was + decided to embed EAP inside an encrypted tunnel. Many + types of EAP authentication methods have been designed, + the most common methods are EAP-TLS, EAP-TTLS and + EAP-PEAP. + + EAP-TLS (EAP with Transport Layer Security) is a + very well-supported authentication protocol in the + wireless world since it was the first EAP method to be + certified by the Wi-Fi alliance. + EAP-TLS will require three certificates to run: the CA + certificate (installed on all machines), the server + certificate for your authentication server, and one + client certificate for each wireless client. In this + EAP method, both authentication server and wireless + client authenticate each other in presenting their + respective certificates, and they verify that these + certificates were signed by your organization's + certificate authority (CA). + + As previously, the configuration is done via + /etc/wpa_supplicant.conf: + + network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=TLS + identity="loader" + ca_cert="/etc/certs/cacert.pem" + client_cert="/etc/certs/clientcert.pem" + private_key="/etc/certs/clientkey.pem" + private_key_passwd="freebsdmallclient" +} + + + + This field indicates the network name + (SSID). + + + + Here, we use RSN (IEEE 802.11i) protocol, i.e., + WPA2. + + + + The key_mgmt line refers to + the key management protocol we use. In our case it + is WPA using EAP authentication: + WPA-EAP. + + + + In this field, we mention the EAP method for our + connection. + + + + The identity field contains + the identity string for EAP. + + + + The ca_cert field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificat. + + + + The client_cert line gives + the pathname to the client certificate file. This + certificate is unique to each wireless client of the + network. + + + + The private_key field is the + pathname to the client certificate private key + file. + + + + The private_key field + contains the passphrase for the private key. + + + + Then add the following line to + /etc/rc.conf: + + ifconfig_ath0="WPA DHCP" + + The next step is to bring up the interface with the + help of the rc.d facility: + + &prompt.root; /etc/rc.d/netif start +Starting wpa_supplicant. +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100 + + As previously shown, it is also possible to bring up + the interface manually with both + wpa_supplicant and + ifconfig commands. + + + + WPA with EAP-TTLS + + With EAP-TLS both the authentication server and the + client need a certificate, with EAP-TTLS (EAP-Tunneled + Transport Layer Security) a client certificate is + optional. This method is close to what some secure web + sites do , where the web server can create a secure SSL + tunnel even if the visitors do not have client-side + certificates. EAP-TTLS will use the encrypted TLS + tunnel for safe transport of the authentication + data. + + The configuration is done via the + /etc/wpa_supplicant.conf + file: + + network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=TTLS + identity="test" + password="test" + ca_cert="/etc/certs/cacert.pem" + phase2="auth=MD5" +} + + + + In this field, we mention the EAP method for our + connection. + + + + The identity field contains + the identity string for EAP authentication inside + the encrypted TLS tunnel. + + + + The password field contains + the passphrase for the EAP authentication. + + + + The ca_cert field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificat. + + + + In this field, we mention the authentication + method used in the encrypted TLS tunnel. In our + case, EAP with MD5-Challenge has been used. The + inner authentication phase is often + called phase2. + + + + You also have to add the following line to + /etc/rc.conf: + + ifconfig_ath0="WPA DHCP" + + The next step is to bring up the interface: + + &prompt.root; /etc/rc.d/netif start +Starting wpa_supplicant. +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100 + + + + WPA with EAP-PEAP + + PEAP (Protected EAP) has been designed as an + alternative to EAP-TTLS. There are two types of PEAP + methods, the most common one is PEAPv0/EAP-MSCHAPv2. In + the rest of this document, we will use the PEAP term to + refers to that EAP method. PEAP is the most used EAP + standard after EAP-TLS, in other words if you have a + network with mixed OSes, PEAP should be the most + supported standard after EAP-TLS. + + PEAP is similar to EAP-TTLS: it uses a server-side + certificate to authenticate clients by creating an + encrypted TLS tunnel between the client and the + authentication server, which protects the ensuing + exchange of authentication information. In term of + security the difference between EAP-TTLS and PEAP is + that PEAP authentication broadcasts the username in + clear, only the password is sent in the encrypted TLS + tunnel. EAP-TTLS will use the TLS tunnel for both + username and password. + + We have to edit the + /etc/wpa_supplicant.conf file and + add the EAP-PEAP related settings: + + network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=PEAP + identity="test" + password="test" + ca_cert="/etc/certs/cacert.pem" + phase1="peaplabel=0" + phase2="auth=MSCHAPV2" +} + + + + In this field, we mention the EAP method for our + connection. + + + + The identity field contains + the identity string for EAP authentication inside + the encrypted TLS tunnel. + + + + The password field contains + the passphrase for the EAP authentication. + + + + The ca_cert field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificat. + + + + This field contains the parameters for the + first phase of the authentication (the TLS + tunnel). According to the authentication server + used, you will have to specify a specific label + for the authentication. Most of time, the label + will be client EAP encryption which + is set by using peaplabel=0. + More information can be found in the + &man.wpa.supplicant.conf.5; manual page. + + + + In this field, we mention the authentication + protocol used in the encrypted TLS tunnel. In the + case of PEAP, it is + auth=MSCHAPV2. + + + + The following must be added to + /etc/rc.conf: + + ifconfig_ath0="WPA DHCP" + + Then, we can bring up the interface: + + &prompt.root; /etc/rc.d/netif start +Starting wpa_supplicant. +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100 + + + + + WEP + + WEP (Wired Equivalent Privacy) is part of the original + 802.11 standard. There is no authentication mechanism, + only a weak form of access control, and it is easily to be + cracked. + + WEP can be set up with + ifconfig: + + &prompt.root; ifconfig ath0 inet 192.168.1.100 netmask 255.255.255.0 ssid my_net \ + wepmode on weptxkey 3 wepkey 3:0x3456789012 + + + + The weptxkey means which WEP + key will be used in the transmission. Here we used the + third key. This must match the setting in the access + point. + + + + The wepkey means setting the + selected WEP key. It should in the format + index:key, if the index is + not given, key 1 is set. That is + to say we need to set the index if we use keys other + than the first key. + + + You must replace + the 0x3456789012 with the key + configured for use on the access point. + + + + + You are encouraged to read &man.ifconfig.8; manual + page for further information. + + The wpa_supplicant facility also + can be used to configure your wireless interface with WEP. + The example above can be set up by adding the following + lines to + /etc/wpa_supplicant.conf: + + network={ + ssid="my_net" + key_mgmt=NONE + wep_key3=3456789012 + wep_tx_keyidx=3 +} + + Then: + + &prompt.root; wpa_supplicant -i ath0 -c /etc/wpa_supplicant.conf +Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz) +Associated with 00:13:46:49:41:76 + + + + + + Ad-hoc Mode + + IBSS mode, also called ad-hoc mode, is designed for point + to point connections. For example, to establish an ad-hoc + network between the machine A and the machine + B we will just need to choose two IP adresses + and a SSID. + + On the box A: + + &prompt.root; ifconfig ath0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mediaopt adhoc +&prompt.root; ifconfig ath0 + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 + ether 00:11:95:c3:0d:ac + media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>) + status: associated + ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100 + + The adhoc parameter indicates the + interface is running in the IBSS mode. + + On B, we should be able to detect + A: + + &prompt.root; ifconfig ath0 up scan + SSID BSSID CHAN RATE S:N INT CAPS + freebsdap 02:11:95:c3:0d:ac 2 54M 19:0 100 IS + + The I in the output confirms the + machine A is in ad-hoc mode. We just have to + configure B with a different IP + address: + + &prompt.root; ifconfig ath0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap mediaopt adhoc +&prompt.root; ifconfig ath0 + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>) + status: associated + ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100 + + Both A and B are now + ready to exchange informations. + + + + Troubleshooting + + If you are having trouble with wireless networking, there + are a number of steps you can take to help troubleshoot the + problem. + + + + If you do not see the access point listed when + scanning be sure you have not configured your wireless + device to a limited set of channels. + + + + If you cannot associate to an access point verify the + configuration of your station matches the one of the + access point. This includes the authentication scheme and + any security protocols. Simplify your configuration as + much as possible. If you are using a security protocol + such as WPA or WEP configure the access point for open + authentication and no security to see if you can get + traffic to pass. + + + + Once you can associate to the access point diagnose + any security configuration using simple tools like + &man.ping.8;. + + The wpa_supplicant has much + debugging support; try running it manually with the + option and look at the system + logs. + + + + There are also many lower-level debugging tools. You + can enable debugging messages in the 802.11 protocol + support layer using the wlandebug + program found in + /usr/src/tools/tools/net80211. For + example: + + &prompt.root; wlandebug -i ath0 +scan+auth+debug+assoc + net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan> + + can be used to enable console messages related to + scanning for access points and doing the 802.11 protocol + handshakes required to arrange communication. + + There are also many useful statistics maintained by + the 802.11 layer; the wlanstats tool + will dump these informations. These statistics should + identify all errors identified by the 802.11 layer. + Beware however that some errors are identified in the + device drivers that lie below the 802.11 layer so they may + not show up. To diagnose device-specific problems you + need to refer to the drivers' documentation. + + + + If the above information does not help to clarify the + problem, please submit a problem report and include output + from the above tools. + + + + + + + + Pav + Lucistnik + Written by + +
pav@FreeBSD.org
+ + + + + Bluetooth + + Bluetooth + + Introduction + Bluetooth is a wireless technology for creating personal networks + operating in the 2.4 GHz unlicensed band, with a range of 10 meters. + Networks are usually formed ad-hoc from portable devices such as + cellular phones, handhelds and laptops. Unlike the other popular + wireless technology, Wi-Fi, Bluetooth offers higher level service + profiles, e.g. FTP-like file servers, file pushing, voice transport, + serial line emulation, and more. + + The Bluetooth stack in &os; is implemented using the Netgraph + framework (see &man.netgraph.4;). A broad variety of Bluetooth USB + dongles is supported by the &man.ng.ubt.4; driver. The Broadcom BCM2033 + chip based Bluetooth devices are supported via the &man.ubtbcmfw.4; and + &man.ng.ubt.4; drivers. The 3Com Bluetooth PC Card 3CRWB60-A is + supported by the &man.ng.bt3c.4; driver. Serial and UART based + Bluetooth devices are supported via &man.sio.4;, &man.ng.h4.4; + and &man.hcseriald.8;. This section describes the use of the USB + Bluetooth dongle. + + + + Plugging in the Device + By default Bluetooth device drivers are available as kernel modules. + Before attaching a device, you will need to load the driver into the + kernel: + + &prompt.root; kldload ng_ubt + + If the Bluetooth device is present in the system during system + startup, load the module from + /boot/loader.conf: + + ng_ubt_load="YES" + + Plug in your USB dongle. The output similar to the following will + appear on the console (or in syslog): + + ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2 +ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2 +ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3, + wMaxPacketSize=49, nframes=6, buffer size=294 + + + The Bluetooth stack has to be started manually on &os; 6.0, and + on &os; 5.X before 5.5. It is done automatically from &man.devd.8; + on &os; 5.5, 6.1 and newer. + + Copy + /usr/share/examples/netgraph/bluetooth/rc.bluetooth + into some convenient place, like /etc/rc.bluetooth. + This script is used to start and stop the Bluetooth stack. It is a good + idea to stop the stack before unplugging the device, but it is not + (usually) fatal. When starting the stack, you will receive output similar + to the following: + + &prompt.root; /etc/rc.bluetooth start ubt0 +BD_ADDR: 00:02:72:00:d4:1a +Features: 0xff 0xff 0xf 00 00 00 00 00 +<3-Slot> <5-Slot> <Encryption> <Slot offset> +<Timing accuracy> <Switch> <Hold mode> <Sniff mode> +<Park mode> <RSSI> <Channel quality> <SCO link> +<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD> +<Paging scheme> <Power control> <Transparent SCO data> +Max. ACL packet size: 192 bytes +Number of ACL packets: 8 +Max. SCO packet size: 64 bytes +Number of SCO packets: 8 + + + + + HCI + + Host Controller Interface (HCI) + + Host Controller Interface (HCI) provides a command interface to the + baseband controller and link manager, and access to hardware status and + control registers. This interface provides a uniform method of accessing + the Bluetooth baseband capabilities. HCI layer on the Host exchanges + data and commands with the HCI firmware on the Bluetooth hardware. + The Host Controller Transport Layer (i.e. physical bus) driver provides + both HCI layers with the ability to exchange information with each + other. + + A single Netgraph node of type hci is + created for a single Bluetooth device. The HCI node is normally + connected to the Bluetooth device driver node (downstream) and + the L2CAP node (upstream). All HCI operations must be performed + on the HCI node and not on the device driver node. Default name + for the HCI node is devicehci. + For more details refer to the &man.ng.hci.4; manual page. + + One of the most common tasks is discovery of Bluetooth devices in + RF proximity. This operation is called inquiry. + Inquiry and other HCI related operations are done with the + &man.hccontrol.8; utility. The example below shows how to find out + which Bluetooth devices are in range. You should receive the list of + devices in a few seconds. Note that a remote device will only answer + the inquiry if it put into discoverable + mode. + + &prompt.user; hccontrol -n ubt0hci inquiry +Inquiry result, num_responses=1 +Inquiry result #0 + BD_ADDR: 00:80:37:29:19:a4 + Page Scan Rep. Mode: 0x1 + Page Scan Period Mode: 00 + Page Scan Mode: 00 + Class: 52:02:04 + Clock offset: 0x78ef +Inquiry complete. Status: No error [00] + + BD_ADDR is unique address of a Bluetooth + device, similar to MAC addresses of a network card. This address + is needed for further communication with a device. It is possible + to assign human readable name to a BD_ADDR. + The /etc/bluetooth/hosts file contains information + regarding the known Bluetooth hosts. The following example shows how + to obtain human readable name that was assigned to the remote + device: + + &prompt.user; hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4 +BD_ADDR: 00:80:37:29:19:a4 +Name: Pav's T39 + + If you perform an inquiry on a remote Bluetooth device, it will + find your computer as your.host.name (ubt0). The name + assigned to the local device can be changed at any time. + + The Bluetooth system provides a point-to-point connection (only two + Bluetooth units involved), or a point-to-multipoint connection. In the + point-to-multipoint connection the connection is shared among several + Bluetooth devices. The following example shows how to obtain the list + of active baseband connections for the local device: + + &prompt.user; hccontrol -n ubt0hci read_connection_list +Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State +00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN + + A connection handle is useful when termination + of the baseband connection is required. Note, that it is normally not + required to do it by hand. The stack will automatically terminate + inactive baseband connections. + + &prompt.root; hccontrol -n ubt0hci disconnect 41 +Connection handle: 41 +Reason: Connection terminated by local host [0x16] + + Refer to hccontrol help for a complete listing + of available HCI commands. Most of the HCI commands do not require + superuser privileges. + + + + L2CAP + + Logical Link Control and Adaptation Protocol (L2CAP) + + Logical Link Control and Adaptation Protocol (L2CAP) provides + connection-oriented and connectionless data services to upper layer + protocols with protocol multiplexing capability and segmentation and + reassembly operation. L2CAP permits higher level protocols and + applications to transmit and receive L2CAP data packets up to 64 + kilobytes in length. + + L2CAP is based around the concept of channels. + Channel is a logical connection on top of baseband connection. Each + channel is bound to a single protocol in a many-to-one fashion. Multiple + channels can be bound to the same protocol, but a channel cannot be + bound to multiple protocols. Each L2CAP packet received on a channel is + directed to the appropriate higher level protocol. Multiple channels + can share the same baseband connection. + + A single Netgraph node of type l2cap is + created for a single Bluetooth device. The L2CAP node is normally + connected to the Bluetooth HCI node (downstream) and Bluetooth sockets + nodes (upstream). Default name for the L2CAP node is + devicel2cap. For more details refer to the + &man.ng.l2cap.4; manual page. + + A useful command is &man.l2ping.8;, which can be used to ping + other devices. Some Bluetooth implementations might not return all of + the data sent to them, so 0 bytes in the following + example is normal. + + &prompt.root; l2ping -a 00:80:37:29:19:a4 +0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0 + + The &man.l2control.8; utility is used to perform various operations + on L2CAP nodes. This example shows how to obtain the list of logical + connections (channels) and the list of baseband connections for the + local device: + + &prompt.user; l2control -a 00:02:72:00:d4:1a read_channel_list +L2CAP channels: +Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State +00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN +&prompt.user; l2control -a 00:02:72:00:d4:1a read_connection_list +L2CAP connections: +Remote BD_ADDR Handle Flags Pending State +00:07:e0:00:0b:ca 41 O 0 OPEN + + Another diagnostic tool is &man.btsockstat.1;. It does a job + similar to as &man.netstat.1; does, but for Bluetooth network-related + data structures. The example below shows the same logical connection as + &man.l2control.8; above. + + &prompt.user; btsockstat +Active L2CAP sockets +PCB Recv-Q Send-Q Local address/PSM Foreign address CID State +c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN +Active RFCOMM sessions +L2PCB PCB Flag MTU Out-Q DLCs State +c2afe900 c2b53380 1 127 0 Yes OPEN +Active RFCOMM sockets +PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State +c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN + + + + RFCOMM + + RFCOMM Protocol + + The RFCOMM protocol provides emulation of serial ports over the + L2CAP protocol. The protocol is based on the ETSI standard TS 07.10. + RFCOMM is a simple transport protocol, with additional provisions for + emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The + RFCOMM protocol supports up to 60 simultaneous connections (RFCOMM + channels) between two Bluetooth devices. + + For the purposes of RFCOMM, a complete communication path involves + two applications running on different devices (the communication + endpoints) with a communication segment between them. RFCOMM is intended + to cover applications that make use of the serial ports of the devices + in which they reside. The communication segment is a Bluetooth link from + one device to another (direct connect). + + RFCOMM is only concerned with the connection between the devices in + the direct connect case, or between the device and a modem in the + network case. RFCOMM can support other configurations, such as modules + that communicate via Bluetooth wireless technology on one side and + provide a wired interface on the other side. + + In &os; the RFCOMM protocol is implemented at the Bluetooth sockets + layer. + + + pairing + + Pairing of Devices + + By default, Bluetooth communication is not authenticated, and any + device can talk to any other device. A Bluetooth device (for example, + cellular phone) may choose to require authentication to provide a + particular service (for example, Dial-Up service). Bluetooth + authentication is normally done with PIN codes. + A PIN code is an ASCII string up to 16 characters in length. User is + required to enter the same PIN code on both devices. Once user has + entered the PIN code, both devices will generate a + link key. After that the link key can be stored + either in the devices themselves or in a persistent storage. Next time + both devices will use previously generated link key. The described + above procedure is called pairing. Note that if + the link key is lost by any device then pairing must be repeated. + + The &man.hcsecd.8; daemon is responsible for handling of all + Bluetooth authentication requests. The default configuration file is + /etc/bluetooth/hcsecd.conf. An example section for + a cellular phone with the PIN code arbitrarily set to + 1234 is shown below: + + device { + bdaddr 00:80:37:29:19:a4; + name "Pav's T39"; + key nokey; + pin "1234"; + } + + There is no limitation on PIN codes (except length). Some devices + (for example Bluetooth headsets) may have a fixed PIN code built in. + The switch forces the &man.hcsecd.8; daemon to stay + in the foreground, so it is easy to see what is happening. Set the + remote device to receive pairing and initiate the Bluetooth connection + to the remote device. The remote device should say that pairing was + accepted, and request the PIN code. Enter the same PIN code as you + have in hcsecd.conf. Now your PC and the remote + device are paired. Alternatively, you can initiate pairing on the remote + device. + + On &os; 5.5, 6.1 and newer, the following line can be added to the + /etc/rc.conf file to have + hcsecd started automatically on system + start: + + hcsecd_enable="YES" + + The following is a sample of the + hcsecd daemon output: + +hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist +hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists +hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 + + + + SDP + + Service Discovery Protocol (SDP) + The Service Discovery Protocol (SDP) provides the means for client + applications to discover the existence of services provided by server + applications as well as the attributes of those services. The attributes + of a service include the type or class of service offered and the + mechanism or protocol information needed to utilize the service. + + SDP involves communication between a SDP server and a SDP client. + The server maintains a list of service records that describe the + characteristics of services associated with the server. Each service + record contains information about a single service. A client may + retrieve information from a service record maintained by the SDP server + by issuing a SDP request. If the client, or an application associated + with the client, decides to use a service, it must open a separate + connection to the service provider in order to utilize the service. + SDP provides a mechanism for discovering services and their attributes, + but it does not provide a mechanism for utilizing those services. + + Normally, a SDP client searches for services based on some desired + characteristics of the services. However, there are times when it is + desirable to discover which types of services are described by an SDP + server's service records without any a priori information about the + services. This process of looking for any offered services is called + browsing. + + The Bluetooth SDP server &man.sdpd.8; and command line client + &man.sdpcontrol.8; are included in the standard &os; installation. + The following example shows how to perform a SDP browse query. + + &prompt.user; sdpcontrol -a 00:01:03:fc:6e:ec browse +Record Handle: 00000000 +Service Class ID List: + Service Discovery Server (0x1000) +Protocol Descriptor List: + L2CAP (0x0100) + Protocol specific parameter #1: u/int/uuid16 1 + Protocol specific parameter #2: u/int/uuid16 1 + +Record Handle: 0x00000001 +Service Class ID List: + Browse Group Descriptor (0x1001) + +Record Handle: 0x00000002 +Service Class ID List: + LAN Access Using PPP (0x1102) +Protocol Descriptor List: + L2CAP (0x0100) + RFCOMM (0x0003) + Protocol specific parameter #1: u/int8/bool 1 +Bluetooth Profile Descriptor List: + LAN Access Using PPP (0x1102) ver. 1.0 + + + ... and so on. Note that each service has a list of attributes + (RFCOMM channel for example). Depending on the service you might need to + make a note of some of the attributes. Some Bluetooth implementations do + not support service browsing and may return an empty list. In this case + it is possible to search for the specific service. The example below + shows how to search for the OBEX Object Push (OPUSH) service: + + &prompt.user; sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH + + Offering services on &os; to Bluetooth clients is done with the + &man.sdpd.8; server. On &os; 5.5, 6.1 and newer, the following line can + be added to the /etc/rc.conf file: + + sdpd_enable="YES" + + Then the sdpd daemon can be started with: + + &prompt.root; /etc/rc.d/sdpd start + + On &os; 6.0, and on &os; 5.X before 5.5, + sdpd is not integrated into the system + startup scripts. It has to be started manually with: + + &prompt.root; sdpd + + The local server application that wants to provide Bluetooth + service to the remote clients will register service with the local + SDP daemon. The example of such application is &man.rfcomm.pppd.8;. + Once started it will register Bluetooth LAN service with the local + SDP daemon. + + The list of services registered with the local SDP server can be + obtained by issuing SDP browse query via local control channel: + + &prompt.root; sdpcontrol -l browse + + + + + Dial-Up Networking (DUN) and Network Access with PPP (LAN) + Profiles + + The Dial-Up Networking (DUN) profile is mostly used with modems + and cellular phones. The scenarios covered by this profile are the + following: + + + use of a cellular phone or modem by a computer as + a wireless modem for connecting to a dial-up Internet access server, + or using other dial-up services; + + use of a cellular phone or modem by a computer to + receive data calls. + + + Network Access with PPP (LAN) profile can be used in the following + situations: + + + LAN access for a single Bluetooth device; + + + LAN access for multiple Bluetooth devices; + + + PC to PC (using PPP networking over serial cable + emulation). + + + In &os; both profiles are implemented with &man.ppp.8; and + &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth + connection into something PPP can operate with. Before any profile + can be used, a new PPP label in the /etc/ppp/ppp.conf + must be created. Consult &man.rfcomm.pppd.8; manual page for examples. + + + In the following example &man.rfcomm.pppd.8; will be used to open + RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on + DUN RFCOMM channel. The actual RFCOMM channel number will be obtained + from the remote device via SDP. It is possible to specify RFCOMM channel + by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP + query. Use &man.sdpcontrol.8; to find out RFCOMM + channel on the remote device. + + &prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup + + In order to provide Network Access with PPP (LAN) service the + &man.sdpd.8; server must be running. A new entry for LAN clients must + be created in the /etc/ppp/ppp.conf file. Consult + &man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP + server on valid RFCOMM channel number. The RFCOMM PPP server will + automatically register Bluetooth LAN service with the local SDP daemon. + The example below shows how to start RFCOMM PPP server. + + &prompt.root; rfcomm_pppd -s -C 7 -l rfcomm-server + + + + OBEX + + OBEX Object Push (OPUSH) Profile + OBEX is a widely used protocol for simple file transfers between + mobile devices. Its main use is in infrared communication, where it is + used for generic file transfers between notebooks or PDAs, + and for sending business cards or calendar entries between cellular + phones and other devices with PIM applications. + + The OBEX server and client are implemented as a third-party package + obexapp, which is available as + comms/obexapp port. + + OBEX client is used to push and/or pull objects from the OBEX server. + An object can, for example, be a business card or an appointment. + The OBEX client can obtain RFCOMM channel number from the remote device + via SDP. This can be done by specifying service name instead of RFCOMM + channel number. Supported service names are: IrMC, FTRN and OPUSH. + It is possible to specify RFCOMM channel as a number. Below is an + example of an OBEX session, where device information object is pulled + from the cellular phone, and a new object (business card) is pushed + into the phone's directory. + + &prompt.user; obexapp -a 00:80:37:29:19:a4 -C IrMC +obex> get telecom/devinfo.txt devinfo-t39.txt +Success, response: OK, Success (0x20) +obex> put new.vcf +Success, response: OK, Success (0x20) +obex> di +Success, response: OK, Success (0x20) + + In order to provide OBEX Object Push service, + &man.sdpd.8; server must be running. A root folder, where all incoming + objects will be stored, must be created. The default path to the root + folder is /var/spool/obex. Finally, start OBEX + server on valid RFCOMM channel number. The OBEX server will + automatically register OBEX Object Push service with the local SDP + daemon. The example below shows how to start OBEX server. + + &prompt.root; obexapp -s -C 10 + + + + Serial Port Profile (SPP) + The Serial Port Profile (SPP) allows Bluetooth devices to perform + RS232 (or similar) serial cable emulation. The scenario covered by this + profile deals with legacy applications using Bluetooth as a cable + replacement, through a virtual serial port abstraction. + + The &man.rfcomm.sppd.1; utility implements the Serial Port profile. + A pseudo tty is used as a virtual serial port abstraction. The example + below shows how to connect to a remote device Serial Port service. + Note that you do not have to specify a RFCOMM channel - + &man.rfcomm.sppd.1; can obtain it from the remote device via SDP. + If you would like to override this, specify a RFCOMM channel on the + command line. + + &prompt.root; rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6 +rfcomm_sppd[94692]: Starting on /dev/ttyp6... + + Once connected, the pseudo tty can be used as serial port: + + &prompt.root; cu -l ttyp6 + + + + + Troubleshooting + + + A remote device cannot connect + Some older Bluetooth devices do not support role switching. + By default, when &os; is accepting a new connection, it tries to + perform a role switch and become master. Devices, which do not + support this will not be able to connect. Note that role switching is + performed when a new connection is being established, so it is not + possible to ask the remote device if it does support role switching. + There is a HCI option to disable role switching on the local + side: + + &prompt.root; hccontrol -n ubt0hci write_node_role_switch 0 + + + + + Something is going wrong, can I see what exactly is happening? + Yes, you can. Use the third-party package + hcidump, which is available as + comms/hcidump port. + The hcidump utility is similar to + &man.tcpdump.1;. It can be used to display the content of the Bluetooth + packets on the terminal and to dump the Bluetooth packets to a + file. + + + + + + + + + + + Steve + Peterson + Written by + + + + Bridging + + + Introduction + IP subnet + bridge + It is sometimes useful to divide one physical network + (such as an Ethernet segment) into two separate network + segments without having to create IP subnets and use a router + to connect the segments together. A device that connects two + networks together in this fashion is called a + bridge. A FreeBSD system with two network + interface cards can act as a bridge. + + The bridge works by learning the MAC layer addresses + (Ethernet addresses) of the devices on each of its network interfaces. + It forwards traffic between two networks only when its source and + destination are on different networks. + + In many respects, a bridge is like an Ethernet switch with very + few ports. + + + + Situations Where Bridging Is Appropriate + + There are two common situations in which a bridge is used + today. + + + High Traffic on a Segment + + Situation one is where your physical network segment is + overloaded with traffic, but you do not want for whatever reason to + subnet the network and interconnect the subnets with a + router. + + Let us consider an example of a newspaper where the Editorial and + Production departments are on the same subnetwork. The Editorial + users all use server A for file service, and the Production users + are on server B. An Ethernet network is used to connect all users together, + and high loads on the network are slowing things down. + + If the Editorial users could be segregated on one + network segment and the Production users on another, the two + network segments could be connected with a bridge. Only the + network traffic destined for interfaces on the + other side of the bridge would be sent to the + other network, reducing congestion on each network + segment. + + + + Filtering/Traffic Shaping Firewall + firewall + NAT + + The second common situation is where firewall functionality is + needed without network address translation (NAT). + + An example is a small company that is connected via DSL + or ISDN to their ISP. They have a 13 globally-accessible IP + addresses from their ISP and have 10 PCs on their network. + In this situation, using a router-based firewall is + difficult because of subnetting issues. + + router + DSL + ISDN + A bridge-based firewall can be configured and dropped into the + path just downstream of their DSL/ISDN router without any IP + numbering issues. + + + + + Configuring a Bridge + + + Network Interface Card Selection + + A bridge requires at least two network cards to function. + Unfortunately, not all network interface cards + support bridging. Read &man.bridge.4; for details on the cards that + are supported. + + Install and test the two network cards before continuing. + + + + Kernel Configuration Changes + + kernel options + BRIDGE + + + To enable kernel support for bridging, add the: + + options BRIDGE + + statement to your kernel configuration file, and rebuild your + kernel. + + + + Firewall Support + firewall + If you are planning to use the bridge as a firewall, you + will need to add the IPFIREWALL option as + well. Read for general + information on configuring the bridge as a firewall. + + If you need to allow non-IP packets (such as ARP) to flow + through the bridge, there is a firewall option that + must be set. This option is + IPFIREWALL_DEFAULT_TO_ACCEPT. Note that this + changes the default rule for the firewall to accept any packet. + Make sure you know how this changes the meaning of your ruleset + before you set it. + + + + Traffic Shaping Support + + If you want to use the bridge as a traffic shaper, you will need + to add the DUMMYNET option to your kernel + configuration. Read &man.dummynet.4; for further + information. + + + + + Enabling the Bridge + + Add the line: + + net.link.ether.bridge.enable=1 + + to /etc/sysctl.conf to enable the bridge at + runtime, and the line: + + net.link.ether.bridge.config=if1,if2 + + to enable bridging on the specified interfaces (replace + if1 and + if2 with the names of your two + network interfaces). If you want the bridged packets to be + filtered by &man.ipfw.8;, you should add: + + net.link.ether.bridge.ipfw=1 + + as well. + + For versions prior to &os; 5.2-RELEASE, use instead the following + lines: + + net.link.ether.bridge=1 +net.link.ether.bridge_cfg=if1,if2 +net.link.ether.bridge_ipfw=1 + + + + + Other Information + + If you want to be able to &man.ssh.1; into the bridge from the network, + it is correct to assign one of the network cards an IP address. The + consensus is that assigning both cards an address is a bad + idea. + + If you have multiple bridges on your network, there cannot be more + than one path between any two workstations. Technically, this means + that there is no support for spanning tree link management. + + A bridge can add latency to your &man.ping.8; times, especially for + traffic from one segment to another. + + + + + + + + + Jean-François + Dockès + Updated by + + + + + Alex + Dupre + Reorganized and enhanced by + + + + Diskless Operation + + diskless workstation + diskless operation + + A FreeBSD machine can boot over the network and operate without a + local disk, using file systems mounted from an NFS server. No system + modification is necessary, beyond standard configuration files. + Such a system is relatively easy to set up because all the necessary elements + are readily available: + + + There are at least two possible methods to load the kernel over + the network: + + + PXE: The &intel; Preboot eXecution + Environment system is a form of smart boot ROM built into some + networking cards or motherboards. See &man.pxeboot.8; for more + details. + + + The Etherboot + port (net/etherboot) produces + ROM-able code to boot kernels over the network. The + code can be either burnt into a boot PROM on a network + card, or loaded from a local floppy (or hard) disk + drive, or from a running &ms-dos; system. Many network + cards are supported. + + + + + + A sample script + (/usr/share/examples/diskless/clone_root) eases + the creation and maintenance of the workstation's root file system + on the server. The script will probably require a little + customization but it will get you started very quickly. + + + + Standard system startup files exist in /etc + to detect and support a diskless system startup. + + + + Swapping, if needed, can be done either to an NFS file or to + a local disk. + + + + There are many ways to set up diskless workstations. Many + elements are involved, and most can be customized to suit local + taste. The following will describe variations on the setup of a complete system, + emphasizing simplicity and compatibility with the + standard FreeBSD startup scripts. The system described has the + following characteristics: + + + + The diskless workstations use a shared + read-only / file system, and a shared + read-only /usr. + The root file system is a copy of a + standard FreeBSD root (typically the server's), with some + configuration files overridden by ones specific to diskless + operation or, possibly, to the workstation they belong to. + The parts of the root which have to be + writable are overlaid with &man.md.4; file systems. Any changes + will be lost when the system reboots. + + + The kernel is transferred and loaded either with + Etherboot or PXE + as some situations may mandate the use of either method. + + + + As described, this system is insecure. It should + live in a protected area of a network, and be untrusted by + other hosts. + + + All the information in this section has been tested + using &os; 5.2.1-RELEASE. + + + Background Information + + Setting up diskless workstations is both relatively + straightforward and prone to errors. These are sometimes + difficult to diagnose for a number of reasons. For example: + + + + Compile time options may determine different behaviors at + runtime. + + + + Error messages are often cryptic or totally absent. + + + + In this context, having some knowledge of the background + mechanisms involved is very useful to solve the problems that + may arise. + + Several operations need to be performed for a successful + bootstrap: + + + + The machine needs to obtain initial parameters such as its IP + address, executable filename, server name, root path. This is + done using the DHCP or BOOTP protocols. + DHCP is a compatible extension of BOOTP, and + uses the same port numbers and basic packet format. + + It is possible to configure a system to use only BOOTP. + The &man.bootpd.8; server program is included in the base &os; + system. + + However, DHCP has a number of advantages + over BOOTP (nicer configuration files, possibility of using + PXE, plus many others not directly related to + diskless operation), and we will describe mainly a + DHCP configuration, with equivalent examples + using &man.bootpd.8; when possible. The sample configuration will + use the ISC DHCP software package + (release 3.0.1.r12 was installed on the test server). + + + + The machine needs to transfer one or several programs to local + memory. Either TFTP or NFS + are used. The choice between TFTP and + NFS is a compile time option in several places. + A common source of error is to specify filenames for the wrong + protocol: TFTP typically transfers all files from + a single directory on the server, and would expect filenames + relative to this directory. NFS needs absolute + file paths. + + + + The possible intermediate bootstrap programs and the kernel + need to be initialized and executed. There are several important + variations in this area: + + + + PXE will load &man.pxeboot.8;, which is + a modified version of the &os; third stage loader. The + &man.loader.8; will obtain most parameters necessary to system + startup, and leave them in the kernel environment before + transferring control. It is possible to use a + GENERIC kernel in this case. + + + + Etherboot, will directly + load the kernel, with less preparation. You will need to + build a kernel with specific options. + + + + PXE and Etherboot + work equally well; however, because kernels + normally let the &man.loader.8; do more work for them, + PXE is the preferred method. + + If your BIOS and network cards support + PXE, you should probably use it. + + + + Finally, the machine needs to access its file systems. + NFS is used in all cases. + + + + See also &man.diskless.8; manual page. + + + + Setup Instructions + + + Configuration Using <application>ISC DHCP</application> + + DHCP + diskless operation + + + The ISC DHCP server can answer + both BOOTP and DHCP requests. + + ISC DHCP + 3.0 is not part of the base + system. You will first need to install the + net/isc-dhcp3-server port or the + corresponding package. + + Once ISC DHCP is installed, it + needs a configuration file to run, (normally named + /usr/local/etc/dhcpd.conf). Here follows + a commented example, where host margaux + uses Etherboot and host + corbieres uses PXE: + + +default-lease-time 600; +max-lease-time 7200; +authoritative; + +option domain-name "example.com"; +option domain-name-servers 192.168.4.1; +option routers 192.168.4.1; + +subnet 192.168.4.0 netmask 255.255.255.0 { + use-host-decl-names on; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.4.255; + + host margaux { + hardware ethernet 01:23:45:67:89:ab; + fixed-address margaux.example.com; + next-server 192.168.4.4; + filename "/data/misc/kernel.diskless"; + option root-path "192.168.4.4:/data/misc/diskless"; + } + host corbieres { + hardware ethernet 00:02:b3:27:62:df; + fixed-address corbieres.example.com; + next-server 192.168.4.4; + filename "pxeboot"; + option root-path "192.168.4.4:/data/misc/diskless"; + } +} + + + + This option tells + dhcpd to send the value in the + host declarations as the hostname for the + diskless host. An alternate way would be to add an + option host-name + margaux inside the + host declarations. + + + The + next-server directive designates + the TFTP or NFS server to + use for loading loader or kernel file (the default is to use + the same host as the + DHCP server). + + + The + filename directive defines the file that + Etherboot or PXE + will load for the next execution step. It must be specified + according to the transfer method used. + Etherboot can be compiled to use + NFS or TFTP. The &os; + port configures NFS by default. + PXE uses TFTP, which is + why a relative filename is used here (this may depend on the + TFTP server configuration, but would be + fairly typical). Also, PXE loads + pxeboot, not the kernel. There are other + interesting possibilities, like loading + pxeboot from a &os; CD-ROM + /boot directory (as + &man.pxeboot.8; can load a GENERIC kernel, + this makes it possible to use PXE to boot + from a remote CD-ROM). + + + The + root-path option defines the path to + the root file system, in usual NFS notation. + When using PXE, it is possible to leave off + the host's IP as long as you do not enable the kernel option + BOOTP. The NFS server will then be + the same as the TFTP one. + + + + + + Configuration Using BOOTP + + BOOTP + diskless operation + + + Here follows an equivalent bootpd + configuration (reduced to one client). This would be found in + /etc/bootptab. + + Please note that Etherboot + must be compiled with the non-default option + NO_DHCP_SUPPORT in order to use BOOTP, + and that PXE needs DHCP. The only + obvious advantage of bootpd is + that it exists in the base system. + + +.def100:\ + :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\ + :sm=255.255.255.0:\ + :ds=192.168.4.1:\ + :gw=192.168.4.1:\ + :hd="/tftpboot":\ + :bf="/kernel.diskless":\ + :rp="192.168.4.4:/data/misc/diskless": + +margaux:ha=0123456789ab:tc=.def100 + + + + + Preparing a Boot Program with + <application>Etherboot</application> + + + Etherboot + + + Etherboot's Web + site contains + + extensive documentation mainly intended for Linux + systems, but nonetheless containing useful information. The + following will just outline how you would use + Etherboot on a FreeBSD + system. + + You must first install the net/etherboot package or port. + + You can change the Etherboot + configuration (i.e. to use TFTP instead of + NFS) by editing the Config + file in the Etherboot source + directory. + + For our setup, we shall use a boot floppy. For other methods + (PROM, or &ms-dos; program), please refer to the + Etherboot documentation. + + To make a boot floppy, insert a floppy in the drive on the + machine where you installed Etherboot, + then change your current directory to the src + directory in the Etherboot tree and + type: + + +&prompt.root; gmake bin32/devicetype.fd0 + + + devicetype depends on the type of + the Ethernet card in the diskless workstation. Refer to the + NIC file in the same directory to determine the + right devicetype. + + + + + Booting with <acronym>PXE</acronym> + + By default, the &man.pxeboot.8; loader loads the kernel via + NFS. It can be compiled to use + TFTP instead by specifying the + LOADER_TFTP_SUPPORT option in + /etc/make.conf. See the comments in + /usr/share/examples/etc/make.conf + for instructions. + + There are two other undocumented make.conf + options which may be useful for setting up a serial console diskless + machine: BOOT_PXELDR_PROBE_KEYBOARD, and + BOOT_PXELDR_ALWAYS_SERIAL. + + To use PXE when the machine starts, you will + usually need to select the Boot from network + option in your BIOS setup, or type a function key + during the PC initialization. + + + + Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers + + + TFTP + diskless operation + + + NFS + diskless operation + + + If you are using PXE or + Etherboot configured to use + TFTP, you need to enable + tftpd on the file server: + + + Create a directory from which tftpd + will serve the files, e.g. /tftpboot. + + + + Add this line to your + /etc/inetd.conf: + + tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot + + It appears that at least some PXE versions want + the TCP version of TFTP. In this case, add a second line, + replacing dgram udp with stream + tcp. + + + + Tell inetd to reread its configuration + file. The must be in + the /etc/rc.conf file for this + command to execute correctly: + &prompt.root; /etc/rc.d/inetd restart + + + + You can place the tftpboot + directory anywhere on the server. Make sure that the + location is set in both inetd.conf and + dhcpd.conf. + + In all cases, you also need to enable NFS and export the + appropriate file system on the NFS server. + + + + Add this to /etc/rc.conf: + nfs_server_enable="YES" + + + + Export the file system where the diskless root directory + is located by adding the following to + /etc/exports (adjust the volume mount + point and replace margaux corbieres + with the names of the diskless workstations): + + /data/misc -alldirs -ro margaux corbieres + + + Tell mountd to reread its configuration + file. If you actually needed to enable NFS in + /etc/rc.conf + at the first step, you probably want to reboot instead. + &prompt.root; /etc/rc.d/mountd restart + + + + + + + Building a Diskless Kernel + + + diskless operation + kernel configuration + + + If using Etherboot, you need to + create a kernel configuration file for the diskless client + with the following options (in addition to the usual ones): + + +options BOOTP # Use BOOTP to obtain IP address/hostname +options BOOTP_NFSROOT # NFS mount root file system using BOOTP info + + + You may also want to use BOOTP_NFSV3, + BOOT_COMPAT and BOOTP_WIRED_TO + (refer to NOTES). + + These option names are historical and slightly misleading as + they actually enable indifferent use of DHCP and + BOOTP inside the kernel (it is also possible to force strict BOOTP + or DHCP use). + + Build the kernel (see ), + and copy it to the place specified + in dhcpd.conf. + + + When using PXE, building a kernel with the + above options is not strictly necessary (though suggested). + Enabling them will cause more DHCP requests to be + issued during kernel startup, with a small risk of inconsistency + between the new values and those retrieved by &man.pxeboot.8; in some + special cases. The advantage of using them is that the host name + will be set as a side effect. Otherwise you will need to set the + host name by another method, for example in a client-specific + rc.conf file. + + + + In order to be loadable with + Etherboot, a kernel needs to have + the device hints compiled in. You would typically set the + following option in the configuration file (see the + NOTES configuration comments file): + + hints "GENERIC.hints" + + + + + + Preparing the Root Filesystem + + + root file system + diskless operation + + + You need to create a root file system for the diskless + workstations, in the location listed as + root-path in + dhcpd.conf. + + + Using <command>make world</command> to populate root + + This method is quick and + will install a complete virgin system (not only the root file system) + into DESTDIR. + All you have to do is simply execute the following script: + + #!/bin/sh +export DESTDIR=/data/misc/diskless +mkdir -p ${DESTDIR} +cd /usr/src; make buildworld && make buildkernel +cd /usr/src/etc; make distribution + + Once done, you may need to customize your + /etc/rc.conf and + /etc/fstab placed into + DESTDIR according to your needs. + + + + + Configuring Swap + + If needed, a swap file located on the server can be + accessed via NFS. + + + <acronym>NFS</acronym> Swap + + The kernel does not support enabling NFS + swap at boot time. Swap must be enabled by the startup scripts, + by mounting a writable file system and creating and enabling a + swap file. To create a swap file of appropriate size, you can do + like this: + + &prompt.root; dd if=/dev/zero of=/path/to/swapfile bs=1k count=1 oseek=100000 + + To enable it you have to add the following line to your + rc.conf: + + swapfile=/path/to/swapfile + + + + + Miscellaneous Issues + + + + Running with a Read-only <filename>/usr</filename> + + + diskless operation + /usr read-only + + + If the diskless workstation is configured to run X, you + will have to adjust the XDM configuration file, which puts + the error log on /usr by default. + + + Using a Non-FreeBSD Server + + When the server for the root file system is not running FreeBSD, + you will have to create the root file system on a + FreeBSD machine, then copy it to its destination, using + tar or cpio. + In this situation, there are sometimes + problems with the special files in /dev, + due to differing major/minor integer sizes. A solution to this + problem is to export a directory from the non-FreeBSD server, + mount this directory onto a FreeBSD machine, and + use &man.devfs.5; to allocate device nodes transparently for + the user. + + + + + + + + + + ISDN + + + ISDN + + + A good resource for information on ISDN technology and hardware is + Dan Kegel's ISDN + Page. + + A quick simple road map to ISDN follows: + + + + If you live in Europe you might want to investigate the ISDN card + section. + + + + If you are planning to use ISDN primarily to connect to the + Internet with an Internet Provider on a dial-up non-dedicated basis, + you might look into Terminal Adapters. This will give you the + most flexibility, with the fewest problems, if you change + providers. + + + + If you are connecting two LANs together, or connecting to the + Internet with a dedicated ISDN connection, you might consider + the stand alone router/bridge option. + + + + Cost is a significant factor in determining what solution you will + choose. The following options are listed from least expensive to most + expensive. + + + + + + Hellmuth + Michaelis + Contributed by + + + + ISDN Cards + + + ISDN + cards + + + FreeBSD's ISDN implementation supports only the DSS1/Q.931 + (or Euro-ISDN) standard using passive cards. Some active cards + are supported where the firmware + also supports other signaling protocols; this also includes the + first supported Primary Rate (PRI) ISDN card. + + The isdn4bsd software allows you to connect + to other ISDN routers using either IP over raw HDLC or by using + synchronous PPP: either by using kernel PPP with isppp, a + modified &man.sppp.4; driver, or by using userland &man.ppp.8;. By using + userland &man.ppp.8;, channel bonding of two or more ISDN + B-channels is possible. A telephone answering machine + application is also available as well as many utilities such as + a software 300 Baud modem. + + Some growing number of PC ISDN cards are supported under + FreeBSD and the reports show that it is successfully used all + over Europe and in many other parts of the world. + + The passive ISDN cards supported are mostly the ones with + the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, + but also ISDN cards with chips from Cologne Chip (ISA bus only), + PCI cards with Winbond W6692 chips, some cards with the + Tiger300/320/ISAC chipset combinations and some vendor specific + chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the + AVM Fritz!Card PnP. + + Currently the active supported ISDN cards are the AVM B1 + (ISA and PCI) BRI cards and the AVM T1 PCI PRI cards. + + For documentation on isdn4bsd, + have a look at /usr/share/examples/isdn/ + directory on your FreeBSD system or at the homepage of + isdn4bsd which also has pointers to hints, erratas and + much more documentation such as the isdn4bsd + handbook. + + In case you are interested in adding support for a + different ISDN protocol, a currently unsupported ISDN PC card or + otherwise enhancing isdn4bsd, please + get in touch with &a.hm;. + + For questions regarding the installation, configuration + and troubleshooting isdn4bsd, a + &a.isdn.name; mailing list is available. + + + + ISDN Terminal Adapters + + Terminal adapters (TA), are to ISDN what modems are to regular + phone lines. + modem + Most TA's use the standard Hayes modem AT command set, and can be + used as a drop in replacement for a modem. + + A TA will operate basically the same as a modem except connection + and throughput speeds will be much faster than your old modem. You + will need to configure PPP exactly the same + as for a modem setup. Make sure you set your serial speed as high as + possible. + PPP + The main advantage of using a TA to connect to an Internet + Provider is that you can do Dynamic PPP. As IP address space becomes + more and more scarce, most providers are not willing to provide you + with a static IP anymore. Most stand-alone routers are not able to + accommodate dynamic IP allocation. + + TA's completely rely on the PPP daemon that you are running for + their features and stability of connection. This allows you to + upgrade easily from using a modem to ISDN on a FreeBSD machine, if you + already have PPP set up. However, at the same time any problems you + experienced with the PPP program and are going to persist. + + If you want maximum stability, use the kernel PPP option, not the userland PPP. + + The following TA's are known to work with FreeBSD: + + + + Motorola BitSurfer and Bitsurfer Pro + + + + Adtran + + + + Most other TA's will probably work as well, TA vendors try to make + sure their product can accept most of the standard modem AT command + set. + + The real problem with external TA's is that, like modems, + you need a good serial card in your computer. + + You should read the FreeBSD Serial + Hardware tutorial for a detailed understanding of + serial devices, and the differences between asynchronous and + synchronous serial ports. + + A TA running off a standard PC serial port (asynchronous) limits + you to 115.2 Kbs, even though you have a 128 Kbs connection. + To fully utilize the 128 Kbs that ISDN is capable of, + you must move the TA to a synchronous serial card. + + Do not be fooled into buying an internal TA and thinking you have + avoided the synchronous/asynchronous issue. Internal TA's simply have + a standard PC serial port chip built into them. All this will do is + save you having to buy another serial cable and find another empty + electrical socket. + + A synchronous card with a TA is at least as fast as a stand-alone + router, and with a simple 386 FreeBSD box driving it, probably more + flexible. + + The choice of synchronous card/TA v.s. stand-alone router is largely a + religious issue. There has been some discussion of this in + the mailing lists. We suggest you search the archives for + the complete discussion. + + + + Stand-alone ISDN Bridges/Routers + + ISDN + stand-alone bridges/routers + + ISDN bridges or routers are not at all specific to FreeBSD + or any other operating system. For a more complete + description of routing and bridging technology, please refer + to a networking reference book. + + In the context of this section, the terms router and bridge will + be used interchangeably. + + As the cost of low end ISDN routers/bridges comes down, it + will likely become a more and more popular choice. An ISDN + router is a small box that plugs directly into your local + Ethernet network, and manages its own connection to the other + bridge/router. It has built in software to communicate via + PPP and other popular protocols. + + A router will allow you much faster throughput than a + standard TA, since it will be using a full synchronous ISDN + connection. + + The main problem with ISDN routers and bridges is that + interoperability between manufacturers can still be a problem. + If you are planning to connect to an Internet provider, you + should discuss your needs with them. + + If you are planning to connect two LAN segments together, + such as your home LAN to the office LAN, this is the simplest + lowest + maintenance solution. Since you are buying the equipment for + both sides of the connection you can be assured that the link + will work. + + For example to connect a home computer or branch office + network to a head office network the following setup could be + used: + + + Branch Office or Home Network + + 10 base 2 + Network uses a bus based topology with 10 base 2 + Ethernet (thinnet). Connect router to network cable with + AUI/10BT transceiver, if necessary. + + + + + + + + ---Sun workstation +| +---FreeBSD box +| +---Windows 95 +| +Stand-alone router + | +ISDN BRI line + + + + 10 Base 2 Ethernet + + + + If your home/branch office is only one computer you can use a + twisted pair crossover cable to connect to the stand-alone router + directly. + + + + Head Office or Other LAN + + 10 base T + Network uses a star topology with 10 base T Ethernet + (Twisted Pair). + + + + + + + + -------Novell Server + | H | + | ---Sun + | | + | U ---FreeBSD + | | + | ---Windows 95 + | B | + |___---Stand-alone router + | + ISDN BRI line + + + + ISDN Network Diagram + + + + + One large advantage of most routers/bridges is that they allow you + to have 2 separate independent PPP connections to + 2 separate sites at the same time. This is not + supported on most TA's, except for specific (usually expensive) models + that + have two serial ports. Do not confuse this with channel bonding, MPP, + etc. + + This can be a very useful feature if, for example, you + have an dedicated ISDN connection at your office and would + like to tap into it, but do not want to get another ISDN line + at work. A router at the office location can manage a + dedicated B channel connection (64 Kbps) to the Internet + and use the other B channel for a separate data connection. + The second B channel can be used for dial-in, dial-out or + dynamically bonding (MPP, etc.) with the first B channel for + more bandwidth. + + IPX/SPX + An Ethernet bridge will also allow you to transmit more than just + IP traffic. You can also send IPX/SPX or whatever other protocols you + use. + + + + + + + + Chern + Lee + Contributed by + + + + Network Address Translation + + + Overview + + natd + + FreeBSD's Network Address Translation daemon, commonly known as + &man.natd.8; is a daemon that accepts incoming raw IP packets, + changes the source to the local machine and re-injects these packets + back into the outgoing IP packet stream. &man.natd.8; does this by changing + the source IP address and port such that when data is received back, + it is able to determine the original location of the data and forward + it back to its original requester. + Internet connection sharing + NAT + The most common use of NAT is to perform what is commonly known as + Internet Connection Sharing. + + + + Setup + Due to the diminishing IP space in IPv4, and the increased number + of users on high-speed consumer lines such as cable or DSL, people are + increasingly in need of an Internet Connection Sharing solution. The + ability to connect several computers online through one connection and + IP address makes &man.natd.8; a reasonable choice. + + Most commonly, a user has a machine connected to a cable or DSL + line with one IP address and wishes to use this one connected computer to + provide Internet access to several more over a LAN. + + To do this, the FreeBSD machine on the Internet must act as a + gateway. This gateway machine must have two NICs—one for connecting + to the Internet router, the other connecting to a LAN. All the + machines on the LAN are connected through a hub or switch. + + + There are many ways to get a LAN connected to the Internet + through a &os; gateway. This example will only cover a + gateway with at least two NICs. + + + + + + + + + _______ __________ ________ + | | | | | | + | Hub |-----| Client B |-----| Router |----- Internet + |_______| |__________| |________| + | + ____|_____ +| | +| Client A | +|__________| + + + + Network Layout + + + + A setup like this is commonly used to share an Internet + connection. One of the LAN machines is + connected to the Internet. The rest of the machines access + the Internet through that gateway + machine. + + + + + kernel + configuration + + Configuration + The following options must be in the kernel configuration + file: + options IPFIREWALL +options IPDIVERT + + Additionally, at choice, the following may also be suitable: + options IPFIREWALL_DEFAULT_TO_ACCEPT +options IPFIREWALL_VERBOSE + + The following must be in /etc/rc.conf: + + gateway_enable="YES" +firewall_enable="YES" +firewall_type="OPEN" +natd_enable="YES" +natd_interface="fxp0" +natd_flags="" + + + + Sets up the machine to act as a gateway. Running + sysctl net.inet.ip.forwarding=1 would + have the same effect. + + + + Enables the firewall rules in + /etc/rc.firewall at boot. + + + + This specifies a predefined firewall ruleset that + allows anything in. See + /etc/rc.firewall for additional + types. + + + + Indicates which interface to forward packets through + (the interface connected to the Internet). + + + + Any additional configuration options passed to + &man.natd.8; on boot. + + + + Having the previous options defined in + /etc/rc.conf would run + natd -interface fxp0 at boot. This can also + be run manually. + + + It is also possible to use a configuration file for + &man.natd.8; when there are too many options to pass. In this + case, the configuration file must be defined by adding the + following line to /etc/rc.conf: + + natd_flags="-f /etc/natd.conf" + + The /etc/natd.conf file will + contain a list of configuration options, one per line. For + example the next section case would use the following + file: + + redirect_port tcp 192.168.0.2:6667 6667 +redirect_port tcp 192.168.0.3:80 80 + + For more information about the configuration file, + consult the &man.natd.8; manual page about the + option. + + + Each machine and interface behind the LAN should be + assigned IP address numbers in the private network space as + defined by RFC 1918 + and have a default gateway of the natd machine's internal IP + address. + + For example, client A and + B behind the LAN have IP addresses of 192.168.0.2 and 192.168.0.3, while the natd machine's + LAN interface has an IP address of 192.168.0.1. Client A + and B's default gateway must be set to that + of the natd machine, 192.168.0.1. The natd machine's + external, or Internet interface does not require any special + modification for &man.natd.8; to work. + + + + Port Redirection + + The drawback with &man.natd.8; is that the LAN clients are not accessible + from the Internet. Clients on the LAN can make outgoing connections to + the world but cannot receive incoming ones. This presents a problem + if trying to run Internet services on one of the LAN client machines. + A simple way around this is to redirect selected Internet ports on the + natd machine to a LAN client. + + + For example, an IRC server runs on client A, and a web server runs + on client B. For this to work properly, connections received on ports + 6667 (IRC) and 80 (web) must be redirected to the respective machines. + + + The must be passed to + &man.natd.8; with the proper options. The syntax is as follows: + -redirect_port proto targetIP:targetPORT[-targetPORT] + [aliasIP:]aliasPORT[-aliasPORT] + [remoteIP[:remotePORT[-remotePORT]]] + + In the above example, the argument should be: + + -redirect_port tcp 192.168.0.2:6667 6667 + -redirect_port tcp 192.168.0.3:80 80 + + + This will redirect the proper tcp ports to the + LAN client machines. + + + The argument can be used to indicate port + ranges over individual ports. For example, tcp + 192.168.0.2:2000-3000 2000-3000 would redirect + all connections received on ports 2000 to 3000 to ports 2000 + to 3000 on client A. + + These options can be used when directly running + &man.natd.8;, placed within the + natd_flags="" option in + /etc/rc.conf, + or passed via a configuration file. + + For further configuration options, consult &man.natd.8; + + + + Address Redirection + address redirection + Address redirection is useful if several IP addresses are + available, yet they must be on one machine. With this, + &man.natd.8; can assign each LAN client its own external IP address. + &man.natd.8; then rewrites outgoing packets from the LAN clients + with the proper external IP address and redirects + all traffic incoming on that particular IP address back to + the specific LAN client. This is also known as static NAT. + For example, the IP addresses 128.1.1.1, + 128.1.1.2, and + 128.1.1.3 belong to the natd gateway + machine. 128.1.1.1 can be used + as the natd gateway machine's external IP address, while + 128.1.1.2 and + 128.1.1.3 are forwarded back to LAN + clients A and B. + + The syntax is as follows: + + -redirect_address localIP publicIP + + + + + + + localIP + The internal IP address of the LAN client. + + + publicIP + The external IP address corresponding to the LAN client. + + + + + + In the example, this argument would read: + + -redirect_address 192.168.0.2 128.1.1.2 +-redirect_address 192.168.0.3 128.1.1.3 + + Like , these arguments are also placed within + the natd_flags="" option of /etc/rc.conf, or passed via a configuration file. With address + redirection, there is no need for port redirection since all data + received on a particular IP address is redirected. + + The external IP addresses on the natd machine must be active and aliased + to the external interface. Look at &man.rc.conf.5; to do so. + + + + + + Parallel Line IP (PLIP) + + PLIP + + Parallel Line IP + PLIP + + + PLIP lets us run TCP/IP between parallel ports. It is + useful on machines without network cards, or to install on + laptops. In this section, we will discuss: + + + + Creating a parallel (laplink) cable. + + + + Connecting two computers with PLIP. + + + + + Creating a Parallel Cable + + You can purchase a parallel cable at most computer supply + stores. If you cannot do that, or you just want to know how + it is done, the following table shows how to make one out of a normal parallel + printer cable. + + + Wiring a Parallel Cable for Networking + + + + + A-name + + A-End + + B-End + + Descr. + + Post/Bit + + + + + + DATA0 +-ERROR + + 2 +15 + + 15 +2 + + Data + + 0/0x01 +1/0x08 + + + + DATA1 ++SLCT + + 3 +13 + + 13 +3 + + Data + + 0/0x02 +1/0x10 + + + + DATA2 ++PE + + 4 +12 + + 12 +4 + + Data + + 0/0x04 +1/0x20 + + + + DATA3 +-ACK + + 5 +10 + + 10 +5 + + Strobe + + 0/0x08 +1/0x40 + + + + DATA4 +BUSY + + 6 +11 + + 11 +6 + + Data + + 0/0x10 +1/0x80 + + + + GND + + 18-25 + + 18-25 + + GND + + - + + + +
+ + + + Setting Up PLIP + + First, you have to get a laplink cable. + Then, confirm that both computers have a kernel with &man.lpt.4; driver + support: + + &prompt.root; grep lp /var/run/dmesg.boot +lpt0: <Printer> on ppbus0 +lpt0: Interrupt-driven port + + The parallel port must be an interrupt driven port, + you should have lines similar to the + following in your in the + /boot/device.hints file: + + hint.ppc.0.at="isa" +hint.ppc.0.irq="7" + + Then check if the kernel configuration file has a + device plip line or if the + plip.ko kernel module is loaded. In both + cases the parallel networking interface should appear when you + use the &man.ifconfig.8; command to display it: + + &prompt.root; ifconfig plip0 +plip0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 + + Plug the laplink cable into the parallel interface on + both computers. + + Configure the network interface parameters on both + sites as root. For example, if you want to connect + the host host1 with another machine host2: + + host1 <-----> host2 +IP Address 10.0.0.1 10.0.0.2 + + Configure the interface on host1 by doing: + + &prompt.root; ifconfig plip0 10.0.0.1 10.0.0.2 + + Configure the interface on host2 by doing: + + &prompt.root; ifconfig plip0 10.0.0.2 10.0.0.1 + + + You now should have a working connection. Please read the + manual pages &man.lp.4; and &man.lpt.4; for more details. + + You should also add both hosts to + /etc/hosts: + + 127.0.0.1 localhost.my.domain localhost +10.0.0.1 host1.my.domain host1 +10.0.0.2 host2.my.domain + + To confirm the connection works, go to each host and ping + the other. For example, on host1: + + &prompt.root; ifconfig plip0 +plip0: 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 +host2 host1 UH 0 0 plip0 +&prompt.root; ping -c 4 host2 +PING host2 (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 + +--- host2 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 ms + + + + + + + + + Aaron + Kaplan + Originally Written by + + + + + Tom + Rhodes + Restructured and Added by + + + + + Brad + Davis + Extended by + + + + + + IPv6 + IPv6 (also know as IPng IP next generation) is + the new version of the well known IP protocol (also know as + IPv4). Like the other current *BSD systems, + FreeBSD includes the KAME IPv6 reference implementation. + So your FreeBSD system comes with all you will need to experiment with IPv6. + This section focuses on getting IPv6 configured and running. + + In the early 1990s, people became aware of the rapidly + diminishing address space of IPv4. Given the expansion rate of the + Internet there were two major concerns: + + + + Running out of addresses. Today this is not so much of a concern + anymore since RFC1918 private address space + (10.0.0.0/8, + 172.16.0.0/12, and + 192.168.0.0/16) + and Network Address Translation (NAT) are + being employed. + + + + Router table entries were getting too large. This is + still a concern today. + + + + IPv6 deals with these and many other issues: + + + + 128 bit address space. In other words theoretically there are + 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses + available. This means there are approximately + 6.67 * 10^27 IPv6 addresses per square meter on our planet. + + + + Routers will only store network aggregation addresses in their routing + tables thus reducing the average space of a routing table to 8192 + entries. + + + + There are also lots of other useful features of IPv6 such as: + + + + Address autoconfiguration (RFC2462) + + + + Anycast addresses (one-out-of many) + + + + Mandatory multicast addresses + + + + IPsec (IP security) + + + + Simplified header structure + + + + Mobile IP + + + + IPv6-to-IPv4 transition mechanisms + + + + + For more information see: + + + + IPv6 overview at playground.sun.com + + + + KAME.net + + + + 6bone.net + + + + + Background on IPv6 Addresses + There are different types of IPv6 addresses: Unicast, Anycast and + Multicast. + + Unicast addresses are the well known addresses. A packet sent + to a unicast address arrives exactly at the interface belonging to + the address. + + Anycast addresses are syntactically indistinguishable from unicast + addresses but they address a group of interfaces. The packet destined for + an anycast address will arrive at the nearest (in router metric) + interface. Anycast addresses may only be used by routers. + + Multicast addresses identify a group of interfaces. A packet destined + for a multicast address will arrive at all interfaces belonging to the + multicast group. + + The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed + by multicast addresses in IPv6. + + + Reserved IPv6 addresses + + + + + IPv6 address + Prefixlength (Bits) + Description + Notes + + + + + + :: + 128 bits + unspecified + cf. 0.0.0.0 in + IPv4 + + + + ::1 + 128 bits + loopback address + cf. 127.0.0.1 in + IPv4 + + + + ::00:xx:xx:xx:xx + 96 bits + embedded IPv4 + The lower 32 bits are the IPv4 address. Also + called IPv4 compatible IPv6 + address + + + + ::ff:xx:xx:xx:xx + 96 bits + IPv4 mapped IPv6 address + The lower 32 bits are the IPv4 address. + For hosts which do not support IPv6. + + + + fe80:: - feb:: + 10 bits + link-local + cf. loopback address in IPv4 + + + + fec0:: - fef:: + 10 bits + site-local +   + + + + ff:: + 8 bits + multicast +   + + + + 001 (base + 2) + 3 bits + global unicast + All global unicast addresses are assigned from + this pool. The first 3 bits are + 001. + + + +
+ + + + Reading IPv6 Addresses + The canonical form is represented as: x:x:x:x:x:x:x:x, each + x being a 16 Bit hex value. For example + FEBC:A574:382B:23C1:AA49:4592:4EFE:9982 + + Often an address will have long substrings of all zeros + therefore one such substring per address can be abbreviated by ::. + Also up to three leading 0s per hexquad can be omitted. + For example fe80::1 + corresponds to the canonical form + fe80:0000:0000:0000:0000:0000:0000:0001. + + A third form is to write the last 32 Bit part in the + well known (decimal) IPv4 style with dots . + as separators. For example + 2002::10.0.0.1 + corresponds to the (hexadecimal) canonical representation + 2002:0000:0000:0000:0000:0000:0a00:0001 + which in turn is equivalent to + writing 2002::a00:1. + + By now the reader should be able to understand the following: + + &prompt.root; ifconfig + + rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255 + inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1 + ether 00:00:21:03:08:e1 + media: Ethernet autoselect (100baseTX ) + status: active + + fe80::200:21ff:fe03:8e1%rl0 + is an auto configured link-local address. It is generated from the MAC + address as part of the auto configuration. + + For further information on the structure of IPv6 addresses + see RFC3513. + + + + Getting Connected + + Currently there are four ways to connect to other IPv6 hosts and networks: + + + + Join the experimental 6bone + + + + Getting an IPv6 network from your upstream provider. Talk to your + Internet provider for instructions. + + + + Tunnel via 6-to-4 (RFC3068) + + + + Use the net/freenet6 port if you are on a dial-up connection. + + + + Here we will talk on how to connect to the 6bone since it currently seems + to be the most popular way. + + First take a look at the 6bone site and find a 6bone connection nearest to + you. Write to the responsible person and with a little bit of luck you + will be given instructions on how to set up your connection. Usually this + involves setting up a GRE (gif) tunnel. + + Here is a typical example on setting up a &man.gif.4; tunnel: + + &prompt.root; ifconfig gif0 create +&prompt.root; ifconfig gif0 +gif0: flags=8010<POINTOPOINT,MULTICAST> mtu 1280 +&prompt.root; ifconfig gif0 tunnel MY_IPv4_ADDR MY_IPv4_REMOTE_TUNNEL_ENDPOINT_ADDR +&prompt.root; ifconfig gif0 inet6 alias MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR + + Replace the capitalized words by the information you received from the + upstream 6bone node. + + This establishes the tunnel. Check if the tunnel is working by &man.ping6.8; + 'ing ff02::1%gif0. You should receive two ping replies. + + In case you are intrigued by the address ff02:1%gif0, this is a + multicast address. %gif0 states that the multicast address at network + interface gif0 is to be used. Since we ping a multicast address the + other endpoint of the tunnel should reply as well. + + By now setting up a route to your 6bone uplink should be rather + straightforward: + + &prompt.root; route add -inet6 default -interface gif0 +&prompt.root; ping6 -n MY_UPLINK + + &prompt.root; traceroute6 www.jp.FreeBSD.org +(3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets + 1 atnet-meta6 14.147 ms 15.499 ms 24.319 ms + 2 6bone-gw2-ATNET-NT.ipv6.tilab.com 103.408 ms 95.072 ms * + 3 3ffe:1831:0:ffff::4 138.645 ms 134.437 ms 144.257 ms + 4 3ffe:1810:0:6:290:27ff:fe79:7677 282.975 ms 278.666 ms 292.811 ms + 5 3ffe:1800:0:ff00::4 400.131 ms 396.324 ms 394.769 ms + 6 3ffe:1800:0:3:290:27ff:fe14:cdee 394.712 ms 397.19 ms 394.102 ms + + This output will differ from machine to machine. By now you should be + able to reach the IPv6 site www.kame.net + and see the dancing tortoise — that is if you have a IPv6 enabled browser such as + www/mozilla, Konqueror, + which is part of x11/kdebase3, + or www/epiphany. + + + + + DNS in the IPv6 World + + There used to be two types of DNS records for IPv6. The IETF + has declared A6 records obsolete. AAAA records are the standard + now. + + Using AAAA records is straightforward. Assign your hostname to the new + IPv6 address you just received by adding: + + MYHOSTNAME AAAA MYIPv6ADDR + + To your primary zone DNS file. In case you do not serve your own + DNS zones ask your DNS provider. + Current versions of bind (version 8.3 and 9) + and dns/djbdns (with the IPv6 patch) + support AAAA records. + + + + Applying the needed changes to <filename>/etc/rc.conf</filename> + + + IPv6 Client Settings + + These settings will help you configure a machine that will be on + your LAN and act as a client, not a router. To have &man.rtsol.8; + autoconfigure your interface on boot all you need to add is: + + ipv6_enable="YES" + + To statically assign an IP address such as + 2001:471:1f11:251:290:27ff:fee0:2093, to your + fxp0 interface, add: + + ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093" + + To assign a default router of + 2001:471:1f11:251::1 + add the following to /etc/rc.conf: + + ipv6_defaultrouter="2001:471:1f11:251::1" + + + + + IPv6 Router/Gateway Settings + + This will help you take the directions that your tunnel provider, + such as the 6bone, has + given you and convert it into settings that will persist through reboots. + To restore your tunnel on startup use something like the following in + /etc/rc.conf: + + List the Generic Tunneling interfaces that will be configured, for + example gif0: + + gif_interfaces="gif0" + + To configure the interface with a local endpoint of + MY_IPv4_ADDR to a remote endpoint of + REMOTE_IPv4_ADDR: + + gifconfig_gif0="MY_IPv4_ADDR REMOTE_IPv4_ADDR" + + To apply the IPv6 address you have been assigned for use as your + IPv6 tunnel endpoint, add: + + ipv6_ifconfig_gif0="MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR" + + Then all you have to do is set the default route for IPv6. This is + the other side of the IPv6 tunnel: + + ipv6_defaultrouter="MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR" + + + + + IPv6 Tunnel Settings + + If the server is to route IPv6 between the rest of your network + and the world, the following /etc/rc.conf + setting will also be needed: + + ipv6_gateway_enable="YES" + + + + + + Router Advertisement and Host Auto Configuration + + This section will help you setup &man.rtadvd.8; to advertise the + IPv6 default route. + + To enable &man.rtadvd.8; you will need the following in your + /etc/rc.conf: + + rtadvd_enable="YES" + + It is important that you specify the interface on which to do + IPv6 router solicitation. For example to tell &man.rtadvd.8; to use + fxp0: + + rtadvd_interfaces="fxp0" + + Now we must create the configuration file, + /etc/rtadvd.conf. Here is an example: + + fxp0:\ + :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether: + + Replace fxp0 with the interface you + are going to be using. + + Next, replace 2001:471:1f11:246:: + with the prefix of your allocation. + + If you are dedicated a /64 subnet + you will not need to change anything else. Otherwise, you will need to + change the prefixlen# to the correct value. + + + + + + + + + Harti + Brandt + Contributed by + + + + + Asynchronous Transfer Mode (ATM) + + + Configuring classical IP over ATM (PVCs) + + Classical IP over ATM (CLIP) is the + simplest method to use Asynchronous Transfer Mode (ATM) + with IP. It can be used with + switched connections (SVCs) and with permanent connections + (PVCs). This section describes how to set up a network based + on PVCs. + + + Fully meshed configurations + + The first method to set up a CLIP with + PVCs is to connect each machine to each other machine in the + network via a dedicated PVC. While this is simple to + configure it tends to become impractical for a larger number + of machines. The example supposes that we have four + machines in the network, each connected to the ATM network + with an ATM adapter card. The first step is the planning of + the IP addresses and the ATM connections between the + machines. We use the following: + + + + + + + + Host + IP Address + + + + + + hostA + 192.168.173.1 + + + + hostB + 192.168.173.2 + + + + hostC + 192.168.173.3 + + + + hostD + 192.168.173.4 + + + + + + To build a fully meshed net we need one ATM connection + between each pair of machines: + + + + + + + + Machines + VPI.VCI couple + + + + + + hostA - hostB + 0.100 + + + + hostA - hostC + 0.101 + + + + hostA - hostD + 0.102 + + + + hostB - hostC + 0.103 + + + + hostB - hostD + 0.104 + + + + hostC - hostD + 0.105 + + + + + + The VPI and VCI values at each end of the connection may + of course differ, but for simplicity we assume that they are + the same. Next we need to configure the ATM interfaces on + each host: + + hostA&prompt.root; ifconfig hatm0 192.168.173.1 up +hostB&prompt.root; ifconfig hatm0 192.168.173.2 up +hostC&prompt.root; ifconfig hatm0 192.168.173.3 up +hostD&prompt.root; ifconfig hatm0 192.168.173.4 up + + assuming that the ATM interface is + hatm0 on all hosts. Now the PVCs + need to be configured on hostA (we assume that + they are already configured on the ATM switches, you need to + consult the manual for the switch on how to do this). + + hostA&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr +hostA&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr +hostA&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr + +hostB&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr +hostB&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr +hostB&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr + +hostC&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr +hostC&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr +hostC&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr + +hostD&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr +hostD&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr +hostD&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr + + Of course other traffic contracts than UBR can be used + given the ATM adapter supports those. In this case the name + of the traffic contract is followed by the parameters of the + traffic. Help for the &man.atmconfig.8; tool can be + obtained with: + + &prompt.root; atmconfig help natm add + + or in the &man.atmconfig.8; manual page. + + The same configuration can also be done via + /etc/rc.conf. + For hostA this would look like: + +network_interfaces="lo0 hatm0" +ifconfig_hatm0="inet 192.168.173.1 up" +natm_static_routes="hostB hostC hostD" +route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr" +route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr" +route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr" + + The current state of all CLIP routes + can be obtained with: + + hostA&prompt.root; atmconfig natm show + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/appendix.decl b/pl_PL.ISO8859-2/books/handbook/appendix.decl new file mode 100644 index 0000000000..ddd974539b --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/appendix.decl @@ -0,0 +1,2 @@ + + diff --git a/pl_PL.ISO8859-2/books/handbook/audit/Makefile b/pl_PL.ISO8859-2/books/handbook/audit/Makefile new file mode 100644 index 0000000000..84cb9b04ee --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/audit/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= audit/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/audit/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/audit/chapter.sgml new file mode 100644 index 0000000000..e2455e6a3a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/audit/chapter.sgml @@ -0,0 +1,570 @@ + + + + + + + + + Tom + Rhodes + Written by + + + + + Security Event Auditing + + + Synopsis + + AUDIT + + Security Event Auditing + MAC + + + The &os; 7-CURRENT development branch includes + support for Event Auditing based on the &posix;.1e draft and + Sun's published BSM API and file format. + Event auditing permits the selective logging of security-relevant + system events for the purposes of post-mortem analysis, system + monitoring, and intrusion detection. After some settling time in + &os; 7-CURRENT, this support will be merged to &os; 6-STABLE + and appear in subsequent releases. + + + The audit facility in FreeBSD is considered experimental, and + production deployment should occur only after careful consideration + of the risks of deploying experimental software. + + + This chapter will focus mainly on the installation and + configuration of Event Auditing. Explanation of audit policies, + and an example configuration will be provided for the + convenience of the reader. + + After reading this chapter, you will know: + + + + What Event Auditing is and how it works. + + + + How to configure Event Auditing on &os; for users + and processes. + + + + Before reading this chapter, you should: + + + + Understand &unix; and &os; basics + (). + + + + Be familiar with the basics of kernel + configuration/compilation + (). + + + + Have some familiarity with security and how it + pertains to &os; (). + + + + + Event auditing can generate a great deal of log file + data, exceeding gigabytes a week in some configurations. An + administrator should read this chapter in its entirety to avoid + possible self-inflicted DoS attacks due to + improper configuration. + + + The implementation of Event Auditing in &os; is similar to + that of the &sun; Basic Security Module, or BSM + library. Thus, the configuration is almost completely + interchangeable with &solaris; and Mac OS X/Darwin operating + systems. + + + + Key Terms - Words to Know + + Before reading this chapter, a few key terms must be + explained. This is intended to clear up any confusion that + may occur and to avoid the abrupt introduction of new terms + and information. + + + + event: An auditable event is + an event that can be logged using the audit subsystem. The + administrator can configure which events will be audited. + Examples of security-relevant events include the creation of + a file, the building of a network connection, or the logging + in of a user. Events are either attributable, + meaning that they can be traced back to a user + authentication, or non-attributable. Examples + of non-attributable events are any events that occur before + authentication has succeeded in the login process, such as + failed authentication attempts. + + + + class: Events may be assigned to + one or more classes, usually based on the general category + of the events, such as file creation, + file access, or network. Login + and logout events are assigned to the lo + class. The use of classes allows the administrator to + specify high level auditing rules without having to specify + whether each individual auditable operation will be logged. + + + + record: A record is a log entry + describing a security event. Records typically have a + record event type, information on the subject (user) associated + with the event, time information, information on any objects, + such as files, and information on whether the event corresponded + to a successful operation. + + + + trail: An audit trail, or log file, + consists of a series of audit records describing security + events. Typically, trails are in roughly chronological + order with respect to the time events completed. Only + authorized processes are allowed to commit records to the + audit trail. + + + prefix: A prefix is considered to + be the configuration element used to toggle auditing for + success and failed events. + + + + + + Installing Audit Support + + Support for Event Auditing is installed with + the normal installworld process. An + administrator may confirm this by viewing the contents + of /etc/security. Files + beginning with the word audit should be present. + For example, audit_event. + + In-kernel support for the framework must also exist. This + may be done by adding the following lines to the local kernel + configuration file: + + options AUDIT + + Rebuild and reinstall + the kernel via the normal process explained in + . + + Once completed, enable the audit daemon by adding the + following line to &man.rc.conf.5;: + + auditd_enable="YES" + + Functionality not provided by the default may be added + here with the option. + + + + Audit Configuration + + All configuration files for security audit are found in + /etc/security. The following + files must be present before the audit daemon is started: + + + + audit_class - Contains the + definitions of the audit classes. + + + + audit_control - Controls aspects + of the audit subsystem, such as default audit classes, + minimum disk space to leave on the audit log volume, + etc. + + + + audit_event - Defines the kernel + audit events. These map, mostly, to system calls. + + + + audit_user - The events to audit + for individual users. Users not appearing here will be + subject to the default configuration in the control + configuration file. + + + + audit_warn - A shell script + used by auditd to generate warning messages in + exceptional situations, such as when space for audit + records is running low. + + + + + Audit File Syntax + + The configuration file syntax is rather arcane, albeit easy + to work with. One thing an administrator must be leery about + is overriding system defaults. This could create potential + openings for audit data to not be collected properly. + + The audit subsystem will accept both the short name and + long name with regards to configuration syntax. A syntax + map has been included below. + + The following list contains all supported audit + classes: + + + + - all - All + audit flags set. + + + + - administrative + - Administrative actions performed on the system as a + whole. + + + + - application - + Application defined action. + + + + - file_close - + Audit calls to the close system + call. + + + + - exec - Audit + program or utility execution. + + + + - file_attr_acc + - Audit the access of object attributes such as + &man.stat.1;, &man.pathconf.2; and similar events. + + + + - file_creation + - Audit events where a file is created as a result. + + + + - file_deletion + - Audit events where file deletion occurs. + + + + - file_attr_mod + - Audit events where file attribute modification occurs, + such as &man.chown.8;, &man.chflags.1;, &man.flock.2;, + etc. + + + + - file_read + - Audit events in which data is read, files are opened for + reading, etc. + + + + - file_write - + Audit events in which data is written, files are written + or modified, etc. + + + + - ioctl - Audit + use of the &man.ioctl.2; system call. + + + + - ipc - Audit + various forms of Inter-Process Communication, including POSIX + pipes and System V IPC operations. + + + + - login_logout - + Audit &man.login.1; and &man.logout.1; events occurring + on the system. + + + + - non_attrib - + Audit non-attributable events. + + + + - no_class - + Null class used to disable event auditing. + + + + - network - + Audit events related to network actions, such as + &man.connect.2; and &man.accept.2;. + + + + - other - + Audit miscellaneous events. + + + + - process - + Audit process operations, such as &man.exec.3; and + &man.exit.3;. + + + + Following is a list of all supported audit prefixes: + + + + none - Audit both the success + or failure of an event. For example, just listing a + class will result in the auditing of both success and + failure. + + + + + - Audit successful events + only. + + + + - - Audit failed events + only. + + + + + Using the class with either the + positive or negative prefix can generate a large amount + of data at an extremely rapid rate. + + + Extra prefixes used to modify the default configuration + values: + + + + ^- - Disable auditing of failed events. + + + + ^+ - Enable auditing of successful events. + + + + ^ - Disable auditing of both successful and failed + events. + + + + + + Configuration Files + + In most cases, administrators will need to modify only two files + when configuring the audit system: audit_control + and audit_user. The first controls system-wide + audit paramaters and defaults for both attributable and + non-attributable events. The second may be used to tune the level + and nature of auditing for individual users. + + + The <filename>audit_control</filename> File + + The audit_control file contains some basic + defaults that the administrator may wish to modify. Perhaps + even set some new ones. Viewing the contents of this file, + we see the following: + + dir:/var/audit +flags:lo +minfree:20 +naflags:lo + + The option is used to set the default + directory where audit logs are stored. Audit is frequently + configured so that audit logs are stored on a dedicated file + system, so as to prevent interference between the audit + subsystem and other subsystems when file systems become full. + + + The option is used to set the + system-wide defaults. The current setting, + configures the auditing of all &man.login.1; and &man.logout.1; + actions. A more complex example, + audits all system + &man.login.1; and &man.logout.1; actions, all administrator + actions, all failed events in the system, and finally disables + auditing of failed attempts for , + , and . Even though + the turned on the auditing of all + failed attempts, the prefix will override + that for the latter options. + + Notice that the previous paragraph shows the file is + read from left to right. As such, values further on the + right side may override a previous value specified to + its left. + + The option defines the minimum + percentage of free space for audit file systems. This + relates to the file system where audit logs are stored. + For example, if the specifies + /var/audit and + is set to twenty (20), warning + messages will be generated when the + /var file system grows + to eighty (80) percent full. + + The option specifies audit + classes to be audited for non-attributed events — + that is, events for which there is no authenticated user. + + + + + The <filename>audit_user</filename> File + + The audit_user file permits the + administrator to determine which classes of audit events + should be logged for which system users. + + The following is the defaults currently placed in + the audit_user file: + + root:lo:no +audit:fc:no + + Notice how the default is to audit all cases of + login/logout + and disable auditing of all other actions for + root. This configuration + also audits all file creation and disables all + other auditing for the audit + user. While event auditing does not require a special + user exist, some configurations, specifically environments + making use of MAC, may require it. + + + + + + Event Audit Administration + + Events written by the kernel audit subsystem cannot + be altered or read in plain text. Data is stored and accessed + in a method similar to that of &man.ktrace.1; and &man.kdump.1;, + that is, they may only be viewed by dumping them using the + praudit command; audit trails may be reduced + using the auditreduce command, which selects + records from an audit trail based on properties of interest, such + as the user, time of the event, and type of operation. + + For example, the praudit utility will dump the + entire contents of a specified audit log in plain text. To dump an + audit log in its entirety, use: + + &prompt.root; praudit /var/audit/AUDITFILE + + Where AUDITFILE is the audit log + of viewing choice. Since audit logs may contain enormous + amounts of data, an administrator may prefer to select records + for specific users. This is made possible with the following + command, where trhodes is the user of + choice: + + &prompt.root; auditreduce -e trhodes /var/audit/AUDITFILE | praudit + + This will select all audit records produced by the user + trhodes stored in the + AUDITFILE file. + + There are several other options available for reading audit + records, see the aforementioned command's manual pages for + a more in depth explanation. + + + Rotating Audit Log Files + + Due to log reliability requirements, audit trails + are written to only by the kernel, and managed only by + auditd. Administrators should not + attempt to use &man.newsyslog.conf.5; or other tools to + directly rotate audit logs. Instead, the audit + management tool should be used to shut down auditing, + reconfigure the audit system, and perform log rotation. + The following command causes the audit daemon to create a + new audit log and signal the kernel to switch to using the + new log. The old log will be terminated and renamed, at + which point it may then be manipulated by the administrator. + + &prompt.root; audit -n + + + If the auditd daemon is not currently + running, the previous command will fail and an error message + will be produced. + + + Adding the following line to + /etc/crontab will force the rotation + every twelve hours from &man.cron.8;: + + * */12 * * * root /usr/sbin/audit -n + + The change will take effect once you have saved the + new /etc/crontab. + + + + Delegating Audit Review Rights + + By default, only the root user has the right to read system audit + logs. However, that right may be delegated to members of the + audit group, as the audit directory and audit + trail files are assigned to that group, and made group-readable. As + the ability to track audit log contents provides significant insight + into the behavior of users and processes, it is recommended that the + delegation of audit review rights be performed with caution. + + + diff --git a/pl_PL.ISO8859-2/books/handbook/basics/Makefile b/pl_PL.ISO8859-2/books/handbook/basics/Makefile new file mode 100644 index 0000000000..fea6942368 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= basics/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/basics/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/basics/chapter.sgml new file mode 100644 index 0000000000..95ab39cf42 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/chapter.sgml @@ -0,0 +1,2585 @@ + + + + + + + Chris + Shumway + Rozdzia³ na nowo napisa³ + + + + + + Micha³ + Wojciechowski + T³umaczy³ + + + + + Podstawy Uniksa + + + Strzeszczenie + + W niniejszym rozdziale omówione zostan± podstawowe polecenia + i mo¿liwo¶ci systemu operacyjnego FreeBSD. Wiele informacji dotyczyæ + bêdzie ogó³em systemów typu &unix;. Czytelnikom zaznajomionym z t± + tematyk± w zupe³no¶ci wystarczy pobie¿ne przejrzenie rozdzia³u. + Natomiast ci, którzy dopiero rozpoczynaj± swoj± przygodê z FreeBSD, + powinni przeczytaæ go bardzo uwa¿nie. + + Po przeczytaniu tego rozdzia³u bêdziemy wiedzieæ: + + + + Jak korzystaæ z konsol wirtualnych FreeBSD. + + + Jak dzia³aj± prawa dostêpu do plików i flagi plików we &os;. + + + Jaki jest domy¶lny uk³ad systemu plików &os;. + + + Jaka jest organizacja dysku we &os;. + + + Jak montowaæ i odmontowywaæ systemy plików. + + + Czym s± procesy, demony i sygna³y. + + + Co to jest pow³oka, oraz jak mo¿na zmieniæ w³asne ¶rodowisko pracy. + + + Jak pos³ugiwaæ siê prostymi edytorami tekstu. + + + Jaki jest zwi±zek pomiêdzy urz±dzeniami i plikami wêz³owymi urz±dzeñ. + + + Jaki format binarny jest wykorzystywany we &os;. + + + W jaki sposób korzystaæ z dokumentacji systemowej w poszukiwaniu dodatkowych informacji. + + + + + + + Konsole wirtualne i terminale + konsole wirtualne + terminale + + Z systemu FreeBSD korzystaæ mo¿na na ró¿ne sposoby; jednym z + nich jest wpisywanie poleceñ w terminalu tekstowym. Wiêkszo¶æ + systemów operacyjnych typu &unix; dostêpna jest w³a¶nie poprzez polecenia. + W niniejszej czê¶ci dowiemy siê, czym s± terminale i + konsole, oraz jak siê nimi pos³ugiwaæ we FreeBSD. + + + Konsola + konsola + + Je¶li konfiguruj±c FreeBSD nie wybrali¶my, by przy + uruchamianiu systemu by³o automatycznie ³adowane ¶rodowisko + graficzne, to po uruchomieniu i wykonaniu skryptów startowych + system przywita nas komunikatem logowania siê do systemu. + Zobaczymy mniej wiêcej co¶ takiego: + + Additional ABI support:. +Local package initialization:. +Additional TCP options:. + +Fri Sep 20 13:01:06 EEST 2002 + +FreeBSD/i386 (pc3.example.org) (ttyv0) + +login: + + Na ró¿nych komputerach komunikat ten mo¿e wygl±daæ nieco inaczej, + jednak z pewno¶ci± bêdzie podobny. W tej chwili interesuj± nas jego dwa + ostatnie wiersze. Wiersz drugi od koñca ma postaæ: + + FreeBSD/i386 (pc3.example.org) (ttyv0) + + Widaæ tu kilka informacji o systemie, który w³a¶nie zosta³ + uruchomiony. Mamy przed oczami konsolê FreeBSD, + dzia³aj±c± na komputerze z procesorem firmy Intel (lub kompatybilnym) + z rodziny x86 + Takie jest znaczenie symbolu i386. Zwróæmy + uwagê, ¿e nawet wówczas, gdy FreeBSD dzia³a na procesorze Intela + innym ni¿ 386, w tym miejscu znajdzie siê napis i386. + Nie okre¶la on bowiem typu u¿ywanego procesora, lecz jego + architekturê. + . Komputer ten zosta³ nazwany (ka¿dy komputer uniksowy + ma nazwê) pc3.example.org i w tej chwili widoczna + jest jego konsola systemowa — terminal + ttyv0. + + Ostatni wiersz ma zawsze tak± postaæ: + + login: + + Tu wpisujemy nazwê u¿ytkownika, by zalogowaæ + siê do systemu. Opis tej czynno¶ci przedstawiony jest w kolejnej + czê¶ci. + + + + Logowanie siê do FreeBSD + + FreeBSD jest systemem wielou¿ytkownikowym i wielozadaniowym. + Tak oficjalnie okre¶la siê system, z którego na jednym komputerze + mo¿e korzystaæ wiele ró¿nych osób, uruchamiaj±c jednocze¶nie wiele + programów. + + Ka¿dy system wielou¿ytkownikowy musi mieæ mo¿liwo¶æ + odró¿nienia jednego u¿ytkownika od pozosta³ych. + FreeBSD (i wszystkie systemy uniksopodobne) wymaga, aby u¿ytkownik + zalogowa³ siê do systemu, zanim bêdzie móg³ + uruchamiaæ programy. Ka¿dy u¿ytkownik ma niepowtarzaln± nazwê + (nazwê u¿ytkownika) oraz sobie tylko znany klucz + (has³o). FreeBSD wymaga wpisania jednego i drugiego, + zanim zezwoli u¿ytkownikowi na uruchamianie jakichkolwiek + programów. + + skrypty startowe + Zaraz po za³adowaniu systemu i zakoñczeniu uruchamiania + skryptów startowych + Skrypty startowe to programy uruchamiane automatycznie + podczas ³adowania FreeBSD. Ich podstawowym zadaniem jest + przygotowanie ¶rodowiska pracy dla innych programów, oraz + uruchomienie wybranych us³ug dzia³aj±cych w tle, pe³ni±cych + ró¿ne przydatne funkcje. + , FreeBSD wy¶wietli komunikat z pro¶b± o podanie nazwy + u¿ytkownika: + + login: + + Dla przyk³adu za³ó¿my, ¿e nasz u¿ytkownik nazywa siê + janek. Wpisujemy tutaj janek + i naciskamy Enter. Powinni¶my zostaæ poproszeni + o podanie has³a: + + login: janek +Password: + + Nastêpnie wpisujemy has³o janka, i naciskamy + Enter. Has³o nie pojawia siê! + Na razie nie bêdziemy siê tym zajmowaæ. Wystarczy wiedzieæ, ¿e dzieje + siê tak ze wzglêdów bezpieczeñstwa. + + Je¶li podali¶my prawid³owe has³o, powinni¶my byæ ju¿ zalogowani + do FreeBSD, i gotowi do eksperymentowania z dostêpnymi poleceniami. + + Powinni¶my zobaczyæ wiadomo¶æ dnia (ang. message of the day + MOTD) oraz znak zachêty (#, + $ b±d¼ %). Oznacza to, ¿e + uda³o nam siê zalogowaæ do FreeBSD. + + + + Konsole wirtualne + + Polecenia uniksowe mo¿na z powodzeniem wpisywaæ na jednej konsoli, + jednak FreeBSD potrafi wykonywaæ wiele programów jednocze¶nie. + Korzystanie z jednej konsoli do wydawania poleceñ zakrawa na marnotrawstwo, + poniewa¿ system zdolny jest obs³u¿yæ w jednej chwili ca³e mnóstwo programów. + W wykorzystaniu tej mo¿liwo¶ci bardzo pomocne s± konsole + wirtualne. + + Konfiguruj±c FreeBSD mo¿emy uaktywniæ wiele konsol wirtualnych. + Z dowolnej z nich mo¿emy siê prze³±czyæ na inn± naciskaj±c odpowiedni± + kombinacjê klawiszy. Ka¿da konsola ma w³asny kana³ wyj¶ciowy, FreeBSD + zajmuje siê odpowiednim przekazywaniem informacji wprowadzanych z + klawiatury i wypisywanych na ekranie, gdy dochodzi do prze³±czenia + konsoli na inn±. + + Pewne kombinacje klawiszy u¿ywane s± do przechodzenia miêdzy + konsolami + Szczegó³owy opis obecnych we FreeBSD sterowników konsoli + i klawiatury mo¿na znale¼æ w dokumentacji systemowej + &man.syscons.4;, &man.atkbd.4;, &man.vidcontrol.1; i &man.kbdcontrol.1;. + Nie bêdziemy tutaj zajmowaæ siê szczegó³ami, zainteresowani + czytelnicy s± jak najbardziej zachêcani do zapoznania siê z + dokumentacj± systemow±, w której omawiane teraz zagadnienia opisane + s± dok³adniej. + . Kombinacje + AltF1, + AltF2, a¿ do + AltF8 s³u¿± do + prze³±czania na kolejn± konsolê wirtualn±. + + Przechodz±c z jednej konsoli na inn±, FreeBSD zajmuje siê + zachowaniem i odtworzeniem wygl±du ekranu. W efekcie otrzymujemy + z³udzenie posiadania wielu wirtualnych + ekranów i klawiatur, które mog± s³u¿yæ do wydawania poleceñ systemowi + FreeBSD. Programy uruchomione na jednej z konsol nie przerywaj± swej + pracy, gdy ta konsola przestaje byæ widoczna — po przej¶ciu na + inn± konsolê wirtualn± programy kontynuuj± swoje dzia³anie. + + + + Plik <filename>/etc/ttys</filename> + + Zgodnie z domy¶ln± konfiguracj± FreeBSD uruchamia osiem konsol + wirtualnych. Nie jest to jednak permanentne ustawienie, i mo¿e + byæ w ³atwy sposób zmienione, aby konsol wirtualnych by³o wiêcej + lub mniej. Plik /etc/ttys odpowiedzialny jest + za liczbê konsol wirtualnych i ich konfiguracjê. + + Modyfikuj±c plik /etc/ttys mo¿emy zmieniaæ + konfiguracjê konsol wirtualnych FreeBSD. Ka¿dy nie bêd±cy komentarzem + wiersz tego pliku (czyli wiersz nie rozpoczynaj±cy siê znakiem + #) zawiera ustawienia jednego z terminali lub + konsoli wirtualnej. W domy¶lnej wersji tego pliku wystêpuj±cej + we FreeBSD skonfigurowanych jest 9 konsol wirtualnych, przy czym 8 + z nich jest w³±czonych. Za ich konfiguracjê odpowiadaj± wiersze + rozpoczynaj±ce siê symbolem ttyv: + + # name getty type status comments +# +ttyv0 "/usr/libexec/getty Pc" cons25 on secure +# Virtual terminals +ttyv1 "/usr/libexec/getty Pc" cons25 on secure +ttyv2 "/usr/libexec/getty Pc" cons25 on secure +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/X11R6/bin/xdm -nodaemon" xterm off secure + + Dok³adny opis poszczególnych kolumn tego pliku i opcji, + za pomoc± których konfiguruje siê konsole wirtualne, znale¼æ + mo¿na w dokumentacji systemowej &man.ttys.5;. + + + + Konsola trybu jednego u¿ytkownika + + Tryb jednego u¿ytkownika szczegó³owo + opisuje . Istotne jest, ¿e w trybie + jednego u¿ytkownika dostêpna jest tylko jedna konsola. Nie jest + mo¿liwe korzystanie z konsol wirtualnych. Konfiguracja konsoli + trybu jednego u¿ytkownika równie¿ znajduje siê w pliku + /etc/ttys. Odpowiada jej wiersz rozpoczynaj±cy + siê s³owem console: + + # name getty type status comments +# +# If console is marked "insecure", then init will ask for the root password +# when going to single-user mode. +console none unknown off secure + + + Zgodnie z informacj± zawart± w komentarzu nad wierszem + console, wiersz ten mo¿na zmodyfikowaæ, + zmieniaj±c parametr secure na + insecure. Je¶li tak zrobimy, FreeBSD + po uruchomieniu w trybie jednego u¿ytkownika bêdzie pytaæ + o has³o u¿ytkownika root. + + Zachowajmy jednak ostro¿no¶æ, je¶li wpisujemy tu + insecure. Je¿eli zdarzy siê nam + zapomnieæ has³a u¿ytkownika root, mo¿e + okazaæ siê potrzebne uruchomienie trybu jednego u¿ytkownika. + Bêdzie to nadal mo¿liwe, mo¿e jednak byæ nieco trudne dla osób + nie orientuj±cych siê w procesie uruchamiania FreeBSD i + uczestnicz±cych w nim programach. + + + + + + Prawa dostêpu + UNIX + + FreeBSD, bêd±c bezpo¶rednim potomkiem systemu &unix; BSD, + oparte jest na kilku kluczowych za³o¿eniach Uniksa. Najbardziej + widocznym z nich jest fakt, ¿e FreeBSD jest systemem wielou¿ytkownikowym + — potrafi jednocze¶nie obs³ugiwaæ wielu u¿ytkowników pracuj±cych + niezale¿nie od siebie. System jest odpowiedzialny za w³a¶ciwe zarz±dzanie + odwo³aniami do sprzêtu, pamiêci i czasu procesora, po równo dla ka¿dego + z u¿ytkowników. + + Ze wzglêdu na obs³ugê wielu u¿ytkowników, zasoby, którymi + zarz±dza system, maj± przypisane prawa dostêpu okre¶laj±ce, kto + mo¿e czytaæ, zapisywaæ i uruchamiaæ dany zasób. Prawa dostêpu + przechowywane s± w postaci dwóch oktetów podzielonych na trzy czê¶ci, + z których pierwsza odnosi sie do w³a¶ciciela pliku, druga do + grupy posiadaj±cej plik, a trzecia do innych u¿ytkowników. + W postaci numerycznej zapisuje siê to nastêpuj±co: + + permissions + + file permissions + + + + + + Warto¶æ + Uprawnienia + Symbol + + + + + + 0 + Odczyt: nie, zapis: nie, wykonywanie: nie + --- + + + + 1 + Odczyt: nie, zapis: nie, wykonywanie: tak + --x + + + + 2 + Odczyt: nie, zapis: tak, wykonywanie: nie + -w- + + + + 3 + Odczyt: nie, zapis: tak, wykonywanie: tak + -wx + + + + 4 + Odczyt: tak, zapis: nie, wykonywanie: nie + r-- + + + + 5 + Odczyt: tak, zapis: nie, wykonywanie: tak + r-x + + + + 6 + Odczyt: tak, zapis: tak, wykonywanie: nie + rw- + + + + 7 + Odczyt: tak, zapis: tak, wykonywanie: tak + rwx + + + + + + ls + + katalogi + + Korzystaj±c z polecenia &man.ls.1; mo¿emy pos³u¿yæ siê opcj± + , by zawarto¶æ katalogu zosta³a pokazana + w formie szczegó³owej, z uwzglêdnieniem kolumny zawieraj±cej + informacjê o prawach dostêpu do pliku dla jego w³a¶ciciela, + grupy, oraz wszystkich innych. Przyk³adowy wynik polecenia + ls -l: + + &prompt.user; ls -l +total 530 +-rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile +-rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile +-rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt +... + + Pierwsza kolumna listy plików po wykonaniu polecenia + ls -l ma nastêpuj±c± postaæ: + + -rw-r--r-- + + Pierwszy znak (od lewej) okre¶la, czy plik jest + zwyczajnym plikiem, katalogiem, urz±dzeniem znakowym, + gniazdem, czy jakimkolwiek innym urz±dzeniem pseudo-plikowym. + Widoczny w przyk³adzie znak - oznacza + zwyk³y plik. Kolejne trzy znaki, w przyk³adzie s± to + rw-, reprezentuj± prawa dostêpu, którymi + dysponuje w³a¶ciciel pliku. Nastêpne trzy znaki r--, + okre¶laj± prawa dostêpu grupy, do której nale¿y plik. Ostatnia trójka + r--, oznacza prawa dostêpu dla innych. Minus + oznacza brak jednego z praw dostêpu. Plik przedstawiony w + przyk³adzie mo¿e byæ wiêc odczytywany i zapisywany przez swojego + w³a¶ciciela, oraz jedynie odczytywany przez grupê i innych. + Zgodnie z powy¿sz± tabel±, prawa dostêpu do tego pliku maj± + warto¶æ 644, przy czym ka¿da cyfra reprezentuje + trzy czê¶ci uprawnieñ. + + W porz±dku, ale w jaki sposób system kontroluje dostêp + do urz±dzeñ? Zasadniczo wiêkszo¶æ urz±dzeñ jest traktowana + przez FreeBSD jak pliki, które mog± byæ otwierane, odczytywane + i zapisywane podobnie jak wszystkie inne pliki. Specjalne pliki + urz±dzeñ przechowywane s± w katalogu + /dev. + + Równie¿ katalogi traktowane s± jak pliki — te¿ s± + im przypisywane prawa odczytu, zapisu i wykonania. Bit wykonania + katalogu ma nieco inne znaczenie ni¿ w przypadku pliku. + Posiadanie prawa wykonania katalogu oznacza, ¿e mo¿na do niego + wej¶æ, czyli pos³u¿yæ siê poleceniem cd. + Ponadto umo¿liwia to dostêp do zawartych w katalogu plików + o znanych nazwach (oczywi¶cie obowi±zuj± tak¿e indywidualne + prawa dostêpu do ka¿dego z plików). + + W szczególno¶ci, wy¶wietlenie listy plików katalogu wymaga + posiadania prawa do jego odczytu, natomiast do usuniêcia pliku + o znanej nazwie potrzebne bêd± prawa do zapisu i + wykonania dla katalogu, w którym ów plik siê znajduje. + + Jest jeszcze kilka innych bitów uprawnieñ, jednak s± one + stosowane w specjalnych przypadkach, np. do w³±czenia atrybutu + SUID, lub lepkiego bitu dla katlogu. Wiêcej + informacji o prawach dostêpu i o ich przydzielaniu mo¿na + znale¼æ w dokumentacji systemowej polecenia &man.chmod.1;. + + + + + + Tom + Rhodes + Napisa³ + + + + + Cezary + Morga + T³umaczy³ + + + + + Uprawnienia symboliczne + uprawnieniasymboliczne + + Uprawnienia symboliczne, okre¶lane równie¿ jako wyra¿enia symboliczne, + przy okre¶laniu praw dostêpu do plików lub katalogów wykorzystuj± + litery w miejsce warto¶ci liczbowych. Wyra¿enia symboliczne wykorzystuj± + sk³adniê: (kto) (akcja) (uprawnienia), przy czym dostêpne s± nastêpuj±ce + warto¶ci: + + + + + + Opcja + Litera + Znaczenie + + + + + + (kto) + u + U¿ytkownik (w³a¶ciciel) + + + + (kto) + g + Grupa + + + + (kto) + o + Inni + + + + (kto) + a + Wszyscy (¶wiat) + + + + (akcja) + + + Dodanie uprawnieñ + + + + (akcja) + - + Usuniêcie uprawnieñ + + + + (akcja) + = + Ustawienie uprawnieñ + + + + (uprawnienia) + r + Odczyt + + + + (uprawnienia) + w + Zapis + + + + (uprawnienia) + x + Wykonywanie + + + + (uprawnienia) + t + Bit lepki + + + + (uprawnienia) + s + Ustawienie UID lub GID + + + + + + Do ustawienia tych warto¶ci, podobnie jak w przypadku + warto¶ci liczbowych, wykorzystywane jest polecenie + &man.chmod.1;. Przyk³adowo, by zablokowaæ dostêp + innych u¿ytkowników do PLIKU + nale¿y wpisaæ: + + &prompt.user; chmod go= PLIK + + Gdy musimy wykonaæ wiêcej ni¿ jedn± zmianê uprawnieñ + parametry nale¿y oddzieliæ przecinkami. Na przyk³ad, + poni¿sze polecenie usunie prawa zapisu do + PLIKU grupie i innym. + Nastêpnie doda wszystkim prawo wykonywania: + + &prompt.user; chmod go-w,a+x PLIK + + + + + + + + + Tom + Rhodes + Napisa³ + + + + + Cezary + Morga + T³umaczy³ + + + + + Flagi plików we &os; + + Dodatkowo, oprócz opisanych wy¿ej praw dostêpu, + &os; wykorzystuje równie¿ flagi plików. + Flagi te umo¿liwiaj± wprowadzenie dodatkowego poziomu + ochrony i kontroli plików. Nie dotycz± natomiast + katalogów. + + Dziêki zwiêkszonemu poziomowi kontroli plików + system mo¿e zagwarantowaæ, ¿e w niektórych sytuacjach + nawet u¿ytkownik root nie bêdzie + móg³ usun±æ b±d¼ zmodyfikowaæ plików. + + Zmiany flag plików dokonuje siê poleceniem &man.chflags.1;. + Przyk³adowo, by plikowi plik1 nadaæ flagê + nieusuwalno¶ci nale¿y wydaæ poni¿esz polecenie: + + &prompt.root; chflags sunlink plik1 + + Natomiast, by usun±æ flagê nieusuwalno¶ci + wystarczy wprowadziæ takie samo polecenie dodaj±c + no przed : + + &prompt.root; chflags nosunlink plik1 + + By wy¶wietliæ flagi danego pliku wystarczy wpisaæ + polecenie &man.ls.1; z parametrem : + + &prompt.root; ls -lo plik1 + + + Wynik powinien byæ zbli¿ony do poni¿szego: + + -rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 plik1 + + Niektóre z flag mog± byæ dodawane i usuwane jedynie przez + u¿ytkownika root, podczas gdy inne mog± + byæ ustawiane równie¿ przez w³a¶ciciela pliku. Zaleca siê aby + administratorzy przeczytali strony podrêcznika systemowego + &man.chflags.1; oraz &man.chflags.2;. + + + + + Struktura katalogów + hierarchia katalogów + + Poznanie hierarchii katalogów FreeBSD jest podstaw± + ogólnego zrozumienia dzia³ania systemu. Najwa¿niejszym + zagadnieniem jest koncepcja katalogu g³ównego, /. + Jest on montowany jako pierwszy podczas uruchamiania systemu + i zawiera podstawowe pliki niezbêdne do przygotowania + systemu do pracy w trybie wielou¿ytkownikowym. Ponadto + w katalogu g³ównym znajduj± siê punkty montowania innych + systemów plików, które mo¿emy montowaæ. + + Punktem montowania nazywany jest katalog, poprzez + który inny system plików mo¿e byæ do³±czony do g³ównego + systemu plików. + zawiera wiêcej informacji. Przyk³adem typowego punktu + montowania mo¿e byæ + /usr, /var, + /tmp, /mnt + oraz /cdrom. Najczê¶ciej ka¿demu + z takich katalogów odpowiada wpis w pliku + /etc/fstab. Plik ten zawiera tabelê + systemów plików i ich punktów montowania, z której korzysta + system. Wiêkszo¶æ systemów plików wymienionych w + /etc/fstab jest montowana automatycznie + przez skrypt &man.rc.8; podczas uruchamiania systemu, + wyj±tkiem s± te wpisy, które maj± opcjê . + zawiera wiêcej informacji. + + Pe³ny opis struktury systemu plików znajduje siê w dokumentacji + systemowej &man.hier.7;. Tu ograniczymy siê do pobie¿nego + zapoznania siê z najwa¿niejszymi katalogami. + + + + + + + Katalog + Opis + + + + + / + G³ówny katalog systemu plików. + + + + /bin/ + Programy u¿ytkowe wykorzystywane zarówno w trybie + jednego u¿ytkownika, jak i w trybie wielu u¿ytkowników. + + + + /boot/ + Programy i pliki konfiguracyjne u¿ywane podczas + uruchamiania systemu. + + + + /boot/defaults/ + Pliki z domy¶ln± konfiguracj± uruchamiania systemu; patrz + &man.loader.conf.5;. + + + + /dev/ + Pliki urz±dzeñ; patrz &man.intro.4;. + + + + /etc/ + Pliki i skrypty konfiguracyjne. + + + + /etc/defaults/ + Pliki z domy¶ln± konfiguracj± systemu; patrz &man.rc.8;. + + + + /etc/mail/ + Pliki konfiguracyjne dla serwerów poczty, na przyk³ad + &man.sendmail.8;. + + + + /etc/namedb/ + Pliki konfigracyjne programu named; patrz + &man.named.8;. + + + + /etc/periodic/ + Skrypty uruchamiane raz dziennie, raz na tydzieñ i raz na miesi±c + za po¶rednictwem &man.cron.8;; patrz &man.periodic.8;. + + + + /etc/ppp/ + Pliki konfiguracyjne ppp; patrz + &man.ppp.8;. + + + + /mnt/ + Pusty katalog, najczê¶ciej wykorzystywany przez administratorów + jako tymczasowy punkt montowania.. + + + + /proc/ + System plików procesów, patrz &man.procfs.5;, + &man.mount.procfs.8;. + + + + /rescue/ + Katalog zawieraj±cy programy przydatne w przypadku awarii; patrz + &man.rescue.8;. + + + + /root/ + Katalog domowy u¿ytkownika root. + + + + /sbin/ + Programy i narzêdzia administracyjne wykorzystywane zarówno + w trybie jednego u¿ytkownika, jak i w trybie wielu u¿ytkowników. + + + + /stand/ + Programy u¿ywane w samodzielnym ¶rodowisku. + + + + + /tmp/ + Pliki tymczasowe. Zawarto¶æ katalogu + /tmp NIE JEST zachowywana + przy ponownym uruchamianiu systemu. Równie¿ pamiêciowy system + plików jest czêsto montowany w katalogu + /tmp. Proces ten mo¿e + zostaæ zautomatyzowany wykorzystuj±c zmienne &man.rc.conf.5; + zwi±zane z tmpmfs (b±dz za pomoc± wpisu w + /etc/fstab; patrz &man.mdmfs.8;). + + + + + /usr/ + Wiêkszo¶æ programów i aplikacji wykorzystywanych przez u¿ytkowników. + + + + /usr/bin/ + Najczê¶ciej u¿ywane programy, narzêdzia programistyczne, aplikacje. + + + + /usr/include/ + Pliki nag³ówkowe C. + + + + /usr/lib/ + Biblioteki. + + + + + /usr/libdata/ + Pliki danych ró¿nych programów u¿ytkowych. + + + + /usr/libexec/ + SDemony i programy systemowe (uruchamiane przez inne programy). + + + + /usr/local/ + + Lokalne programy, biblioteki, itp. Ponadto jest + to domy¶lny katalog dla instalowanych portów. Ogólna + struktura katalogów wewn±trz /usr/local + powinna odpowiadaæ strukturze /usr + opisanej w dokumentacji &man.hier.7;. Wyj±tkiem jest katalog + man, umieszczony bezpo¶rednio w /usr/local, + a nie w /usr/local/share, oraz dokumentacja + portów, znajduj±ca siê w + share/doc/port. + + + + + /usr/obj/ + Pliki zale¿ne od architektury komputera, tworzone w procesie + budowania drzewa /usr/src. + + + + /usr/ports + Kolekcja portów FreeBSD (opcjonalna). + + + + /usr/sbin/ + Demony i programy systemowe (dostêpne dla u¿ytkowników). + + + + /usr/share/ + Pliki niezale¿ne od architektury systemu. + + + + /usr/src/ + Pliki ¼ród³owe BSD, lokalne pliki ¼ród³owe. + + + + /usr/X11R6/ + Pliki wykonywalne, biblioteki, i inne pliki dystrybucji + X11R6 (opcjonalnie). + + + + /var/ + Rozmaite pliki dzienników systemowych, pliki tymczasowe, + pliki kolejek. Równie¿ pamiêciowy system plików jest czêsto + montowany w tym katalogu. Proces ten mo¿e zostaæ + zautomatyzowany wykorzystuj±c zmienne &man.rc.conf.5; zwi±zane + z varmfs (b±dz za pomoc± wpisu w /etc/fstab; + patrz &man.mdmfs.8;). + + + + + /var/log/ + Pliki dzienników systemowych. + + + + /var/mail/ + Skrzynki pocztowe u¿ytkowników. + + + + /var/spool/ + Katalogi kolejek systemu drukowania i poczty. + + + + /var/tmp/ + Pliki tymczasowe nie usuwane przy ponownym uruchamianiu + systemu. + + + + /var/yp + Mapy us³ugi NIS. + + + + + + + + + + + Organizacja dysku + + Najmniejsz± jednostk± organizacji dysku u¿ywan± przez FreeBSD + do odnajdywania plików jest nazwa pliku. W nazwach plików rozró¿niane + s± du¿e i ma³e litery, tak wiêc readme.txt + i README.TXT to dwa ró¿ne pliki. FreeBSD + nie wykorzystuje rozszerzeñ nazw plików (.txt) + do okre¶lenia, czy plik jest programem, dokumentem, czy innym + zbiorem danych. + + Pliki przechowywane s± w katalogach. Katalog mo¿e byæ pusty, + lub mo¿e zawieraæ setki plików. Mo¿e równie¿ zawieraæ inne katalogi, + dziêki czemu mamy mo¿liwo¶æ zbudowania hierarchicznej struktury + katalogów. Pozwala to na ³atw± organizacjê danych. + + Dostêp do plików i katalogów uzyskuje siê podaj±c nazwê pliku + lub katalogu, poprzedzon± uko¶nikiem / i innymi + wymaganymi nazwami katalogów. Je¶li mamy katalog foo, + a w nim katalog bar, w którym znajduje siê plik + readme.txt, wówczas pe³n± nazw±, b±d¼ ¶cie¿k± + dostêpu do pliku jest foo/bar/readme.txt. + + Katalogi i pliki przechowywane s± w systemie plików. Ka¿dy + system plików ma jeden katalog najwy¿szego poziomu, zwany katalogiem + g³ównym systemu plików. W katalogu g³ównym mog± byæ umieszczone + nastêpne katalogi. + + To, o czym mówimy, jest zapewne podobne do innych systemów operacyjnych, + z którymi byæ mo¿e zetknêli¶my siê wcze¶niej. S± jednak ró¿nice; na przyk³ad + w systemie &ms-dos; nazwy plików i katalogów oddzielane s± znakiem + \, w &macos; natomiast znakiem :. + + We FreeBSD nie s± u¿ywane litery dysków, lub inne nazwy dysków w + ¶cie¿ce. Nie spotkamy siê w FreeBSD z czym¶ takim jak + c:/foo/bar/readme.txt. + + Jest natomiast jeden system plików pe³ni±cy rolê g³ównego + systemu plików. Zawiera on katalog g³ówny dostêpny jako + /. Ka¿dy inny system plików jest montowany + w g³ownym systemie plików. Niezale¿nie od tego, ile dysków mamy w komputerze, + we FreeBSD ka¿dy katalog wydaje siê byæ czê¶ci± tego samego dysku. + + Za³ó¿my, ¿e mamy trzy systemy plików, nazwane A, + B i C. Ka¿dy z nich ma katalog + g³ówny, zawieraj±cy dwa katalogi o nazwach A1, + A2 (oraz odpowiednio + B1, B2 i + C1, C2). + + Niech A bêdzie g³ównym systemem plików. + Gdyby¶my sprawdzili jego zawarto¶æ poleceniem ls, + zobaczyliby¶my dwa podkatalogi A1 i + A2. Drzewo katalogów wygl±da nastêpuj±co: + + + + + + + + / + | + +--- A1 + | + `--- A2 + + + + System plików musi byæ montowany w katalogu innego systemu + plików. Przyjmijmy teraz, ¿e montujemy system plików B + w katalogu A1. G³ówny katalog B + zast±pi A1, a podkatalogi B + pojawi± siê w odpowiednim miejscu: + + + + + + + + / + | + +--- A1 + | | + | +--- B1 + | | + | `--- B2 + | + `--- A2 + + + + Do plików znajduj±cych siê w katalogach B1 + i B2 mo¿na siê dostaæ pos³uguj±c siê ¶cie¿k± + /A1/B1 lub /A1/B2. + Pliki poprzednio obecne w katalogu /A1 + s± tymczasowo ukryte. Pojawi± siê ponownie po + odmontowaniu + B z A. + + Gdyby zamontowaæ B w A2, + drzewo katalogów wygl±da³oby tak: + + + + + + + + / + | + +--- A1 + | + `--- A2 + | + +--- B1 + | + `--- B2 + + + + ¶cie¿ki natomiast mia³yby postaæ /A2/B1 + i /A2/B2. + + Systemy plików mog± byæ montowane jeden na drugim. Rozwijaj±c + poprzedni przyk³ad, mo¿emy zamontowaæ system plików C + w katalogu B1 systemu plików B, + otrzymuj±c nastêpuj±c± postaæ drzewa katalogów: + + + + + + + + / + | + +--- A1 + | + `--- A2 + | + +--- B1 + | | + | +--- C1 + | | + | `--- C2 + | + `--- B2 + + + + Mo¿na równie dobrze zamontowaæ C + bezpo¶rednio w systemie plików A, + w katalogu A1: + + + + + + + + / + | + +--- A1 + | | + | +--- C1 + | | + | `--- C2 + | + `--- A2 + | + +--- B1 + | + `--- B2 + + + + Znaj±cym system &ms-dos; mo¿e to przypominaæ polecenie + join, choæ nie jest to to samo. + + Zwykle nie trzeba zajmowaæ siê opisanymi powy¿ej rzeczami. + Najczê¶ciej tworzymy systemy plików podczas instalacji FreeBSD, + wybieramy miejsce ich zamontowania i nie wprowadzamy po¼niej + ¿adnych zmian, chyba, ¿e zainstalujemy nowy dysk. + + Mo¿na utworzyæ jeden obszerny g³ówny system plików + i nie tworzyæ ¿adnych innych. Takie podej¶cie ma kilka wad + i jedn± zaletê. + + + Korzy¶ci z kilku systemów plików + + + Odrêbne systemy plików mog± mieæ ró¿ne opcje + montowania (mount options). Na przyk³ad, przy + odpowiednim przygotowaniu, g³ówny system plików mo¿e byæ + zamontowany tylko do odczytu, przez co niemo¿liwe bêdzie + przypadkowe usuniêcie lub zmiana wa¿nego pliku. Oddzielenie + systemów plików dostêpnych do zapisu dla u¿ytkowników, jak + np. /home, od innych pozwala równie¿ + na montowanie ich z opcj± nosuid; + co z kolei pozwala zwiêkszyæ bezpieczeñstwo systemu + uniemo¿liwiaj±c wykorzystanie bitów + suid/guid. + + + + FreeBSD automatycznie optymalizuje uk³ad plików w systemie + plików, w zale¿no¶ci od tego, jak ów system jest wykorzystywany. + System plików zawieraj±cy wiele czêsto zapisywanych ma³ych plików + bêdzie optymalizowany inaczej ni¿ taki, w którym przechowywane + jest mniej plików o du¿ych rozmiarach. W przypadku jednego du¿ego + systemu plików taka optymalizacja nie zadzia³a. + + + + Systemy plików FreeBSD s± odporne na awarie zasilania. + W niesprzyjaj±cych okoliczno¶ciach mo¿e siê jednak zdarzyæ, + ¿e przerwa w dostawie pr±du w krytycznym momencie spowoduje + uszkodzenie struktury systemu plików. Przechowywanie danych + w kilku systemach plików zwiêksza szansê, ¿e system uruchomi + siê ponownie, dziêki czemu ³atwiej bêdzie odzyskaæ dane + z kopii zapasowej. + + + + + Korzy¶æ z pojedynczego systemu plików + + + Systemy plików maj± sta³y rozmiar. Podczas instalacji + FreeBSD tworzymy system plików o zadanym rozmiarze; pó¼niej + mo¿e siê okazaæ, ¿e trzeba powiêkszyæ partycjê. Nie³atwo + jest to zrobiæ inaczej, ni¿ przez przygotowanie zapasowej + kopii danych, utworzenie na nowo systemu plików o wiêkszych + rozmiarach, oraz skopiowanie danych z powrotem. + + + We &os; dostêpne jest polecenie &man.growfs.8;, + które pozwala na zwiêkszenie rozmiaru systemu plików + w locie, pomijaj±c wspomniane ograniczenie. + + + + + Systemy plików przechowywane s± na partycjach. Pojêcie + partycji ma tu inne znaczenie ni¿ popularnie stosowane (np. + partycja systemu &ms-dos;), ze wzglêdu na uniksowy rodowód + &os;. Ka¿da z partycji oznaczana jest liter±, od a + do h. Pojedyncza partycja mo¿e zawieraæ + jeden system plików, dlatego te¿ do systemów plików czêsto + odwo³uje siê albo poprzez miejsce ich zamontowania w g³ównym + systemie plików, albo przez literowe oznaczenie partycji, na + której dany system plików siê znajduje. + + Przestrzeñ dyskowa jest równie¿ u¿ywana we FreeBSD + jako przestrzeñ wymiany, pe³ni±c w + ten sposób rolê pamiêci wirtualnej. + Komputer mo¿e dziêki temu dysponowaæ wiêksz± ilo¶ci± pamiêci, + ni¿ ma w rzeczywisto¶ci. Kiedy pamiêci zaczyna brakowaæ, + FreeBSD odsy³a niektóre nieu¿ywane dane do przestrzeni + wymiany, a gdy znów oka¿± siê potrzebne, przenosi je z powrotem + (odsy³aj±c jednocze¶nie inne dane). + + Z niektórymi partycjami zwi±zane s± pewne konwencje + dotycz±ce ich zastosowania./para> + + + + + + + + + Patrycja + + Konwencja + + + + + + a + + Zwykle zawiera g³ówny system plików + + + + b + + Zwykle zawiera przestrzeñ wymiany + + + + c + + Zwykle jest tego samego rozmiaru, co obejmuj±cy + j± segment. Dziêki temu programy dzia³aj±ce na ca³ym + segmencie (na przyk³ad wykrywaj±ce uszkodzone obszary + dysku) mog± dzia³aæ na partycji c. + Zwykle nie tworzy siê na tej partycji systemu plików. + + + + d + + Swego czasu partycja d mia³a specjalne znaczenie, + obecnie ju¿ go nie ma. Do dzi¶ jednak niektóre programy + mog± dziwnie siê zachowywaæ, je¶li ka¿e im siê pracowaæ + na partycji d, dlatego te¿ + sysinstall + zwykle wogóle jej nie tworzy. + + + + + + Ka¿da partycja zawieraj±ca system plików przechowywana jest na czym¶, + co we FreeBSD nosi nazwê segmentu. Jest to okre¶lenie + tego, co wcze¶niej zwane by³o partycj±, i ponownie jest to konsekwencj± + uniksowych korzeni FreeBSD. Segmenty s± oznaczane liczbami od 1 do 4. + + segmenty + partycje + niebezpiecznie dedykowane + + Numery segmentów, wraz z przedrostkiem s, + poprzedzone s± nazw± urz±dzenia. Tak wiêc + da0s1 + jest pierwszym segmentem na pierwszym dysku SCSI. Na dysku mog± + byæ najwy¿ej cztery fizyczne segmenty, mo¿na jednak tworzyæ segmenty + logiczne wewn±trz segmentów fizycznych specjalnego typu. Powsta³e + w ten sposób segmenty rozszerzone maj± numery od 5 wzwy¿, zatem + ad0s5 odpowiada pierwszemu + rozszerzonemu segmentowi na dysku IDE. Urz±dzenia te s± wykorzystywane + przez systemy plików, które zajmuj± ca³y segment. + + Segmenty, dyski niebezpiecznie dedykowane + i inne dyski zawieraj± partycje, + oznaczane literami od a do h. + Litera dopisywana jest do nazwy urz±dzenia, wiêc + da0a odpowiadaæ bêdzie + partycji a na pierwszym dysku da, niebezpiecznie + dedykowanym. Z kolei ad1s3e + oznacza pi±t± partycjê w trzecim segmencie drugiego dysku IDE. + + W³asne oznaczenie ma tak¿e ka¿dy dysk. Nazwa dysku sk³ada siê + z symbolu okre¶laj±cego typ dysku, oraz numeru, okre¶laj±cego + który to dysk. Dyski, inaczej ni¿ segmenty, numerowane s± od zera. + zawiera najczê¶ciej spotykane zwykle + oznaczenia. + + Gdy odwo³ujemy siê do partycji, FreeBSD wymaga, by¶my podali + równie¿ nazwê obejmuj±cego j± segmentu i dysku. Z kolei gdy odwo³ujemy + siê do segmentu, podajemy równie¿ nazwê dysku. Kolejno podajemy wiêc + nazwê dysku, s, numer segmentu, a na koniec + literê partycji; patrz . + + pokazuje schematyczny + model dysku, z pomoc± którego ³atwiej bêdzie zrozumieæ pewne rzeczy. + + Gdy instalujemy FreeBSD, w pierwszej kolejno¶ci musimy przygotowaæ + segmenty na dysku, nastêpnie w segmencie przeznaczonym dla FreeBSD + utworzyæ partycje, nastêpnie wewn±trz partycji stworzyæ system plików + (lub przestrzeñ wymiany) i okre¶liæ miejsce jego montowania. + + + Oznaczenia dysków + + + + + + + + Oznaczenie + + Znaczenie + + + + + + ad + + Dysk ATAPI (IDE) + + + + da + + Dysk SCSI o dostêpie bezpo¶rednim + + + + acd + + CDROM ATAPI (IDE) + + + + cd + + CDROM SCSI + + + + fd + + Stacja dyskietek + + + +
+ + + Przyk³adowe nazwy dysków, segmentów i partycji + + + + + + + + + Nazwa + + Znaczenie + + + + + + ad0s1a + + Pierwsza partycja (a) + w pierwszym segmencie (s1) + na pierwszym dysku IDE (ad0). + + + + da1s2e + + Pi±ta partycja e w drugim + segmencie (s2) na drugim dysku + SCSI (da1). + + + + + + + + Schematyczny model dysku + + Rysunek przedstawia pierwszy dysk IDE z punktu widzenia + FreeBSD. Zak³adamy, ¿e dysk ma rozmiar 4 GB i jest podzielony + na dwa segmenty (partycje w &ms-dos;) o rozmiarze po 2 GB. + Pierwszy segment zawiera DOS-owy dysk C:, + natomiast w drugim segmencie znajduje siê przyk³adowa instalacja + FreeBSD, z trzema partycjami oraz partycj± wymiany. + + Ka¿da z trzech partycji przechowuje system plików. Na + partycji a umieszczony jest g³ówny system plików, + na e znajduje siê katalog /var, + a na f katalog /usr. + + + + + + + + .-----------------. --. +| | | +| DOS / Windows | | +: : > First slice, ad0s1 +: : | +| | | +:=================: ==: --. +| | | Partition a, mounted as / | +| | > referred to as ad0s2a | +| | | | +:-----------------: ==: | +| | | Partition b, used as swap | +| | > referred to as ad0s2b | +| | | | +:-----------------: ==: | Partition c, no +| | | Partition e, used as /var > file system, all +| | > referred to as ad0s2e | of FreeBSD slice, +| | | | ad0s2c +:-----------------: ==: | +| | | | +: : | Partition f, used as /usr | +: : > referred to as ad0s2f | +: : | | +| | | | +| | --' | +`-----------------' --' + + + + + + + + + Montowanie i odmontowywanie systemów plików + + System plików mo¿na sobie wyobraziæ jako drzewo, którego + korzeniem jest /. /dev, + /usr i inne podkatalogi katalogu g³ównego + s± ga³êziami, z których mog± wyrastaæ kolejne ga³êzie, na + przyk³ad /usr/local, itd. + + g³ówny system plików + Jest kilka powodów, dla których warto jest trzymaæ niektóre + katalogi w oddzielnych systemach plików. W katalogu + /var znajduj± siê podkatalogi + log/ i spool/ oraz rozmaite + pliki tymczasowe, z tego powodu mo¿e siê on zape³niæ. Zape³nienie + g³ównego systemu plików jest raczej niepo¿±dane, wiêc czêsto zaleca + siê oddzielenie /var od /. + + Czêsto niektóre katalogi umieszczane s± na odrêbnych systemach + plików ze wzglêdu na to, ¿e znajduj± siê na osobnych dyskach fizycznych + lub dyskach wirtualnych, jak na przyk³ad pliki udostêpniane poprzez + Network File System + lub napêdy CDROM. + + + Plik <filename>fstab</filename> + + file systems + mounted with fstab + + + Systemy plików wymienione w pliku /etc/fstab + s± automatycznie montowane podczas ³adowania + systemu (prócz oznaczonych opcj± )./para> + + Wpisy w pliku /etc/fstab s± nastêpuj±cej postaci: + + urz±dzenie /punkt-montowania typ opcje archiwizacja nr-przebiegu + + + + urz±dzenie + + Nazwa pliku urz±dzenia (istniej±cego), zgodnie z opisem w + . + + + + + punkt-montowania + + Katalog (istniej±cy), w którym system + plików ma byæ zamontowany. + + + + + typ + + Typ systemu plików przekazywany poleceniu + &man.mount.8;. We FreeBSD domy¶lnie jest to + ufs. + + + + + opcje + + Pierwsz± opcj± jest , je¶li + w systemie plików ma byæ mo¿liwy odczyt i zapis, albo + , je¿eli dozwolony ma byæ tylko odczyt. + W nastêpnej kolejno¶ci podawane s± inne opcje. Czêsto stosowana + jest opcja , która zapobiega automatycznemu + montowaniu systemu plików podczas uruchamiania systemu. + Pozosta³e opcje opisane s± w dokumentacji systemowej &man.mount.8;. + + + + + archiwizacja + + Na podstawie tej informacji program &man.dump.8; + stwierdza, które systemy plików maj± byæ archwizowane. Je¶li pole + to zostanie pominiête, domy¶lnie przyjmowana jest warto¶æ zero. + + + + + nr-przebiegu + + + Na podstawie tego pola wyznaczana jest kolejno¶æ, w jakiej + systemy plików poddawane s± sprawdzaniu. Systemy plików, które + nie maj± byæ sprawdzane, powinny mieæ nr-przebiegu + ustawiony na zero. G³ówny system plików (powinien byæ sprawdzony + jako pierwszy) powinien mieæ nr-przebiegu o warto¶ci + jeden, a inne systemy plików powinny mieæ wpisan± warto¶æ wiêksz± od + jednego. Je¶li dwa lub wiêcej systemów plików bêdzie mia³o taki sam + nr-przebiegu, wówczas &man.fsck.8;, o ile bêdzie + to mo¿liwe, podejmie próbê rownoleg³ego sprawdzenia tych systemów + plików. + + + + + Wiêcej informacji o formacie pliku /etc/fstab + oraz definiowanych w nim opcji dostêpnych w podrêczniku systemowym &man.fstab.5; + + + + Polecenie <command>mount</command> + + systemy plików + montowanie + + + Polecenie &man.mount.8; jest g³ównym poleceniem u¿ywanym + do montowania systemów plików. + + W najprostszej postaci, u¿ywa siê go nastêpuj±co: + + + &prompt.root; mount urz±dzenie punkt-montowania + + + Polecenie to ma mnóstwo opcji wymienionych w dokumentacji + systemowej &man.mount.8;. Do najczê¶ciej stosowanych nale¿±: + + + Opcje montowania + + + + + + Montowanie wszystkich systemów plików + wymienionych w /etc/fstab. + Nie s± montowane systemy plików z opcj± noauto + oraz wykluczone przez opcjê , + jak równie¿ systemy plików ju¿ zamontowane. + + + + + + + + Wykonanie wszystkiego, oprócz faktycznego wywo³ania + funkcji systemowej montowania. W po³±czeniu z opcj± + mo¿na w ten sposób sprawdziæ, co + tak naprawdê &man.mount.8; stara siê zrobiæ. + + + + + + + + Wymuszenie montowania nieuporz±dkowanego systemu + plików (niebezpieczne), lub wymuszenie odebrania prawa + do zapisu przy zmianie trybu montowania systemu plików + z trybu odczyt i zapis na + tylko do odczytu. + + + + + + + + Montowanie systemu plików w trybie tylko do odczytu. + Taki sam efekt ma zastosowanie opcji + z argumentem (b±d¼ + w wersjach FreeBSD wcze¶niejszych ni¿ 5.2). + + + + + + typ + + + Montowanie systemu plików o okre¶lonym typie. + Przy zastosowaniu opcji montowane + s± tylko systemy plików podanego typu. + + Domy¶lnym typem systemu plików jest ufs. + + + + + + + + Uaktualnienie opcji montowania systemu plików. + + + + + + + + Pokazywanie dodatkowych komunikatów. + + + + + + + + Montowanie w trybie odczytu i zapisu. + + + + + Opcji towarzyszy lista oddzielonych + przecinkami parametrów, oto niektóre z nich: + + + + nodev + + + Ignorowanie obecnych w systemie plików urz±dzeñ + specjalnych. Przydatna opcja, je¶li chodzi + o bezpieczeñstwo. + + + + + noexec + + + Wy³±czenie uruchamiania programów wykonywalnych + na systemie plików. Równie¿ s³u¿y bezpieczeñstwu. + + + + + nosuid + + + Ignorowanie bitów setuid i setgid w systemie + plików. Kolejna opcja s³u¿±ca bezpieczeñstwu. + + + + + + + Polecenie <command>umount</command> Command + + systemy plików + odmontowywanie + + + Poleceniu &man.umount.8; nale¿y podaæ jako parametr + punkt montowania, nazwê urz±dzenia b±d¼ opcjê lub + . + + Ka¿dej z form wywo³ania polecenia mo¿na podaæ opcjê + , która nakazuje dokonaæ bezwarunkowego + odmontowania, oraz opcjê , powoduj±c± + wypisywanie dodatkowych komunikatów. Nale¿y mieæ na uwadze, + ¿e raczej nie zaleca siê korzystania z . + Bezwarunkowe odmontowywanie systemu plików mo¿e doprowadziæ + do awarii systemu lub uszkodzenia danych znajduj±cych siê + w danym systemie plików. + + Opcje oraz s³u¿± + do odmontowania wszystkich zamontowanych systemów plików, + lub systemów plików wybranych typów, okre¶lonych w opcji + . Opcja nie dokonuje + próby odmontowania g³ównego systemu plików. + + + + + Procesy + + FreeBSD jest wielozadaniowym systemem operacyjnym. Oznacza + to, ¿e korzystaj±c z systemu mamy wra¿enie, ¿e wiele programów + dzia³a jednocze¶nie. Dzia³aj±cy w danej chwili program nazywany + jest procesem. Po wydaniu dowolnego + polecenia uruchamiany jest przynajmniej jeden proces. S± równie¿ + procesy systemowe, które dzia³aj± nieprzerwanie, zapewniaj±c + prawid³owe funkcjonowanie systemu. + + Ka¿demu procesowi przypisany jest jednoznaczny numer zwany + identyfikatorem procesu, lub po prostu + PID. Podobnie jak plik, równie¿ ka¿dy + proces ma swojego w³a¶ciciela i grupê. Na podstawie informacji + o w³a¶cicielu i grupie system operacyjny przydziela procesowi + prawa do otwierania plików i urz±dzeñ, przy zastosowaniu opisanych + wcze¶niej praw dostêpu. Wiêkszo¶æ procesów ma swój proces macierzysty; + jest to proces, który uruchomi³ dany proces. Przyk³adowo, kiedy wydajemy + polecenia w pow³oce, to zarówno pow³oka jest procesem, jak i ka¿de + z wykonanych poleceñ. Procesem macierzystym ka¿dego uruchomionego + w ten sposób procesu bêdzie pow³oka. Wyj±tkiem jest specjalny proces + zwany &man.init.8;. init jest pierwszym procesem, + wiêc jego PID jest zawsze równy 1. Proces init + uruchamiany jest przez j±dro systemu podczas ³adowania FreeBSD. + + S± dwa bardzo przydatne polecenia, które pozwalaj± zobaczyæ, + jakie procesy s± uruchomione: &man.ps.1; i &man.top.1;. Polecenie + ps pokazuje statyczn± listê dzia³aj±cych w danej + chwili procesów, uwzglêdniaj±c informacje takie jak PID-y procesów, + zu¿ywan± pamiêæ, wydane do uruchomienia procesów polecenia, itd. + Polecenie top wy¶wietla listê uruchomionych + procesów, która jest co kilka sekund uaktualniana, dziêki czemu mo¿emy + na bie¿±co ¶ledziæ, czym zajmuje siê komputer. + + Domy¶lnie ps pokazuje tylko dzia³aj±ce procesy + nale¿±ce do u¿ytkownika wydaj±cego polecenie. Na przyk³ad: + + &prompt.user; ps + PID TT STAT TIME COMMAND + 298 p0 Ss 0:01.10 tcsh + 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14) +37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14) +48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi +48730 p0 IW 0:00.00 (dns helper) (navigator-linux-) +72210 p0 R+ 0:00.00 ps + 390 p1 Is 0:01.14 tcsh + 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y + 6688 p3 IWs 0:00.00 tcsh +10735 p4 IWs 0:00.00 tcsh +20256 p5 IWs 0:00.00 tcsh + 262 v0 IWs 0:00.00 -tcsh (tcsh) + 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16 + 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16 + 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc + 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish + + Jak widzimy, &man.ps.1; wy¶wietla informacje w kilku kolumnach. + W kolumnie PID pokazywany jest omówiony wcze¶niej + identyfikator procesu. PID-y s± przydzielane po kolei od 1 do 99999 + i znów od pocz±tku, gdy siê skoñcz±. Kolumna TT + pokazuje terminal, na którym dzia³a program — na razie nie bêdziemy + siê tym zajmowaæ. W kolumnie STAT przedstawiony jest + stan procesu, jego tak¿e na razie nie bêdziemy omawiaæ. TIME + pokazuje czas wykorzystywania procesora przez dany proces, niekoniecznie + odpowiada on czasowi, jaki up³yn±³ od uruchomienia programu, poniewa¿ wiele + programów przez d³ugi czas oczekuje na jakie¶ zdarzenie, a dopiero potem + wykorzystuje procesor. Ostatnia kolumna, COMMAND, pokazuje + polecenie, którym uruchomiony zosta³ program. + + &man.ps.1; ma wiele rozmaitych opcji, które maj± wp³yw na wy¶wietlane + informacje. Jedn± z najbardziej przydatnych kombinacji opcji jest + auxww. Opcja a pokazuje informacje o wszystkich + dzia³aj±cych procesach, równie¿ nie nale¿±cych do nas. + pokazuje nazwê u¿ytkownika, do którego nale¿y proces, jak równie¿ wykorzystanie pamiêci. + pokazuje informacje o procesach — demonach. + Opcja nakazuje, by polecenie &man.ps.1; wy¶wietla³o + pe³n± liniê polecenia, nie obcinaj±c jej, by zmie¶ci³a siê na ekranie. + + Informacje pokazywane przez &man.top.1; wygl±daj± podobnie. Oto przyk³ad: + + &prompt.user; top +last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10 +47 processes: 1 running, 46 sleeping +CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle +Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free +Swap: 256M Total, 38M Used, 217M Free, 15% Inuse + + PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND +72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top + 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14 + 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA + 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm +48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu + 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd + 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt +... + + Informacje podzielone s± na dwie czê¶ci. Nag³ówek (pierwsze piêæ + wierszy) zawiera PID ostatnio uruchomionego procesu, ¶rednie obci±¿enie + systemu (miara zapracowania systemu), czas dzia³ania systemu (od ostatniego + uruchonienia) oraz aktualny czas. Inne liczby w nag³ówku informuj± o liczbie + dzia³aj±cych procesów (w przyk³adzie 47), jak du¿o pamiêci i przestrzeni + wymiany jest zajête, oraz ile czasu system przebywa w ró¿nych stanach + procesora. + + Pod nag³ówkiem w kilku kolumnach pokazane s± informacje zbli¿one + do przedstawianych przez &man.ps.1;. Podobnie mo¿na tu znale¼æ PID + procesu, nazwê u¿ytkownika, czas zajmowania procesora, oraz polecenie, + którym uruchomiono proces. &man.top.1; pokazuje domy¶lnie tak¿e rozmiar + pamiêci zajmowanej przez proces. Ta ostatnia informacja podzielona jest + na dwie kolumny; jedna odpowiada ca³kowitemu rozmiarowi, druga rozmiarowi + rezydentnemu. Ca³kowity rozmiar oznacza, ile pamiêci by³o potrzebne programowi, + z kolei rozmiar rezydentny informuje, ile pamiêci wykorzystuje program w danej + chwili. W przyk³adzie widaæ, ¿e &netscape; + potrzebowa³ prawie 30 MB pamiêci RAM, jednak obecnie wykorzystuje tylko + 9 MB. + + &man.top.1; automatycznie aktualizuje wy¶wietlane informacje co dwie + sekundy; mo¿na to zmieniæ opcj± . + + + + Demony, sygna³y i unicestwianie procesów + + Kiedy korzystamy z edytora tekstu, mo¿emy go w prosty sposób + obs³ugiwaæ, wczytywaæ pliki, itp. Jest to mo¿liwe dziêki cechom + samego edytora oraz dziêki temu, ¿e edytor jest pod³±czony do + terminala. Jednak¿e, niektóre programy + pracuj± bez ci±g³ej komunikacji z u¿ytkownikiem, s± wiêc od³±czone + od terminala. Przyk³adem takiego programu mo¿e byæ serwer WWW, + nieustannie odpowiadaj±cy na ¿±dania pochodz±ce z sieci, bez potrzeby + komunikacji z u¿ytkownikiem. Inny przyk³ad to programy przesy³aj±ce + emaile pomiêdzy komputerami. + + Takie programy nazywane s± demonami (ang. daemons). + Demony to postaci z mitologii greckiej — niewielkie us³u¿ne istoty, + ani dobre, ani z³e, które w rozmaity sposób pomaga³y ludziom. Podobnie + pomagaj± dzisiejsze serwery pocztowe i serwery WWW. Dlatego w³a¶nie od + d³ugiego czasu maskotk± BSD jest weso³y demon z wid³ami i w + + Przyjêto, i¿ programy uruchamiane jako demony maj± nazwy zakoñczone + liter± d. BIND (Berkeley Internet + Name Daemon) jest serwerem nazw uruchamianym przez program + named, serwer WWW Apache + nosi nazwê httpd, demon kolejkowania drukarki (line printer + spooling daemon) to lpd, itd. Nie jest to sztywna regu³a, + lecz przyjêta konwencja; na przyk³ad g³ówny demon pocztowy programu + Sendmail nazywa siê sendmail, + a nie jak mo¿na by przypuszczaæ maild. + + Niekiedy istnieje potrzeba komunikacji z procesem — demonem. + Odbywa siê ona poprzez signa³y, to znaczy mo¿emy + porozumieæ siê z demonem (lub jakimkolwiek dzia³aj±cym procesem) wysy³aj±c + mu sygna³. S± ró¿ne rodzaje sygna³ów, które mo¿emy wys³aæ — niektóre + z nich maj± okre¶lone znaczenie, inne s± odpowiednio interpretowane przez + aplikacjê, co powinno byæ opisane w dokumentacji aplikacji. Sygna³ mo¿emy + wys³aæ tylko do procesu, którego jeste¶my w³a¶cicielem. Wys³anie sygna³u + do procesu nale¿±cego do kogo¶ innego za po¶rednictwem &man.kill.1; lub + &man.kill.2; spowoduje odmowê dostêpu. Wyj±tkiem jest u¿ytkownik + root, który mo¿e wysy³aæ sygna³y do dowolnego + procesu, niezale¿nie od jego w³a¶ciciela. + + Zdarza siê, ¿e samo FreeBSD równie¿ wysy³a aplikacjom sygna³y. + Je¿eli niew³a¶ciwie napisany program próbuje dostaæ siê do niedostêpnego + dla niego obszaru pamiêci, FreeBSD wysy³a procesowi sygna³ Segmentation + Violation (SIGSEGV). Aplikacja mo¿e skorzystaæ + z funkcji systemowej &man.alarm.3;, wówczas po up³yniêciu pewnego czasu + zostanie do niej wys³any sygna³ Alarm (SIGALRM). + I tak dalej. + + Do zatrzymania procesu mo¿na wykorzystaæ dwa sygna³y: SIGTERM + i SIGKILL. Pierwszy z nich jest ³agodnym sposobem + unicestwienia procesu; proces mo¿e przechwyciæ + ten sygna³, nastêpnie zakoñczyæ swoj± pracê, np. zamykaj±c pliki, + które otworzy³. Czasami proces mo¿e zignorowaæ sygna³ SIGTERM, + je¶li akurat zajmuje siê czym¶, co nie powinno byæ przerywane. + + Sygna³ SIGKILL nie mo¿e zostaæ zignorowany. + Dzia³a wed³ug zasady Nie obchodzi mnie, co robisz, w tej + chwili przestañ. Wys³anie procesowi sygna³u SIGKILL + powoduje, i¿ FreeBSD natychmiast go wstrzymuje + Nie do koñca jest to prawd± — w kilku przypadkach nie + mo¿na przerwaæ procesu. Na przyk³ad gdy proces stara siê przeczytaæ + plik znajduj±cy siê na innym komputerze w sieci, a ów inny komputer + z jakiego¶ powodu bêdzie niedostêpny (na skutek awarii sieci, + lub po prostu zostanie wy³±czony), to proces stanie siê + nieprzerywalny. Po chwili (zwykle po dwóch + minutach) proces przekroczy czas oczekiwania, wówczas + zostanie unicestwiony. + . + + Inne u¿yteczne sygna³y to + SIGHUP, SIGUSR1 i + SIGUSR2. S± to sygna³y ogólnego przeznaczenia, + ró¿ne aplikacje reaguj± na nie w ró¿ny sposób. + + Powiedzmy, ¿e dokonali¶my zmiany w pliku konfiguracji + serwera WWW, i chcemy nakazaæ serwerowi, aby konfiguracja zosta³a + ponownie wczytana. Mogliby¶my zatrzymaæ i ponownie uruchomiæ + httpd, ale ubocznym efektem takiego postêpowania + by³aby chwilowa przerwa w pracy serwera, co jest raczej niepo¿±dane. + Wiêkszo¶æ demonów dzia³a w taki sposób, i¿ po otrzymaniu sygna³u + SIGHUP dokonuj± ponownego przeczytania swojego + pliku konfiguracyjnego. Dziêki temu zamiast unicestwiania i ponownego + uruchamiania httpd mo¿emy wys³aæ mu sygna³ + SIGHUP. Nie jest jednoznacznie okre¶lone, + jak procesy reaguj± na sygna³ SIGHUP, dlatego + ró¿ne demony mog± zachowywaæ siê w ró¿ny sposób — w razie + niepewno¶ci warto zapoznaæ siê z dokumentacj± konkretnego demona. + + Sygna³y wysy³ane s± przy u¿yciu polecenia &man.kill.1;, jak + w poni¿szym przyk³adzie. + + + Wysy³anie sygna³u do procesu + + W tym przyk³adzie zaprezentowano wysy³anie sygna³u do &man.inetd.8;. + Plik konfiguracyjny dla inetd to + /etc/inetd.conf. Wys³anie sygna³u + SIGHUP spowoduje ponowne przeczytanie tego pliku. + + + Trzeba ustaliæ PID procesu, do którego wysy³aæ bêdziemy sygna³ + — do tego celu pos³u¿± polecenia &man.ps.1; i &man.grep.1;. + Polecenia &man.grep.1; u¿ywamy do odnalezienia podanego ci±gu + znaków. Poniewa¿ polecenia wydajemy jako zwyk³y u¿ytkownik, + a &man.inetd.8; dzia³a jako root, polecenie + &man.ps.1; musimy wywo³aæ z opcj± . + + &prompt.user; ps -ax | grep inetd + 198 ?? IWs 0:00.00 inetd -wW + + Jak widaæ, &man.inetd.8; ma PID o warto¶ci 198. Niekiedy w + przedstawionym powy¿ej przyk³adzie mo¿e siê tak¿e pojawiæ proces + grep inetd, wynika to ze sposobu, w jaki + &man.ps.1; odnajduje dzia³aj±ce procesy. + + + + Sygna³ wysy³amy przy pomocy polecenia &man.kill.1;. + Najpierw skorzystamy jednak z polecenia &man.su.1; by staæ siê + rootem, gdy¿ &man.inetd.8; dzia³a jako + root. + + &prompt.user; su +Password: +&prompt.root; /bin/kill -s HUP 198 + + Podobnie jak wiele poleceñ w systemach &unix;, &man.kill.1; + nie wy¶wietla ¿adnego komunikatu w przypadku powodzenia. Je¿eli + natomiast sygna³ zosta³ wys³any do procesu, którego nie jest siê + w³a¶cicielem, pojawi siê informacja: kill: + PID: Operation not + permitted (niedozwolona operacja). B³êdne wpisanie + PID-u spowoduje albo wys³anie sygna³u do niew³a¶ciwego procesu, + co mo¿e skoñczyæ siê ¼le, albo te¿ wys³anie sygna³u do PID-u, + który nie jest w danej chwili wykorzystywany — pojawi siê + wówczas komunikat kill: + PID: No such process + (nie ma takiego procesu). + + + Dlaczego warto korzystaæ z <command>/bin/kill</command>? + + W wielu pow³okach polecenie kill jest wbudowane; + oznacza to, ¿e sama pow³oka zajmuje siê wysy³aniem sygna³u, nie + wywo³uj±c /bin/kill. Mo¿e to byæ u¿yteczne, + jednak¿e w ró¿nych pow³okach stosowana jest ró¿na sk³adnia do + okre¶lenia nazwy sygna³u, który ma byæ wys³any. Zamiast wiêc + zapamiêtywania wszystkich mo¿liwych sk³adni, ³atwiej jest po + prostu korzystaæ z polecenia + /bin/kill ... + + + + + Inne sygna³y wysy³a siê t± sam± metod±, wystarczy zast±piæ + TERM lub KILL w odpowiedni + sposób. + + + nicestwianie losowo wybranego procesu jest raczej z³ym pomys³em. + Szczególne znaczenie ma &man.init.8;, proces o PID równym 1. + Wydanie polecenia /bin/kill -s KILL 1 jest szybk± + metod± wy³±czenia systemu. Nale¿y zawsze sprawdzaæ poprawno¶æ + argumentów polecenia &man.kill.1; przed naci¶niêciem klawisza + Return. + + + + + Pow³oki + pow³oki + linia poleceñ + + W codziennej pracy z FreeBSD bardzo czêsto wykorzystywany jest + interfejs linii poleceñ, zwany pow³ok± (ang. shell). Podstawowym + zadaniem pow³oki jest przyjmowanie poleceñ i wykonywanie ich. + Wiele pow³ok wyposa¿onych jest tak¿e w dodatkowe funkcje u³atwiaj±ce + pracê, np. usprawnienia zarz±dzania plikami, dopasowywanie nazw plików, + u³atwienia korzystania z linii poleceñ, makropolecenia i zmienne ¶rodowiskowe. + We FreeBSD dostêpnych jest kilka pow³ok, np. Bourne Shell sh + i ulepszony C-shell tcsh. Wiele innych pow³ok, jak choæby + zsh czy bash, mo¿na znale¼æ w kolekcji + portów FreeBSD. + + Której z pow³ok najlepiej jest u¿ywaæ? To w³a¶ciwie kwestia gustu. + Dla programistów C najwygodniejsze mog± byæ pow³oki o sk³adni wzorowanej + na jêzyku C, np. tcsh. U¿ytkownikom Linuxa i tym, + dla których interfejs linii poleceñ systemów 8unix; jest nowo¶ci±, mo¿na + poleciæ bash. Do wyboru jest wiele pow³ok, ka¿da z nich + ma pewne charakterystyczne tylko dla niej w³a¶ciwo¶ci, które niekoniecznie + bêd± dzia³aæ w ka¿dych warunkach. + + Czêsto spotykanym udogodnieniem pow³oki jest uzupe³nianie nazw plików. + Po wpisaniu kilku pierwszych liter polecenia lub nazwy pliku pow³oka potrafi + zwykle uzupe³niæ dalszy ci±g polecenia lub nazwy, dzieje siê to po wci¶niêciu + klawisza Tab. Przyjmijmy przyk³adowo, ¿e istniej± dwa pliki + o nazwach foobar i foo.bar. + Chcemy usun±æ plik foo.bar. Mo¿emy wiêc wydaæ polecenie: + rm fo[Tab].[Tab]. + + Pow³oka wy¶wietli: rm foo[BIIP].bar. + + Napis [BIIP] oznacza sygna³ d¼wiêkowy, bêd±cy informacj± od pow³oki, + ¿e uzupe³nienie nazwy pliku nie by³o mo¿liwe, poniewa¿ mo¿na dopasowaæ + wiêcej ni¿ jedn± nazwê. Zarówno foobar jak i + foo.barzaczynaj± siê od fo. + Pow³oka mog³a jednak¿e uzupe³niæ pocz±tek, czyli foo. + Teraz mo¿na wpisaæ kropkê . i ponownie wcisn±æ + Tab, tym razem pow³oka uzupe³ni nazwê do koñca. + zmienne ¶rodowiskowe + + Inn± cech± pow³oki s± zmienne ¶rodowiskowe. Przechowywane s± one + w przestrzeni ¶rodowiska pow³oki w postaci par nazwa = + warto¶æ. Przestrzeñ ¶rodowiska jest widoczna dla ka¿dego + programu uruchamianego przez pow³okê, dlatego te¿ przechowuje siê tam + wiele parametrów konfiguracyjnych dla programów. Oto najczê¶ciej + spotykane zmienne ¶rodowiskowe wraz z krótkim opisem: + zmienne ¶rodowiskowe + + + + + + Zmienna + Opis + + + + + + USER + Nazwa aktualnie zalogowanego u¿ytkownika. + + + + PATH + Lista katalogów zawieraj±cych pliki wykonywalne + oddzielona przecinkami. + + + + DISPLAY + Nazwa ekranu X11, je¶li takowy jest dostêpny. + + + + SHELL + Wykorzystywana pow³oka. + + + + TERM + Nazwa terminala u¿ytkownika, wykorzystywana do + okre¶lenia w³a¶ciwo¶ci terminala. + + + + TERMCAP + Zapis z bazy termcap zawieraj±cy sekwencje kodów + odpowiadaj±cych ró¿nym funkcjom terminala. + + + + OSTYPE + Typ systemu operacyjnego, np. FreeBSD. + + + + MACHTYPE + Architektura sprzêtowa, na jakiej dzia³a system. + + + + EDITOR + Preferowany przez u¿ytkownika edytor tekstu. + + + + PAGER + Preferowany przez u¿ytkownika program wy¶wietlaj±cy + pliki tekstowe. + + + + MANPATH + Lista katalogów zawieraj±cych dokumentacjê systemow± + oddzielona przecinkami. + + + + + + Bourne shells + Sposób odczytywania i ustawiania zmiennych ¶rodowiskowych + zale¿y od rodzaju u¿ywanej pow³oki. Na przyk³ad w pow³okach + wzorowanych na C, jak tcsh i csh, + do ustawiania i przegl±dania zmiennych ¶rodowiskowych s³u¿y polecenie + setenv, natomiast w pow³okach Bourne'a, czyli + sh i bash, do tych celów + wykorzystywane jest polecenie export. Przyk³adowo, + aby zmieniæ zmienn± ¶rodowiskow± EDITOR na + /usr/local/bin/emacs w pow³oce csh + lub tcsh, nale¿y wydaæ polecenie: + + &prompt.user; setenv EDITOR /usr/local/bin/emacs + + A w pow³okach Bourne'a: + + &prompt.user; export EDITOR="/usr/local/bin/emacs" + + W wiêkszo¶ci pow³ok mo¿na wy¶wietliæ warto¶æ zmiennej + ¶rodowiskowej przez poprzedzenie jej nazwy znakiem $. + Dla przyk³adu, polecenie echo $TERM poka¿e warto¶æ + zmiennej $TERM, poniewa¿ pow³oka zastêpuje wyra¿enie + $TERM warto¶ci± zmiennej i przekazuje j± do + echo. + + Wiele znaków, zwanych meta-znakami, traktowanych jest przez + pow³oki w specjalny sposób. Najczê¶ciej wykorzystywanym jest + *, oznaczaj±cy dowolny ci±g znaków w nazwie pliku, + umo¿liwiaj±cy wykonywanie operacji na wielu plikach. Przyk³adowo, + wywo³anie echo * jest prawie identyczne z wywo³aniem + ls, poniewa¿ pow³oka przekazuje do echo + nazwy wszystkich plików pasuj±cych *. + + Je¶li potrzeba, by pow³oka nie interpretowa³a znaku jako znak + specjalny, nale¿y go poprzedziæ znakiem uko¶nika (\). + Wywo³anie echo $TERM powoduje wypisanie ustawionego + typu terminala, podczas gdy efektem polecenia echo \$TERM + jest po prostu napis $TERM. + + + Zmiana pow³oki + + Naj³atwiej jest zmieniæ pow³okê przy u¿yciu polecenia chsh. + Wywo³anie tego polecenia uruchomi edytor wskazany przez zmienn± + EDITOR, lub edytor vi, je¶li nie jest ona + zdefiniowana. Nastêpnie nale¿y zmieniæ nazwê pow³oki w wierszu + Shell:. + + Mo¿na te¿ skorzystaæ z chsh z opcj± , + która automatycznie zmieni pow³okê, bez uruchamiania edytora. Poni¿ej + przedstawiono wywo³anie zmieniaj±ce pow³okê na bash: + + &prompt.user; chsh -s /usr/local/bin/bash + + + Wybrana pow³oka musi byæ wymieniona w pliku + /etc/shells. Je¶li pow³okê zainstalowano z + kolekcji portów powinna zostaæ dopisana + automatycznie. Je¶li natomiast przeprowadzono rêczn± instalacjê + pow³oki, trzeba to zrobiæ samemu. + + Dla przyk³adu, je¶li pow³oka bash zosta³a zainstalowana + i umieszczona w /usr/local/bin, trzeba bêdzie wydaæ + polecenie: + + &prompt.root; echo "/usr/local/bin/bash" >> /etc/shells + + Oraz uruchomiæ chsh. + + + + + + + + + Aleksander + Fafu³a + T³umaczy³ + + + + + Edytory tekstu + edytory tekstu + edytory + + Konfiguracja FreeBSD polega g³ównie na edytowaniu plików + tekstowych. Z tego w³a¶nie powodu, dobrze by³oby zapoznaæ + siê z edytorami tekstu. FreeBSD posiada ich kilka, a kolejne + mo¿na doinstalowaæ z drzewa portów. + + + ee + + + edytory + ee + + Naj³atwiejszym do nauki i w u¿yciu jest edytor + ee, co jest skrótem od Easy Editor + (ang. £atwy Edytor). Aby uruchomiæ ee, + nale¿y u¿yæ polecenia ee plik, + gdzie plik jest to, co chcemy edytowaæ. + Na przyk³ad, aby wyedytowaæ plik /etc/rc.conf, + napiszemy ee /etc/rc.conf. Gdy ju¿ jeste¶my w + ee, mo¿emy zauwa¿yæ, ¿e wszystkie niezbêdne + komendy s± wypisane u góry ekranu. Znak ^ oznacza + wci¶niêty klawisz Ctrl. Innymi s³owy ^e + oznacza, ¿e nale¿y trzymaæ Ctrl i wcisn±æ klawisz + e. Aby wyj¶æ z ee, wci¶nij + Esc, nastêpnie wybierz leave editor (opu¶æ edytor). + Edytor zapyta, czy zachowaæ zmiany, je¶li plik zosta³ zmodyfikowany. + + + vi + + + edytory + vi + + + emacs + + + edytory + emacs + + FreeBSD w swoich zasobach ma tak¿e potê¿ny edytor tekstu, jakim jest + vi. W kolekcji portów dostêpny jest tak¿e + Emacs, czy vim + (editors/emacs i + editors/vim). Edytory te oferuj± + du¿o wiêksz± funkcjonalno¶æ, ale oczekuj± w zamian wiêkszego obeznania + u¿ytkownika z zasadami ich dzia³ania, ponadto ich obs³uga jest trudniejsza + do nauki. Jednak¿e, je¶li planujesz edytowaæ wiele tekstu, nauka + Emacs lub vim zwróci + siê w d³ugim okresie w postaci zaoszczêdzonego czasu. + + + + Urz±dzenia i pliki urz±dzeñ + + Mianem urz±dzeñ okre¶la siê komponenty komputera, takie jak dysk, + drukarka, karta graficzna czy klawiatura. Podczas ³adowania systemu + FreeBSD wiêkszo¶æ wy¶wietlanych komunikatów dotyczy wykrywanych urz±dzeñ. + Komunikaty startowe dostêpne s± do pó¼niejszego przegl±dania w pliku + /var/run/dmesg.boot. + + Przyk³adowo, acd0 odpowiada pierwszemu + napêdowi CDROM IDE, natomiast kbd0 oznacza + klawiaturê. + + Dostêp do wiêkszo¶ci urz±dzeñ w systemie operacyjnym &unix; + odbywa siê poprzez specjalne pliki, zwane plikami urz±dzeñ, + znajduj±ce siê w katalogu /dev. + + + Tworzenie plików urz±dzeñ + Kiedy wyposa¿amy komputer w nowe urz±dzenie, lub kompilujemy + j±dro z obs³ug± dodatkowych urz±dzeñ, konieczne mo¿e okazaæ siê + utworzenie nowych plików urz±dzeñ. + + + <literal>DEVFS</literal> (DEVice File System) + + System plików urz±dzeñ, zwany DEVFS, + udostêpnia przestrzeñ nazw urz±dzeñ j±dra jako czê¶æ przestrzeni + nazw g³ównego systemu plików. DEVFS zajmuje siê + obs³ug± systemu plików urz±dzeñ, dziêki czemu nie trzeba samodzielnie + tworzyæ b±d¼ modyfikowaæ plików urz±dzeñ. + + Wiêcej informacji znale¼æ mo¿na w dokumentacji systemowej &man.devfs.5;. + + + + + + + + + Cezary + Morga + T³umaczy³ + + + + + Formaty binarne + + By zrozumieæ czemu FreeBSD u¿ywa formatu &man.elf.5;, musimy wpierw + poznaæ trzy obecnie dominujace formaty plików wykonywalnych + w systemach &unix;: + + + + &man.a.out.5; + + Najstarszy i najbardziej klasyczny format w Uniksie. + Wykorzystuje krótki nag³ówek z magicznym numerem na samym pocz±tku, + czêsto wykorzystywanym do okre¶lenia rodzaju pliku (szczegó³owy opis + dostêpny jest w &man.a.out.5;). Na plik sk³adaj± siê trzy segmenty: + .text, .data i .bss oraz tablice symboli i ci±gów tekstowych. + + + + COFF + + Format obiektowy pochodz±cy z SVR3. W tym formacie sekcja tablic + w wchodzi ju¿ w sk³ad nag³ówka, tak wiêc mo¿liwe jest zawarcie w pliku + wiêcej sekcji ni¿ tylko .text, .data i .bss. + + + + &man.elf.5; + + Nastepca COFF zawieraj±cy wiele dodatkowych + sekcji o 32- b±d¼ nawet 64-bitowych warto¶ciach. Jednym, acz wielkim + minusem jest fakt, i¿ przy projektowaniu formatu ELF + równie¿ za³o¿ono, ¿e na ka¿d± architekturê sprzêtow± bêdzie istnia³ + tylko jeden interfejs ABI. Okaza³o siê natomiast, i¿ takie za³o¿enie + jest b³êdne nawet w ¶wiecie komercyjnych SYSV (z którego pochodz± + przynajmniej trzy ABI: SVR4, Solaris i SCO). + + Sposobem na rozwi±zanie tego problemu we FreeBSD s± narzêdzia + do metkowania plików wykonywalnych + ELF informacjami, z którymi ABI jest on zgodny. + Wiêcej informacji dostêpnych jest w podrêczniku systemowym + &man.brandelf.1;. + + + + System FreeBSD pochodzi z klasycznego obozu. + Wykorzystywa³ on zatem format &man.a.out.5; — technologiê + wypróbowan± w wielu pokoleniach systemów BSD i z powodzeniem + stosowan± a¿ do ga³êzi 3.X. Mimo, ¿e skompilowanie i uruchomienie + w sposób natywny plików binarnych ELF (a tak¿e + j±dra) by³o mo¿liwe we FreeBSD ju¿ od pewnego czasu, Projekt + oficjalnie opiera³ siê przed migracj± do formatu ELF + jako podstawowego. Dlaczego? Otó¿, gdy obóz linuksowy wykona³ ten + bolesny krok ku ELF nie uda³o siê tak ³atwo uciec + od formatu a.out. Wynika³o to przede wszystkim + z faktu, i¿ niezbyt elastyczny plan migracji bazowa³ na mechani¼mie + wspó³dzielonych bibliotek, których modyfikacja nastrêcza³a wielu + trudno¶ci zarówno producentom sprzêtu jak i projektantom. Dopiero od + momentu gdy narzêdzia dostêpne dla ELF zaoferowa³y + sposób rozwi±zania problemu ze wspó³dzielonymi bibliotekami, zaczê³y + byæ postrzegane ogólnie jako droga do przodu, a tym + samym koszty migracji mog³y zostaæ uznane za niezbêdne do poniesienia. + Mechanizm wspó³dzielonych bibliotek FreeBSD w du¿ej mierze przypomina + mechanizm z &sunos; Sun'a i jako taki jest bardzo ³atwy w u¿yciu. + + Sk±d wiêc tyle ró¿nych formatów? + + W zamierzch³ych czasach do dyspozycji by³ prost sprzêt komputerowy. + Ów prosty sprzêt obs³ugiwa³ ma³y, prosty system. St±d te¿ format + a.outby³ ca³kowicie odpowiednim do prezentacji + plików binarnych w tym prostym systemie (PDP-11). Gdy &unix; zosta³ + przeniesiony z tego prostego systemu na platformy typu Motorola 68k czy + VAXen, zachowany zosta³ format a.out, zdecydowanie + wystarcz±jacy dla wczesnych wersji Uniksa. + + Pewien czas pó¼niej, jaki¶ bystry in¿ynier sprzêtowy stwierdzi³ + ¿e gdyby potrafi³ zmusiæ oprogramowanie do robienia kilku obskurnych + sztuczek, wówczas móg³by pozbyæ siê kilku bramek z uk³adu scalonego + i zmusiæ CPU do szybszej pracy. Pomimo, ¿e format a.out + potrafi³ wspó³pracowaæ z tym nowym rodzajem sprzêtu (zwanego wówczas + RISC) to mimo wszystko nie by³ najlepszym do tego + formatem. Dlatego te¿ rozpoczêto prace nad innymi formatami binarnymi, + które mia³y osi±gn±æ lepsze wyniki ni¿ ograniczony, prosty a.out + móg³ zaoferowaæ. Stworzone zosta³y COFF, + ECOFF oraz kilka mniej znanych formatów, nim powsta³ + ELF. + + Kolejnym problemem okaza³ siê wzrost rozmiarów programów przy + wzglednie ma³ej pojemno¶ci dysków oraz pamiêci fizycznych, a tak¿e + zwiêkszieniu stopnia skomplikowania pamiêci wirtualnej VM. Tak te¿ + narodzi³a siê koncepcja wspó³dzielonych bibliotek. Mimo, ¿e ów postêp + osi±gniêty by³ przy pomocy formatu a.out zakres + jego przydatno¶ci by³ stale rozci±gany, wraz z ka¿d± now± funkcj±. + Pojawi³a siê konieczno¶æ dynamicznego wczytywanie pewnych rzeczy ju¿ + w trakcie uruchamiania programu czy zapisywania czê¶ci programu zaraz + po wykonaniu kodu init w pamiêci lub przestrzeni wymiany. Równie¿ jêzyki + programowania stawa³y siê coraz bardziej wyrafinowane. Wiele poprawek + wprowadzonych do formatu a.out umo¿liwia³y realizacjê + kolejnych funkcji, przy czym z regu³y dzia³a³y one tylko przez pewien czas. + Niestety, format a.out sta³ siê z czasem niezdolny do rozwi±zywania wszystkich + problemów bez wci±¿ rozrastaj±cego siê narzutu w kodzie i poziomu skomplikowania. + Mimo, ¿e ELF potrafi³ rozwi±zaæ wiele z ówczesnych problemów, + zmiana formatu binarnego, który generalnie dzia³a³, wci±¿ by³a wielk± uci±¿liwo¶ci±. + Dlatego te¿ ELF musia³ poczekaæ a¿ bardziej bolesnym okaza³o + siê pozostanie przy a.out niz przej¶cie + do ELF. + + Wraz z up³ywem czasu, narzêdzia kompilacyjne, z których FreeBSD wywodzi + w³asne narzêdzia (przede wszystkim assembler i loader), wyewoluowa³y w dwa + równoleg³e projekty. Odmiana FreeBSD da³a wspó³dzielone biblioteki oraz poprawki + kilku b³êdów. Ludzie z GNU, którzy oryginalnie napisali te programy, + przepisali je na nowo i dodali proste kompilatory wskro¶ne, pozwalaj±ce na + pracê w ró¿nych formatach. Nowy pakiet narzêdzi GNU + (binutils) wspiera kompilowanie wskro¶ne, + format ELF, wspó³dzielone biblioteki, rozszerzenia + C++, itp. Dodatkowo, wielu producentów sprzêtu przygotowuje binaria + ELF. Jest to zatem dobra rzecz dla FreeBSD, ¿e + je obs³uguje. + + Format ELF oferuje wiêksz± rozszerzalno¶æ niz + a.out. Narzêdzia ELF s± lepiej + przygotowywane i oferuj± kompilacjê wskro¶n±, co jest istotne dla wielu + programistów. Co prawda ELF mo¿e byæ trochê wolniejszy + ni¿ a.out, jednak¿e próba pomiaru mo¿e byæ trudna. + Istnieje równie¿ wiele innych szczegó³ów ró¿nych dla obydwu formatów, + m.in. sposób mapowania stron, obs³ugi kodu init itp. Co prawda, + ¿adne z nich nie jest istotne, jednak¿e ró¿nice istniej±. Z czasem, + wsparcie dla a.out zostanie wstrzymane z jadra + GENERIC i ostatecznie usuniête z j±dra gdy tylko + zniknie potrzeba obs³ugi programów a.out. + + + + Wiêcej informacji + + + Dokumentacja systemowa + podrêcznik systemowy + + Najdok³adniejsz± dokumentacj± we FreeBSD jest dokumentacja + systemowa. Dla prawie ka¿dego dostêpnego w systemie programu + przygotowana jest krótka instrukcja obs³ugi, omawiaj±ca podstawy + jego dzia³ania i rozmaite opcje. Dokumentacjê mo¿emy przegl±daæ + przy pomocy polecenia man. Korzystanie z tego + polecenia jest bardzo proste: + + &prompt.user; man polecenie + + polecenie jest nazw± polecenia, o którym chcemy + uzyskaæ informacje. Na przyk³ad, aby dowiedzieæ siê czego¶ na temat + polecenia ls wpisujemy: + + &prompt.user; man ls + + Dokumentacja systemowa podzielona jest na ponumerowane czê¶ci: + + + + Polecenia dostêpne dla u¿ytkowników. + + + + Funkcje systemowe i kody b³êdów. + + + + Funkcje z bibliotek jêzyka C. + + + + Sterowniki urz±dzeñ. + + + + Formaty plików. + + + + Gry i inne rozrywki. + + + + Ró¿ne informacje. + + + + Polecenia s³u¿±ce do zarz±dzania systemem. + + + + Informacje dla programistów j±dra. + + + + Niekiedy takie samo zagadnienie mo¿e pojawiæ siê w kilku + czê¶ciach dokumentacji. Na przyk³ad istnieje polecenie + chmod, oraz funkcja systemowa + chmod(). W taki wypadku mo¿emy wybraæ + interesuj±c± nas czê¶æ dokumentacji, podaj±c jej numer jako + parametr polecenia man: + + &prompt.user; man 1 chmod + + W efekcie pokazana zostanie dokumentacja polecenia chmod. + Zgodnie z przyjêt± konwencj±, numer odpowiedniej czê¶ci dokumentacji + podawany jest w nawiasach, tak wiêc &man.chmod.1; odpowiada poleceniu + chmod, natomiast &man.chmod.2; odpowiada funkcji + systemowej. + + W opisany powy¿ej sposób mo¿emy dowiedzieæ siê, jak korzystaæ + z danego polecenia, je¶li znamy jego nazwê. Co zrobiæ, je¶li nie + mo¿emy sobie przypomnieæ nazwy polecenia? Otó¿, man + potrafi równie¿ wyszukiwaæ wybranych s³ów kluczowych w opisach + poleceñ, s³u¿y do tego opcja : + + &prompt.user; man -k mail + + Wpisanie takiego polecenia spowoduje wy¶wietlenie listy + poleceñ, których opisy zawieraj± s³owo kluczowe mail. + Takie dzia³anie jest równowa¿ne skorzystaniu z polecenia + apropos. + + Je¶li wiêc, przegl±daj±c zawarto¶æ katalogu + /usr/bin, zastanawiamy siê, do czego + w³a¶ciwie s³u¿± znajduj±ce siê tam polecenia, mo¿emy wpisaæ: + + &prompt.user; cd /usr/bin +&prompt.user; man -f * + + lub + + &prompt.user; cd /usr/bin +&prompt.user; whatis * + + W obu przypadkach efekt bêdzie taki sam. + + + + Pliki GNU Info + Free Software Foundation + + Do FreeBSD do³±czonych jest wiele programów i narzêdzi + stworzonych przez Free Software Foundation (FSF). Prócz + dokumentacji systemowej, do tych programów do³±czone s± + bardziej rozbudowane dokumenty hipertekstowe, zwane plikami + info. Mo¿na je przegl±daæ poleceniem + info, lub trybem info emacsa, + o ile emacs zosta³ zainstalowany. + + By skorzystaæ z polecenia &man.info.1;, wpisujemy: + + &prompt.user; info + + Krótkie wprowadzenie pojawia siê po wpisaniu h. + Spis poleceñ jest dostêpny po wpisaniu ?. + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir1.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir1.dot new file mode 100644 index 0000000000..f259e8377d --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir1.dot @@ -0,0 +1,7 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir2.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir2.dot new file mode 100644 index 0000000000..b846c82399 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir2.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "B1/"; + "A1/" -> "B2/"; + root -> "A2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir3.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir3.dot new file mode 100644 index 0000000000..178a3a91bb --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir3.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir4.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir4.dot new file mode 100644 index 0000000000..82d12b421a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir4.dot @@ -0,0 +1,9 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/" -> "C1/"; + "B1/" -> "C2/"; + "A2/" -> "B2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir5.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir5.dot new file mode 100644 index 0000000000..f5aa6e01dc --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir5.dot @@ -0,0 +1,9 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "C1/"; + "A1/" -> "C2/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/bibliography/Makefile b/pl_PL.ISO8859-2/books/handbook/bibliography/Makefile new file mode 100644 index 0000000000..f926466a22 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/bibliography/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= bibliography/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/bibliography/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/bibliography/chapter.sgml new file mode 100644 index 0000000000..aee600218a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/bibliography/chapter.sgml @@ -0,0 +1,655 @@ + + + + Bibliografia + + While the manual pages provide the definitive reference for individual + pieces of the FreeBSD operating system, they are notorious for not + illustrating how to put the pieces together to make the whole operating + system run smoothly. For this, there is no substitute for a good book on + &unix; system administration and a good users' manual. + + + Books & Magazines Specific to FreeBSD + + International books & + Magazines: + + + + Using FreeBSD (in Chinese). + + + + + FreeBSD Unleashed (Chinese translation), published by + China Machine + Press. ISBN 7-111-10201-0. + + + + + FreeBSD From Scratch First Edition (in Chinese), + published by China Machine Press. ISBN 7-111-07482-3. + + + + + FreeBSD From Scratch Second Edition (in Chinese), + published by China Machine Press. ISBN 7-111-10286-X. + + + + + FreeBSD Handbook (Chinese translation), published by + Posts & Telecom + Press. ISBN 7-115-10541-3. + + + + + + FreeBSD 3.x Internet (in Chinese), published by + Tsinghua + University Press. ISBN 7-900625-66-6. + + + + FreeBSD & Windows (in Chinese), ISBN 7-113-03845-X + + + + FreeBSD Internet Services HOWTO (in Chinese), ISBN 7-113-03423-3 + + + + FreeBSD for PC 98'ers (in Japanese), published by SHUWA System + Co, LTD. ISBN 4-87966-468-5 C3055 P2900E. + + + + FreeBSD (in Japanese), published by CUTT. ISBN 4-906391-22-2 + C3055 P2400E. + + + + Complete Introduction to FreeBSD (in Japanese), published by Shoeisha Co., Ltd. ISBN 4-88135-473-6 P3600E. + + + + Personal UNIX Starter Kit FreeBSD (in Japanese), published by ASCII. ISBN 4-7561-1733-3 P3000E. + + + + FreeBSD Handbook (Japanese translation), published by ASCII. ISBN 4-7561-1580-2 + P3800E. + + + + FreeBSD mit Methode (in German), published by Computer und + Literatur Verlag/Vertrieb Hanser, 1998. ISBN 3-932311-31-0. + + + + FreeBSD 4 - Installieren, Konfigurieren, Administrieren + (in German), published by Computer und Literatur Verlag, 2001. + ISBN 3-932311-88-4. + + + + FreeBSD 5 - Installieren, Konfigurieren, Administrieren + (in German), published by Computer und Literatur Verlag, 2003. + ISBN 3-936546-06-1. + + + + + FreeBSD de Luxe (in German), published by + Verlag Modere Industrie, + 2003. ISBN 3-8266-1343-0. + + + + + FreeBSD Install and Utilization Manual (in Japanese), published by Mainichi Communications Inc.. + + + + Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil Widodo + + Building Internet Server with + FreeBSD (in Indonesia Language), published + by Elex Media Komputindo. + + + + + English language books & Magazines: + + + + Absolute + BSD: The Ultimate Guide to FreeBSD, published by + No Starch Press, 2002. + ISBN: 1886411743 + + + + + The Complete FreeBSD, published by + O'Reilly, 2003. + ISBN: 0596005164 + + + + The + FreeBSD Corporate Networker's Guide, published by + Addison-Wesley, 2000. + ISBN: 0201704811 + + + + + FreeBSD: An Open-Source Operating System for Your Personal + Computer, published by The Bit Tree Press, 2001. + ISBN: 0971204500 + + + + Teach Yourself FreeBSD in 24 Hours, published by + Sams, 2002. + ISBN: 0672324245 + + + + FreeBSD unleashed, published by + Sams, 2002. + ISBN: 0672324563 + + + + FreeBSD: The Complete Reference, published by + McGrawHill, 2003. + ISBN: 0072224096 + + + + + + + Users' Guides + + + + Computer Systems Research Group, UC Berkeley. 4.4BSD + User's Reference Manual. O'Reilly & Associates, + Inc., 1994. ISBN 1-56592-075-9 + + + + Computer Systems Research Group, UC Berkeley. 4.4BSD + User's Supplementary Documents. O'Reilly & + Associates, Inc., 1994. ISBN 1-56592-076-7 + + + + UNIX in a Nutshell. O'Reilly & + Associates, Inc., 1990. ISBN 093717520X + + + + Mui, Linda. What You Need To Know When You Can't Find + Your UNIX System Administrator. O'Reilly & + Associates, Inc., 1995. ISBN 1-56592-104-6 + + + + Ohio State + University has written a UNIX + Introductory Course which is available online in HTML and + PostScript format. + + An Italian translation + of this document is available as part of the FreeBSD Italian + Documentation Project. + + + + Jpman Project, Japan + FreeBSD Users Group. FreeBSD User's + Reference Manual (Japanese translation). Mainichi Communications + Inc., 1998. ISBN4-8399-0088-4 P3800E. + + + + Edinburgh + University has written an Online Guide for + newcomers to the UNIX environment. + + + + + + Administrators' Guides + + + + Albitz, Paul and Liu, Cricket. DNS and + BIND, 4th Ed. O'Reilly & Associates, Inc., 2001. + ISBN 1-59600-158-4 + + + + Computer Systems Research Group, UC Berkeley. 4.4BSD + System Manager's Manual. O'Reilly & Associates, + Inc., 1994. ISBN 1-56592-080-5 + + + + Costales, Brian, et al. Sendmail, 2nd Ed. + O'Reilly & Associates, Inc., 1997. ISBN 1-56592-222-0 + + + + Frisch, Æleen. Essential System + Administration, 2nd Ed. O'Reilly & Associates, + Inc., 1995. ISBN 1-56592-127-5 + + + + Hunt, Craig. TCP/IP Network + Administration, 2nd Ed. O'Reilly & Associates, Inc., 1997. + ISBN 1-56592-322-7 + + + + Nemeth, Evi. UNIX System Administration + Handbook. 3rd Ed. Prentice Hall, 2000. ISBN + 0-13-020601-6 + + + + Stern, Hal Managing NFS and NIS O'Reilly + & Associates, Inc., 1991. ISBN 0-937175-75-7 + + + + Jpman Project, Japan + FreeBSD Users Group. FreeBSD System + Administrator's Manual (Japanese translation). Mainichi Communications + Inc., 1998. ISBN4-8399-0109-0 P3300E. + + + + Dreyfus, Emmanuel. Cahiers + de l'Admin: BSD 2nd Ed. (in French), Eyrolles, 2004. + ISBN 2-212-11463-X + + + + + + Programmers' Guides + + + + Asente, Paul, Converse, Diana, and Swick, Ralph. + X Window System Toolkit. Digital Press, + 1998. ISBN 1-55558-178-1 + + + + Computer Systems Research Group, UC Berkeley. 4.4BSD + Programmer's Reference Manual. O'Reilly & + Associates, Inc., 1994. ISBN 1-56592-078-3 + + + + Computer Systems Research Group, UC Berkeley. 4.4BSD + Programmer's Supplementary Documents. O'Reilly & + Associates, Inc., 1994. ISBN 1-56592-079-1 + + + + Harbison, Samuel P. and Steele, Guy L. Jr. C: A + Reference Manual. 4th ed. Prentice Hall, 1995. + ISBN 0-13-326224-3 + + + + Kernighan, Brian and Dennis M. Ritchie. The C + Programming Language. 2nd Ed. PTR Prentice Hall, 1988. + ISBN 0-13-110362-8 + + + + Lehey, Greg. Porting UNIX Software. + O'Reilly & Associates, Inc., 1995. ISBN 1-56592-126-7 + + + + Plauger, P. J. The Standard C Library. + Prentice Hall, 1992. ISBN 0-13-131509-9 + + + + Spinellis, Diomidis. Code + Reading: The Open Source Perspective. + Addison-Wesley, 2003. ISBN 0-201-79940-5 + + + + Spinellis, Diomidis. Code + Quality: The Open Source Perspective. + Addison-Wesley, 2006. ISBN 0-321-16607-8 + + + + Stevens, W. Richard and Stephen A. Rago. + Advanced Programming in the UNIX + Environment. 2nd Ed. + Reading, Mass. : Addison-Wesley, 2005. + ISBN 0-201-43307-9 + + + + Stevens, W. Richard. UNIX Network + Programming. 2nd Ed, PTR Prentice Hall, 1998. ISBN + 0-13-490012-X + + + + Wells, Bill. Writing Serial Drivers for UNIX. + Dr. Dobb's Journal. 19(15), December 1994. + pp68-71, 97-99. + + + + + + Operating System Internals + + + + Andleigh, Prabhat K. UNIX System + Architecture. Prentice-Hall, Inc., 1990. ISBN + 0-13-949843-5 + + + + Jolitz, William. Porting UNIX to the 386. + Dr. Dobb's Journal. January 1991-July + 1992. + + + + Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and + John Quarterman The Design and Implementation of the + 4.3BSD UNIX Operating System. Reading, Mass. : + Addison-Wesley, 1989. ISBN 0-201-06196-1 + + + + Leffler, Samuel J., Marshall Kirk McKusick, The Design + and Implementation of the 4.3BSD UNIX Operating System: Answer + Book. Reading, Mass. : Addison-Wesley, 1991. ISBN + 0-201-54629-9 + + + + McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and + John Quarterman. The Design and Implementation of the + 4.4BSD Operating System. Reading, Mass. : + Addison-Wesley, 1996. ISBN 0-201-54979-4 + + (Chapter 2 of this book is available online as part of + the FreeBSD Documentation Project, and chapter 9 + here.) + + + + Marshall Kirk McKusick, George V. Neville-Neil The Design + and Implementation of the FreeBSD Operating System. + Boston, Mass. : Addison-Wesley, 2004. ISBN 0-201-70245-2 + + + + Stevens, W. Richard. TCP/IP Illustrated, Volume 1: + The Protocols. Reading, Mass. : Addison-Wesley, + 1996. ISBN 0-201-63346-9 + + + + Schimmel, Curt. Unix Systems for Modern + Architectures. Reading, Mass. : Addison-Wesley, 1994. + ISBN 0-201-63338-8 + + + + Stevens, W. Richard. TCP/IP Illustrated, Volume 3: + TCP for Transactions, HTTP, NNTP and the UNIX Domain + Protocols. Reading, Mass. : Addison-Wesley, 1996. + ISBN 0-201-63495-3 + + + + Vahalia, Uresh. UNIX Internals -- The New + Frontiers. Prentice Hall, 1996. ISBN + 0-13-101908-2 + + + + Wright, Gary R. and W. Richard Stevens. TCP/IP + Illustrated, Volume 2: The Implementation. Reading, + Mass. : Addison-Wesley, 1995. ISBN 0-201-63354-X + + + + + + Security Reference + + + + Cheswick, William R. and Steven M. Bellovin. Firewalls + and Internet Security: Repelling the Wily Hacker. + Reading, Mass. : Addison-Wesley, 1995. ISBN + 0-201-63357-4 + + + + Garfinkel, Simson and Gene Spafford. + Practical UNIX & Internet Security. + 2nd Ed. O'Reilly & Associates, Inc., 1996. ISBN + 1-56592-148-8 + + + + Garfinkel, Simson. PGP Pretty Good + Privacy O'Reilly & Associates, Inc., 1995. ISBN + 1-56592-098-8 + + + + + + Hardware Reference + + + + Anderson, Don and Tom Shanley. Pentium Processor + System Architecture. 2nd Ed. Reading, Mass. : + Addison-Wesley, 1995. ISBN 0-201-40992-5 + + + + Ferraro, Richard F. Programmer's Guide to the EGA, + VGA, and Super VGA Cards. 3rd ed. Reading, Mass. : + Addison-Wesley, 1995. ISBN 0-201-62490-7 + + + + Intel Corporation publishes documentation on their CPUs, + chipsets and standards on their developer web site, + usually as PDF files. + + + + Shanley, Tom. 80486 System Architecture. + 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN + 0-201-40994-1 + + + + Shanley, Tom. ISA System Architecture. + 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN + 0-201-40996-8 + + + + Shanley, Tom. PCI System Architecture. + 4th ed. Reading, Mass. : Addison-Wesley, 1999. ISBN + 0-201-30974-2 + + + + Van Gilluwe, Frank. The Undocumented PC, 2nd Ed. + Reading, Mass: Addison-Wesley Pub. Co., 1996. ISBN + 0-201-47950-8 + + + + Messmer, Hans-Peter. The Indispensable PC Hardware Book, 4th Ed. + Reading, Mass: Addison-Wesley Pub. Co., 2002. ISBN + 0-201-59616-4 + + + + + + + &unix; History + + + + Lion, John Lion's Commentary on UNIX, 6th Ed. With + Source Code. ITP Media Group, 1996. ISBN + 1573980137 + + + + Raymond, Eric S. The New Hacker's Dictionary, 3rd + edition. MIT Press, 1996. ISBN + 0-262-68092-0. Also known as the Jargon + File + + + + Salus, Peter H. A quarter century of UNIX. + Addison-Wesley Publishing Company, Inc., 1994. ISBN + 0-201-54777-5 + + + + Simon Garfinkel, Daniel Weise, Steven Strassmann. The + UNIX-HATERS Handbook. IDG Books Worldwide, Inc., + 1994. ISBN 1-56884-203-1. Out of print, but available + online. + + + + Don Libes, Sandy Ressler Life with UNIX + — special edition. Prentice-Hall, Inc., 1989. ISBN + 0-13-536657-7 + + + + The BSD family tree. + + or /usr/share/misc/bsd-family-tree + on a FreeBSD machine. + + + + The BSD Release Announcements collection. + 1997. + + + + Networked Computer Science Technical Reports + Library. + + + + Old BSD releases from the Computer Systems Research + group (CSRG). + : + The 4CD set covers all BSD versions from 1BSD to 4.4BSD and + 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). The last + disk also holds the final sources plus the SCCS files. + + + + + + Magazines and Journals + + + + The C/C++ Users Journal. R&D + Publications Inc. ISSN 1075-2838 + + + + Sys Admin — The Journal for UNIX System + Administrators Miller Freeman, Inc., ISSN + 1061-2688 + + + + freeX — Das Magazin für Linux - BSD - UNIX + (in German) Computer- und Literaturverlag GmbH, ISSN 1436-7033 + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/book.sgml b/pl_PL.ISO8859-2/books/handbook/book.sgml new file mode 100644 index 0000000000..b2d52e5db4 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/book.sgml @@ -0,0 +1,343 @@ + + + +%books.ent; + +%chapters; + +%txtfiles; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + %pgpkeys; +]> + + + + Podrêcznik FreeBSD + + Projekt Dokumentacji FreeBSD + + Luty 1999 + + + 1995 + 1996 + 1997 + 1998 + 1999 + 2000 + 2001 + 2002 + 2003 + 2004 + 2005 + 2006 + Projekt Dokumentacji FreeBSD + + + &bookinfo.legalnotice; + + + &tm-attrib.freebsd; + &tm-attrib.3com; + &tm-attrib.3ware; + &tm-attrib.arm; + &tm-attrib.adaptec; + &tm-attrib.adobe; + &tm-attrib.apple; + &tm-attrib.corel; + &tm-attrib.creative; + &tm-attrib.cvsup; + &tm-attrib.heidelberger; + &tm-attrib.ibm; + &tm-attrib.ieee; + &tm-attrib.intel; + &tm-attrib.intuit; + &tm-attrib.linux; + &tm-attrib.lsilogic; + &tm-attrib.m-systems; + &tm-attrib.macromedia; + &tm-attrib.microsoft; + &tm-attrib.netscape; + &tm-attrib.nexthop; + &tm-attrib.opengroup; + &tm-attrib.oracle; + &tm-attrib.powerquest; + &tm-attrib.realnetworks; + &tm-attrib.redhat; + &tm-attrib.sap; + &tm-attrib.sun; + &tm-attrib.symantec; + &tm-attrib.themathworks; + &tm-attrib.thomson; + &tm-attrib.usrobotics; + &tm-attrib.vmware; + &tm-attrib.waterloomaple; + &tm-attrib.wolframresearch; + &tm-attrib.xfree86; + &tm-attrib.xiph; + &tm-attrib.general; + + + + Witamy w ¶wiecie FreeBSD! Zadaniem niniejszego podrêcznika jest + opisanie procesu instalacji i czynno¶ci zwi±zanych z codziennym + u¿ytkowaniem systemu FreeBSD w wersji &rel2.current;-RELEASE + oraz &rel.current;-RELEASE. Prace nad tym podrêcznikiem + trwaj± ca³y czas. Stanowi on dzie³o wielu osób z + ca³ego ¶wiata. Tym nie mniej mamy ¶wiadomo¶æ, i¿ wiele rozdzia³ów wci±¿ + nie zosta³o napisanych, a niektóre spo¶ród istniej±cych wymagaj± aktualizacji. + Je¶li jeste¶ zainteresowany pomoc± w rozwoju projektu wy¶lij email na adres + &a.pl.doc.d;. Najnowsza wersja anglojêzyczna niniejszego dokumentu jest + zawsze dostêpna na stronie domowej FreeBSD + (wersje wcze¶niejsze dostêpne s± pod adresem ). Podrêcznik dostêpny jest + równie¿ w innych formatach dokumentów oraz w postaci skompresowanej z serwera FTP Projektu + FreeBSD b±d¼ jednego z wielu serwerów lustrzanych. Dla osób zainteresowanych, + drukowan± wersjê podrêcznika (jêzyk ang.) mo¿na nabyæ wprost z witryny FreeBSD Mall. Dostêpne jest + równie¿ przeszukiwanie podrêcznika. + + + + &chap.preface; + + + Pierwsze kroki + + + Ta czê¶æ Podrêcznika FreeBSD adresowana jest do u¿ytkowników i + administratorów, który nie mieli dotychczas kontaktu z systemem FreeBSD. + Niniejsze rozdzia³y maj± za zadanie: + + + + Zaprezentowaæ system FreeBSD. + + + + Przeprowadziæ przez proces instalacji. + + + + Nauczyæ podstaw systemu &unix;. + + + + Pokazaæ jak zainstalowaæ programy innych autorów, dostêpne w ogromnej + ilo¶ci dla systemu FreeBSD. + + + + Przedstawiæ system X - system okien &unix;, oraz szczegó³owo wyja¶niæ + jak prawid³owo skonfigurowaæ ¶rodowisko graficzne, tak by zwiêkszyæ + efektywno¶æ swej pracy. + + + + Starali¶my siê sprowadziæ liczbê odno¶ników wewn±trz tekstu do mo¿liwie + najmniejszej, tak by zminimalizowaæ ilo¶æ przeskoków i u³atwiæ + czytanie Podrêcznika od deski do deski. + + + + + + + + + + + Codzienne czynno¶ci + + + Now that the basics have been covered, this part of the + FreeBSD Handbook will discuss some frequently used features of + FreeBSD. These chapters: + + + + Introduce you to popular and useful desktop + applications: browsers, productivity tools, document + viewers, etc. + + + + Introduce you to a number of multimedia tools + available for FreeBSD. + + + + Explain the process of building a customized FreeBSD + kernel, to enable extra functionality on your system. + + + + Describe the print system in detail, both for desktop + and network-connected printer setups. + + + + Show you how to run Linux applications on your FreeBSD + system. + + + + + Some of these chapters recommend that you do some prior + reading, and this is noted in the synopsis at the beginning of + each chapter. + + + + + + + + + + + + Administracja systemem + + + The remaining chapters of the FreeBSD Handbook cover all + aspects of FreeBSD system administration. Each chapter + starts by describing what you will learn as a result of reading + the chapter, and also details what you are expected to know + before tackling the material. + + These chapters are designed to be read when + you need the information. You do not have to read them in any + particular order, nor do you need to read all of them before you + can begin using FreeBSD. + + + + + + + + + + + + + + + + + Komunikacja sieciowa + + + FreeBSD is one of the most widely deployed operating + systems for high performance network servers. The chapters in + this part cover: + + + + Serial communication + + + + PPP and PPP over Ethernet + + + + Electronic Mail + + + + Running Network Servers + + + + Firewalls + + + + Other Advanced Networking Topics + + + + These chapters are designed to be read when + you need the information. You do not have to read them in any + particular order, nor do you need to read all of them before you + can begin using FreeBSD in a network environment. + + + + + + + + + + + + + Dodatki + + + + + + + + + &chap.colophon; + + + diff --git a/pl_PL.ISO8859-2/books/handbook/boot/Makefile b/pl_PL.ISO8859-2/books/handbook/boot/Makefile new file mode 100644 index 0000000000..92105efc40 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/boot/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= boot/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/boot/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/boot/chapter.sgml new file mode 100644 index 0000000000..267f81ecc0 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/boot/chapter.sgml @@ -0,0 +1,820 @@ + + + + The FreeBSD Booting Process + + + Synopsis + booting + bootstrap + + The process of starting a computer and loading the operating system + is referred to as the bootstrap process, or simply + booting. FreeBSD's boot process provides a great deal of + flexibility in customizing what happens when you start the system, + allowing you to select from different operating systems installed on the + same computer, or even different versions of the same operating system + or installed kernel. + + This chapter details the configuration options you can set and how + to customize the FreeBSD boot process. This includes everything that + happens until the FreeBSD kernel has started, probed for devices, and + started &man.init.8;. If you are not quite sure when this happens, it + occurs when the text color changes from bright white to grey. + + After reading this chapter, you will know: + + + + What the components of the FreeBSD bootstrap system are, and how + they interact. + + + + The options you can give to the components in the FreeBSD + bootstrap to control the boot process. + + + + The basics of &man.device.hints.5;. + + + + + x86 Only + + This chapter only describes the boot process for FreeBSD running + on Intel x86 systems. + + + + + The Booting Problem + + Turning on a computer and starting the operating system poses an + interesting dilemma. By definition, the computer does not know how to + do anything until the operating system is started. This includes + running programs from the disk. So if the computer can not run a + program from the disk without the operating system, and the operating + system programs are on the disk, how is the operating system + started? + + This problem parallels one in the book The Adventures of + Baron Munchausen. A character had fallen part way down a + manhole, and pulled himself out by grabbing his bootstraps, and + lifting. In the early days of computing the term + bootstrap was applied to the mechanism used to + load the operating system, which has become shortened to + booting. + + BIOS + + Basic Input/Output SystemBIOS + + On x86 hardware the Basic Input/Output System (BIOS) is responsible + for loading the operating system. To do this, the BIOS looks on the + hard disk for the Master Boot Record (MBR), which must be located on a + specific place on the disk. The BIOS has enough knowledge to load and + run the MBR, and assumes that the MBR can then carry out the rest of the + tasks involved in loading the operating system, + possibly with the help of the BIOS. + + Master Boot Record (MBR) + + Boot Manager + + Boot Loader + + The code within the MBR is usually referred to as a boot + manager, especially when it interacts with the user. In this case + the boot manager usually has more code in the first + track of the disk or within some OS's file system. (A + boot manager is sometimes also called a boot loader, + but FreeBSD uses that term for a later stage of booting.) Popular boot + managers include boot0 (a.k.a. Boot + Easy, the standard &os; boot manager), + Grub, GAG, and + LILO. + (Only boot0 fits within the MBR.) + + If you have only one operating system installed on your disks then + a standard PC MBR will suffice. This MBR searches for the first bootable + (a.k.a. active) slice on the disk, and then runs the code on that slice to + load the remainder of the operating system. The MBR installed by + &man.fdisk.8;, by default, is such an MBR. It is based on + /boot/mbr. + + If you have installed multiple operating systems on your disks then + you can install a different boot manager, one that can display a list of + different operating systems, and allows you to choose the one to boot + from. Two of these are discussed in the next subsection. + + The remainder of the FreeBSD bootstrap system is divided into three + stages. The first stage is run by the MBR, which knows just enough to + get the computer into a specific state and run the second stage. The + second stage can do a little bit more, before running the third stage. + The third stage finishes the task of loading the operating system. The + work is split into these three stages because the PC standards put + limits on the size of the programs that can be run at stages one and + two. Chaining the tasks together allows FreeBSD to provide a more + flexible loader. + + kernel + init + + The kernel is then started and it begins to probe for devices + and initialize them for use. Once the kernel boot + process is finished, the kernel passes control to the user process + &man.init.8;, which then makes sure the disks are in a usable state. + &man.init.8; then starts the user-level resource configuration which + mounts file systems, sets up network cards to communicate on the + network, and generally starts all the processes that usually + are run on a FreeBSD system at startup. + + + + The Boot Manager and Boot Stages + + Boot Manager + + + The Boot Manager + Master Boot Record (MBR) + + The code in the MBR or boot manager is sometimes referred to as + stage zero of the boot process. This subsection + discusses two of the boot managers previously mentioned: + boot0 and LILO. + + The <application>boot0</application> Boot Manager: + The MBR installed by FreeBSD's installer or &man.boot0cfg.8;, by + default, is based on /boot/boot0. + (The boot0 program is very simple, since the + program in the MBR can only be 446 bytes long because of the slice + table and 0x55AA identifier at the end of the MBR.) + If you have installed boot0 and + multiple operating systems on your hard disks, then you will see a + display similar to this one at boot time: + + + <filename>boot0</filename> Screenshot + + F1 DOS +F2 FreeBSD +F3 Linux +F4 ?? +F5 Drive 1 + +Default: F2 + + + Other operating systems, in particular &windows;, have been known + to overwrite an existing MBR with their own. If this happens to you, + or you want to replace your existing MBR with the FreeBSD MBR then use + the following command: + + &prompt.root; fdisk -B -b /boot/boot0 device + + where device is the device that you + boot from, such as ad0 for the first IDE + disk, ad2 for the first IDE disk on a second + IDE controller, da0 for the first SCSI disk, + and so on. Or, if you want a custom configuration of the MBR, + use &man.boot0cfg.8;. + + The LILO Boot Manager: + + To install this boot manager so it will also boot FreeBSD, first + start Linux and add the following to your existing + /etc/lilo.conf configuration file: + + other=/dev/hdXY +table=/dev/hdX +loader=/boot/chain.b +label=FreeBSD + + In the above, specify FreeBSD's primary partition and drive using + Linux specifiers, replacing X with the Linux + drive letter and Y with the Linux primary + partition number. If you are using a SCSI drive, you + will need to change /dev/hd to read something + similar to /dev/sd. The + line can be omitted if you have + both operating systems on the same drive. Now run + /sbin/lilo -v to commit your new changes to the + system; this should be verified by checking its screen messages. + + + + Stage One, <filename>/boot/boot1</filename>, and Stage Two, + <filename>/boot/boot2</filename> + + Conceptually the first and second stages are part of the same + program, on the same area of the disk. Because of space constraints + they have been split into two, but you would always install them + together. They are copied from the combined file + /boot/boot by the installer or + bsdlabel (see below). + + They are located outside file systems, in the first track of + the boot slice, starting with the first sector. This is where boot0, or any other boot manager, + expects to find a program to run which will + continue the boot process. The number of sectors used is easily + determined from the size of /boot/boot. + + boot1 is very simple, since it + can only be 512 bytes + in size, and knows just enough about the FreeBSD + bsdlabel, which stores information + about the slice, to find and execute boot2. + + boot2 is slightly more sophisticated, and understands + the FreeBSD file system enough to find files on it, and can + provide a simple interface to choose the kernel or loader to + run. + + Since the loader is + much more sophisticated, and provides a nice easy-to-use + boot configuration, boot2 usually runs + it, but previously it + was tasked to run the kernel directly. + + + <filename>boot2</filename> Screenshot + + >> FreeBSD/i386 BOOT +Default: 0:ad(0,a)/boot/loader +boot: + + + If you ever need to replace the installed + boot1 and boot2 use + &man.bsdlabel.8;: + + &prompt.root; bsdlabel -B diskslice + + where diskslice is the disk and slice + you boot from, such as ad0s1 for the first + slice on the first IDE disk. + + + Dangerously Dedicated Mode + + If you use just the disk name, such as + ad0, in the &man.bsdlabel.8; command you + will create a dangerously dedicated disk, without slices. This is + almost certainly not what you want to do, so make sure you double + check the &man.bsdlabel.8; command before you press + Return. + + + + + Stage Three, <filename>/boot/loader</filename> + + boot-loader + The loader is the final stage of the three-stage + bootstrap, and is located on the file system, usually as + /boot/loader. + + The loader is intended as a user-friendly method for + configuration, using an easy-to-use built-in command set, + backed up by a more powerful interpreter, with a more complex + command set. + + + Loader Program Flow + + During initialization, the loader will probe for a + console and for disks, and figure out what disk it is + booting from. It will set variables accordingly, and an + interpreter is started where user commands can be passed from + a script or interactively. + loader + loader configuration + + The loader will then read + /boot/loader.rc, which by default reads + in /boot/defaults/loader.conf which + sets reasonable defaults for variables and reads + /boot/loader.conf for local changes to + those variables. loader.rc then acts + on these variables, loading whichever modules and kernel are + selected. + + Finally, by default, the loader issues a 10 second wait + for key presses, and boots the kernel if it is not interrupted. + If interrupted, the user is presented with a prompt which + understands the easy-to-use command set, where the user may + adjust variables, unload all modules, load modules, and then + finally boot or reboot. + + + + + Loader Built-In Commands + + These are the most commonly used loader commands. For a + complete discussion of all available commands, please see + &man.loader.8;. + + + + autoboot seconds + + + Proceeds to boot the kernel if not interrupted + within the time span given, in seconds. It displays a + countdown, and the default time span is 10 + seconds. + + + + + boot + -options + kernelname + + + Immediately proceeds to boot the kernel, with the + given options, if any, and with the kernel name given, + if it is. + + + + + boot-conf + + + Goes through the same automatic configuration of + modules based on variables as what happens at boot. + This only makes sense if you use + unload first, and change some + variables, most commonly kernel. + + + + + help + topic + + + Shows help messages read from + /boot/loader.help. If the topic + given is index, then the list of + available topics is given. + + + + + include filename + … + + + Processes the file with the given filename. The + file is read in, and interpreted line by line. An + error immediately stops the include command. + + + + load + type + filename + + + Loads the kernel, kernel module, or file of the + type given, with the filename given. Any arguments + after filename are passed to the file. + + + + ls + path + + + Displays a listing of files in the given path, or + the root directory, if the path is not specified. If + is specified, file sizes will be + shown too. + + + + lsdev + + + Lists all of the devices from which it may be + possible to load modules. If is + specified, more details are printed. + + + + + lsmod + + + Displays loaded modules. If is + specified, more details are shown. + + + + + more filename + + + Displays the files specified, with a pause at each + LINES displayed. + + + + + reboot + + + Immediately reboots the system. + + + + + set variable + set + variable=value + + + Sets the loader's environment variables. + + + + + unload + + + Removes all loaded modules. + + + + + + + Loader Examples + + Here are some practical examples of loader usage: + + + single-user mode + + To simply boot your usual kernel, but in single-user + mode: + + boot -s + + + + To unload your usual kernel and modules, and then + load just your old (or another) kernel: + + kernel.old + + + unload +load kernel.old + + You can use kernel.GENERIC to + refer to the generic kernel that comes on the install + disk, or kernel.old to refer to + your previously installed kernel (when you have upgraded + or configured your own kernel, for example). + + + Use the following to load your usual modules with + another kernel: + + unload +set kernel="kernel.old" +boot-conf + + + + To load a kernel configuration script (an automated + script which does the things you would normally do in the + kernel boot-time configurator): + + load -t userconfig_script /boot/kernel.conf + + + + + + + + Kernel Interaction During Boot + + kernel + boot interaction + + + Once the kernel is loaded by either loader (as usual) or boot2 (bypassing the loader), it + examines its boot flags, if any, and adjusts its behavior as + necessary. + + + + kernel + bootflags + + Kernel Boot Flags + + Here are the more common boot flags: + + + + + + + during kernel initialization, ask for the device + to mount as the root file system. + + + + + + + + boot from CDROM. + + + + + + + + run UserConfig, the boot-time kernel + configurator + + + + + + + + boot into single-user mode + + + + + + + + be more verbose during kernel startup + + + + + + There are other boot flags, read &man.boot.8; for more + information on them. + + + + + + + + + + Tom + Rhodes + Contributed by + + + + + + device.hints + + Device Hints + + This is a FreeBSD 5.0 and later feature which does not + exist in earlier versions. + + During initial system startup, the boot &man.loader.8; will read the + &man.device.hints.5; file. This file stores kernel boot information + known as variables, sometimes referred to as device hints. + These device hints are used by device drivers for device + configuration. + + Device hints may also be specified at the + Stage 3 boot loader prompt. Variables can be added using + set, removed with unset, and viewed + with the show commands. Variables set in the + /boot/device.hints file can be overridden here also. Device hints entered at + the boot loader are not permanent and will be forgotten on the next + reboot. + + Once the system is booted, the &man.kenv.1; command can be used to + dump all of the variables. + + The syntax for the /boot/device.hints file is one variable per line, using + the standard hash # as comment markers. Lines are + constructed as follows: + + hint.driver.unit.keyword="value" + + The syntax for the Stage 3 boot loader is: + set hint.driver.unit.keyword=value + + driver is the device driver name, unit + is the device driver unit number, and keyword is the hint + keyword. The keyword may consist of the following options: + + + + at: specifies the bus which the device is attached to. + + + + port: specifies the start address of the I/O + to be used. + + + + irq: specifies the interrupt request number to be used. + + + + drq: specifies the DMA channel number. + + + + maddr: specifies the physical memory address occupied by the + device. + + + + flags: sets various flag bits for the device. + + + + disabled: if set to 1 the device is disabled. + + + + Device drivers may accept (or require) more hints not listed here, viewing + their manual page is recommended. For more information, consult the + &man.device.hints.5;, &man.kenv.1;, &man.loader.conf.5;, and &man.loader.8; + manual pages. + + + + + init + + Init: Process Control Initialization + + Once the kernel has finished booting, it passes control to + the user process &man.init.8;, which is located at + /sbin/init, or the program path specified + in the init_path variable in + loader. + + + Automatic Reboot Sequence + + The automatic reboot sequence makes sure that the + file systems available on the system are consistent. If they + are not, and &man.fsck.8; cannot fix the + inconsistencies, &man.init.8; drops the system + into single-user mode + for the system administrator to take care of the problems + directly. + + + + Single-User Mode + single-user mode + console + + This mode can be reached through the automatic reboot + sequence, or by the user booting with the + option or setting the + boot_single variable in + loader. + + It can also be reached by calling + &man.shutdown.8; without the reboot + () or halt () options, + from multi-user + mode. + + If the system console is set + to insecure in /etc/ttys, + then the system prompts for the root password + before initiating single-user mode. + + + An Insecure Console in <filename>/etc/ttys</filename> + + # name getty type status comments +# +# If console is marked "insecure", then init will ask for the root password +# when going to single-user mode. +console none unknown off insecure + + + + An insecure console means that you + consider your physical security to the console to be + insecure, and want to make sure only someone who knows the + root password may use single-user mode, and it + does not mean that you want to run your console insecurely. Thus, + if you want security, choose insecure, + not secure. + + + + + Multi-User Mode + multi-user mode + + If &man.init.8; finds your file systems to be + in order, or once the user has finished in single-user mode, the + system enters multi-user mode, in which it starts the + resource configuration of the system. + + + rc files + Resource Configuration (rc) + + The resource configuration system reads in + configuration defaults from + /etc/defaults/rc.conf, and + system-specific details from + /etc/rc.conf, and then proceeds to + mount the system file systems mentioned in + /etc/fstab, start up networking + services, start up miscellaneous system daemons, and + finally runs the startup scripts of locally installed + packages. + + The &man.rc.8; manual page is a good reference to the resource + configuration system, as is examining the scripts + themselves. + + + + + + Shutdown Sequence + + shutdown + + + Upon controlled shutdown, via &man.shutdown.8;, + &man.init.8; will attempt to run the script + /etc/rc.shutdown, and then proceed to send + all processes the TERM signal, and subsequently + the KILL signal to any that do not terminate + timely. + + To power down a FreeBSD machine on architectures and systems + that support power management, simply use the command + shutdown -p now to turn the power off + immediately. To just reboot a FreeBSD system, just use + shutdown -r now. You need to be + root or a member of + operator group to run &man.shutdown.8;. + The &man.halt.8; and &man.reboot.8; commands can also be used, + please refer to their manual pages and to &man.shutdown.8;'s one + for more information. + + + Power management requires &man.acpi.4; support in the kernel + or loaded as module for. + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/chapter.decl b/pl_PL.ISO8859-2/books/handbook/chapter.decl new file mode 100644 index 0000000000..3aac7b965b --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/chapter.decl @@ -0,0 +1,2 @@ + + diff --git a/pl_PL.ISO8859-2/books/handbook/chapters.ent b/pl_PL.ISO8859-2/books/handbook/chapters.ent new file mode 100644 index 0000000000..476882f131 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/chapters.ent @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/colophon.sgml b/pl_PL.ISO8859-2/books/handbook/colophon.sgml new file mode 100644 index 0000000000..a3cc069be4 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/colophon.sgml @@ -0,0 +1,30 @@ + + + + Niniejsza ksi±¿ka jest dzie³em setek osób z Projektu + Dokumentacji FreeBSD. Tekst jest przygotowywany w jêzyku + SGML zgodnie ze standardem DocBook DTD, a nastêpnie konwertowany do + ca³ej rzeszy innych formatów za pomoc± modu³u DSSSL + Jade. Instrukcje formatowania tekstu + zosta³y przygotowane przy wykorzystaniu arkuszy styli DSSSL Norma + Walsha. Przygotowanie wersji do wydruku nie by³oby mo¿liwe gdyby nie + jêzyk sk³adu tekstu &tex; Donalda Knutha, + LaTeX Lesliego Lamporta, czy makra + JadeTeX Sebastiana Rahtza. + + + diff --git a/pl_PL.ISO8859-2/books/handbook/config/Makefile b/pl_PL.ISO8859-2/books/handbook/config/Makefile new file mode 100644 index 0000000000..40c8e11572 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/config/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= config/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/config/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/config/chapter.sgml new file mode 100644 index 0000000000..959bd62835 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/config/chapter.sgml @@ -0,0 +1,3223 @@ + + + + + + + Chern + Lee + Written by + + + + + Mike + Smith + Based on a tutorial written by + + + + + Matt + Dillon + Also based on tuning(7) written by + + + + + Configuration and Tuning + + + Synopsis + + system configuration + system optimization + + One of the important aspects of &os; is system configuration. + Correct system configuration will help prevent headaches during future upgrades. + This chapter will explain much of the &os; configuration process, + including some of the parameters which + can be set to tune a &os; system. + + + After reading this chapter, you will know: + + + + How to efficiently work with + file systems and swap partitions. + + + The basics of rc.conf configuration and + /usr/local/etc/rc.d startup systems. + + + How to configure and test a network card. + + + How to configure virtual hosts on your network devices. + + + How to use the various configuration files in + /etc. + + + How to tune &os; using sysctl + variables. + + + How to tune disk performance and modify kernel + limitations. + + + + Before reading this chapter, you should: + + + + Understand &unix; and &os; basics (). + + + Be familiar with the basics of kernel configuration/compilation + (). + + + + + + Initial Configuration + + + Partition Layout + + partition layout + + /etc + + + /var + + + /usr + + + + Base Partitions + + When laying out file systems with &man.bsdlabel.8; + or &man.sysinstall.8;, remember that hard + drives transfer data faster from the outer + tracks to the inner. + Thus smaller and heavier-accessed file systems + should be closer to the outside of the drive, while + larger partitions like /usr should be placed + toward the inner. It is a good idea to create + partitions in a similar order to: root, swap, + /var, /usr. + + The size of /var + reflects the intended machine usage. + /var is used to hold + mailboxes, log files, and printer spools. Mailboxes and log + files can grow to unexpected sizes depending + on how many users exist and how long log + files are kept. Most users would never require a gigabyte, + but remember that /var/tmp + must be large enough to contain packages. + + + The /usr partition holds much + of the files required to support the system, the &man.ports.7; + collection (recommended) and the source code (optional). Both + of which are optional at install time. + At least 2 gigabytes would be recommended for this partition. + + When selecting partition sizes, keep the space + requirements in mind. Running out of space in + one partition while barely using another can be a + hassle. + + Some users have found that &man.sysinstall.8;'s + Auto-defaults partition sizer will + sometimes select smaller than adequate /var + and / partitions. Partition wisely and + generously. + + + + + Swap Partition + + swap sizing + swap partition + + As a rule of thumb, the swap partition should be + about double the size of system memory (RAM). For example, + if the machine has 128 megabytes of memory, + the swap file should be 256 megabytes. Systems with + less memory may perform better with more swap. + Less than 256 megabytes of swap is not recommended and + memory expansion should be considered. + The kernel's VM paging algorithms are tuned to + perform best when the swap partition is at least two times the + size of main memory. Configuring too little swap can lead to + inefficiencies in the VM page scanning code and might create + issues later if more memory is added. + + On larger systems with multiple SCSI disks (or + multiple IDE disks operating on different controllers), it is + recommend that a swap is configured on each drive (up + to four drives). The swap partitions should be + approximately the same size. The kernel can handle arbitrary + sizes but internal data structures scale to 4 times the + largest swap partition. Keeping the swap partitions near the + same size will allow the kernel to optimally stripe swap space + across disks. + Large swap sizes are fine, even if swap is not + used much. It might be easier to recover + from a runaway program before being forced to reboot. + + + + Why Partition? + + Several users think a single large partition will be fine, + but there are several reasons why this is a bad idea. + First, each partition has different operational + characteristics and separating them allows the file system to + tune accordingly. For example, the root + and /usr partitions are read-mostly, without + much writing. While a lot of reading and writing could + occur in /var and + /var/tmp. + + By properly partitioning a system, fragmentation + introduced in the smaller write heavy partitions + will not bleed over into the mostly-read partitions. + Keeping the write-loaded partitions closer to + the disk's edge, + will + increase I/O performance in the partitions where it occurs + the most. Now while I/O + performance in the larger partitions may be needed, + shifting them more toward the edge of the disk will not + lead to a significant performance improvement over moving + /var to the edge. + Finally, there are safety concerns. A smaller, neater root + partition which is mostly read-only has a greater + chance of surviving a bad crash. + + + + + + + Core Configuration + + + rc files + rc.conf + + + The principal location for system configuration information + is within /etc/rc.conf. This file + contains a wide range of configuration information, principally + used at system startup to configure the system. Its name + directly implies this; it is configuration information for the + rc* files. + + An administrator should make entries in the + rc.conf file to + override the default settings from + /etc/defaults/rc.conf. The defaults file + should not be copied verbatim to /etc - it + contains default values, not examples. All system-specific + changes should be made in the rc.conf + file itself. + + A number of strategies may be applied in clustered + applications to separate site-wide configuration from + system-specific configuration in order to keep administration + overhead down. The recommended approach is to place site-wide + configuration into another file, + such as /etc/rc.conf.site, and then include + this file into /etc/rc.conf, which will + contain only system-specific information. + + As rc.conf is read by &man.sh.1; it is + trivial to achieve this. For example: + + + rc.conf: + . /etc/rc.conf.site + hostname="node15.example.com" + network_interfaces="fxp0 lo0" + ifconfig_fxp0="inet 10.1.1.1" + rc.conf.site: + defaultrouter="10.1.1.254" + saver="daemon" + blanktime="100" + + + The rc.conf.site file can then be + distributed to every system using rsync or a + similar program, while the rc.conf file + remains unique. + + Upgrading the system using &man.sysinstall.8; + or make world will not overwrite the + rc.conf + file, so system configuration information will not be lost. + + + + + Application Configuration + + Typically, installed applications have their own + configuration files, with their own syntax, etc. It is + important that these files be kept separate from the base + system, so that they may be easily located and managed by the + package management tools. + + /usr/local/etc + + Typically, these files are installed in + /usr/local/etc. In the case where an + application has a large number of configuration files, a + subdirectory will be created to hold them. + + Normally, when a port or package is installed, sample + configuration files are also installed. These are usually + identified with a .default suffix. If there + are no existing + configuration files for the application, they will be created by + copying the .default files. + + For example, consider the contents of the directory + /usr/local/etc/apache: + +-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf +-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default +-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf +-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default +-rw-r--r-- 1 root wheel 12205 May 20 1998 magic +-rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default +-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types +-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default +-rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf +-rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default + + The file sizes show that only the srm.conf + file has been changed. A later update of the Apache port would not + overwrite this changed file. + + + + + + + + Tom + Rhodes + Contributed by + + + + + Starting Services + + services + + Many users choose to install third party software on &os; + from the Ports Collection. In many of these situations it + may be necessary to configure the software in a manner which + will allow it to be started upon system initialization. Services, + such as mail/postfix or + www/apache13 are just two + of the many software packages which may be started during system + initialization. This section explains the procedures available + for starting third party software. + + In &os;, most included services, such as &man.cron.8;, are + started through the system start up scripts. These scripts may + differ depending on &os; or vendor version; however, the most + important aspect to consider is that their start up configuration + can be handled through simple startup scripts. + + Before the advent of rc.d, applications would drop a + simple start up script into the + /usr/local/etc/rc.d + directory which would be read by the system initialization + scripts. These scripts would then be executed during the latter + stages of system start up. + + While many individuals have spent hours trying to merge the + old configuration style into the new system, the fact remains + that some third party utilities still require a script simply + dropped into the aforementioned directory. The subtle differences + in the scripts depend whether or not rc.d is being used. Prior + to &os; 5.1 the old configuration style is used and in + almost all cases a new style script would do just fine. + + While every script must meet some minimal requirements, most + of the time these requirements are &os; version + agnostic. Each script must have a .sh + extension appended to the end and every script must be + executable by the system. The latter may be achieved by using + the chmod command and setting the unique permissions + of 755. There should also be, at minimal, + an option to start the application and an + option to stop the application. + + The simplest start up script would probably look a little + bit like this one: + + #!/bin/sh +echo -n ' utility' + +case "$1" in +start) + /usr/local/bin/utility + ;; +stop) + kill -9 `cat /var/run/utility.pid` + ;; +*) + echo "Usage: `basename $0` {start|stop}" >&2 + exit 64 + ;; +esac + +exit 0 + + This script provides for a stop and + start option for + the application hereto referred simply as + utility. + + Could be started manually with: + + &prompt.root; /usr/local/etc/rc.d/utility.sh start + + While not all third party software requires the line in + rc.conf, almost every day a new port will + be modified to accept this configuration. Check the final output + of the installation for more information on a specific + application. Some third party software will provide start up + scripts which permit the application to be used with + rc.d; although, this will be discussed in the next section. + + + Extended Application Configuration + + Now that &os; includes rc.d, configuration + of application startup has become easier, and more + featureful. Using the key words discussed in the + rc.d section, + applications may now be set to start after certain other + services for example DNS; may permit extra + flags to be passed through rc.conf in + place of hard coded flags in the start up script, etc. A + basic script may look similar to the following: + + #!/bin/sh +# +# PROVIDE: utility +# REQUIRE: DAEMON +# KEYWORD: shutdown + +# +# DO NOT CHANGE THESE DEFAULT VALUES HERE +# SET THEM IN THE /etc/rc.conf FILE +# +utility_enable=${utility_enable-"NO"} +utility_flags=${utility_flags-""} +utility_pidfile=${utility_pidfile-"/var/run/utility.pid"} + +. /etc/rc.subr + +name="utility" +rcvar=`set_rcvar` +command="/usr/local/sbin/utility" + +load_rc_config $name + +pidfile="${utility_pidfile}" + +start_cmd="echo \"Starting ${name}.\"; /usr/bin/nice -5 ${command} ${utility_flags} ${command_args}" + +run_rc_command "$1" + + This script will ensure that the provided + utility will be started after the + daemon service. It also provides a method + for setting and tracking the PID, or process + ID file. + + This application could then have the following line placed + in /etc/rc.conf: + + utility_enable="YES" + + This new method also allows for easier manipulation of the + command line arguments, inclusion of the default functions + provided in /etc/rc.subr, compatibility + with the &man.rcorder.8; utility and provides for easier + configuration via the rc.conf file. + + + + Using Services to Start Services + + Other services, such as POP3 server + daemons, IMAP, etc. could be started using + the &man.inetd.8;. This involves installing the service + utility from the Ports Collection with a configuration line + appended to the /etc/inetd.conf file, + or uncommenting one of the current configuration lines. Working + with inetd and its configuration is + described in depth in the + inetd section. + + In some cases, it may be more plausible to use the + &man.cron.8; daemon to start system services. This approach + has a number of advantages because cron runs + these processes as the crontab's file + owner. This allows regular users to start and maintain some + applications. + + The cron utility provides a unique + feature, @reboot, which may be used in place + of the time specification. This will cause the job to be run + when &man.cron.8; is started, normally during system + initialization. + + + + + + + + + Tom + Rhodes + Contributed by + + + + + Configuring the <command>cron</command> Utility + + cron + configuration + + One of the most useful utilities in &os; is &man.cron.8;. The + cron utility runs in the background and constantly + checks the /etc/crontab file. The cron + utility also checks the /var/cron/tabs directory, in + search of new crontab files. These + crontab files store information about specific + functions which cron is supposed to perform at + certain times. + + The cron utility uses two different + types of configuration files, the system crontab and user crontabs. The + only difference between these two formats is the sixth field. In the + system crontab, the sixth field is the name of a user for the command + to run as. This gives the system crontab the ability to run commands + as any user. In a user crontab, the sixth field is the command to run, + and all commands run as the user who created the crontab; this is an + important security feature. + + + User crontabs allow individual users to schedule tasks without the + need for root privileges. Commands in a user's crontab run with the + permissions of the user who owns the crontab. + + The root user can have a user crontab just like + any other user. This one is different from + /etc/crontab (the system crontab). Because of the + system crontab, there is usually no need to create a user crontab + for root. + + + Let us take a look at the /etc/crontab file + (the system crontab): + + + # /etc/crontab - root's crontab for &os; +# +# $&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp $ +# +# +SHELL=/bin/sh +PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin +HOME=/var/log +# +# +#minute hour mday month wday who command +# +# +*/5 * * * * root /usr/libexec/atrun + + + + + Like most &os; configuration files, the # + character represents a comment. A comment can be placed in + the file as a reminder of what and why a desired action is performed. + Comments cannot be on the same line as a command or else they will + be interpreted as part of the command; they must be on a new line. + Blank lines are ignored. + + + + First, the environment must be defined. The equals + (=) character is used to define any environment + settings, as with this example where it is used for the SHELL, + PATH, and HOME options. If the shell line is + omitted, cron will use the default, which is + sh. If the PATH variable is + omitted, no default will be used and file locations will need to + be absolute. If HOME is omitted, cron + will use the invoking users home directory. + + + + This line defines a total of seven fields. Listed here are the + values minute, hour, + mday, month, wday, + who, and command. These + are almost all self explanatory. minute is the time in minutes the + command will be run. hour is similar to the minute option, just in + hours. mday stands for day of the month. month is similar to hour + and minute, as it designates the month. The wday option stands for + day of the week. All these fields must be numeric values, and follow + the twenty-four hour clock. The who field is special, + and only exists in the /etc/crontab file. + This field specifies which user the command should be run as. + When a user installs his or her crontab file, they + will not have this option. Finally, the command option is listed. + This is the last field, so naturally it should designate the command + to be executed. + + + + This last line will define the values discussed above. Notice here + we have a */5 listing, followed by several more + * characters. These * characters + mean first-last, and can be interpreted as + every time. So, judging by this line, + it is apparent that the atrun command is to be invoked by + root every five minutes regardless of what + day or month it is. For more information on the atrun command, + see the &man.atrun.8; manual page. + + Commands can have any number of flags passed to them; however, + commands which extend to multiple lines need to be broken with the backslash + \ continuation character. + + + + This is the basic set up for every + crontab file, although there is one thing + different about this one. Field number six, where we specified + the username, only exists in the system + /etc/crontab file. This field should be + omitted for individual user crontab + files. + + + + Installing a Crontab + + + You must not use the procedure described here to + edit/install the system crontab. Simply use your favorite + editor: the cron utility will notice that the file + has changed and immediately begin using the updated version. + See + + this FAQ entry for more information. + + + To install a freshly written user + crontab, first use your favorite editor to create + a file in the proper format, and then use the + crontab utility. The most common usage + is: + + &prompt.user; crontab crontab-file + + In this example, crontab-file is the filename + of a crontab that was previously created. + + There is also an option to list installed + crontab files: just pass the + option to crontab and look + over the output. + + For users who wish to begin their own crontab file from scratch, + without the use of a template, the crontab -e + option is available. This will invoke the selected editor + with an empty file. When the file is saved, it will be + automatically installed by the crontab command. + + + If you later want to remove your user crontab + completely, use crontab with the + option. + + + + + + + + + + Tom + Rhodes + Contributed by + + + + + + Using rc under &os; + + In 2002 &os; integrated the NetBSD + rc.d system for system initialization. + Users should notice the files listed in the + /etc/rc.d directory. Many of these files + are for basic services which can be controlled with the + , , + and options. + For instance, &man.sshd.8; can be restarted with the following + command: + + &prompt.root; /etc/rc.d/sshd restart + + This procedure is similar for other services. Of course, + services are usually started automatically at boot time as specified in + &man.rc.conf.5;. For example, enabling the Network Address + Translation daemon at startup is as simple as adding the + following line to /etc/rc.conf: + + natd_enable="YES" + + If a line is already + present, then simply change the to + . The rc scripts will automatically load + any other dependent services during the next reboot, as + described below. + + Since the rc.d system is primarily + intended to start/stop services at system startup/shutdown time, + the standard , + and options will only + perform their action if the appropriate + /etc/rc.conf variables are set. For + instance the above sshd restart command will + only work if sshd_enable is set to + in /etc/rc.conf. To + , or + a service regardless of the settings in + /etc/rc.conf, the commands should be + prefixed with force. For instance to restart + sshd regardless of the current + /etc/rc.conf setting, execute the following + command: + + &prompt.root; /etc/rc.d/sshd forcerestart + + It is easy to check if a service is enabled in + /etc/rc.conf by running the appropriate + rc.d script with the option + . Thus, an administrator can check that + sshd is in fact enabled in + /etc/rc.conf by running: + + &prompt.root; /etc/rc.d/sshd rcvar +# sshd +$sshd_enable=YES + + + The second line (# sshd) is the output + from the sshd command, not a root + console. + + + To determine if a service is running, a + option is available. For instance to + verify that sshd is actually started: + + &prompt.root; /etc/rc.d/sshd status +sshd is running as pid 433. + + In some cases it is also possible to a service. + This will attempt to send a signal to an individual service, forcing the + service to reload its configuration files. In most cases this + means sending the service a SIGHUP + signal. Support for this feature is not included for every service. + + The rc.d system is not only used for network services, it also + contributes to most of the system initialization. For + instance, consider the bgfsck file. When + this script is executed, it will print out the following + message: + + Starting background file system checks in 60 seconds. + + Therefore this file is used for background file system + checks, which are done only during system initialization. + + Many system services depend on other services to function + properly. For example, NIS and other RPC-based services may + fail to start until after the rpcbind + (portmapper) service has started. To resolve this issue, + information about dependencies and other meta-data is included + in the comments at the top of each startup script. The + &man.rcorder.8; program is then used to parse these comments + during system initialization to determine the order in which + system services should be invoked to satisfy the dependencies. + The following words may be included at the top of each startup + file: + + + + PROVIDE: Specifies the services this file provides. + + + + REQUIRE: Lists services which are required for this + service. This file will run after + the specified services. + + + + BEFORE: Lists services which depend on this service. + This file will run before + the specified services. + + + + By using this method, an administrator can easily control system + services without the hassle of runlevels like + some other &unix; operating systems. + + Additional information about the + rc.d system can be found in the &man.rc.8; + and &man.rc.subr.8; manual pages. + + + + + + + Marc + Fonvieille + Contributed by + + + + + + Setting Up Network Interface Cards + + + network cards + configuration + + + Nowadays we can not think about a computer without thinking + about a network connection. Adding and configuring a network + card is a common task for any &os; administrator. + + + Locating the Correct Driver + + + network cards + driver + + + Before you begin, you should know the model of the card + you have, the chip it uses, and whether it is a PCI or ISA card. + &os; supports a wide variety of both PCI and ISA cards. + Check the Hardware Compatibility List for your release to see + if your card is supported. + + Once you are sure your card is supported, you need + to determine the proper driver for the card. + /usr/src/sys/conf/NOTES and + /usr/src/sys/arch/conf/NOTES will give you + the list of network interface drivers with some information + about the supported chipsets/cards. If you have doubts about + which driver is the correct one, read the manual page of the + driver. The manual page will give you more information about + the supported hardware and even the possible problems that + could occur. + + If you own a common card, most of the time you will not + have to look very hard for a driver. Drivers for common + network cards are present in the GENERIC + kernel, so your card should show up during boot, like so: + +dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38 +000ff irq 15 at device 11.0 on pci0 +dc0: Ethernet address: 00:a0:cc:da:da:da +miibus0: <MII bus> on dc0 +ukphy0: <Generic IEEE 802.3u media interface> on miibus0 +ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto +dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30 +000ff irq 11 at device 12.0 on pci0 +dc1: Ethernet address: 00:a0:cc:da:da:db +miibus1: <MII bus> on dc1 +ukphy1: <Generic IEEE 802.3u media interface> on miibus1 +ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto + + In this example, we see that two cards using the &man.dc.4; + driver are present on the system. + + If the driver for your NIC is not present in + GENERIC, you will need to load the proper + driver to use your NIC. This may be accomplished in one of + two ways: + + + + The easiest way is to simply load a kernel module for + your network card with &man.kldload.8;, or automatically at boot time by adding the appropriate line to the file /boot/loader.conf. Not all NIC + drivers are available as modules; notable examples of + devices for which modules do not exist are ISA cards. + + + + Alternatively, you may statically compile the support + for your card into your kernel. Check + /usr/src/sys/conf/NOTES, + /usr/src/sys/arch/conf/NOTES + and the manual page of the driver to know what to add in + your kernel configuration file. For more information + about recompiling your kernel, please see . If your card was detected at + boot by your kernel (GENERIC) you do + not have to build a new kernel. + + + + + Using &windows; NDIS Drivers + + NDIS + NDISulator + &windows; drivers + Microsoft Windows + Microsoft Windows + device drivers + KLD (kernel loadable + object) + + + Unfortunately, there are still many vendors that do not + provide schematics for their drivers to the open source + community because they regard such information as trade + secrets. Consequently, the developers of &os; and other + operating systems are left two choices: develop the drivers + by a long and pain-staking process of reverse engineering or + using the existing driver binaries available for the + µsoft.windows; platforms. Most developers, including + those involved with &os;, have taken the latter + approach. + + Thanks to the contributions of Bill Paul (wpaul), as of + &os; 5.3-RELEASE there is native support + for the Network Driver Interface Specification (NDIS). The + &os; NDISulator (otherwise known as Project Evil) takes a + &windows; driver binary and basically tricks it into + thinking it is running on &windows;. Because the + &man.ndis.4; driver is using a &windows; binary, it is only + usable on &i386; and amd64 systems. + + + The &man.ndis.4; driver is designed to support mainly + PCI, CardBus and PCMCIA devices, USB devices are not yet + supported. + + + In order to use the NDISulator, you need three + things: + + + + Kernel sources + + + &windowsxp; driver binary + (.SYS extension) + + + &windowsxp; driver configuration file + (.INF extension) + + + + Locate the files for your specific card. Generally, + they can be found on the included CDs or at the vendors' + websites. In the following examples, we will use + W32DRIVER.SYS and + W32DRIVER.INF. + + + You can not use a &windows;/i386 driver with + &os;/amd64, you must get a &windows;/amd64 driver to make it + work properly. + + + The next step is to compile the driver binary into a + loadable kernel module. To accomplish this, as + root, use &man.ndisgen.8;: + + &prompt.root; ndisgen /path/to/W32DRIVER.INF /path/to/W32DRIVER.SYS + + The &man.ndisgen.8; utility is interactive and will + prompt for any extra information it requires; it will + produce a kernel module in the current directory which can + be loaded as follows: + + &prompt.root; kldload ./W32DRIVER.ko + + In addition to the generated kernel module, you must + load the ndis.ko and + if_ndis.ko modules. This should be + automatically done when you load any module that depends on + &man.ndis.4;. If you want to load them manually, use the + following commands: + + &prompt.root; kldload ndis +&prompt.root; kldload if_ndis + + The first command loads the NDIS miniport driver + wrapper, the second loads the actual network + interface. + + Now, check &man.dmesg.8; to see if there were any errors + loading. If all went well, you should get output resembling + the following: + + ndis0: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1 +ndis0: NDIS API version: 5.0 +ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5 +ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps +ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps + + From here you can treat the + ndis0 device like any other network + interface (e.g., dc0). + + You can configure the system to load the NDIS modules at + boot time in the same way as with any other module. First, + copy the generated module, + W32DRIVER.ko, to the /boot/modules directory. Then, + add the following line to + /boot/loader.conf: + + W32DRIVER_load="YES" + + + + + Configuring the Network Card + + + network cards + configuration + + + Once the right driver is loaded for the network card, the + card needs to be configured. As with many other things, the + network card may have been configured at installation time by + sysinstall. + + To display the configuration for the network interfaces on + your system, enter the following command: + +&prompt.user; ifconfig +dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255 + ether 00:a0:cc:da:da:da + media: Ethernet autoselect (100baseTX <full-duplex>) + status: active +dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255 + ether 00:a0:cc:da:da:db + media: Ethernet 10baseT/UTP + status: no carrier +lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 + inet 127.0.0.1 netmask 0xff000000 +tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 + + + Old versions of &os; may require the + option following &man.ifconfig.8;, for more details about the + correct syntax of &man.ifconfig.8;, please refer to the manual + page. Note also that entries concerning IPv6 + (inet6 etc.) were omitted in this + example. + + + In this example, the following devices were + displayed: + + + + dc0: The first Ethernet + interface + + + + dc1: The second Ethernet + interface + + + + lp0: The parallel port + interface + + + + lo0: The loopback device + + + + tun0: The tunnel device used by + ppp + + + + &os; uses the driver name followed by the order in + which one the card is detected at the kernel boot to name the + network card. For example sis2 would + be the third network card on the system using the &man.sis.4; + driver. + + In this example, the dc0 device is + up and running. The key indicators are: + + + + UP means that the card is configured + and ready. + + + + The card has an Internet (inet) + address (in this case + 192.168.1.3). + + + + It has a valid subnet mask (netmask; + 0xffffff00 is the same as + 255.255.255.0). + + + + It has a valid broadcast address (in this case, + 192.168.1.255). + + + + The MAC address of the card (ether) + is 00:a0:cc:da:da:da + + + + The physical media selection is on autoselection mode + (media: Ethernet autoselect (100baseTX + <full-duplex>)). We see that + dc1 was configured to run with + 10baseT/UTP media. For more + information on available media types for a driver, please + refer to its manual page. + + + + The status of the link (status) + is active, i.e. the carrier is detected. + For dc1, we see + status: no carrier. This is normal when + an Ethernet cable is not plugged into the card. + + + + If the &man.ifconfig.8; output had shown something similar + to: + +dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 + ether 00:a0:cc:da:da:da + + it would indicate the card has not been configured. + + To configure your card, you need root + privileges. The network card configuration can be done from the + command line with &man.ifconfig.8; but you would have to do it + after each reboot of the system. The file + /etc/rc.conf is where to add the network + card's configuration. + + Open /etc/rc.conf in your favorite + editor. You need to add a line for each network card present on + the system, for example in our case, we added these lines: + +ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0" +ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP" + + You have to replace dc0, + dc1, and so on, with + the correct device for your cards, and the addresses with the + proper ones. You should read the card driver and + &man.ifconfig.8; manual pages for more details about the allowed + options and also &man.rc.conf.5; manual page for more + information on the syntax of + /etc/rc.conf. + + If you configured the network during installation, some + lines about the network card(s) may be already present. Double + check /etc/rc.conf before adding any + lines. + + You will also have to edit the file + /etc/hosts to add the names and the IP + addresses of various machines of the LAN, if they are not already + there. For more information please refer to &man.hosts.5; + and to /usr/share/examples/etc/hosts. + + + + Testing and Troubleshooting + + Once you have made the necessary changes in + /etc/rc.conf, you should reboot your + system. This will allow the change(s) to the interface(s) to + be applied, and verify that the system restarts without any + configuration errors. + + Once the system has been rebooted, you should test the + network interfaces. + + + Testing the Ethernet Card + + + network cards + testing + + + To verify that an Ethernet card is configured correctly, + you have to try two things. First, ping the interface itself, + and then ping another machine on the LAN. + + First test the local interface: + +&prompt.user; ping -c5 192.168.1.3 +PING 192.168.1.3 (192.168.1.3): 56 data bytes +64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms +64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms +64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms +64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms +64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms + +--- 192.168.1.3 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms + + Now we have to ping another machine on the LAN: + +&prompt.user; ping -c5 192.168.1.2 +PING 192.168.1.2 (192.168.1.2): 56 data bytes +64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms +64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms +64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms +64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms +64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms + +--- 192.168.1.2 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms + + You could also use the machine name instead of + 192.168.1.2 if you have set up the + /etc/hosts file. + + + + Troubleshooting + + + network cards + troubleshooting + + + Troubleshooting hardware and software configurations is always + a pain, and a pain which can be alleviated by checking the simple + things first. Is your network cable plugged in? Have you properly + configured the network services? Did you configure the firewall + correctly? Is the card you are using supported by &os;? Always + check the hardware notes before sending off a bug report. Update + your version of &os; to the latest STABLE version. Check the + mailing list archives, or perhaps search the Internet. + + If the card works, yet performance is poor, it would be + worthwhile to read over the &man.tuning.7; manual page. You + can also check the network configuration as incorrect network + settings can cause slow connections. + + Some users experience one or two device + timeout messages, which is normal for some cards. If they + continue, or are bothersome, you may wish to be sure the + device is not conflicting with another device. Double check + the cable connections. Perhaps you may just need to get + another card. + + At times, users see a few watchdog timeout + errors. The first thing to do here is to check your network + cable. Many cards require a PCI slot which supports Bus + Mastering. On some old motherboards, only one PCI slot allows + it (usually slot 0). Check the network card and the + motherboard documentation to determine if that may be the + problem. + + No route to host messages occur if the + system is unable to route a packet to the destination host. + This can happen if no default route is specified, or if a + cable is unplugged. Check the output of netstat + -rn and make sure there is a valid route to the host + you are trying to reach. If there is not, read on to . + + ping: sendto: Permission denied error + messages are often caused by a misconfigured firewall. If + ipfw is enabled in the kernel but no rules + have been defined, then the default policy is to deny all + traffic, even ping requests! Read on to for more information. + + Sometimes performance of the card is poor, or below average. + In these cases it is best to set the media selection mode + from autoselect to the correct media selection. + While this usually works for most hardware, it may not resolve + this issue for everyone. Again, check all the network settings, + and read over the &man.tuning.7; manual page. + + + + + + + Virtual Hosts + + virtual hosts + IP aliases + + A very common use of &os; is virtual site hosting, where + one server appears to the network as many servers. This is + achieved by assigning multiple network addresses to a single + interface. + + A given network interface has one real address, + and may have any number of alias addresses. + These aliases are + normally added by placing alias entries in + /etc/rc.conf. + + An alias entry for the interface fxp0 + looks like: + +ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx" + + Note that alias entries must start with alias0 and proceed + upwards in order, (for example, _alias1, _alias2, and so on). + The configuration process will stop at the first missing number. + + + The calculation of alias netmasks is important, but + fortunately quite simple. For a given interface, there must be + one address which correctly represents the network's netmask. + Any other addresses which fall within this network must have a + netmask of all 1s (expressed as either + 255.255.255.255 or 0xffffffff). + + + For example, consider the case where the + fxp0 interface is + connected to two networks, the 10.1.1.0 + network with a netmask of 255.255.255.0 + and the 202.0.75.16 network with + a netmask of 255.255.255.240. + We want the system to appear at 10.1.1.1 + through 10.1.1.5 and at + 202.0.75.17 through + 202.0.75.20. As noted above, only the + first address in a given network range (in this case, + 10.0.1.1 and + 202.0.75.17) should have a real + netmask; all the rest (10.1.1.2 + through 10.1.1.5 and + 202.0.75.18 through + 202.0.75.20) must be configured with a + netmask of 255.255.255.255. + + The following /etc/rc.conf entries + configure the adapter correctly for this arrangement: + + ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" +ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" +ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" +ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" +ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" +ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" +ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" +ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" +ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255" + + + + + Configuration Files + + + <filename>/etc</filename> Layout + There are a number of directories in which configuration + information is kept. These include: + + + + + + + + + /etc + Generic system configuration information; data here is + system-specific. + + + /etc/defaults + Default versions of system configuration files. + + + /etc/mail + Extra &man.sendmail.8; configuration, other + MTA configuration files. + + + + /etc/ppp + Configuration for both user- and kernel-ppp programs. + + + + /etc/namedb + Default location for &man.named.8; data. Normally + named.conf and zone files are stored + here. + + + /usr/local/etc + Configuration files for installed applications. + May contain per-application subdirectories. + + + /usr/local/etc/rc.d + Start/stop scripts for installed applications. + + + /var/db + Automatically generated system-specific database files, + such as the package database, the locate database, and so + on + + + + + + + + Hostnames + + hostname + DNS + + + <filename>/etc/resolv.conf</filename> + + + resolv.conf + + + /etc/resolv.conf dictates how &os;'s + resolver accesses the Internet Domain Name System (DNS). + + The most common entries to resolv.conf are: + + + + + + + + + + nameserver + The IP address of a name server the resolver + should query. The servers are queried in the order + listed with a maximum of three. + + + search + Search list for hostname lookup. This is normally + determined by the domain of the local hostname. + + + domain + The local domain name. + + + + + + A typical resolv.conf: + + search example.com +nameserver 147.11.1.11 +nameserver 147.11.100.30 + + Only one of the search and + domain options should be used. + + If you are using DHCP, &man.dhclient.8; usually rewrites + resolv.conf with information received from the + DHCP server. + + + + <filename>/etc/hosts</filename> + + hosts + + /etc/hosts is a simple text + database reminiscent of the old Internet. It works in + conjunction with DNS and NIS providing name to IP address + mappings. Local computers connected via a LAN can be placed + in here for simplistic naming purposes instead of setting up + a &man.named.8; server. Additionally, + /etc/hosts can be used to provide a + local record of Internet names, reducing the need to query + externally for commonly accessed names. + + # $&os;$ +# +# Host Database +# This file should contain the addresses and aliases +# for local hosts that share this file. +# In the presence of the domain name service or NIS, this file may +# not be consulted at all; see /etc/nsswitch.conf for the resolution order. +# +# +::1 localhost localhost.my.domain myname.my.domain +127.0.0.1 localhost localhost.my.domain myname.my.domain + +# +# Imaginary network. +#10.0.0.2 myname.my.domain myname +#10.0.0.3 myfriend.my.domain myfriend +# +# According to RFC 1918, you can use the following IP networks for +# private nets which will never be connected to the Internet: +# +# 10.0.0.0 - 10.255.255.255 +# 172.16.0.0 - 172.31.255.255 +# 192.168.0.0 - 192.168.255.255 +# +# In case you want to be able to connect to the Internet, you need +# real official assigned numbers. PLEASE PLEASE PLEASE do not try +# to invent your own network numbers but instead get one from your +# network provider (if any) or from the Internet Registry (ftp to +# rs.internic.net, directory `/templates'). +# + + /etc/hosts takes on the simple format + of: + + [Internet address] [official hostname] [alias1] [alias2] ... + + For example: + + 10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2 + + Consult &man.hosts.5; for more information. + + + + + Log File Configuration + + log files + + + <filename>syslog.conf</filename> + + syslog.conf + + syslog.conf is the configuration file + for the &man.syslogd.8; program. It indicates which types + of syslog messages are logged to particular + log files. + + # $&os;$ +# +# Spaces ARE valid field separators in this file. However, +# other *nix-like systems still insist on using tabs as field +# separators. If you are sharing this file between systems, you +# may want to use only tabs as field separators here. +# Consult the syslog.conf(5) manual page. +*.err;kern.debug;auth.notice;mail.crit /dev/console +*.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages +security.* /var/log/security +mail.info /var/log/maillog +lpr.info /var/log/lpd-errs +cron.* /var/log/cron +*.err root +*.notice;news.err root +*.alert root +*.emerg * +# uncomment this to log all writes to /dev/console to /var/log/console.log +#console.info /var/log/console.log +# uncomment this to enable logging of all log messages to /var/log/all.log +#*.* /var/log/all.log +# uncomment this to enable logging to a remote log host named loghost +#*.* @loghost +# uncomment these if you're running inn +# news.crit /var/log/news/news.crit +# news.err /var/log/news/news.err +# news.notice /var/log/news/news.notice +!startslip +*.* /var/log/slip.log +!ppp +*.* /var/log/ppp.log + + Consult the &man.syslog.conf.5; manual page for more + information. + + + + <filename>newsyslog.conf</filename> + + newsyslog.conf + + newsyslog.conf is the configuration + file for &man.newsyslog.8;, a program that is normally scheduled + to run by &man.cron.8;. &man.newsyslog.8; determines when log + files require archiving or rearranging. + logfile is moved to + logfile.0, logfile.0 + is moved to logfile.1, and so on. + Alternatively, the log files may be archived in &man.gzip.1; format + causing them to be named: logfile.0.gz, + logfile.1.gz, and so on. + + newsyslog.conf indicates which log + files are to be managed, how many are to be kept, and when + they are to be touched. Log files can be rearranged and/or + archived when they have either reached a certain size, or at a + certain periodic time/date. + + # configuration file for newsyslog +# $&os;$ +# +# filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num] +/var/log/cron 600 3 100 * Z +/var/log/amd.log 644 7 100 * Z +/var/log/kerberos.log 644 7 100 * Z +/var/log/lpd-errs 644 7 100 * Z +/var/log/maillog 644 7 * @T00 Z +/var/log/sendmail.st 644 10 * 168 B +/var/log/messages 644 5 100 * Z +/var/log/all.log 600 7 * @T00 Z +/var/log/slip.log 600 3 100 * Z +/var/log/ppp.log 600 3 100 * Z +/var/log/security 600 10 100 * Z +/var/log/wtmp 644 3 * @01T05 B +/var/log/daily.log 640 7 * @T00 Z +/var/log/weekly.log 640 5 1 $W6D0 Z +/var/log/monthly.log 640 12 * $M1D0 Z +/var/log/console.log 640 5 100 * Z + + Consult the &man.newsyslog.8; manual page for more + information. + + + + + <filename>sysctl.conf</filename> + + sysctl.conf + sysctl + + sysctl.conf looks much like + rc.conf. Values are set in a + variable=value + form. The specified values are set after the system goes into + multi-user mode. Not all variables are settable in this mode. + + A sample sysctl.conf turning off logging + of fatal signal exits and letting Linux programs know they are really + running under &os;: + + kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11) +compat.linux.osname=&os; +compat.linux.osrelease=4.3-STABLE + + + + + Tuning with sysctl + + sysctl + + tuning + with sysctl + + + &man.sysctl.8; is an interface that allows you to make changes + to a running &os; system. This includes many advanced + options of the TCP/IP stack and virtual memory system that can + dramatically improve performance for an experienced system + administrator. Over five hundred system variables can be read + and set using &man.sysctl.8;. + + At its core, &man.sysctl.8; serves two functions: to read and + to modify system settings. + + To view all readable variables: + + &prompt.user; sysctl -a + + To read a particular variable, for example, + kern.maxproc: + + &prompt.user; sysctl kern.maxproc +kern.maxproc: 1044 + + To set a particular variable, use the intuitive + variable=value + syntax: + + &prompt.root; sysctl kern.maxfiles=5000 +kern.maxfiles: 2088 -> 5000 + + Settings of sysctl variables are usually either strings, + numbers, or booleans (a boolean being 1 for yes + or a 0 for no). + + If you want to set automatically some variables each time + the machine boots, add them to the + /etc/sysctl.conf file. For more information + see the &man.sysctl.conf.5; manual page and the + . + + + + + + Tom + Rhodes + Contributed by + + + + + &man.sysctl.8; Read-only + + In some cases it may be desirable to modify read-only &man.sysctl.8; + values. While this is sometimes unavoidable, it can only be done + on (re)boot. + + For instance on some laptop models the &man.cardbus.4; device will + not probe memory ranges, and fail with errors which look similar to: + + cbb0: Could not map register memory +device_probe_and_attach: cbb0 attach returned 12 + + Cases like the one above usually require the modification of some + default &man.sysctl.8; settings which are set read only. To overcome + these situations a user can put &man.sysctl.8; OIDs + in their local /boot/loader.conf. Default + settings are located in the /boot/defaults/loader.conf + file. + + Fixing the problem mentioned above would require a user to set + in the aforementioned + file. Now &man.cardbus.4; will work properly. + + + + + + Tuning Disks + + + Sysctl Variables + + + <varname>vfs.vmiodirenable</varname> + + + vfs.vmiodirenable + + + The vfs.vmiodirenable sysctl variable + may be set to either 0 (off) or 1 (on); it is 1 by default. + This variable controls how directories are cached by the + system. Most directories are small, using just a single + fragment (typically 1 K) in the file system and less + (typically 512 bytes) in the buffer cache. + With this variable turned off (to 0), the buffer + cache will only cache a fixed number of directories even if + you have a huge amount of memory. When turned on (to 1), this sysctl + allows the buffer cache to use the VM Page Cache to cache the + directories, making all the memory available for caching + directories. However, + the minimum in-core memory used to cache a directory is the + physical page size (typically 4 K) rather than 512  + bytes. We recommend keeping this option on if you are running + any services which manipulate large numbers of files. Such + services can include web caches, large mail systems, and news + systems. Keeping this option on will generally not reduce + performance even with the wasted memory but you should + experiment to find out. + + + + <varname>vfs.write_behind</varname> + + + vfs.write_behind + + + The vfs.write_behind sysctl variable + defaults to 1 (on). This tells the file system + to issue media writes as full clusters are collected, which + typically occurs when writing large sequential files. The idea + is to avoid saturating the buffer cache with dirty buffers when + it would not benefit I/O performance. However, this may stall + processes and under certain circumstances you may wish to turn it + off. + + + + <varname>vfs.hirunningspace</varname> + + + vfs.hirunningspace + + + The vfs.hirunningspace sysctl variable + determines how much outstanding write I/O may be queued to disk + controllers system-wide at any given instance. The default is + usually sufficient but on machines with lots of disks you may + want to bump it up to four or five megabytes. + Note that setting too high a value (exceeding the buffer cache's + write threshold) can lead to extremely bad clustering + performance. Do not set this value arbitrarily high! Higher + write values may add latency to reads occurring at the same time. + + + There are various other buffer-cache and VM page cache + related sysctls. We do not recommend modifying these values, + the VM system does an extremely good job of + automatically tuning itself. + + + + <varname>vm.swap_idle_enabled</varname> + + + vm.swap_idle_enabled + + + The vm.swap_idle_enabled sysctl variable + is useful in large multi-user systems where you have lots of + users entering and leaving the system and lots of idle processes. + Such systems tend to generate a great deal of continuous pressure + on free memory reserves. Turning this feature on and tweaking + the swapout hysteresis (in idle seconds) via + vm.swap_idle_threshold1 and + vm.swap_idle_threshold2 allows you to depress + the priority of memory pages associated with idle processes more + quickly then the normal pageout algorithm. This gives a helping + hand to the pageout daemon. Do not turn this option on unless + you need it, because the tradeoff you are making is essentially + pre-page memory sooner rather than later; thus eating more swap + and disk bandwidth. In a small system this option will have a + determinable effect but in a large system that is already doing + moderate paging this option allows the VM system to stage whole + processes into and out of memory easily. + + + + <varname>hw.ata.wc</varname> + + + hw.ata.wc + + + &os; 4.3 flirted with turning off IDE write caching. + This reduced write bandwidth to IDE disks but was considered + necessary due to serious data consistency issues introduced + by hard drive vendors. The problem is that IDE + drives lie about when a write completes. With IDE write + caching turned on, IDE hard drives not only write data + to disk out of order, but will sometimes delay writing some + blocks indefinitely when under heavy disk loads. A crash or + power failure may cause serious file system corruption. + &os;'s default was changed to be safe. Unfortunately, the + result was such a huge performance loss that we changed + write caching back to on by default after the release. You + should check the default on your system by observing the + hw.ata.wc sysctl variable. If IDE write + caching is turned off, you can turn it back on by setting + the kernel variable back to 1. This must be done from the + boot loader at boot time. Attempting to do it after the + kernel boots will have no effect. + + For more information, please see &man.ata.4;. + + + + <literal>SCSI_DELAY</literal> + (<varname>kern.cam.scsi_delay</varname>) + + + kern.cam.scsi_delay + + + + kernel options + SCSI_DELAY + + + The SCSI_DELAY kernel config may be used to + reduce system boot times. The defaults are fairly high and can be + responsible for 15 seconds of delay in the + boot process. Reducing it to 5 seconds usually + works (especially with modern drives). Newer versions of &os; + (5.0 and higher) should use the kern.cam.scsi_delay + boot time tunable. The tunable, and kernel config option accept + values in terms of milliseconds and + not seconds. + + + + + Soft Updates + + Soft Updates + tunefs + + The &man.tunefs.8; program can be used to fine-tune a + file system. This program has many different options, but for + now we are only concerned with toggling Soft Updates on and + off, which is done by: + + &prompt.root; tunefs -n enable /filesystem +&prompt.root; tunefs -n disable /filesystem + + A filesystem cannot be modified with &man.tunefs.8; while + it is mounted. A good time to enable Soft Updates is before any + partitions have been mounted, in single-user mode. + + Soft Updates drastically improves meta-data performance, mainly + file creation and deletion, through the use of a memory cache. We + recommend to use Soft Updates on all of your file systems. There + are two downsides to Soft Updates that you should be aware of: First, + Soft Updates guarantees filesystem consistency in the case of a crash + but could very easily be several seconds (even a minute!) behind + updating the physical disk. If your system crashes you may lose more + work than otherwise. Secondly, Soft Updates delays the freeing of + filesystem blocks. If you have a filesystem (such as the root + filesystem) which is almost full, performing a major update, such as + make installworld, can cause the filesystem to run + out of space and the update to fail. + + + More Details about Soft Updates + + + Soft Updates + details + + + There are two traditional approaches to writing a file + systems meta-data back to disk. (Meta-data updates are + updates to non-content data like inodes or + directories.) + + Historically, the default behavior was to write out + meta-data updates synchronously. If a directory had been + changed, the system waited until the change was actually + written to disk. The file data buffers (file contents) were + passed through the buffer cache and backed up + to disk later on asynchronously. The advantage of this + implementation is that it operates safely. If there is + a failure during an update, the meta-data are always in a + consistent state. A file is either created completely + or not at all. If the data blocks of a file did not find + their way out of the buffer cache onto the disk by the time + of the crash, &man.fsck.8; is able to recognize this and + repair the filesystem by setting the file length to + 0. Additionally, the implementation is clear and simple. + The disadvantage is that meta-data changes are slow. An + rm -r, for instance, touches all the files + in a directory sequentially, but each directory + change (deletion of a file) will be written synchronously + to the disk. This includes updates to the directory itself, + to the inode table, and possibly to indirect blocks + allocated by the file. Similar considerations apply for + unrolling large hierarchies (tar -x). + + The second case is asynchronous meta-data updates. This + is the default for Linux/ext2fs and + mount -o async for *BSD ufs. All + meta-data updates are simply being passed through the buffer + cache too, that is, they will be intermixed with the updates + of the file content data. The advantage of this + implementation is there is no need to wait until each + meta-data update has been written to disk, so all operations + which cause huge amounts of meta-data updates work much + faster than in the synchronous case. Also, the + implementation is still clear and simple, so there is a low + risk for bugs creeping into the code. The disadvantage is + that there is no guarantee at all for a consistent state of + the filesystem. If there is a failure during an operation + that updated large amounts of meta-data (like a power + failure, or someone pressing the reset button), + the filesystem + will be left in an unpredictable state. There is no opportunity + to examine the state of the filesystem when the system + comes up again; the data blocks of a file could already have + been written to the disk while the updates of the inode + table or the associated directory were not. It is actually + impossible to implement a fsck which is + able to clean up the resulting chaos (because the necessary + information is not available on the disk). If the + filesystem has been damaged beyond repair, the only choice + is to use &man.newfs.8; on it and restore it from backup. + + + The usual solution for this problem was to implement + dirty region logging, which is also + referred to as journaling, although that + term is not used consistently and is occasionally applied + to other forms of transaction logging as well. Meta-data + updates are still written synchronously, but only into a + small region of the disk. Later on they will be moved + to their proper location. Because the logging + area is a small, contiguous region on the disk, there + are no long distances for the disk heads to move, even + during heavy operations, so these operations are quicker + than synchronous updates. + Additionally the complexity of the implementation is fairly + limited, so the risk of bugs being present is low. A disadvantage + is that all meta-data are written twice (once into the + logging region and once to the proper location) so for + normal work, a performance pessimization + might result. On the other hand, in case of a crash, all + pending meta-data operations can be quickly either rolled-back + or completed from the logging area after the system comes + up again, resulting in a fast filesystem startup. + + Kirk McKusick, the developer of Berkeley FFS, + solved this problem with Soft Updates: all pending + meta-data updates are kept in memory and written out to disk + in a sorted sequence (ordered meta-data + updates). This has the effect that, in case of + heavy meta-data operations, later updates to an item + catch the earlier ones if the earlier ones are still in + memory and have not already been written to disk. So all + operations on, say, a directory are generally performed in + memory before the update is written to disk (the data + blocks are sorted according to their position so + that they will not be on the disk ahead of their meta-data). + If the system crashes, this causes an implicit log + rewind: all operations which did not find their way + to the disk appear as if they had never happened. A + consistent filesystem state is maintained that appears to + be the one of 30 to 60 seconds earlier. The + algorithm used guarantees that all resources in use + are marked as such in their appropriate bitmaps: blocks and inodes. + After a crash, the only resource allocation error + that occurs is that resources are + marked as used which are actually free. + &man.fsck.8; recognizes this situation, + and frees the resources that are no longer used. It is safe to + ignore the dirty state of the filesystem after a crash by + forcibly mounting it with mount -f. In + order to free resources that may be unused, &man.fsck.8; + needs to be run at a later time. This is the idea behind + the background fsck: at system startup + time, only a snapshot of the + filesystem is recorded. The fsck can be + run later on. All file systems can then be mounted + dirty, so the system startup proceeds in + multiuser mode. Then, background fscks + will be scheduled for all file systems where this is required, to free + resources that may be unused. (File systems that do not use + Soft Updates still need the usual foreground + fsck though.) + + The advantage is that meta-data operations are nearly as + fast as asynchronous updates (i.e. faster than with + logging, which has to write the + meta-data twice). The disadvantages are the complexity of + the code (implying a higher risk for bugs in an area that + is highly sensitive regarding loss of user data), and a + higher memory consumption. Additionally there are some + idiosyncrasies one has to get used to. + After a crash, the state of the filesystem appears to be + somewhat older. In situations where + the standard synchronous approach would have caused some + zero-length files to remain after the + fsck, these files do not exist at all + with a Soft Updates filesystem because neither the meta-data + nor the file contents have ever been written to disk. + Disk space is not released until the updates have been + written to disk, which may take place some time after + running rm. This may cause problems + when installing large amounts of data on a filesystem + that does not have enough free space to hold all the files + twice. + + + + + + Tuning Kernel Limits + + + tuning + kernel limits + + + + File/Process Limits + + + <varname>kern.maxfiles</varname> + + + kern.maxfiles + + + kern.maxfiles can be raised or + lowered based upon your system requirements. This variable + indicates the maximum number of file descriptors on your + system. When the file descriptor table is full, + file: table is full will show up repeatedly + in the system message buffer, which can be viewed with the + dmesg command. + + Each open file, socket, or fifo uses one file + descriptor. A large-scale production server may easily + require many thousands of file descriptors, depending on the + kind and number of services running concurrently. + + In older FreeBSD releases, kern.maxfile's default + value is derived from the option in your + kernel configuration file. kern.maxfiles grows + proportionally to the value of . When + compiling a custom kernel, it is a good idea to set this kernel + configuration option according to the uses of your system. From + this number, the kernel is given most of its pre-defined limits. + Even though a production machine may not actually have 256 users + connected at once, the resources needed may be similar to a + high-scale web server. + + As of FreeBSD 4.5, kern.maxusers is + automatically sized at boot based on the amount of memory available + in the system, and may be determined at run-time by inspecting the + value of the read-only kern.maxusers sysctl. + Some sites will require larger or smaller values of + kern.maxusers and may set it as a loader tunable; + values of 64, 128, and 256 are not uncommon. We do not recommend + going above 256 unless you need a huge number of file descriptors; + many of the tunable values set to their defaults by + kern.maxusers may be individually overridden at + boot-time or run-time in /boot/loader.conf (see + the &man.loader.conf.5; man page or the + /boot/defaults/loader.conf file for some hints) + or as described elsewhere in this document. Systems older than + FreeBSD 4.4 must set this value via the kernel &man.config.8; + option instead. + + In older releases, the system will auto-tune + maxusers for you if you explicitly set it to + 0 + The auto-tuning algorithm sets + maxusers equal to the amount of memory in the + system, with a minimum of 32, and a maximum of 384. + . When setting this option, you will want to set + maxusers to at least 4, especially if you are + using the X Window System or compiling software. The reason is that + the most important table set by maxusers is the + maximum number of processes, which is set to 20 + 16 * + maxusers, so if you set maxusers to 1, + then you can only have 36 simultaneous processes, including the 18 + or so that the system starts up at boot time and the 15 or so you + will probably create when you start the X Window System. Even a + simple task like reading a manual page will start up nine + processes to filter, decompress, and view it. Setting + maxusers to 64 will allow you to have up to 1044 + simultaneous processes, which should be enough for nearly all uses. + If, however, you see the dreaded proc table + full error when trying to start another program, or are + running a server with a large number of simultaneous users (like + ftp.FreeBSD.org), you can always + increase the number and rebuild. + + + maxusers does not + limit the number of users which can log into your machine. It + simply sets various table sizes to reasonable values considering + the maximum number of users you will likely have on your system + and how many processes each of them will be running. One keyword + which does limit the number of simultaneous + remote logins and X terminal windows is pseudo-device pty + 16. With &os; 5.X, you do not have to + worry about this number since the &man.pty.4; driver is + auto-cloning; you simply use the line + device pty in your configuration file. + + + + + + <varname>kern.ipc.somaxconn</varname> + + + kern.ipc.somaxconn + + + The kern.ipc.somaxconn sysctl variable + limits the size of the listen queue for accepting new TCP + connections. The default value of 128 is + typically too low for robust handling of new connections in a + heavily loaded web server environment. For such environments, it + is recommended to increase this value to 1024 or + higher. The service daemon may itself limit the listen queue size + (e.g. &man.sendmail.8;, or Apache) but + will often have a directive in its configuration file to adjust + the queue size. Large listen queues also do a better job of + avoiding Denial of Service (DoS) attacks. + + + + + Network Limits + + The NMBCLUSTERS kernel configuration + option dictates the amount of network Mbufs available to the + system. A heavily-trafficked server with a low number of Mbufs + will hinder &os;'s ability. Each cluster represents + approximately 2 K of memory, so a value of 1024 represents 2 + megabytes of kernel memory reserved for network buffers. A + simple calculation can be done to figure out how many are + needed. If you have a web server which maxes out at 1000 + simultaneous connections, and each connection eats a 16 K receive + and 16 K send buffer, you need approximately 32 MB worth of + network buffers to cover the web server. A good rule of thumb is + to multiply by 2, so 2x32 MB / 2 KB = + 64 MB / 2 kB = 32768. We recommend + values between 4096 and 32768 for machines with greater amounts + of memory. Under no circumstances should you specify an + arbitrarily high value for this parameter as it could lead to a + boot time crash. The option to + &man.netstat.1; may be used to observe network cluster + use. + + kern.ipc.nmbclusters loader tunable should + be used to tune this at boot time. Only older versions of &os; + will require you to use the NMBCLUSTERS kernel + &man.config.8; option. + + For busy servers that make extensive use of the + &man.sendfile.2; system call, it may be necessary to increase + the number of &man.sendfile.2; buffers via the + NSFBUFS kernel configuration option or by + setting its value in /boot/loader.conf + (see &man.loader.8; for details). A common indicator that + this parameter needs to be adjusted is when processes are seen + in the sfbufa state. The sysctl + variable kern.ipc.nsfbufs is a read-only + glimpse at the kernel configured variable. This parameter + nominally scales with kern.maxusers, + however it may be necessary to tune accordingly. + + + Even though a socket has been marked as non-blocking, + calling &man.sendfile.2; on the non-blocking socket may + result in the &man.sendfile.2; call blocking until enough + struct sf_buf's are made + available. + + + + <varname>net.inet.ip.portrange.*</varname> + + + net.inet.ip.portrange.* + + + The net.inet.ip.portrange.* sysctl + variables control the port number ranges automatically bound to TCP + and UDP sockets. There are three ranges: a low range, a default + range, and a high range. Most network programs use the default + range which is controlled by the + net.inet.ip.portrange.first and + net.inet.ip.portrange.last, which default to + 1024 and 5000, respectively. Bound port ranges are used for + outgoing connections, and it is possible to run the system out of + ports under certain circumstances. This most commonly occurs + when you are running a heavily loaded web proxy. The port range + is not an issue when running servers which handle mainly incoming + connections, such as a normal web server, or has a limited number + of outgoing connections, such as a mail relay. For situations + where you may run yourself out of ports, it is recommended to + increase net.inet.ip.portrange.last modestly. + A value of 10000, 20000 or + 30000 may be reasonable. You should also + consider firewall effects when changing the port range. Some + firewalls may block large ranges of ports (usually low-numbered + ports) and expect systems to use higher ranges of ports for + outgoing connections — for this reason it is not recommended that + net.inet.ip.portrange.first be lowered. + + + + TCP Bandwidth Delay Product + + + TCP Bandwidth Delay Product Limiting + net.inet.tcp.inflight.enable + + + The TCP Bandwidth Delay Product Limiting is similar to + TCP/Vegas in NetBSD. It can be + enabled by setting net.inet.tcp.inflight.enable + sysctl variable to 1. The system will attempt + to calculate the bandwidth delay product for each connection and + limit the amount of data queued to the network to just the amount + required to maintain optimum throughput. + + This feature is useful if you are serving data over modems, + Gigabit Ethernet, or even high speed WAN links (or any other link + with a high bandwidth delay product), especially if you are also + using window scaling or have configured a large send window. If + you enable this option, you should also be sure to set + net.inet.tcp.inflight.debug to + 0 (disable debugging), and for production use + setting net.inet.tcp.inflight.min to at least + 6144 may be beneficial. However, note that + setting high minimums may effectively disable bandwidth limiting + depending on the link. The limiting feature reduces the amount of + data built up in intermediate route and switch packet queues as + well as reduces the amount of data built up in the local host's + interface queue. With fewer packets queued up, interactive + connections, especially over slow modems, will also be able to + operate with lower Round Trip Times. However, + note that this feature only effects data transmission (uploading + / server side). It has no effect on data reception (downloading). + + + Adjusting net.inet.tcp.inflight.stab is + not recommended. This parameter defaults to + 20, representing 2 maximal packets added to the bandwidth delay + product window calculation. The additional window is required to + stabilize the algorithm and improve responsiveness to changing + conditions, but it can also result in higher ping times over slow + links (though still much lower than you would get without the + inflight algorithm). In such cases, you may wish to try reducing + this parameter to 15, 10, or 5; and may also have to reduce + net.inet.tcp.inflight.min (for example, to + 3500) to get the desired effect. Reducing these parameters + should be done as a last resort only. + + + + + Virtual Memory + + + <varname>kern.maxvnodes</varname> + + A vnode is the internal representation of a file or + directory. So increasing the number of vnodes available to + the operating system cuts down on disk I/O. Normally this + is handled by the operating system and does not need to be + changed. In some cases where disk I/O is a bottleneck and + the system is running out of vnodes, this setting will need + to be increased. The amount of inactive and free RAM will + need to be taken into account. + + To see the current number of vnodes in use: + + &prompt.root; sysctl vfs.numvnodes +vfs.numvnodes: 91349 + + To see the maximum vnodes: + + &prompt.root; sysctl kern.maxvnodes +kern.maxvnodes: 100000 + + If the current vnode usage is near the maximum, increasing + kern.maxvnodes by a value of 1,000 is + probably a good idea. Keep an eye on the number of + vfs.numvnodes. If it climbs up to the + maximum again, kern.maxvnodes will need to + be increased further. A shift in your memory usage as + reported by &man.top.1; should be visible. More memory should + be active. + + + + + + Adding Swap Space + + No matter how well you plan, sometimes a system does not run + as you expect. If you find you need more swap space, it is + simple enough to add. You have three ways to increase swap + space: adding a new hard drive, enabling swap over NFS, and + creating a swap file on an existing partition. + + For information on how to encrypt swap space, what options + for this task exist and why it should be done, please refer to + of the Handbook. + + + Swap on a New Hard Drive + + The best way to add swap, of course, is to use this as an + excuse to add another hard drive. You can always use another + hard drive, after all. If you can do this, go reread the + discussion of swap space + in + of the Handbook for some suggestions on how to best + arrange your swap. + + + + Swapping over NFS + + Swapping over NFS is only recommended if you do not have a + local hard disk to swap to; NFS swapping will be limited + by the available network bandwidth and puts an additional + burden on the NFS server. + + + + Swapfiles + + You can create a file of a specified size to use as a swap + file. In our example here we will use a 64MB file called + /usr/swap0. You can use any name you + want, of course. + + + Creating a Swapfile on &os; + + + + Be certain that your kernel configuration includes + the memory disk driver (&man.md.4;). It is default in + GENERIC kernel. + + device md # Memory "disks" + + + + Create a swapfile (/usr/swap0): + + &prompt.root; dd if=/dev/zero of=/usr/swap0 bs=1024k count=64 + + + + Set proper permissions on (/usr/swap0): + + &prompt.root; chmod 0600 /usr/swap0 + + + + Enable the swap file in /etc/rc.conf: + + swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired. + + + + + Reboot the machine or to enable the swap file immediately, + type: + + &prompt.root; mdconfig -a -t vnode -f /usr/swap0 -u 0 && swapon /dev/md0 + + + + + + + + + + + + Hiten + Pandya + Written by + + + Tom + Rhodes + + + + + Power and Resource Management + + It is very important to utilize hardware resources in an + efficient manner. Before ACPI was introduced, + it was very difficult and inflexible for operating systems to manage + the power usage and thermal properties of a system. The hardware was + controlled by some sort of BIOS embedded + interface, such as Plug and Play BIOS (PNPBIOS), or + Advanced Power Management (APM) and so on. + Power and Resource Management is one of the key components of a modern + operating system. For example, you may want an operating system to + monitor system limits (and possibly alert you) in case your system + temperature increased unexpectedly. + + In this section of the &os; Handbook, we will provide + comprehensive information about ACPI. References + will be provided for further reading at the end. + + + What Is ACPI? + + + ACPI + + + + APM + + + Advanced Configuration and Power Interface + (ACPI) is a standard written by + an alliance of vendors to provide a standard interface for + hardware resources and power management (hence the name). + It is a key element in Operating System-directed + configuration and Power Management, i.e.: it provides + more control and flexibility to the operating system + (OS). + Modern systems stretched the limits of the + current Plug and Play interfaces prior to the introduction of + ACPI. ACPI is the direct + successor to APM + (Advanced Power Management). + + + + Shortcomings of Advanced Power Management (APM) + + The Advanced Power Management (APM) + facility controls the power usage of a system based on its + activity. The APM BIOS is supplied by the (system) vendor and + it is specific to the hardware platform. An APM driver in the + OS mediates access to the APM Software Interface, + which allows management of power levels. + + There are four major problems in APM. Firstly, power + management is done by the (vendor-specific) BIOS, and the OS + does not have any knowledge of it. One example of this, is when + the user sets idle-time values for a hard drive in the APM BIOS, + that when exceeded, it (BIOS) would spin down the hard drive, + without the consent of the OS. Secondly, the APM logic is + embedded in the BIOS, and it operates outside the scope of the + OS. This means users can only fix problems in their APM BIOS by + flashing a new one into the ROM; which is a very dangerous + procedure with the potential to leave the system in an + unrecoverable state if it fails. Thirdly, APM is a vendor-specific + technology, which means that there is a lot of parity + (duplication of efforts) and bugs found in one vendor's BIOS, + may not be solved in others. Last but not the least, the APM + BIOS did not have enough room to implement a sophisticated power + policy, or one that can adapt very well to the purpose of the + machine. + + Plug and Play BIOS (PNPBIOS) was + unreliable in many situations. PNPBIOS is 16-bit technology, + so the OS has to use 16-bit emulation in order to + interface with PNPBIOS methods. + + The &os; APM driver is documented in + the &man.apm.4; manual page. + + + + Configuring <acronym>ACPI</acronym> + + The acpi.ko driver is loaded by default + at start up by the &man.loader.8; and should not + be compiled into the kernel. The reasoning behind this is that modules + are easier to work with, say if switching to another acpi.ko + without doing a kernel rebuild. This has the advantage of making testing easier. + Another reason is that starting ACPI after a system has been + brought up is not too useful, and in some cases can be fatal. In doubt, just + disable ACPI all together. This driver should not and can not + be unloaded because the system bus uses it for various hardware interactions. + ACPI can be disabled with the &man.acpiconf.8; utility. + In fact most of the interaction with ACPI can be done via + &man.acpiconf.8;. Basically this means, if anything about ACPI + is in the &man.dmesg.8; output, then most likely it is already running. + + ACPI and APM cannot coexist and + should be used separately. The last one to load will terminate if the driver + notices the other running. + + In the simplest form, ACPI can be used to put the + system into a sleep mode with &man.acpiconf.8;, the + flag, and a 1-5 option. Most users will only need + 1. Option 5 will do a soft-off + which is the same action as: + + &prompt.root; halt -p + + The other options are available. Check out the &man.acpiconf.8; + manual page for more information. + + + + + + + + Nate + Lawson + Written by + + + + + Peter + Schultz + With contributions from + + + Tom + Rhodes + + + + + Using and Debugging &os; <acronym>ACPI</acronym> + + + ACPI + problems + + + ACPI is a fundamentally new way of + discovering devices, managing power usage, and providing + standardized access to various hardware previously managed + by the BIOS. Progress is being made toward + ACPI working on all systems, but bugs in some + motherboards' ACPI Machine + Language (AML) bytecode, + incompleteness in &os;'s kernel subsystems, and bugs in the &intel; + ACPI-CA interpreter continue to appear. + + This document is intended to help you assist the &os; + ACPI maintainers in identifying the root cause + of problems you observe and debugging and developing a solution. + Thanks for reading this and we hope we can solve your system's + problems. + + + Submitting Debugging Information + + + Before submitting a problem, be sure you are running the latest + BIOS version and, if available, embedded + controller firmware version. + + + For those of you that want to submit a problem right away, + please send the following information to + + freebsd-acpi@FreeBSD.org: + + + + Description of the buggy behavior, including system type + and model and anything that causes the bug to appear. Also, + please note as accurately as possible when the bug began + occurring if it is new for you. + + + + The &man.dmesg.8; output after boot + -v, including any error messages + generated by you exercising the bug. + + + + The &man.dmesg.8; output from boot + -v with ACPI + disabled, if disabling it helps fix the problem. + + + + Output from sysctl hw.acpi. This is also + a good way of figuring out what features your system + offers. + + + + URL where your + ACPI Source Language + (ASL) + can be found. Do not send the + ASL directly to the list as it can be + very large. Generate a copy of your ASL + by running this command: + + &prompt.root; acpidump -t -d > name-system.asl + + (Substitute your login name for + name and manufacturer/model for + system. Example: + njl-FooCo6000.asl) + + + + Most of the developers watch the &a.current; + but please submit problems to &a.acpi.name; to be sure it is + seen. Please be patient, all of us have full-time jobs + elsewhere. If your bug is not immediately apparent, we will + probably ask you to submit a PR via + &man.send-pr.1;. When entering a PR, please + include the same information as requested above. This will help + us track the problem and resolve it. Do not send a + PR without emailing &a.acpi.name; first as we use + PRs as reminders of existing problems, not a + reporting mechanism. It is likely that your problem has been + reported by someone before. + + + + Background + + + ACPI + + + ACPI is present in all modern computers + that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD) + architectures. The full standard has many features including + CPU performance management, power planes + control, thermal zones, various battery systems, embedded + controllers, and bus enumeration. Most systems implement less + than the full standard. For instance, a desktop system usually + only implements the bus enumeration parts while a laptop might + have cooling and battery management support as well. Laptops + also have suspend and resume, with their own associated + complexity. + + An ACPI-compliant system has various + components. The BIOS and chipset vendors + provide various fixed tables (e.g., FADT) + in memory that specify things like the APIC + map (used for SMP), config registers, and + simple configuration values. Additionally, a table of bytecode + (the Differentiated System Description Table + DSDT) is provided that specifies a + tree-like name space of devices and methods. + + The ACPI driver must parse the fixed + tables, implement an interpreter for the bytecode, and modify + device drivers and the kernel to accept information from the + ACPI subsystem. For &os;, &intel; has + provided an interpreter (ACPI-CA) that is + shared with Linux and NetBSD. The path to the + ACPI-CA source code is + src/sys/contrib/dev/acpica. + The glue code that allows ACPI-CA to work on + &os; is in + src/sys/dev/acpica/Osd. Finally, drivers + that implement various ACPI devices are found + in + src/sys/dev/acpica. + + + + Common Problems + + + ACPI + problems + + + For ACPI to work correctly, all the parts + have to work correctly. Here are some common problems, in order + of frequency of appearance, and some possible workarounds or + fixes. + + + Mouse Issues + + In some cases, resuming from a suspend operation will + cause the mouse to fail. A known work around is to add + hint.psm.0.flags="0x3000" to the + /boot/loader.conf file. If this + does not work then please consider sending a bug report + as described above. + + + + Suspend/Resume + + ACPI has three suspend to + RAM (STR) states, + S1-S3, and one suspend + to disk state (STD), called + S4. S5 is + soft off and is the normal state your system + is in when plugged in but not powered up. + S4 can actually be implemented two separate + ways. S4BIOS is a + BIOS-assisted suspend to disk. + S4OS is implemented + entirely by the operating system. + + Start by checking sysctl hw.acpi + for the suspend-related items. Here + are the results for a Thinkpad: + + hw.acpi.supported_sleep_state: S3 S4 S5 +hw.acpi.s4bios: 0 + + This means that we can use acpiconf -s + to test S3, + S4OS, and + S5. If was one + (1), we would have + S4BIOS + support instead of S4 + OS. + + When testing suspend/resume, start with + S1, if supported. This state is most + likely to work since it does not require much driver support. + No one has implemented S2 but if you have + it, it is similar to S1. The next thing + to try is S3. This is the deepest + STR state and requires a lot of driver + support to properly reinitialize your hardware. If you have + problems resuming, feel free to email the &a.acpi.name; list but + do not expect the problem to be resolved since there are a lot + of drivers/hardware that need more testing and work. + + To help isolate the problem, remove as many drivers from + your kernel as possible. If it works, you can narrow down + which driver is the problem by loading drivers until it fails + again. Typically binary drivers like + nvidia.ko, X11 + display drivers, and USB will have the most + problems while Ethernet interfaces usually work fine. If you + can properly load/unload the drivers, you can automate this by + putting the appropriate commands in + /etc/rc.suspend and + /etc/rc.resume. There is a + commented-out example for unloading and loading a driver. Try + setting to zero (0) if + your display is messed up after resume. Try setting longer or + shorter values for to see + if that helps. + + Another thing to try is load a recent Linux distribution + with ACPI support and test their + suspend/resume support on the same hardware. If it works + on Linux, it is likely a &os; driver problem and narrowing down + which driver causes the problems will help us fix the problem. + Note that the ACPI maintainers do not + usually maintain other drivers (e.g sound, + ATA, etc.) so any work done on tracking + down a driver problem should probably eventually be posted + to the &a.current.name; list and mailed to the driver + maintainer. If you are feeling adventurous, go ahead and + start putting some debugging &man.printf.3;s in a problematic + driver to track down where in its resume function it + hangs. + + Finally, try disabling ACPI and + enabling APM instead. If suspend/resume + works with APM, you may be better off + sticking with APM, especially on older + hardware (pre-2000). It took vendors a while to get + ACPI support correct and older hardware is + more likely to have BIOS problems with + ACPI. + + + + System Hangs (temporary or permanent) + + Most system hangs are a result of lost interrupts or an + interrupt storm. Chipsets have a lot of problems based on how + the BIOS configures interrupts before boot, + correctness of the APIC + (MADT) table, and routing of the + System Control Interrupt + (SCI). + + + interrupt storms + + + Interrupt storms can be distinguished from lost interrupts + by checking the output of vmstat -i + and looking at the line that has + acpi0. If the counter is increasing at more + than a couple per second, you have an interrupt storm. If the + system appears hung, try breaking to DDB + (CTRL + ALTESC on + console) and type show interrupts. + + + APIC + disabling + + + Your best hope when dealing with interrupt problems is to + try disabling APIC support with + hint.apic.0.disabled="1" in + loader.conf. + + + + Panics + + Panics are relatively rare for ACPI and + are the top priority to be fixed. The first step is to + isolate the steps to reproduce the panic (if possible) + and get a backtrace. Follow the advice for enabling + options DDB and setting up a serial console + (see ) + or setting up a &man.dump.8; partition. You can get a + backtrace in DDB with + tr. If you have to handwrite the + backtrace, be sure to at least get the lowest five (5) and top + five (5) lines in the trace. + + Then, try to isolate the problem by booting with + ACPI disabled. If that works, you can + isolate the ACPI subsystem by using various + values of . See the + &man.acpi.4; manual page for some examples. + + + + System Powers Up After Suspend or Shutdown + First, try setting + hw.acpi.disable_on_poweroff="0" + in &man.loader.conf.5;. This keeps ACPI + from disabling various events during the shutdown process. + Some systems need this value set to 1 (the + default) for the same reason. This usually fixes + the problem of a system powering up spontaneously after a + suspend or poweroff. + + + + Other Problems + + If you have other problems with ACPI + (working with a docking station, devices not detected, etc.), + please email a description to the mailing list as well; + however, some of these issues may be related to unfinished + parts of the ACPI subsystem so they might + take a while to be implemented. Please be patient and + prepared to test patches we may send you. + + + + + <acronym>ASL</acronym>, <command>acpidump</command>, and + <acronym>IASL</acronym> + + + ACPI + ASL + + + The most common problem is the BIOS + vendors providing incorrect (or outright buggy!) bytecode. This + is usually manifested by kernel console messages like + this: + + ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\ +(Node 0xc3f6d160), AE_NOT_FOUND + + Often, you can resolve these problems by updating your + BIOS to the latest revision. Most console + messages are harmless but if you have other problems like + battery status not working, they are a good place to start + looking for problems in the AML. The + bytecode, known as AML, is compiled from a + source language called ASL. The + AML is found in the table known as the + DSDT. To get a copy of your + ASL, use &man.acpidump.8;. You should use + both the (show contents of the fixed tables) + and (disassemble AML to + ASL) options. See the + Submitting Debugging + Information section for an example syntax. + + The simplest first check you can do is to recompile your + ASL to check for errors. Warnings can + usually be ignored but errors are bugs that will usually prevent + ACPI from working correctly. To recompile + your ASL, issue the following command: + + &prompt.root; iasl your.asl + + + + Fixing Your <acronym>ASL</acronym> + + + ACPI + ASL + + + In the long run, our goal is for almost everyone to have + ACPI work without any user intervention. At + this point, however, we are still developing workarounds for + common mistakes made by the BIOS vendors. + The µsoft; interpreter (acpi.sys and + acpiec.sys) does not strictly check for + adherence to the standard, and thus many BIOS + vendors who only test ACPI under &windows; + never fix their ASL. We hope to continue to + identify and document exactly what non-standard behavior is + allowed by µsoft;'s interpreter and replicate it so &os; can + work without forcing users to fix the ASL. + As a workaround and to help us identify behavior, you can fix + the ASL manually. If this works for you, + please send a &man.diff.1; of the old and new + ASL so we can possibly work around the buggy + behavior in ACPI-CA and thus make your fix + unnecessary. + + + ACPI + error messages + + + Here is a list of common error messages, their cause, and + how to fix them: + + + _OS dependencies + + Some AML assumes the world consists of + various &windows; versions. You can tell &os; to claim it is + any OS to see if this fixes problems you + may have. An easy way to override this is to set + hw.acpi.osname="Windows 2001" + in /boot/loader.conf or other similar + strings you find in the ASL. + + + + Missing Return statements + + Some methods do not explicitly return a value as the + standard requires. While ACPI-CA + does not handle this, &os; has a workaround that allows it to + return the value implicitly. You can also add explicit + Return statements where required if you know what value should + be returned. To force iasl to compile the + ASL, use the + flag. + + + + Overriding the Default <acronym>AML</acronym> + + After you customize your.asl, you + will want to compile it, run: + + &prompt.root; iasl your.asl + + You can add the flag to force creation + of the AML, even if there are errors during + compilation. Remember that some errors (e.g., missing Return + statements) are automatically worked around by the + interpreter. + + DSDT.aml is the default output + filename for iasl. You can load this + instead of your BIOS's buggy copy (which + is still present in flash memory) by editing + /boot/loader.conf as + follows: + + acpi_dsdt_load="YES" +acpi_dsdt_name="/boot/DSDT.aml" + + Be sure to copy your DSDT.aml to the + /boot directory. + + + + + Getting Debugging Output From + <acronym>ACPI</acronym> + + + ACPI + problems + + + + ACPI + debugging + + + The ACPI driver has a very flexible + debugging facility. It allows you to specify a set of subsystems + as well as the level of verbosity. The subsystems you wish to + debug are specified as layers and are broken down + into ACPI-CA components (ACPI_ALL_COMPONENTS) + and ACPI hardware support (ACPI_ALL_DRIVERS). + The verbosity of debugging output is specified as the + level and ranges from ACPI_LV_ERROR (just report + errors) to ACPI_LV_VERBOSE (everything). The + level is a bitmask so multiple options can be set + at once, separated by spaces. In practice, you will want to use + a serial console to log the output if it is so long + it flushes the console message buffer. A full list of the + individual layers and levels is found in the &man.acpi.4; manual + page. + + Debugging output is not enabled by default. To enable it, + add options ACPI_DEBUG to your kernel configuration file + if ACPI is compiled into the kernel. You can + add ACPI_DEBUG=1 to your + /etc/make.conf to enable it globally. If + it is a module, you can recompile just your + acpi.ko module as follows: + + &prompt.root; cd /sys/modules/acpi/acpi +&& make clean && +make ACPI_DEBUG=1 + + Install acpi.ko in + /boot/kernel and add your + desired level and layer to loader.conf. + This example enables debug messages for all + ACPI-CA components and all + ACPI hardware drivers + (CPU, LID, etc.) It will + only output error messages, the least verbose level. + + debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" +debug.acpi.level="ACPI_LV_ERROR" + + If the information you want is triggered by a specific event + (say, a suspend and then resume), you can leave out changes to + loader.conf and instead use + sysctl to specify the layer and level after + booting and preparing your system for the specific event. The + sysctls are named the same as the tunables + in loader.conf. + + + + References + + More information about ACPI may be found + in the following locations: + + + + The &a.acpi; + + + + The ACPI Mailing List Archives + + + + + The old ACPI Mailing List Archives + + + + + The ACPI 2.0 Specification + + + + + &os; Manual pages: &man.acpi.4;, + &man.acpi.thermal.4;, &man.acpidump.8;, &man.iasl.8;, + &man.acpidb.8; + + + + + DSDT debugging resource. + (Uses Compaq as an example but generally useful.) + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/cutting-edge/Makefile b/pl_PL.ISO8859-2/books/handbook/cutting-edge/Makefile new file mode 100644 index 0000000000..29da7845dd --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/cutting-edge/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= cutting-edge/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/cutting-edge/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/cutting-edge/chapter.sgml new file mode 100644 index 0000000000..63f4f9bcd0 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/cutting-edge/chapter.sgml @@ -0,0 +1,1732 @@ + + + + + + + Jim + Mock + Restructured, reorganized, and parts updated by + + + + + + Jordan + Hubbard + Original work by + + + Poul-Henning + Kamp + + + John + Polstra + + + Nik + Clayton + + + + + + The Cutting Edge + + + Synopsis + + &os; is under constant development between releases. For + people who want to be on the cutting edge, there are several easy + mechanisms for keeping your system in sync with the latest + developments. Be warned—the cutting edge is not for everyone! + This chapter will help you decide if you want to track the + development system, or stick with one of the released + versions. + + After reading this chapter, you will know: + + + The difference between the two development + branches: &os.stable; and &os.current;. + + How to keep your system up to date with + CVSup, + CVS, or + CTM. + + How to rebuild and reinstall the entire base + system with make buildworld (etc). + + + + + Before reading this chapter, you should: + + + Properly set up your network connection (). + + Know how to install additional third-party + software (). + + + + + &os.current; vs. &os.stable; + -CURRENT + -STABLE + + There are two development branches to FreeBSD: &os.current; and + &os.stable;. This section will explain a bit about each and describe + how to keep your system up-to-date with each respective tree. + &os.current; will be discussed first, then &os.stable;. + + + Staying Current with &os; + + As you read this, keep in mind that &os.current; is the + bleeding edge of &os; development. + &os.current; users are expected to have a high degree of + technical skill, and should be capable of solving difficult + system problems on their own. If you are new to &os;, think + twice before installing it. + + + What Is &os.current;? + snapshot + + &os.current; is the latest working sources for &os;. + This includes work in progress, experimental changes, and + transitional mechanisms that might or might not be present + in the next official release of the software. While many + &os; developers compile the &os.current; source code daily, + there are periods of time when the sources are not + buildable. These problems are resolved as expeditiously as + possible, but whether or not &os.current; brings disaster or + greatly desired functionality can be a matter of which exact + moment you grabbed the source code in! + + + + Who Needs &os.current;? + + &os.current; is made available for 3 primary + interest groups: + + + + Members of the &os; community who are actively working + on some part of the source tree and for whom keeping + current is an absolute + requirement. + + + + Members of the &os; community who are active testers, + willing to spend time solving problems in order to + ensure that &os.current; remains as sane as possible. + These are also people who wish to make topical + suggestions on changes and the general direction of + &os;, and submit patches to implement them. + + + + Those who merely wish to keep an eye on things, or + to use the current sources for reference purposes + (e.g. for reading, not running). + These people also make the occasional comment or + contribute code. + + + + + + What Is &os.current; <emphasis>Not</emphasis>? + + + + A fast-track to getting pre-release bits because you + heard there is some cool new feature in there and you + want to be the first on your block to have it. Being + the first on the block to get the new feature means that + you are the first on the block to get the new + bugs. + + + + A quick way of getting bug fixes. Any given version + of &os.current; is just as likely to introduce new bugs + as to fix existing ones. + + + + In any way officially supported. We + do our best to help people genuinely in one of the 3 + legitimate &os.current; groups, but we + simply do not have the time to + provide tech support. This is not because we are mean + and nasty people who do not like helping people out (we + would not even be doing &os; if we were). We simply + cannot answer hundreds messages a day + and work on FreeBSD! Given the + choice between improving &os; and answering lots of + questions on experimental code, the developers opt for + the former. + + + + + + Using &os.current; + + + -CURRENT + using + + + + Join the &a.current.name; and the &a.cvsall.name; lists. This is not + just a good idea, it is essential. If + you are not on the &a.current.name; list, + you will not see the comments that people are + making about the current state of the system and thus will + probably end up stumbling over a lot of problems that others + have already found and solved. Even more importantly, you + will miss out on important bulletins which may be critical + to your system's continued health. + + The &a.cvsall.name; list will allow you to see the + commit log entry for each change as it is made along with + any pertinent information on possible side-effects. + + To join these lists, or one of the others available + go to &a.mailman.lists.link; and click on the list that + you wish to subscribe to. Instructions on the rest of + the procedure are available there. + + + + Grab the sources from a &os; mirror + site. You can do this in one of two ways: + + + + cvsup + + + cron + + + -CURRENT + Syncing with CVSup + + + + Use the cvsup program + with the supfile named standard-supfile + available from /usr/share/examples/cvsup. + This is the most recommended + method, since it allows you to grab the entire + collection once and then only what has changed from then + on. Many people run cvsup from + cron and keep their + sources up-to-date automatically. You have to + customize the sample supfile above, and configure + cvsup for your environment. + + + + -CURRENT + Syncing with CTM + + + Use the CTM facility. If you + have very bad connectivity (high price connections or + only email access) CTM is an option. + However, it is a lot of hassle and can give you broken files. + This leads to it being rarely used, which again increases + the chance of it not working for fairly long periods of + time. We recommend using + CVSup + for anybody with a 9600 bps modem or faster connection. + + + + + + + If you are grabbing the sources to run, and not just + look at, then grab all of &os.current;, not + just selected portions. The reason for this is that various + parts of the source depend on updates elsewhere, and trying + to compile just a subset is almost guaranteed to get you + into trouble. + + + -CURRENT + compiling + + Before compiling &os.current;, read the + Makefile in /usr/src + carefully. You should at least install a new kernel and rebuild the world the first time through + as part of the upgrading process. Reading the &a.current; + and /usr/src/UPDATING will keep you up-to-date on other bootstrapping procedures + that sometimes become necessary as we move toward the next + release. + + + + Be active! If you are running &os.current;, we want + to know what you have to say about it, especially if you + have suggestions for enhancements or bug fixes. Suggestions + with accompanying code are received most + enthusiastically! + + + + + + + Staying Stable with &os; + + + What Is &os.stable;? + -STABLE + + &os.stable; is our development branch from which major releases + are made. Changes go into this branch at a different pace, and + with the general assumption that they have first gone into + &os.current; for testing. This is still + a development branch, however, and this means that at any given time, + the sources for &os.stable; may or may not be suitable for any + particular purpose. It is simply another engineering development + track, not a resource for end-users. + + + + Who Needs &os.stable;? + + If you are interested in tracking or contributing to the + FreeBSD development process, especially as it relates to the + next point release of FreeBSD, then you should + consider following &os.stable;. + + While it is true that security fixes also go into the + &os.stable; branch, you do not need to + track &os.stable; to do this. Every security advisory for + FreeBSD explains how to fix the problem for the releases it + affects + That is not quite true. We can not continue to + support old releases of FreeBSD forever, although we do + support them for many years. For a complete description + of the current security policy for old releases of + FreeBSD, please see http://www.FreeBSD.org/security/. + + , and tracking an entire development branch just + for security reasons is likely to bring in a lot of unwanted + changes as well. + + Although we endeavor to ensure that the &os.stable; branch + compiles and runs at all times, this cannot be guaranteed. In + addition, while code is developed in &os.current; before including + it in &os.stable;, more people run &os.stable; than &os.current;, so + it is inevitable that bugs and corner cases will sometimes be found + in &os.stable; that were not apparent in &os.current;. + + For these reasons, we do not recommend that + you blindly track &os.stable;, and it is particularly important that + you do not update any production servers to &os.stable; without + first thoroughly testing the code in your development + environment. + + If you do not have the resources to do this then we recommend + that you run the most recent release of FreeBSD, and use the binary + update mechanism to move from release to release. + + + + Using &os.stable; + + + -STABLE + using + + + + Join the &a.stable.name; list. This will keep you informed of + build-dependencies that may appear in &os.stable; + or any other issues requiring + special attention. Developers will also make announcements + in this mailing list when they are contemplating some + controversial fix or update, giving the users a chance to + respond if they have any issues to raise concerning the + proposed change. + + The &a.cvsall.name; list will allow you to see the + commit log entry for each change as it is made along with + any pertinent information on possible side-effects. + + To join these lists, or one of the others available + go to &a.mailman.lists.link; and click on the list that + you wish to subscribe to. Instructions on the rest of + the procedure are available there. + + + + If you are going to install a new system and want it + to run monthly snapshot built from &os.stable;, please + check the + Snapshots web page for more information. + Alternatively, it is possible to + install the most recent &os.stable; release from the + mirror sites and follow + the instructions below to upgrade your system to the + most up to date &os.stable; source code. + + If you are already running a previous release of &os; + and wish to upgrade via sources then you can easily do so + from &os; mirror site. This can + be done in one of two ways: + + + + cvsup + + + cron + + + -STABLE + syncing with CVSup + + + Use the cvsup program + with the supfile named stable-supfile + from the directory + /usr/share/examples/cvsup. + This is the most recommended + method, since it allows you to grab the entire + collection once and then only what has changed from then + on. Many people run cvsup from + cron to keep their + sources up-to-date automatically. You have to + customize the sample supfile above, + and configure cvsup for your + environment. + + + + -STABLE + syncing with CTM + + + Use the CTM facility. If + you do not have a fast and inexpensive connection to + the Internet, this is the method you should consider + using. + + + + + + + Essentially, if you need rapid on-demand access to the + source and communications bandwidth is not a consideration, + use cvsup or ftp. + Otherwise, use CTM. + + + + -STABLE + compiling + + + Before compiling &os.stable;, read the + Makefile in /usr/src + carefully. You should at least install a new kernel and rebuild the world the first time through + as part of the upgrading process. Reading the &a.stable; and /usr/src/UPDATING will + keep you up-to-date on other bootstrapping procedures that + sometimes become necessary as we move toward the next + release. + + + + + + + + Synchronizing Your Source + + There are various ways of using an Internet (or email) + connection to stay up-to-date with any given area of the &os; + project sources, or all areas, depending on what interests you. The + primary services we offer are Anonymous + CVS, CVSup, and CTM. + + + While it is possible to update only parts of your source tree, + the only supported update procedure is to update the entire tree + and recompile both userland (i.e., all the programs that run in + user space, such as those in /bin and + /sbin) and kernel sources. Updating only part + of your source tree, only the kernel, or only userland will often + result in problems. These problems may range from compile errors + to kernel panics or data corruption. + + + + CVS + anonymous + + + Anonymous CVS and + CVSup use the pull + model of updating sources. In the case of + CVSup the user (or a + cron script) invokes + the cvsup program, and it interacts with a + cvsupd server somewhere to bring your files + up-to-date. The updates you receive are up-to-the-minute and you + get them when, and only when, you want them. You can easily + restrict your updates to the specific files or directories that are + of interest to you. Updates are generated on the fly by the server, + according to what you have and what you want to have. + Anonymous CVS is quite a bit more + simplistic than CVSup in that it is just an extension to + CVS which allows it to pull changes + directly from a remote CVS repository. + CVSup can do this far more efficiently, + but Anonymous CVS is easier to + use. + + + CTM + + CTM, on the other hand, does not + interactively compare the sources you have with those on the master + archive or otherwise pull them across. Instead, a script which + identifies changes in files since its previous run is executed + several times a day on the master CTM machine, any detected changes + being compressed, stamped with a sequence-number and encoded for + transmission over email (in printable ASCII only). Once received, + these CTM deltas can then be handed to the + &man.ctm.rmail.1; utility which will automatically decode, verify + and apply the changes to the user's copy of the sources. This + process is far more efficient than CVSup, + and places less strain on our server resources since it is a + push rather than a pull + model. + + There are other trade-offs, of course. If you inadvertently + wipe out portions of your archive, CVSup + will detect and rebuild the damaged portions for you. + CTM will not do this, and if you wipe some + portion of your source tree out (and do not have it backed up) then + you will have to start from scratch (from the most recent CVS + base delta) and rebuild it all with CTM or, with + Anonymous CVS, simply delete the bad bits and resync. + + + + Rebuilding <quote>world</quote> + + + Rebuilding world + + Once you have synchronized your local source tree against a + particular version of &os; (&os.stable;, &os.current;, and so on) + you can then use the source + tree to rebuild the system. + + + Make a Backup + + It cannot be stressed enough how important it is to make a + backup of your system before you do this. + While rebuilding the world is (as long as you follow these + instructions) an easy task to do, there will inevitably be times + when you make mistakes, or when mistakes made by others in the + source tree render your system unbootable. + + Make sure you have taken a backup. And have a fixit floppy or + bootable CD at + hand. You will probably never have to use it, but it is better to be + safe than sorry! + + + + Subscribe to the Right Mailing List + + mailing list + The &os.stable; and &os.current; branches are, by their + nature, in development. People that + contribute to &os; are human, and mistakes occasionally + happen. + + Sometimes these mistakes can be quite harmless, just causing + your system to print a new diagnostic warning. Or the change may + be catastrophic, and render your system unbootable or destroy your + file systems (or worse). + + If problems like these occur, a heads up is + posted to the appropriate mailing list, explaining the nature of + the problem and which systems it affects. And an all + clear announcement is posted when the problem has been + solved. + + If you try to track &os.stable; or &os.current; and do + not read the &a.stable; or the + &a.current; respectively, then you are + asking for trouble. + + + + Do not use <command>make world</command> + + A lot of older documentation recommends using + make world for this. Doing that skips + some important steps and should only be used if you are + sure of what you are doing. For almost all circumstances + make world is the wrong thing to do, and + the procedure described here should be used instead. + + + + The Canonical Way to Update Your System + + To update your system, you should check + /usr/src/UPDATING for any pre-buildworld steps + necessary for your version of the sources and then use the following + procedure: + + &prompt.root; make buildworld +&prompt.root; make buildkernel +&prompt.root; make installkernel +&prompt.root; reboot + + + There are a few rare cases when an extra run of + mergemaster -p is needed before the + buildworld step. These are + described in UPDATING. In general, + though, you can safely omit this step if you are not + updating across one or more major &os; versions. + + + After installkernel finishes + successfully, you should boot in single user mode + (i.e. using boot -s from the loader + prompt). Then run: + + &prompt.root; mergemaster -p +&prompt.root; make installworld +&prompt.root; mergemaster +&prompt.root; reboot + + + Read Further Explanations + + The sequence described above is only a short resume to + help you getting started. You should however read the + following sections to clearly understand each step, especially + if you want to use a custom kernel configuration. + + + + + Read <filename>/usr/src/UPDATING</filename> + + Before you do anything else, read + /usr/src/UPDATING (or the equivalent file + wherever you have a copy of the source code). This file should + contain important information about problems you might encounter, or + specify the order in which you might have to run certain commands. + If UPDATING contradicts something you read here, + UPDATING takes precedence. + + + Reading UPDATING is not an acceptable + substitute for subscribing to the correct mailing list, as described + previously. The two requirements are complementary, not + exclusive. + + + + + Check <filename>/etc/make.conf</filename> + + make.conf + + + Examine the files + /usr/share/examples/etc/make.conf + and + /etc/make.conf. The first contains some + default defines – most of which are commented out. To + make use of them when you rebuild your system from source, add + them to /etc/make.conf. Keep in mind that + anything you add to /etc/make.conf is also + used every time you run make, so it is a good + idea to set them to something sensible for your system. + + A typical user will probably want to copy the + CFLAGS and + NO_PROFILE lines found in + /usr/share/examples/etc/make.conf + to + /etc/make.conf and uncomment them. + + Examine the other definitions (COPTFLAGS, + NOPORTDOCS and so + on) and decide if they are relevant to you. + + + + Update the Files in <filename>/etc</filename> + + The /etc directory contains a large part + of your system's configuration information, as well as scripts + that are run at system startup. Some of these scripts change from + version to version of FreeBSD. + + Some of the configuration files are also used in the day to + day running of the system. In particular, + /etc/group. + + There have been occasions when the installation part of + make installworld has expected certain usernames or groups + to exist. When performing an upgrade it is likely that these + users or groups did not exist. This caused problems when upgrading. + In some cases make buildworld will check to see if + these users or groups exist. + + An example of this is when the + smmsp user was added. Users had the + installation process fail for them when + &man.mtree.8; was trying to create + /var/spool/clientmqueue. + + The solution is to run &man.mergemaster.8; in + pre-buildworld mode by providing the option. + This will compare only those files that are essential for the success + of buildworld or + installworld. If your old version of + mergemaster does not support , + use the new version in the source tree when running for the first + time: + + &prompt.root; cd /usr/src/usr.sbin/mergemaster +&prompt.root; ./mergemaster.sh -p + + + If you are feeling particularly paranoid, you can check your + system to see which files are owned by the group you are + renaming or deleting: + + &prompt.root; find / -group GID -print + + will show all files owned by group + GID (which can be either a group name + or a numeric group ID). + + + + + Drop to Single User Mode + single-user mode + + You may want to compile the system in single user mode. Apart + from the obvious benefit of making things go slightly faster, + reinstalling the system will touch a lot of important system + files, all the standard system binaries, libraries, include files + and so on. Changing these on a running system (particularly if + you have active users on the system at the time) is asking for + trouble. + + multi-user mode + Another method is to compile the system in multi-user mode, and + then drop into single user mode for the installation. If you would + like to do it this way, simply hold off on the following steps until + the build has completed. You can postpone dropping to single user + mode until you have to installkernel or + installworld. + + As the superuser, you can execute: + + &prompt.root; shutdown now + + from a running system, which will drop it to single user + mode. + + Alternatively, reboot the system, and at the boot prompt, + select the single user option. The system will then boot + single user. At the shell prompt you should then run: + + &prompt.root; fsck -p +&prompt.root; mount -u / +&prompt.root; mount -a -t ufs +&prompt.root; swapon -a + + This checks the file systems, remounts / + read/write, mounts all the other UFS file systems referenced in + /etc/fstab and then turns swapping on. + + + + If your CMOS clock is set to local time and not to GMT + (this is true if the output of the &man.date.1; command + does not show the correct time and zone), + you may also need to run the following command: +&prompt.root; adjkerntz -i + + This will make sure that your local time-zone settings + get set up correctly — without this, you may later run into some + problems. + + + + + + + Remove <filename>/usr/obj</filename> + + As parts of the system are rebuilt they are placed in + directories which (by default) go under + /usr/obj. The directories shadow those under + /usr/src. + + You can speed up the make buildworld process, and + possibly save yourself some dependency headaches by removing this + directory as well. + + Some files below /usr/obj may have the + immutable flag set (see &man.chflags.1; for more information) + which must be removed first. + + &prompt.root; cd /usr/obj +&prompt.root; chflags -R noschg * +&prompt.root; rm -rf * + + + + Recompile the Base System + + + Saving the Output + + It is a good idea to save the output you get from running + &man.make.1; to another file. If something goes wrong you will + have a copy of the error message. While this might not help you + in diagnosing what has gone wrong, it can help others if you post + your problem to one of the &os; mailing lists. + + The easiest way to do this is to use the &man.script.1; + command, with a parameter that specifies the name of the file to + save all output to. You would do this immediately before + rebuilding the world, and then type exit + when the process has finished. + + &prompt.root; script /var/tmp/mw.out +Script started, output file is /var/tmp/mw.out +&prompt.root; make TARGET +… compile, compile, compile … +&prompt.root; exit +Script done, … + + If you do this, do not save the output + in /tmp. This directory may be cleared + next time you reboot. A better place to store it is in + /var/tmp (as in the previous example) or + in root's home directory. + + + + Compile the Base System + + You must be in the /usr/src + directory: + + &prompt.root; cd /usr/src + + (unless, of course, your source code is elsewhere, in which + case change to that directory instead). + make + + To rebuild the world you use the &man.make.1; command. This + command reads instructions from the Makefile, + which describes how the programs that comprise &os; should be + rebuilt, the order in which they should be built, and so on. + + The general format of the command line you will type is as + follows: + + &prompt.root; make -x -DVARIABLE target + + In this example, + is an option that you would pass to &man.make.1;. See the + &man.make.1; manual page for an example of the options you can + pass. + + + passes a variable to the Makefile. The + behavior of the Makefile is controlled by + these variables. These are the same variables as are set in + /etc/make.conf, and this provides another + way of setting them. + + &prompt.root; make -DNO_PROFILE target + + is another way of specifying that profiled libraries should + not be built, and corresponds with the + + NO_PROFILE= true # Avoid compiling profiled libraries + + line in /etc/make.conf. + + target tells &man.make.1; what + you want to do. Each Makefile defines a + number of different targets, and your choice of + target determines what happens. + + Some targets are listed in the + Makefile, but are not meant for you to run. + Instead, they are used by the build process to break out the + steps necessary to rebuild the system into a number of + sub-steps. + + Most of the time you will not need to pass any parameters to + &man.make.1;, and so your command like will look like + this: + + &prompt.root; make target + + Where target will be one of + many build options. The first target should always be + buildworld. + + As the names imply, buildworld + builds a complete new tree under /usr/obj, + and installworld, another target, installs this tree on + the current machine. + + Having separate options is very useful for two reasons. First, it allows you + to do the build safe in the knowledge that no components of + your running system will be affected. The build is + self hosted. Because of this, you can safely + run buildworld on a machine running + in multi-user mode with no fear of ill-effects. It is still + recommended that you run the + installworld part in single user + mode, though. + + Secondly, it allows you to use NFS mounts to upgrade + multiple machines on your network. If you have three machines, + A, B and C that you want to upgrade, run make + buildworld and make installworld on + A. B and C should then NFS mount /usr/src + and /usr/obj from A, and you can then run + make installworld to install the results of + the build on B and C. + + Although the world target still exists, + you are strongly encouraged not to use it. + + Run + + &prompt.root; make buildworld + + It is possible to specify a option to + make which will cause it to spawn several + simultaneous processes. This is most useful on multi-CPU machines. + However, since much of the compiling process is IO bound rather + than CPU bound it is also useful on single CPU machines. + + On a typical single-CPU machine you would run: + + &prompt.root; make -j4 buildworld + + &man.make.1; will then have up to 4 processes running at any one + time. Empirical evidence posted to the mailing lists shows this + generally gives the best performance benefit. + + If you have a multi-CPU machine and you are using an SMP + configured kernel try values between 6 and 10 and see how they speed + things up. + + + + Timings + + rebuilding world + timings + + + Many factors influence the build time, but fairly recent + machines may only take a one or two hours to build + the &os.stable; tree, with no tricks or shortcuts used during the + process. A &os.current; tree will take somewhat longer. + + + + + Compile and Install a New Kernel + + kernel + compiling + + + To take full advantage of your new system you should recompile the + kernel. This is practically a necessity, as certain memory structures + may have changed, and programs like &man.ps.1; and &man.top.1; will + fail to work until the kernel and source code versions are the + same. + + The simplest, safest way to do this is to build and install a + kernel based on GENERIC. While + GENERIC may not have all the necessary devices + for your system, it should contain everything necessary to boot your + system back to single user mode. This is a good test that the new + system works properly. After booting from + GENERIC and verifying that your system works you + can then build a new kernel based on your normal kernel configuration + file. + + On &os; it is important to build world before building a + new kernel. + + If you want to build a custom kernel, and already have a configuration + file, just use KERNCONF=MYKERNEL + like this: + + &prompt.root; cd /usr/src +&prompt.root; make buildkernel KERNCONF=MYKERNEL +&prompt.root; make installkernel KERNCONF=MYKERNEL + + + Note that if you have raised kern.securelevel + above 1 and you have set either the + noschg or similar flags to your kernel binary, you + might find it necessary to drop into single user mode to use + installkernel. Otherwise you should be able + to run both these commands from multi user mode without + problems. See &man.init.8; for details about + kern.securelevel and &man.chflags.1; for details + about the various file flags. + + + + Reboot into Single User Mode + single-user mode + + You should reboot into single user mode to test the new kernel + works. Do this by following the instructions in + . + + + + Install the New System Binaries + + If you were building a version of &os; recent enough to have + used make buildworld then you should now use + installworld to install the new system + binaries. + + Run + + &prompt.root; cd /usr/src +&prompt.root; make installworld + + + If you specified variables on the make + buildworld command line, you must specify the same + variables in the make installworld command + line. This does not necessarily hold true for other options; + for example, must never be used with + installworld. + + For example, if you ran: + + &prompt.root; make -DNO_PROFILE buildworld + + you must install the results with: + + &prompt.root; make -DNO_PROFILE installworld + + otherwise it would try to install profiled libraries that + had not been built during the make buildworld + phase. + + + + + Update Files Not Updated by <command>make installworld</command> + + Remaking the world will not update certain directories (in + particular, /etc, /var and + /usr) with new or changed configuration files. + + The simplest way to update these files is to use + &man.mergemaster.8;, though it is possible to do it manually + if you would prefer to do that. Regardless of which way you + choose, be sure to make a backup of /etc in + case anything goes wrong. + + + + + + Tom + Rhodes + Contributed by + + + + <command>mergemaster</command> + mergemaster + + The &man.mergemaster.8; utility is a Bourne script that will + aid you in determining the differences between your configuration files + in /etc, and the configuration files in + the source tree /usr/src/etc. This is + the recommended solution for keeping the system configuration files up to date + with those located in the source tree. + + To begin simply type mergemaster at your prompt, and + watch it start going. mergemaster will then build a + temporary root environment, from / down, and populate + it with various system configuration files. Those files are then compared + to the ones currently installed in your system. At this point, files that + differ will be shown in &man.diff.1; format, with the sign + representing added or modified lines, and representing + lines that will be either removed completely, or replaced with a new line. + See the &man.diff.1; manual page for more information about the &man.diff.1; + syntax and how file differences are shown. + + &man.mergemaster.8; will then show you each file that displays variances, + and at this point you will have the option of either deleting the new file (referred + to as the temporary file), installing the temporary file in its unmodified state, + merging the temporary file with the currently installed file, or viewing the + &man.diff.1; results again. + + Choosing to delete the temporary file will tell &man.mergemaster.8; that we + wish to keep our current file unchanged, and to delete the new version. + This option is not recommended, unless you see no + reason to change the current file. You can get help at any time by + typing ? at the &man.mergemaster.8; prompt. If the user + chooses to skip a file, it will be presented again after all other files + have been dealt with. + + Choosing to install the unmodified temporary file will replace the + current file with the new one. For most unmodified files, this is the best + option. + + Choosing to merge the file will present you with a text editor, + and the contents of both files. You can now merge them by + reviewing both files side by side on the screen, and choosing parts from + both to create a finished product. When the files are compared side by side, + the l key will select the left contents and the + r key will select contents from your right. + The final output will be a file consisting of both parts, which can then be + installed. This option is customarily used for files where settings have been + modified by the user. + + Choosing to view the &man.diff.1; results again will show you the file differences + just like &man.mergemaster.8; did before prompting you for an option. + + After &man.mergemaster.8; is done with the system files you will be + prompted for other options. &man.mergemaster.8; may ask if you want to rebuild + the password file and will finish up with an option to + remove left-over temporary files. + + + + Manual Update + + If you wish to do the update manually, however, + you cannot just copy over the files from + /usr/src/etc to /etc and + have it work. Some of these files must be installed + first. This is because the /usr/src/etc + directory is not a copy of what your + /etc directory should look like. In addition, + there are files that should be in /etc that are + not in /usr/src/etc. + + If you are using &man.mergemaster.8; (as recommended), + you can skip forward to the next + section. + + The simplest way to do this by hand is to install the + files into a new directory, and then work through them looking + for differences. + + + Backup Your Existing <filename>/etc</filename> + + Although, in theory, nothing is going to touch this directory + automatically, it is always better to be sure. So copy your + existing /etc directory somewhere safe. + Something like: + + &prompt.root; cp -Rp /etc /etc.old + + does a recursive copy, + preserves times, ownerships on files and suchlike. + + + You need to build a dummy set of directories to install the new + /etc and other files into. + /var/tmp/root is a reasonable choice, and + there are a number of subdirectories required under this as + well. + + &prompt.root; mkdir /var/tmp/root +&prompt.root; cd /usr/src/etc +&prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distribution + + This will build the necessary directory structure and install the + files. A lot of the subdirectories that have been created under + /var/tmp/root are empty and should be deleted. + The simplest way to do this is to: + + &prompt.root; cd /var/tmp/root +&prompt.root; find -d . -type d | xargs rmdir 2>/dev/null + + This will remove all empty directories. (Standard error is + redirected to /dev/null to prevent the warnings + about the directories that are not empty.) + + /var/tmp/root now contains all the files that + should be placed in appropriate locations below + /. You now have to go through each of these + files, determining how they differ with your existing files. + + Note that some of the files that will have been installed in + /var/tmp/root have a leading .. At the + time of writing the only files like this are shell startup files in + /var/tmp/root/ and + /var/tmp/root/root/, although there may be others + (depending on when you are reading this). Make sure you use + ls -a to catch them. + + The simplest way to do this is to use &man.diff.1; to compare the + two files: + + &prompt.root; diff /etc/shells /var/tmp/root/etc/shells + + This will show you the differences between your + /etc/shells file and the new + /var/tmp/root/etc/shells file. Use these to decide whether to + merge in changes that you have made or whether to copy over your old + file. + + + Name the New Root Directory + (<filename>/var/tmp/root</filename>) with a Time Stamp, so You Can + Easily Compare Differences Between Versions + + Frequently rebuilding the world means that you have to update + /etc frequently as well, which can be a bit of + a chore. + + You can speed this process up by keeping a copy of the last set + of changed files that you merged into /etc. + The following procedure gives one idea of how to do this. + + + + Make the world as normal. When you want to update + /etc and the other directories, give the + target directory a name based on the current date. If you were + doing this on the 14th of February 1998 you could do the + following: + + &prompt.root; mkdir /var/tmp/root-19980214 +&prompt.root; cd /usr/src/etc +&prompt.root; make DESTDIR=/var/tmp/root-19980214 \ + distrib-dirs distribution + + + + Merge in the changes from this directory as outlined + above. + + Do not remove the + /var/tmp/root-19980214 directory when you + have finished. + + + + When you have downloaded the latest version of the source + and remade it, follow step 1. This will give you a new + directory, which might be called + /var/tmp/root-19980221 (if you wait a week + between doing updates). + + + + You can now see the differences that have been made in the + intervening week using &man.diff.1; to create a recursive diff + between the two directories: + + &prompt.root; cd /var/tmp +&prompt.root; diff -r root-19980214 root-19980221 + + Typically, this will be a much smaller set of differences + than those between + /var/tmp/root-19980221/etc and + /etc. Because the set of differences is + smaller, it is easier to migrate those changes across into your + /etc directory. + + + + You can now remove the older of the two + /var/tmp/root-* directories: + + &prompt.root; rm -rf /var/tmp/root-19980214 + + + + Repeat this process every time you need to merge in changes + to /etc. + + + + You can use &man.date.1; to automate the generation of the + directory names: + + &prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"` + + + + + + Rebooting + + You are now done. After you have verified that everything appears + to be in the right place you can reboot the system. A simple + &man.shutdown.8; should do it: + + &prompt.root; shutdown -r now + + + + Finished + + You should now have successfully upgraded your &os; system. + Congratulations. + + If things went slightly wrong, it is easy to rebuild a particular + piece of the system. For example, if you accidentally deleted + /etc/magic as part of the upgrade or merge of + /etc, the &man.file.1; command will stop working. + In this case, the fix would be to run: + + &prompt.root; cd /usr/src/usr.bin/file +&prompt.root; make all install + + + + Questions + + + + + Do I need to re-make the world for every change? + + + + There is no easy answer to this one, as it depends on the + nature of the change. For example, if you just ran CVSup, and + it has shown the following files as being updated: + + src/games/cribbage/instr.c +src/games/sail/pl_main.c +src/release/sysinstall/config.c +src/release/sysinstall/media.c +src/share/mk/bsd.port.mk + + it probably is not worth rebuilding the entire world. + You could just go to the appropriate sub-directories and + make all install, and that's about it. But + if something major changed, for example + src/lib/libc/stdlib then you should either + re-make the world, or at least those parts of it that are + statically linked (as well as anything else you might have added + that is statically linked). + + At the end of the day, it is your call. You might be happy + re-making the world every fortnight say, and let changes + accumulate over that fortnight. Or you might want to re-make + just those things that have changed, and be confident you can + spot all the dependencies. + + And, of course, this all depends on how often you want to + upgrade, and whether you are tracking &os.stable; or + &os.current;. + + + + + + My compile failed with lots of signal 11 (or other signal + number) errors. What has happened? + + signal 11 + + + + This is normally indicative of hardware problems. + (Re)making the world is an effective way to stress test your + hardware, and will frequently throw up memory problems. These + normally manifest themselves as the compiler mysteriously dying + on receipt of strange signals. + + A sure indicator of this is if you can restart the make and + it dies at a different point in the process. + + In this instance there is little you can do except start + swapping around the components in your machine to determine + which one is failing. + + + + + + Can I remove /usr/obj when I have + finished? + + + + The short answer is yes. + + /usr/obj contains all the object files + that were produced during the compilation phase. Normally, one + of the first steps in the make buildworld process is to + remove this directory and start afresh. In this case, keeping + /usr/obj around after you have finished + makes little sense, and will free up a large chunk of disk space + (currently about 340 MB). + + However, if you know what you are doing you can have + make buildworld skip this step. This will make subsequent + builds run much faster, since most of sources will not need to + be recompiled. The flip side of this is that subtle dependency + problems can creep in, causing your build to fail in odd ways. + This frequently generates noise on the &os; mailing lists, + when one person complains that their build has failed, not + realizing that it is because they have tried to cut + corners. + + + + + + Can interrupted builds be resumed? + + + + This depends on how far through the process you got before + you found a problem. + + In general (and this is not a hard and + fast rule) the make buildworld process builds new + copies of essential tools (such as &man.gcc.1;, and + &man.make.1;) and the system libraries. These tools and + libraries are then installed. The new tools and libraries are + then used to rebuild themselves, and are installed again. The + entire system (now including regular user programs, such as + &man.ls.1; or &man.grep.1;) is then rebuilt with the new + system files. + + If you are at the last stage, and you know it (because you + have looked through the output that you were storing) then you + can (fairly safely) do: + + … fix the problem … +&prompt.root; cd /usr/src +&prompt.root; make -DNO_CLEAN all + + This will not undo the work of the previous + make buildworld. + + If you see the message: + + -------------------------------------------------------------- +Building everything.. +-------------------------------------------------------------- + + in the make buildworld output then it is + probably fairly safe to do so. + + If you do not see that message, or you are not sure, then it + is always better to be safe than sorry, and restart the build + from scratch. + + + + + + How can I speed up making the world? + + + + + + Run in single user mode. + + + + Put the /usr/src and + /usr/obj directories on separate + file systems held on separate disks. If possible, put these + disks on separate disk controllers. + + + + Better still, put these file systems across multiple + disks using the &man.ccd.4; (concatenated disk + driver) device. + + + + Turn off profiling (set NO_PROFILE=true in + /etc/make.conf). You almost certainly + do not need it. + + + + Also in /etc/make.conf, set + CFLAGS to something like . The optimization is much + slower, and the optimization difference between + and is normally + negligible. lets the compiler use + pipes rather than temporary files for communication, which + saves disk access (at the expense of memory). + + + + Pass the option to &man.make.1; to + run multiple processes in parallel. This usually helps + regardless of whether you have a single or a multi processor + machine. + + + The file system holding + /usr/src can be mounted (or remounted) + with the option. This prevents the + file system from recording the file access time. You probably + do not need this information anyway. + + &prompt.root; mount -u -o noatime /usr/src + + + The example assumes /usr/src is + on its own file system. If it is not (if it is a part of + /usr for example) then you will + need to use that file system mount point, and not + /usr/src. + + + + + The file system holding /usr/obj can + be mounted (or remounted) with the + option. This causes disk writes to happen asynchronously. + In other words, the write completes immediately, and the + data is written to the disk a few seconds later. This + allows writes to be clustered together, and can be a + dramatic performance boost. + + + Keep in mind that this option makes your file system + more fragile. With this option there is an increased + chance that, should power fail, the file system will be in + an unrecoverable state when the machine restarts. + + If /usr/obj is the only thing on + this file system then it is not a problem. If you have + other, valuable data on the same file system then ensure + your backups are fresh before you enable this + option. + + + &prompt.root; mount -u -o async /usr/obj + + + As above, if /usr/obj is not on + its own file system, replace it in the example with the + name of the appropriate mount point. + + + + + + + + + What do I do if something goes wrong? + + + + Make absolutely sure your environment has no + extraneous cruft from earlier builds. This is simple + enough. + + &prompt.root; chflags -R noschg /usr/obj/usr +&prompt.root; rm -rf /usr/obj/usr +&prompt.root; cd /usr/src +&prompt.root; make cleandir +&prompt.root; make cleandir + + Yes, make cleandir really should + be run twice. + + Then restart the whole process, starting + with make buildworld. + + If you still have problems, send the error and the + output of uname -a to &a.questions;. + Be prepared to answer other questions about your + setup! + + + + + + + + + + + Mike + Meyer + Contributed by + + + + Tracking for Multiple Machines + + NFS + installing multiple machines + + + If you have multiple machines that you want to track the + same source tree, then having all of them download sources and + rebuild everything seems like a waste of resources: disk space, + network bandwidth, and CPU cycles. It is, and the solution is + to have one machine do most of the work, while the rest of the + machines mount that work via NFS. This section outlines a + method of doing so. + + + Preliminaries + + First, identify a set of machines that is going to run + the same set of binaries, which we will call a + build set. Each machine can have a + custom kernel, but they will be running the same userland + binaries. From that set, choose a machine to be the + build machine. It is going to be the + machine that the world and kernel are built on. Ideally, it + should be a fast machine that has sufficient spare CPU to + run make buildworld and + make buildkernel. You will also want to + choose a machine to be the test + machine, which will test software updates before they + are put into production. This must be a + machine that you can afford to have down for an extended + period of time. It can be the build machine, but need not be. + + All the machines in this build set need to mount + /usr/obj and + /usr/src from the same machine, and at + the same point. Ideally, those are on two different drives + on the build machine, but they can be NFS mounted on that machine + as well. If you have multiple build sets, + /usr/src should be on one build machine, and + NFS mounted on the rest. + + Finally make sure that + /etc/make.conf on all the machines in + the build set agrees with the build machine. That means that + the build machine must build all the parts of the base + system that any machine in the build set is going to + install. Also, each build machine should have its kernel + name set with KERNCONF in + /etc/make.conf, and the build machine + should list them all in KERNCONF, listing + its own kernel first. The build machine must have the kernel + configuration files for each machine in + /usr/src/sys/arch/conf + if it is going to build their kernels. + + + + The Base System + + Now that all that is done, you are ready to build + everything. Build the kernel and world as described in on the build machine, + but do not install anything. After the build has finished, go + to the test machine, and install the kernel you just + built. If this machine mounts /usr/src + and /usr/obj via NFS, when you reboot + to single user you will need to enable the network and mount + them. The easiest way to do this is to boot to multi-user, + then run shutdown now to go to single user + mode. Once there, you can install the new kernel and world and run + mergemaster just as you normally would. When + done, reboot to return to normal multi-user operations for this + machine. + + After you are certain that everything on the test + machine is working properly, use the same procedure to + install the new software on each of the other machines in + the build set. + + + + Ports + + The same ideas can be used for the ports tree. The first + critical step is mounting /usr/ports from + the same machine to all the machines in the build set. You can + then set up /etc/make.conf properly to share + distfiles. You should set DISTDIR to a + common shared directory that is writable by whichever user + root is mapped to by your NFS mounts. Each + machine should set WRKDIRPREFIX to a + local build directory. Finally, if you are going to be + building and distributing packages, you should set + PACKAGES to a directory similar to + DISTDIR. + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/desktop/Makefile b/pl_PL.ISO8859-2/books/handbook/desktop/Makefile new file mode 100644 index 0000000000..6dd222f080 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/desktop/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= desktop/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/desktop/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/desktop/chapter.sgml new file mode 100644 index 0000000000..e317670c06 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/desktop/chapter.sgml @@ -0,0 +1,1117 @@ + + + + + + + Christophe + Juniet + Contributed by + + + + + Desktop Applications + + + Synopsis + + FreeBSD can run a wide variety of desktop applications, such + as browsers and word processors. Most of these are available as + packages or can be automatically built from the ports + collection. Many new users expect to find these kinds of + applications on their desktop. This chapter will show you how + to install some popular desktop applications effortlessly, + either from their packages or from the Ports Collection. + + Note that when installing programs from the ports, they are + compiled from source. This can take a very long time, depending + on what you are compiling and the processing power of your + machine(s). If building from source takes a prohibitively long + amount of time for you, you can install most of the programs of + the Ports Collection from pre-built packages. + + As FreeBSD features Linux binary compatibility, many + applications originally developed for Linux are available for + your desktop. It is strongly recommended that you read + before installing any of the Linux + applications. Many of the ports using the Linux binary + compatibility start with linux-. Remember this + when you search for a particular port, for instance with + &man.whereis.1;. In the following text, it is assumed that you + have enabled Linux binary compatibility before installing any of + the Linux applications. + + Here are the categories covered by this chapter: + + + + Browsers (such as Mozilla, + Opera, + Firefox, + Konqueror) + + + + Productivity (such as + KOffice, + AbiWord, + The GIMP, + OpenOffice.org) + + + + Document Viewers (such as &acrobat.reader;, + gv, + Xpdf, + GQview) + + + + Finance (such as + GnuCash, + Gnumeric, + Abacus) + + + + Before reading this chapter, you should: + + + + Know how to install additional third-party software + (). + + + + Know how to install additional Linux software + (). + + + + For information on how to get a multimedia environment, read + . If you want to set up and use + electronic mail, please refer to . + + + + Browsers + + + browsers + web + + + FreeBSD does not come with a particular browser + pre-installed. Instead, the + www + directory of the Ports Collection contains a lot of browsers + ready to be installed. If you do not have time to compile + everything (this can take a very long time in some cases) many + of them are available as packages. + + KDE and + GNOME already provide HTML browsers. + Please refer to for more information on + how to set up these complete desktops. + + If you are looking for light-weight browsers, you should + investigate the Ports Collection for + www/dillo, + www/links, or + www/w3m. + + This section covers these applications: + + + + + + Application Name + Resources Needed + Installation from Ports + Major Dependencies + + + + + + Mozilla + heavy + heavy + Gtk+ + + + + Opera + light + light + FreeBSD and Linux versions available. The Linux + version depends on the Linux Binary Compatibility and + linux-openmotif. + + + + Firefox + medium + heavy + Gtk+ + + + + Konqueror + medium + heavy + KDE Libraries + + + + + + + Mozilla + + Mozilla + + + Mozilla is a modern, + stable browser that is fully ported to FreeBSD. It features a very + standards-compliant HTML display engine. It provides a mail + and news reader. It even has a HTML composer if you plan to + write some web pages yourself. Users of + &netscape; will recognize the + similarities with Communicator + suite, as both browsers shared the same basis. + + On slow machines, with a CPU speed less than 233MHz or + with less than 64MB of RAM, Mozilla + can be too resource-consuming to be fully usable. You may + want to look at the Opera browser + instead, described a little later in this chapter. + + If you cannot or do not want to compile + Mozilla for any reason, the FreeBSD + GNOME team has already done this for you. Just install the + package from the network by: + + &prompt.root; pkg_add -r mozilla + + If the package is not available, and you have enough time + and disk space, you can get the source for + Mozilla, compile it and install it + on your system. This is accomplished by: + + &prompt.root; cd /usr/ports/www/mozilla +&prompt.root; make install clean + + The Mozilla port ensures a + correct initialization by running the chrome registry setup + with root privileges. However, if you + want to fetch some add-ons like mouse gestures, you must run + Mozilla as + root to get them properly + installed. + + Once you have completed the installation of + Mozilla, you do not need to be + root any longer. You can start + Mozilla as a browser by typing: + + &prompt.user; mozilla + + You can start it directly as a mail and news reader as + shown below: + + &prompt.user; mozilla -mail + + + + Firefox + + Firefox + + + Firefox is the next-generation + browser based on the Mozilla + codebase. Mozilla is a complete + suite of applications, such as a browser, a mail client, a chat + client and much more. Firefox is + just a browser, which makes it smaller and faster. + + Install the package by typing: + + &prompt.root; pkg_add -r firefox + + You can also use the Ports Collection if you + prefer to compile from source code: + + &prompt.root; cd /usr/ports/www/firefox +&prompt.root; make install clean + + + + Firefox, Mozilla and &java; plugin + + + In this section and in the next one, we assume you + already installed Firefox or + Mozilla. + + + The &os; Foundation has a license with Sun Microsystems to + distribute &os; binaries for the Java Runtime Environment + (&jre;) and Java Development Kit (&jdk;). Binary packages for + &os; are available on the &os; + Foundation web site. + + To add &java; support to + Firefox or + Mozilla, you have to install, at + first, the java/javavmwrapper port. Then, + download the Diablo &jre; package + from , + and install it with &man.pkg.add.1;. + + Start your browser, enter + about:plugins in the location bar and press + Enter. A page regarding installed plugins + will be displayed, the &java; + plugin should be listed there now. + + + + + + Firefox, Mozilla and ¯omedia; &flash; plugin + + ¯omedia; &flash; plugin is not available for &os;. However, + a software layer (wrapper) for running the Linux version of the plugin + exists. This wrapper also supports &adobe; &acrobat; plugin, + RealPlayer plugin and more. + + Install the www/linuxpluginwrapper + port. This port requires + emulators/linux_base which is a + large port. Follow the instructions displayed by the port to set up + your /etc/libmap.conf correctly! Example + configurations are installed into + /usr/local/share/examples/linuxpluginwrapper/ + directory. + + The next step is to install the www/linux-flashplugin7 port. Once + the plugin is installed, start your browser, enter + about:plugins in the location bar and press + Enter. + A list should appear with all the currently + available plugins. + + If the &flash; plugin is not listed, this is, most of time, + caused by a missing symlink. As root, + run the following commands: + + &prompt.root; ln -s /usr/X11R6/lib/linux-flashplugin7/libflashplayer.so \ + /usr/X11R6/lib/browser_plugins/ +&prompt.root; ln -s /usr/X11R6/lib/linux-flashplugin7/flashplayer.xpt \ + /usr/X11R6/lib/browser_plugins/ + + If you restart your browser the plugin should now appears + in the previously mentioned list. Your browser may also crash + when playing some &flash; animations, in this case a patch + can help you: + + &prompt.root; cd /usr/src +&prompt.root; fetch http://people.FreeBSD.org/~nork/rtld_dlsym_hack.diff +&prompt.root; patch < rtld_dlsym_hack.diff +&prompt.root; cd libexec/rtld-elf/ +&prompt.root; make clean +&prompt.root; make obj +&prompt.root; make depend +&prompt.root; make && make install + + Then reboot your machine. + + + The linuxpluginwrapper only works on + the &i386; system architecture. + + + + + + Opera + + Opera + + + Opera is a + full-featured and standards-compliant browser. It also + comes with a built-in mail and news reader, an IRC client, + an RSS/Atom feeds reader and much more. Despite this, + Opera is relatively lightweight + and very fast. It comes in two flavors: a native + FreeBSD version and a version that runs under Linux + emulation. + + To browse the Web with the FreeBSD version of Opera, + install the package: + + &prompt.root; pkg_add -r opera + + Some FTP sites do not have all the packages, but the same + result can be obtained with the Ports Collection by + typing: + + &prompt.root; cd /usr/ports/www/opera +&prompt.root; make install clean + + To install the Linux version of + Opera, substitute + linux-opera in place of + opera in the examples above. The Linux + version is useful in situations requiring the use of plug-ins + that are only available for Linux, such as Adobe + &acrobat.reader;. In all other respects, the + FreeBSD and Linux versions appear to be functionally + identical. + + + + + Konqueror + + Konqueror + + + Konqueror is part of + KDE but it can also be used outside + of KDE by installing + x11/kdebase3. + Konqueror is much more than a browser, + it is also a file manager and a multimedia viewer. + + Konqueror also comes with a set of plugins, + available in misc/konq-plugins. + + Konqueror also supports &flash; and a How To + is available at . + + + + + Productivity + + When it comes to productivity, new users often look for a + good office suite or a friendly word processor. While some + desktop environments like + KDE already provide an office suite, + there is no default application. FreeBSD provides all that is + needed, regardless of your desktop environment. + + This section covers these applications: + + + + + + Application Name + Resources Needed + Installation from Ports + Major Dependencies + + + + + + KOffice + light + heavy + KDE + + + + AbiWord + light + light + Gtk+ or GNOME + + + + The Gimp + light + heavy + Gtk+ + + + + OpenOffice.org + heavy + huge + &jdk; 1.4, Mozilla + + + + + + + KOffice + + KOffice + + + office suite + KOffice + + + The KDE community has provided its desktop environment + with an office suite which can be used outside + KDE. It includes the four standard + components that can be found in other office suites. + KWord is the word processor, + KSpread is the spreadsheet program, + KPresenter manages slide + presentations, and Kontour lets you + draw graphical documents. + + Before installing the latest + KOffice, make sure you have an + up-to-date version of KDE. + + To install KOffice as a + package, issue the following command: + + &prompt.root; pkg_add -r koffice + + If the package is not available, you can use the ports + collection. For instance, to install + KOffice for + KDE3, do: + + &prompt.root; cd /usr/ports/editors/koffice-kde3 +&prompt.root; make install clean + + + + AbiWord + + AbiWord + + + AbiWord is a free word + processing program similar in look and feel to µsoft; Word. + It is suitable for typing papers, letters, reports, memos, and + so forth. It is very fast, contains many features, and is + very user-friendly. + + AbiWord can import or export + many file formats, including some proprietary ones like + Microsoft .doc. + + AbiWord is available as a + package. You can install it by: + + &prompt.root; pkg_add -r abiword + + If the package is not available, it can be compiled from + the Ports Collection. The Ports Collection should be more + up to date. It can be done as follows: + + &prompt.root; cd /usr/ports/editors/abiword +&prompt.root; make install clean + + + + The GIMP + + The GIMP + + + For image authoring or picture retouching, + The GIMP is a very sophisticated + image manipulation program. It can be used as a simple paint + program or as a quality photo retouching suite. It supports a + large number of plug-ins and features a scripting interface. + The GIMP can read and write a wide + range of file formats. It supports interfaces with scanners + and tablets. + + You can install the package by issuing this + command: + + &prompt.root; pkg_add -r gimp + + If your FTP site does not have this package, you can use + the Ports Collection. The + graphics + directory of the Ports Collection also contains + The Gimp Manual. Here is how to + get them installed: + + &prompt.root; cd /usr/ports/graphics/gimp +&prompt.root; make install clean +&prompt.root; cd /usr/ports/graphics/gimp-manual-pdf +&prompt.root; make install clean + + + The + graphics + directory of the Ports Collection holds the development + version of The GIMP in + graphics/gimp-devel. + An HTML version of + The Gimp Manual is available from + graphics/gimp-manual-html. + + + + + OpenOffice.org + + OpenOffice.org + + + office suite + OpenOffice.org + + + OpenOffice.org includes all of the + mandatory applications in a complete office productivity + suite: a word processor, a spreadsheet, a presentation manager, + and a drawing program. Its user interface is very similar + to other office suites, and it can import and export in various + popular file formats. It is available in a number of + different languages including interfaces, spell checkers, and + dictionaries. + + The word processor of + OpenOffice.org uses a native XML + file format for increased portability and flexibility. The + spreadsheet program features a macro language and it can be + interfaced with external databases. + OpenOffice.org is already stable + and runs natively on &windows;, &solaris;, Linux, FreeBSD, + and &macos; X. More + information about OpenOffice.org + can be found on the + OpenOffice.org web site. + For FreeBSD specific information, and to directly + download packages use the FreeBSD OpenOffice.org + Porting Team's web site. + + To install OpenOffice.org, + do: + + &prompt.root; pkg_add -r openoffice + + + When running a -RELEASE version of &os;, this should work. + Otherwise, you should look on the &os; OpenOffice.org Porting Team's + web site to download and install the appropriate package + using &man.pkg.add.1;. Both the current release and + development version are available for download at this + location. + + + Once the package is installed, you just have to type the + following command to run + OpenOffice.org: + + &prompt.user; openoffice.org + + + During the first launch, you will be asked some + questions and a .openoffice.org2 folder + will be created in your home directory. + + + If the OpenOffice.org packages + are not available, you still have the option to compile the + port. However, you must bear in mind that it requires a lot of + disk space and a fairly long time to compile. + + &prompt.root; cd /usr/ports/editors/openoffice.org-2.0 +&prompt.root; make install clean + + + If you want to build a localized version, replace the + previous command line with the following: + + &prompt.root; make LOCALIZED_LANG=your_language install clean + + You have to replace + your_language with the correct + language ISO-code. A list of supported language codes is + available in the + files/Makefile.localized file, located + in the port directory. + + + Once this is done, + OpenOffice.org can be launched with + the command: + + &prompt.user; openoffice.org + + + + + Document Viewers + + Some new document formats have recently gained popularity. + The standard viewers they require may not be available in the + base system. We will see how to install them in this + section. + + This section covers these applications: + + + + + + Application Name + Resources Needed + Installation from Ports + Major Dependencies + + + + + + &acrobat.reader; + light + light + Linux Binary Compatibility + + + + gv + light + light + Xaw3d + + + + Xpdf + light + light + FreeType + + + + GQview + light + light + Gtk+ or GNOME + + + + + + + &acrobat.reader; + + Acrobat Reader + + + PDF + viewing + + + Many documents are now distributed as PDF files, + which stands for Portable Document Format. One + of the recommended viewers for these types of files is + &acrobat.reader;, released by Adobe + for Linux. As FreeBSD can run Linux binaries, it is also + available for FreeBSD. + + To install &acrobat.reader; 7 from + the Ports collection, do: + + &prompt.root; cd /usr/ports/print/acroread7 +&prompt.root; make install clean + + A package is not available due to licencing restrictions. + + + + + gv + + gv + + + PDF + viewing + + + PostScript + viewing + + + gv is a &postscript; and PDF + viewer. It is originally based on + ghostview but it has a nicer look + thanks to the Xaw3d library. It is fast and its interface is + clean. gv has many features like + orientation, paper size, scale, or antialias. Almost any + operation can be done either from the keyboard or the + mouse. + + To install gv as a package, + do: + + &prompt.root; pkg_add -r gv + + If you cannot get the package, you can use the Ports + collection: + + &prompt.root; cd /usr/ports/print/gv +&prompt.root; make install clean + + + + Xpdf + + Xpdf + + + PDF + viewing + + + If you want a small FreeBSD PDF viewer, + Xpdf is a light-weight and + efficient viewer. It requires very few resources and is + very stable. It uses the standard X fonts and does not + require &motif; or any other X toolkit. + + To install the Xpdf package, + issue this command: + + &prompt.root; pkg_add -r xpdf + + If the package is not available or you prefer to use the + Ports Collection, do: + + &prompt.root; cd /usr/ports/graphics/xpdf +&prompt.root; make install clean + + Once the installation is complete, you can launch + Xpdf and use the right mouse button + to activate the menu. + + + + GQview + + GQview + + + GQview is an image manager. + You can view a file with a single click, launch an external + editor, get thumbnail previews, and much more. It also + features a slideshow mode and some basic file operations. You + can manage image collections and easily find duplicates. + GQview can do full screen viewing + and supports internationalization. + + If you want to install the + GQview package, do: + + &prompt.root; pkg_add -r gqview + + If the package is not available or you prefer to use the + Ports Collection, do: + + &prompt.root; cd /usr/ports/graphics/gqview +&prompt.root; make install clean + + + + + Finance + + If, for any reason, you would like to manage your personal + finances on your FreeBSD Desktop, there are some powerful and + easy to use applications ready to be installed. Some of them + are compatible with widespread file formats like those of + Quicken or Excel documents. + + This section covers these applications: + + + + + + Application Name + Resources Needed + Installation from Ports + Major Dependencies + + + + + + GnuCash + light + heavy + GNOME + + + + Gnumeric + light + heavy + GNOME + + + + Abacus + light + light + Tcl/Tk + + + + + + + GnuCash + + GnuCash + + + GnuCash is part of the + GNOME effort to provide + user-friendly yet powerful applications to end-users. With + GnuCash, you can keep track of your + income and expenses, your bank accounts, or your stocks. It + features an intuitive interface while remaining very + professional. + + GnuCash provides a smart + register, a hierarchical system of accounts, many keyboard + accelerators and auto-completion methods. It can split a + single transaction into several more detailed pieces. + GnuCash can import and merge + Quicken QIF files. It also handles most international date + and currency formats. + + To install GnuCash on your + system, do: + + &prompt.root; pkg_add -r gnucash + + If the package is not available, you can use the ports + collection: + + &prompt.root; cd /usr/ports/finance/gnucash +&prompt.root; make install clean + + + + Gnumeric + + Gnumeric + + + spreadsheet + Gnumeric + + + Gnumeric is a spreadsheet, part + of the GNOME desktop environment. + It features convenient automatic guessing of user + input according to the cell format and an autofill system for + many sequences. It can import files in a number of popular + formats like those of Excel, Lotus 1-2-3, or Quattro Pro. + Gnumeric supports graphs through + the math/guppi graphing + program. It has a large number of built-in functions and + allows all of the usual cell formats such as number, currency, + date, time, and much more. + + To install Gnumeric as a + package, type in: + + &prompt.root; pkg_add -r gnumeric + + If the package is not available, you can use the ports + collection by doing: + + &prompt.root; cd /usr/ports/math/gnumeric +&prompt.root; make install clean + + + + Abacus + + Abacus + + + spreadsheet + Abacus + + + Abacus is a small and easy to + use spreadsheet. It includes many built-in functions useful + in several domains such as statistics, finances, and + mathematics. It can import and export the Excel file format. + Abacus can produce &postscript; + output. + + To install Abacus from its + package, do: + + &prompt.root; pkg_add -r abacus + + If the package is not available, you can use the ports + collection by doing: + + &prompt.root; cd /usr/ports/deskutils/abacus +&prompt.root; make install clean + + + + + Summary + + While FreeBSD is popular among ISPs for its performance and + stability, it is quite ready for day-to-day use as a desktop. + With several thousand applications available as + packages or + ports, + you can build a perfect desktop that suits all your needs. + + Once you have achieved the installation of your desktop, you + may want to go one step further with + misc/instant-workstation. + This meta-port allows you to build a typical set + of ports for a workstation. You can customize it by editing + /usr/ports/misc/instant-workstation/Makefile. + Follow the syntax used for the default set to add or remove + ports, and build it with the usual procedure. + Eventually, you will be able to create a big package that + corresponds to your very own desktop and install it to your + other workstations! + + Here is a quick review of all the desktop applications + covered in this chapter: + + + + + + Application Name + Package Name + Ports Name + + + + + + Mozilla + mozilla + www/mozilla + + + + Opera + opera + www/opera + + + + Firefox + firefox + www/firefox + + + + KOffice + koffice-kde3 + editors/koffice-kde3 + + + + AbiWord + abiword + editors/abiword + + + + The GIMP + gimp + graphics/gimp + + + + OpenOffice.org + openoffice + editors/openoffice-1.1 + + + + &acrobat.reader; + acroread + print/acroread7 + + + + gv + gv + print/gv + + + + Xpdf + xpdf + graphics/xpdf + + + + GQview + gqview + graphics/gqview + + + + GnuCash + gnucash + finance/gnucash + + + + Gnumeric + gnumeric + math/gnumeric + + + + Abacus + abacus + deskutils/abacus + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/disks/Makefile b/pl_PL.ISO8859-2/books/handbook/disks/Makefile new file mode 100644 index 0000000000..140975c79e --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/disks/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= disks/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/disks/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/disks/chapter.sgml new file mode 100644 index 0000000000..1b12843d99 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/disks/chapter.sgml @@ -0,0 +1,4061 @@ + + + + Storage + + + Synopsis + + + This chapter covers the use of disks in FreeBSD. This + includes memory-backed disks, network-attached disks, + standard SCSI/IDE storage devices, and devices using the USB + interface. + + After reading this chapter, you will know: + + The terminology FreeBSD uses to describe the + organization of data on a physical disk (partitions and slices). + + How to add additional hard disks to your system. + + + How to configure &os; to use USB storage devices. + + How to set up virtual file systems, such as memory + disks. + + How to use quotas to limit disk space usage. + + + How to encrypt disks to secure them against attackers. + + + How to create and burn CDs and DVDs on FreeBSD. + + + The various storage media options for backups. + + + How to use backup programs available under FreeBSD. + + + How to backup to floppy disks. + + + What file system snapshots are and how to use them efficiently. + + + + Before reading this chapter, you should: + + + + Know how to configure and install a new FreeBSD kernel + (). + + + + + + + Device Names + + The following is a list of physical storage devices + supported in FreeBSD, and the device names associated with + them. + + + Physical Disk Naming Conventions + + + + + Drive type + Drive device name + + + + + IDE hard drives + ad + + + IDE CDROM drives + acd + + + SCSI hard drives and USB Mass storage devices + da + + + SCSI CDROM drives + cd + + + Assorted non-standard CDROM drives + mcd for Mitsumi CD-ROM and + scd for Sony CD-ROM devices + + + + Floppy drives + fd + + + SCSI tape drives + sa + + + IDE tape drives + ast + + + Flash drives + fla for &diskonchip; Flash device + + + RAID drives + aacd for &adaptec; AdvancedRAID, + mlxd and mlyd + for &mylex;, + amrd for AMI &megaraid;, + idad for Compaq Smart RAID, + twed for &tm.3ware; RAID. + + + +
+ + + + + + + David + O'Brien + Originally contributed by + + + + + + Adding Disks + + + disks + adding + + + Lets say we want to add a new SCSI disk to a machine that + currently only has a single drive. First turn off the computer + and install the drive in the computer following the instructions + of the computer, controller, and drive manufacturer. Due to the + wide variations of procedures to do this, the details are beyond + the scope of this document. + + Login as user root. After you have installed the + drive, inspect /var/run/dmesg.boot to ensure the new + disk was found. Continuing with our example, the newly added drive will + be da1 and we want to mount it on + /1 (if you are adding an IDE drive, the device name + will be ad1). + + partitions + slices + + fdisk + + + FreeBSD runs on IBM-PC compatible computers, therefore it must + take into account the PC BIOS partitions. These are different + from the traditional BSD partitions. A PC disk has up to four + BIOS partition entries. If the disk is going to be truly + dedicated to FreeBSD, you can use the + dedicated mode. Otherwise, FreeBSD will + have to live within one of the PC BIOS partitions. FreeBSD + calls the PC BIOS partitions slices so as + not to confuse them with traditional BSD partitions. You may + also use slices on a disk that is dedicated to FreeBSD, but used + in a computer that also has another operating system installed. + This is a good way to avoid confusing the fdisk utility of + other, non-FreeBSD operating systems. + + In the slice case the drive will be added as + /dev/da1s1e. This is read as: SCSI disk, + unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1), + and e BSD partition. In the dedicated + case, the drive will be added simply as + /dev/da1e. + + Due to the use of 32-bit integers to store the number of sectors, + &man.bsdlabel.8; is + limited to 2^32-1 sectors per disk or 2TB in most cases. The + &man.fdisk.8; format allows a starting sector of no more than + 2^32-1 and a length of no more than 2^32-1, limiting partitions to + 2TB and disks to 4TB in most cases. The &man.sunlabel.8; format + is limited to 2^32-1 sectors per partition and 8 partitions for + a total of 16TB. For larger disks, &man.gpt.8; partitions may be + used. + + + Using &man.sysinstall.8; + + sysinstall + adding disks + + + su + + + + Navigating <application>Sysinstall</application> + + You may use sysinstall to + partition and label a new disk using its easy to use menus. + Either login as user root or use the + su command. Run + sysinstall and enter the + Configure menu. Within the + FreeBSD Configuration Menu, scroll down and + select the Fdisk option. + + + + <application>fdisk</application> Partition Editor + Once inside fdisk, typing A will + use the entire disk for FreeBSD. When asked if you want to + remain cooperative with any future possible operating + systems, answer YES. Write the + changes to the disk using W. Now exit the + FDISK editor by typing q. Next you will be + asked about the Master Boot Record. Since you are adding a + disk to an already running system, choose + None. + + + + Disk Label Editor + BSD partitions + + Next, you need to exit sysinstall + and start it again. Follow the directions above, although this + time choose the Label option. This will + enter the Disk Label Editor. This + is where you will create the traditional BSD partitions. A + disk can have up to eight partitions, labeled + a-h. + A few of the partition labels have special uses. The + a partition is used for the root partition + (/). Thus only your system disk (e.g, + the disk you boot from) should have an a + partition. The b partition is used for + swap partitions, and you may have many disks with swap + partitions. The c partition addresses the + entire disk in dedicated mode, or the entire FreeBSD slice in + slice mode. The other partitions are for general use. + + sysinstall's Label editor + favors the e + partition for non-root, non-swap partitions. Within the + Label editor, create a single file system by typing + C. When prompted if this will be a FS + (file system) or swap, choose FS and type in a + mount point (e.g, /mnt). When adding a + disk in post-install mode, sysinstall + will not create entries + in /etc/fstab for you, so the mount point + you specify is not important. + + You are now ready to write the new label to the disk and + create a file system on it. Do this by typing + W. Ignore any errors from + sysinstall that + it could not mount the new partition. Exit the Label Editor + and sysinstall completely. + + + + Finish + + The last step is to edit /etc/fstab + to add an entry for your new disk. + + + + + + Using Command Line Utilities + + + Using Slices + + This setup will allow your disk to work correctly with + other operating systems that might be installed on your + computer and will not confuse other operating systems' + fdisk utilities. It is recommended + to use this method for new disk installs. Only use + dedicated mode if you have a good reason + to do so! + + &prompt.root; dd if=/dev/zero of=/dev/da1 bs=1k count=1 +&prompt.root; fdisk -BI da1 #Initialize your new disk +&prompt.root; bsdlabel -B -w -r da1s1 auto #Label it. +&prompt.root; bsdlabel -e da1s1 # Edit the bsdlabel just created and add any partitions. +&prompt.root; mkdir -p /1 +&prompt.root; newfs /dev/da1s1e # Repeat this for every partition you created. +&prompt.root; mount /dev/da1s1e /1 # Mount the partition(s) +&prompt.root; vi /etc/fstab # Add the appropriate entry/entries to your /etc/fstab. + + If you have an IDE disk, substitute ad + for da. + + + + Dedicated + OS/2 + + If you will not be sharing the new drive with another operating + system, you may use the dedicated mode. Remember + this mode can confuse Microsoft operating systems; however, no damage + will be done by them. IBM's &os2; however, will + appropriate any partition it finds which it does not + understand. + + &prompt.root; dd if=/dev/zero of=/dev/da1 bs=1k count=1 +&prompt.root; bsdlabel -Brw da1 auto +&prompt.root; bsdlabel -e da1 # create the `e' partition +&prompt.root; newfs -d0 /dev/da1e +&prompt.root; mkdir -p /1 +&prompt.root; vi /etc/fstab # add an entry for /dev/da1e +&prompt.root; mount /1 + + An alternate method is: + + &prompt.root; dd if=/dev/zero of=/dev/da1 count=2 +&prompt.root; bsdlabel /dev/da1 | bsdlabel -BrR da1 /dev/stdin +&prompt.root; newfs /dev/da1e +&prompt.root; mkdir -p /1 +&prompt.root; vi /etc/fstab # add an entry for /dev/da1e +&prompt.root; mount /1 + + + + + + + RAID + + + Software RAID + + + + + + Christopher + Shumway + Original work by + + + + + Jim + Brown + Revised by + + + + +RAIDsoftware + + RAIDCCD + + + Concatenated Disk Driver (CCD) Configuration + When choosing a mass storage solution the most important + factors to consider are speed, reliability, and cost. It is + rare to have all three in balance; normally a fast, reliable mass + storage device is expensive, and to cut back on cost either speed + or reliability must be sacrificed. + + In designing the system described below, cost was chosen + as the most important factor, followed by speed, then reliability. + Data transfer speed for this system is ultimately + constrained by the network. And while reliability is very important, + the CCD drive described below serves online data that is already + fully backed up on CD-R's and can easily be replaced. + + Defining your own requirements is the first step + in choosing a mass storage solution. If your requirements prefer + speed or reliability over cost, your solution will differ from + the system described in this section. + + + + Installing the Hardware + + In addition to the IDE system disk, three Western + Digital 30GB, 5400 RPM IDE disks form the core + of the CCD disk described below providing approximately + 90GB of online storage. Ideally, + each IDE disk would have its own IDE controller + and cable, but to minimize cost, additional + IDE controllers were not used. Instead the disks were + configured with jumpers so that each IDE controller has + one master, and one slave. + + Upon reboot, the system BIOS was configured to + automatically detect the disks attached. More importantly, + FreeBSD detected them on reboot: + + ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33 +ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33 +ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33 +ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33 + + If FreeBSD does not detect all the disks, ensure + that you have jumpered them correctly. Most IDE drives + also have a Cable Select jumper. This is + not the jumper for the master/slave + relationship. Consult the drive documentation for help in + identifying the correct jumper. + + Next, consider how to attach them as part of the file + system. You should research both &man.vinum.8; () and &man.ccd.4;. In this + particular configuration, &man.ccd.4; was chosen. + + + + Setting Up the CCD + + The &man.ccd.4; driver allows you to take + several identical disks and concatenate them into one + logical file system. In order to use + &man.ccd.4;, you need a kernel with + &man.ccd.4; support built in. + Add this line to your kernel configuration file, rebuild, and + reinstall the kernel: + + device ccd + + The &man.ccd.4; support can also be + loaded as a kernel loadable module. + + To set up &man.ccd.4;, you must first use + &man.bsdlabel.8; to label the disks: + + bsdlabel -r -w ad1 auto +bsdlabel -r -w ad2 auto +bsdlabel -r -w ad3 auto + + This creates a bsdlabel for ad1c, ad2c and ad3c that + spans the entire disk. + + The next step is to change the disk label type. You + can use &man.bsdlabel.8; to edit the + disks: + + bsdlabel -e ad1 +bsdlabel -e ad2 +bsdlabel -e ad3 + + This opens up the current disk label on each disk with + the editor specified by the EDITOR + environment variable, typically &man.vi.1;. + + An unmodified disk label will look something like + this: + + 8 partitions: +# size offset fstype [fsize bsize bps/cpg] + c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) + + Add a new e partition for &man.ccd.4; to use. This + can usually be copied from the c partition, + but the must + be 4.2BSD. The disk label should + now look something like this: + + 8 partitions: +# size offset fstype [fsize bsize bps/cpg] + c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) + e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597) + + + + + Building the File System + + Now that you have all the disks labeled, you must + build the &man.ccd.4;. To do that, + use &man.ccdconfig.8;, with options similar to the following: + + ccdconfig ccd0 32 0 /dev/ad1e /dev/ad2e /dev/ad3e + + The use and meaning of each option is shown below: + + + + The first argument is the device to configure, in this case, + /dev/ccd0c. The /dev/ + portion is optional. + + + + + The interleave for the file system. The interleave + defines the size of a stripe in disk blocks, each normally 512 bytes. + So, an interleave of 32 would be 16,384 bytes. + + + + Flags for &man.ccdconfig.8;. If you want to enable drive + mirroring, you can specify a flag here. This + configuration does not provide mirroring for + &man.ccd.4;, so it is set at 0 (zero). + + + + The final arguments to &man.ccdconfig.8; + are the devices to place into the array. Use the complete pathname + for each device. + + + + + After running &man.ccdconfig.8; the &man.ccd.4; + is configured. A file system can be installed. Refer to &man.newfs.8; + for options, or simply run: + + newfs /dev/ccd0c + + + + + + Making it All Automatic + + Generally, you will want to mount the + &man.ccd.4; upon each reboot. To do this, you must + configure it first. Write out your current configuration to + /etc/ccd.conf using the following command: + + ccdconfig -g > /etc/ccd.conf + + During reboot, the script /etc/rc + runs ccdconfig -C if /etc/ccd.conf + exists. This automatically configures the + &man.ccd.4; so it can be mounted. + + If you are booting into single user mode, before you can + &man.mount.8; the &man.ccd.4;, you + need to issue the following command to configure the + array: + + ccdconfig -C + + + To automatically mount the &man.ccd.4;, + place an entry for the &man.ccd.4; in + /etc/fstab so it will be mounted at + boot time: + + /dev/ccd0c /media ufs rw 2 2 + + + + + The Vinum Volume Manager + +RAIDsoftware + + RAID + Vinum + + + The Vinum Volume Manager is a block device driver which + implements virtual disk drives. It isolates disk hardware + from the block device interface and maps data in ways which + result in an increase in flexibility, performance and + reliability compared to the traditional slice view of disk + storage. &man.vinum.8; implements the RAID-0, RAID-1 and + RAID-5 models, both individually and in combination. + + See for more + information about &man.vinum.8;. + + + + + Hardware RAID + + + RAID + hardware + + + FreeBSD also supports a variety of hardware RAID + controllers. These devices control a RAID subsystem + without the need for FreeBSD specific software to manage the + array. + + Using an on-card BIOS, the card controls most of the disk operations + itself. The following is a brief setup description using a Promise IDE RAID + controller. When this card is installed and the system is started up, it + displays a prompt requesting information. Follow the instructions + to enter the card's setup screen. From here, you have the ability to + combine all the attached drives. After doing so, the disk(s) will look like + a single drive to FreeBSD. Other RAID levels can be set up + accordingly. + + + + + Rebuilding ATA RAID1 Arrays + + FreeBSD allows you to hot-replace a failed disk in an array. This requires + that you catch it before you reboot. + + You will probably see something like the following in /var/log/messages or in the &man.dmesg.8; + output: + + ad6 on monster1 suffered a hard error. +ad6: READ command timeout tag=0 serv=0 - resetting +ad6: trying fallback to PIO mode +ata3: resetting devices .. done +ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11)\\ +status=59 error=40 +ar0: WARNING - mirror lost + + Using &man.atacontrol.8;, check for further information: + + &prompt.root; atacontrol list +ATA channel 0: + Master: no device present + Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0 + +ATA channel 1: + Master: no device present + Slave: no device present + +ATA channel 2: + Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 + Slave: no device present + +ATA channel 3: + Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 + Slave: no device present + +&prompt.root; atacontrol status ar0 +ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED + + + + You will first need to detach the ata channel with the failed + disk so you can safely remove it: + + &prompt.root; atacontrol detach ata3 + + + + Replace the disk. + + + + Reattach the ata channel: + + &prompt.root; atacontrol attach ata3 +Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 +Slave: no device present + + + + Add the new disk to the array as a spare: + + &prompt.root; atacontrol addspare ar0 ad6 + + + + Rebuild the array: + + &prompt.root; atacontrol rebuild ar0 + + + + It is possible to check on the progress by issuing the + following command: + + &prompt.root; dmesg | tail -10 +[output removed] +ad6: removed from configuration +ad6: deleted from ar0 disk1 +ad6: inserted into ar0 disk1 as spare + +&prompt.root; atacontrol status ar0 +ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed + + + + Wait until this operation completes. + + + + + + + + + + Marc + Fonvieille + Contributed by + + + + + + USB Storage Devices + + USB + disks + + + A lot of external storage solutions, nowadays, use the + Universal Serial Bus (USB): hard drives, USB thumbdrives, CD-R + burners, etc. &os; provides support for these devices. + + + Configuration + + The USB mass storage devices driver, &man.umass.4;, + provides the support for USB storage devices. If you use the + GENERIC kernel, you do not have to change + anything in your configuration. If you use a custom kernel, + be sure that the following lines are present in your kernel + configuration file: + + device scbus +device da +device pass +device uhci +device ohci +device usb +device umass + + The &man.umass.4; driver uses the SCSI subsystem to access + to the USB storage devices, your USB device will be seen as a + SCSI device by the system. Depending on the USB chipset on + your motherboard, you only need either device + uhci or device ohci, however + having both in the kernel configuration file is harmless. Do + not forget to compile and install the new kernel if you added + any lines. + + + If your USB device is a CD-R or DVD burner, the SCSI CD-ROM + driver, &man.cd.4;, must be added to the kernel via the + line: + + device cd + + Since the burner is seen as a SCSI drive, the driver + &man.atapicam.4; should not be used in the kernel + configuration. + + + Support for USB 2.0 controllers is provided on + &os;; however, you must add: + + device ehci + + to your configuration file for USB 2.0 support. Note + &man.uhci.4; and &man.ohci.4; drivers are still needed if you + want USB 1.X support. + + + + Testing the Configuration + + The configuration is ready to be tested: plug in your USB + device, and in the system message buffer (&man.dmesg.8;), the + drive should appear as something like: + + umass0: USB Solid state disk, rev 1.10/1.00, addr 2 +GEOM: create disk da0 dp=0xc2d74850 +da0 at umass-sim0 bus 0 target 0 lun 0 +da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device +da0: 1.000MB/s transfers +da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C) + + Of course, the brand, the device node + (da0) and other details can differ + according to your configuration. + + Since the USB device is seen as a SCSI one, the + camcontrol command can be used to list the + USB storage devices attached to the system: + + &prompt.root; camcontrol devlist +<Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0) + + If the drive comes with a file system, you should be able + to mount it. The will help you + to format and create partitions on the USB drive if + needed. + + If you unplug the device (the disk must be unmounted + before), you should see, in the system message buffer, + something like the following: + + umass0: at uhub0 port 1 (addr 2) disconnected +(da0:umass-sim0:0:0:0): lost device +(da0:umass-sim0:0:0:0): removing device entry +GEOM: destroy disk da0 dp=0xc2d74850 +umass0: detached + + + + Further Reading + + Beside the Adding + Disks and Mounting and + Unmounting File Systems sections, reading various + manual pages may be also useful: &man.umass.4;, + &man.camcontrol.8;, and &man.usbdevs.8;. + + + + + + + + Mike + Meyer + Contributed by + + + + + + + Creating and Using Optical Media (CDs) + + CDROMs + creating + + + + Introduction + + CDs have a number of features that differentiate them from + conventional disks. Initially, they were not writable by the + user. They are designed so that they can be read continuously without + delays to move the head between tracks. They are also much easier + to transport between systems than similarly sized media were at the + time. + + CDs do have tracks, but this refers to a section of data to + be read continuously and not a physical property of the disk. To + produce a CD on FreeBSD, you prepare the data files that are going + to make up the tracks on the CD, then write the tracks to the + CD. + + ISO 9660 + + file systems + ISO 9660 + + The ISO 9660 file system was designed to deal with these + differences. It unfortunately codifies file system limits that were + common then. Fortunately, it provides an extension mechanism that + allows properly written CDs to exceed those limits while still + working with systems that do not support those extensions. + + + sysutils/cdrtools + + The sysutils/cdrtools + port includes &man.mkisofs.8;, a program that you can use to + produce a data file containing an ISO 9660 file + system. It has options that support various extensions, and is + described below. + + + CD burner + ATAPI + + Which tool to use to burn the CD depends on whether your CD burner + is ATAPI or something else. ATAPI CD burners use the burncd program that is part of + the base system. SCSI and USB CD burners should use + cdrecord from + the sysutils/cdrtools port. + It is also possible to use cdrecord and other tools + for SCSI drives on ATAPI hardware with the ATAPI/CAM module. + + If you want CD burning software with a graphical user + interface, you may wish to take a look at either + X-CD-Roast or + K3b. These tools are available as + packages or from the sysutils/xcdroast and sysutils/k3b ports. + X-CD-Roast and + K3b require the ATAPI/CAM module with ATAPI + hardware. + + + + mkisofs + + The &man.mkisofs.8; program, which is part of the + sysutils/cdrtools port, + produces an ISO 9660 file system + that is an image of a directory tree in the &unix; file system name + space. The simplest usage is: + + &prompt.root; mkisofs -o imagefile.iso /path/to/tree + + + file systems + ISO 9660 + + This command will create an imagefile.iso + containing an ISO 9660 file system that is a copy of the tree at + /path/to/tree. In the process, it will + map the file names to names that fit the limitations of the + standard ISO 9660 file system, and will exclude files that have + names uncharacteristic of ISO file systems. + + + file systems + HFS + + + file systems + Joliet + + A number of options are available to overcome those + restrictions. In particular, enables the + Rock Ridge extensions common to &unix; systems, + enables Joliet extensions used by Microsoft systems, and + can be used to create HFS file systems used + by &macos;. + + For CDs that are going to be used only on FreeBSD systems, + can be used to disable all filename + restrictions. When used with , it produces a + file system image that is identical to the FreeBSD tree you started + from, though it may violate the ISO 9660 standard in a number of + ways. + + + CDROMs + creating bootable + + The last option of general use is . This is + used to specify the location of the boot image for use in producing an + El Torito bootable CD. This option takes an + argument which is the path to a boot image from the top of the + tree being written to the CD. By default, &man.mkisofs.8; creates an + ISO image in the so-called floppy disk emulation mode, + and thus expects the boot image to be exactly 1200, 1440 or + 2880 KB in size. Some boot loaders, like the one used by the + FreeBSD distribution disks, do not use emulation mode; in this case, + the option should be used. So, if + /tmp/myboot holds a bootable FreeBSD system + with the boot image in + /tmp/myboot/boot/cdboot, you could produce the + image of an ISO 9660 file system in + /tmp/bootable.iso like so: + + &prompt.root; mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot + + Having done that, if you have md + configured in your kernel, you can mount the file system with: + + &prompt.root; mdconfig -a -t vnode -f /tmp/bootable.iso -u 0 +&prompt.root; mount -t cd9660 /dev/md0 /mnt + + At which point you can verify that /mnt + and /tmp/myboot are identical. + + There are many other options you can use with + &man.mkisofs.8; to fine-tune its behavior. In particular: + modifications to an ISO 9660 layout and the creation of Joliet + and HFS discs. See the &man.mkisofs.8; manual page for details. + + + + burncd + + CDROMs + burning + + If you have an ATAPI CD burner, you can use the + burncd command to burn an ISO image onto a + CD. burncd is part of the base system, installed + as /usr/sbin/burncd. Usage is very simple, as + it has few options: + + &prompt.root; burncd -f cddevice data imagefile.iso fixate + + Will burn a copy of imagefile.iso on + cddevice. The default device is + /dev/acd0. See &man.burncd.8; for options to + set the write speed, eject the CD after burning, and write audio + data. + + + + cdrecord + + If you do not have an ATAPI CD burner, you will have to use + cdrecord to burn your + CDs. cdrecord is not part of the base system; + you must install it from either the port at sysutils/cdrtools + or the appropriate + package. Changes to the base system can cause binary versions of + this program to fail, possibly resulting in a + coaster. You should therefore either upgrade the + port when you upgrade your system, or if you are tracking -STABLE, upgrade the port when a + new version becomes available. + + While cdrecord has many options, basic usage + is even simpler than burncd. Burning an ISO 9660 + image is done with: + + &prompt.root; cdrecord dev=device imagefile.iso + + The tricky part of using cdrecord is finding + the to use. To find the proper setting, use + the flag of cdrecord, + which might produce results like this: + + CDROMs + burning + + &prompt.root; cdrecord -scanbus +Cdrecord-Clone 2.01 (i386-unknown-freebsd7.0) Copyright (C) 1995-2004 Jörg Schilling +Using libscg version 'schily-0.1' +scsibus0: + 0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk + 0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk + 0,2,0 2) * + 0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk + 0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM + 0,5,0 5) * + 0,6,0 6) * + 0,7,0 7) * +scsibus1: + 1,0,0 100) * + 1,1,0 101) * + 1,2,0 102) * + 1,3,0 103) * + 1,4,0 104) * + 1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM + 1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner + 1,7,0 107) * + + This lists the appropriate value for the + devices on the list. Locate your CD burner, and use the three + numbers separated by commas as the value for + . In this case, the CRW device is 1,5,0, so the + appropriate input would be + . There are easier + ways to specify this value; see &man.cdrecord.1; for + details. That is also the place to look for information on writing + audio tracks, controlling the speed, and other things. + + + + Duplicating Audio CDs + + You can duplicate an audio CD by extracting the audio data from + the CD to a series of files, and then writing these files to a blank + CD. The process is slightly different for ATAPI and SCSI + drives. + + + SCSI Drives + + + Use cdda2wav to extract the audio. + + &prompt.user; cdda2wav -v255 -D2,0 -B -Owav + + + + Use cdrecord to write the + .wav files. + + &prompt.user; cdrecord -v dev=2,0 -dao -useinfo *.wav + + Make sure that 2,0 is set + appropriately, as described in . + + + + + ATAPI Drives + + + The ATAPI CD driver makes each track available as + /dev/acddtnn, + where d is the drive number, and + nn is the track number written with two + decimal digits, prefixed with zero as needed. + So the first track on the first disk is + /dev/acd0t01, the second is + /dev/acd0t02, the third is + /dev/acd0t03, and so on. + + Make sure the appropriate files exist in + /dev. If the entries are missing, + force the system to retaste the media: + + &prompt.root; dd if=/dev/acd0 of=/dev/null count=1 + + + + Extract each track using &man.dd.1;. You must also use a + specific block size when extracting the files. + + &prompt.root; dd if=/dev/acd0t01 of=track1.cdr bs=2352 +&prompt.root; dd if=/dev/acd0t02 of=track2.cdr bs=2352 +... + + + + + Burn the extracted files to disk using + burncd. You must specify that these are audio + files, and that burncd should fixate the disk + when finished. + + &prompt.root; burncd -f /dev/acd0 audio track1.cdr track2.cdr ... fixate + + + + + + Duplicating Data CDs + + You can copy a data CD to a image file that is + functionally equivalent to the image file created with + &man.mkisofs.8;, and you can use it to duplicate + any data CD. The example given here assumes that your CDROM + device is acd0. Substitute your + correct CDROM device. + + &prompt.root; dd if=/dev/acd0 of=file.iso bs=2048 + + Now that you have an image, you can burn it to CD as + described above. + + + + Using Data CDs + + Now that you have created a standard data CDROM, you + probably want to mount it and read the data on it. By + default, &man.mount.8; assumes that a file system is of type + ufs. If you try something like: + + &prompt.root; mount /dev/cd0 /mnt + + you will get a complaint about Incorrect super + block, and no mount. The CDROM is not a + UFS file system, so attempts to mount it + as such will fail. You just need to tell &man.mount.8; that + the file system is of type ISO9660, and + everything will work. You do this by specifying the + option &man.mount.8;. For + example, if you want to mount the CDROM device, + /dev/cd0, under + /mnt, you would execute: + + &prompt.root; mount -t cd9660 /dev/cd0 /mnt + + Note that your device name + (/dev/cd0 in this example) could be + different, depending on the interface your CDROM uses. Also, + the option just executes + &man.mount.cd9660.8;. The above example could be shortened + to: + +&prompt.root; mount_cd9660 /dev/cd0 /mnt + + You can generally use data CDROMs from any vendor in this + way. Disks with certain ISO 9660 extensions might behave + oddly, however. For example, Joliet disks store all filenames + in two-byte Unicode characters. The FreeBSD kernel does not + speak Unicode (yet!), so non-English characters show up as + question marks. (The FreeBSD + CD9660 driver includes hooks to load an appropriate Unicode + conversion table on the fly. Modules for some of the common + encodings are available via the + sysutils/cd9660_unicode port.) + + Occasionally, you might get Device not + configured when trying to mount a CDROM. This + usually means that the CDROM drive thinks that there is no + disk in the tray, or that the drive is not visible on the bus. + It can take a couple of seconds for a CDROM drive to realize + that it has been fed, so be patient. + + Sometimes, a SCSI CDROM may be missed because it did not + have enough time to answer the bus reset. If you have a SCSI + CDROM please add the following option to your kernel + configuration and rebuild your kernel. + + options SCSI_DELAY=15000 + + This tells your SCSI bus to pause 15 seconds during boot, + to give your CDROM drive every possible chance to answer the + bus reset. + + + + Burning Raw Data CDs + + You can choose to burn a file directly to CD, without + creating an ISO 9660 file system. Some people do this for + backup purposes. This runs more quickly than burning a + standard CD: + + &prompt.root; burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate + + In order to retrieve the data burned to such a CD, you + must read data from the raw device node: + + &prompt.root; tar xzvf /dev/acd1 + + You cannot mount this disk as you would a normal CDROM. + Such a CDROM cannot be read under any operating system + except FreeBSD. If you want to be able to mount the CD, or + share data with another operating system, you must use + &man.mkisofs.8; as described above. + + + + + + + Marc + Fonvieille + Contributed by + + + + + + CD burner + ATAPI/CAM driver + + Using the ATAPI/CAM Driver + + This driver allows ATAPI devices (CD-ROM, CD-RW, DVD + drives etc...) to be accessed through the SCSI subsystem, and + so allows the use of applications like sysutils/cdrdao or + &man.cdrecord.1;. + + To use this driver, you will need to add the following + line to the /boot/loader.conf + file: + + atapicam_load="YES" + + then, reboot your machine. + + + If you prefer to statically compile the &man.atapicam.4; + support in your kernel, you will have to add this line to + your kernel configuration file: + + device atapicam + + You also need the following lines in your kernel + configuration file: + + device ata +device scbus +device cd +device pass + + which should already be present. Then rebuild, install + your new kernel, and reboot your machine. + + + During the boot process, your burner should show up, + like so: + + acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4 +cd0 at ata1 bus 0 target 0 lun 0 +cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device +cd0: 16.000MB/s transfers +cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed + + The drive could now be accessed via the + /dev/cd0 device name, for example to + mount a CD-ROM on /mnt, just type the + following: + + &prompt.root; mount -t cd9660 /dev/cd0 /mnt + + As root, you can run the following + command to get the SCSI address of the burner: + + &prompt.root; camcontrol devlist +<MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0) + + So 1,0,0 will be the SCSI address to + use with &man.cdrecord.1; and other SCSI application. + + For more information about ATAPI/CAM and SCSI system, + refer to the &man.atapicam.4; and &man.cam.4; manual + pages. + + + + + + + + Marc + Fonvieille + Contributed by + + + + + Andy + Polyakov + With inputs from + + + + + + Creating and Using Optical Media (DVDs) + + DVD + burning + + + + Introduction + + Compared to the CD, the DVD is the next generation of + optical media storage technology. The DVD can hold more data + than any CD and is nowadays the standard for video + publishing. + + Five physical recordable formats can be defined for what + we will call a recordable DVD: + + + + DVD-R: This was the first DVD recordable format + available. The DVD-R standard is defined by the DVD Forum. + This format is write once. + + + + DVD-RW: This is the rewritable version of + the DVD-R standard. A DVD-RW can be rewritten about 1000 + times. + + + + DVD-RAM: This is also a rewritable format + supported by the DVD Forum. A DVD-RAM can be seen as a + removable hard drive. However, this media is not + compatible with most DVD-ROM drives and DVD-Video players; + only a few DVD writers support the DVD-RAM format. Read + the for more information + on DVD-RAM use. + + + + DVD+RW: This is a rewritable format defined by + the DVD+RW + Alliance. A DVD+RW can be rewritten about 1000 + times. + + + + DVD+R: This format is the write once variation + of the DVD+RW format. + + + + A single layer recordable DVD can hold up to + 4,700,000,000 bytes which is actually 4.38 GB or + 4485 MB (1 kilobyte is 1024 bytes). + + + A distinction must be made between the physical media and + the application. For example, a DVD-Video is a specific + file layout that can be written on any recordable DVD + physical media: DVD-R, DVD+R, DVD-RW etc. Before choosing + the type of media, you must be sure that both the burner and the + DVD-Video player (a standalone player or a DVD-ROM drive on + a computer) are compatible with the media under consideration. + + + + Configuration + + The program &man.growisofs.1; will be used to perform DVD + recording. This command is part of the + dvd+rw-tools utilities (sysutils/dvd+rw-tools). The + dvd+rw-tools support all DVD media + types. + + These tools use the SCSI subsystem to access to the + devices, therefore the ATAPI/CAM + support must be added to your kernel. If your burner + uses the USB interface this addition is useless, and you should + read the for more details on USB + devices configuration. + + You also have to enable DMA access for ATAPI devices, this + can be done in adding the following line to the + /boot/loader.conf file: + + hw.ata.atapi_dma="1" + + Before attempting to use the + dvd+rw-tools you should consult the + dvd+rw-tools' + hardware compatibility notes for any information + related to your DVD burner. + + + If you want a graphical user interface, you should have + a look to K3b (sysutils/k3b) which provides a + user friendly interface to &man.growisofs.1; and many others + burning tools. + + + + + Burning Data DVDs + + The &man.growisofs.1; command is a frontend to mkisofs, it will invoke + &man.mkisofs.8; to create the file system layout and will + perform the write on the DVD. This means you do not need to + create an image of the data before the burning process. + + To burn onto a DVD+R or a DVD-R the data from the /path/to/data directory, use the + following command: + + &prompt.root; growisofs -dvd-compat -Z /dev/cd0 -J -R /path/to/data + + The options are passed to + &man.mkisofs.8; for the file system creation (in this case: an + ISO 9660 file system with Joliet and Rock Ridge extensions), + consult the &man.mkisofs.8; manual page for more + details. + + The option is used for the initial + session recording in any case: multiple sessions or not. The + DVD device, /dev/cd0, must be + changed according to your configuration. The + parameter will close the disk, + the recording will be unappendable. In return this should provide better + media compatibility with DVD-ROM drives. + + It is also possible to burn a pre-mastered image, for + example to burn the image + imagefile.iso, we will run: + + &prompt.root; growisofs -dvd-compat -Z /dev/cd0=imagefile.iso + + The write speed should be detected and automatically set + according to the media and the drive being used. If you want + to force the write speed, use the + parameter. For more information, read the &man.growisofs.1; + manual page. + + + + DVD + DVD-Video + + + + Burning a DVD-Video + + A DVD-Video is a specific file layout based on ISO 9660 + and the micro-UDF (M-UDF) specifications. The DVD-Video also + presents a specific data structure hierarchy, it is the reason + why you need a particular program such as multimedia/dvdauthor to author the + DVD. + + If you already have an image of the DVD-Video file system, + just burn it in the same way as for any image, see the + previous section for an example. If you have made the DVD + authoring and the result is in, for example, the directory + /path/to/video, the + following command should be used to burn the DVD-Video: + + &prompt.root; growisofs -Z /dev/cd0 -dvd-video /path/to/video + + The option will be passed down to + &man.mkisofs.8; and will instruct it to create a DVD-Video file system + layout. Beside this, the option + implies &man.growisofs.1; + option. + + + + DVD + DVD+RW + + + + Using a DVD+RW + + Unlike CD-RW, a virgin DVD+RW needs to be formatted before + first use. The &man.growisofs.1; program will take care of it + automatically whenever appropriate, which is the + recommended way. However you can use the + dvd+rw-format command to format the + DVD+RW: + + &prompt.root; dvd+rw-format /dev/cd0 + + You need to perform this operation just once, keep in mind + that only virgin DVD+RW medias need to be formatted. Then you + can burn the DVD+RW in the way seen in previous + sections. + + If you want to burn new data (burn a totally new file + system not append some data) onto a DVD+RW, you do not need to + blank it, you just have to write over the previous recording + (in performing a new initial session), like this: + + &prompt.root; growisofs -Z /dev/cd0 -J -R /path/to/newdata + + DVD+RW format offers the possibility to easily append data + to a previous recording. The operation consists in merging a + new session to the existing one, it is not multisession + writing, &man.growisofs.1; will grow the + ISO 9660 file system present on the media. + + For example, if we want to append data to our previous + DVD+RW, we have to use the following: + + &prompt.root; growisofs -M /dev/cd0 -J -R /path/to/nextdata + + The same &man.mkisofs.8; options we used to burn the + initial session should be used during next writes. + + + You may want to use the + option if you want better media compatibility with DVD-ROM + drives. In the DVD+RW case, this will not prevent you from + adding data. + + + If for any reason you really want to blank the media, do + the following: + + &prompt.root; growisofs -Z /dev/cd0=/dev/zero + + + + DVD + DVD-RW + + + + Using a DVD-RW + + A DVD-RW accepts two disc formats: the incremental + sequential one and the restricted overwrite. By default + DVD-RW discs are in sequential format. + + A virgin DVD-RW can be directly written without the need + of a formatting operation, however a non-virgin DVD-RW in + sequential format needs to be blanked before to be able to + write a new initial session. + + To blank a DVD-RW in sequential mode, run: + + &prompt.root; dvd+rw-format -blank=full /dev/cd0 + + + A full blanking () will take + about one hour on a 1x media. A fast blanking can be + performed using the option if the + DVD-RW will be recorded in Disk-At-Once (DAO) mode. To burn + the DVD-RW in DAO mode, use the command: + + &prompt.root; growisofs -use-the-force-luke=dao -Z /dev/cd0=imagefile.iso + + The option + should not be required since &man.growisofs.1; attempts to + detect minimally (fast blanked) media and engage DAO + write. + + In fact one should use restricted overwrite mode with + any DVD-RW, this format is more flexible than the default + incremental sequential one. + + + To write data on a sequential DVD-RW, use the same + instructions as for the other DVD formats: + + &prompt.root; growisofs -Z /dev/cd0 -J -R /path/to/data + + If you want to append some data to your previous + recording, you will have to use the &man.growisofs.1; + option. However, if you perform data + addition on a DVD-RW in incremental sequential mode, a new + session will be created on the disc and the result will be a + multi-session disc. + + A DVD-RW in restricted overwrite format does not need to + be blanked before a new initial session, you just have to + overwrite the disc with the option, this + is similar to the DVD+RW case. It is also possible to grow an + existing ISO 9660 file system written on the disc in a same + way as for a DVD+RW with the option. The + result will be a one-session DVD. + + To put a DVD-RW in the restricted overwrite format, the + following command must be used: + + &prompt.root; dvd+rw-format /dev/cd0 + + To change back to the sequential format use: + + &prompt.root; dvd+rw-format -blank=full /dev/cd0 + + + + Multisession + + Very few DVD-ROM drives support + multisession DVDs, they will most of time, hopefully, only read + the first session. DVD+R, DVD-R and DVD-RW in sequential + format can accept multiple sessions, the notion of multiple + sessions does not exist for the DVD+RW and the DVD-RW + restricted overwrite formats. + + Using the following command after an initial (non-closed) + session on a DVD+R, DVD-R, or DVD-RW in sequential format, + will add a new session to the disc: + + &prompt.root; growisofs -M /dev/cd0 -J -R /path/to/nextdata + + Using this command line with a DVD+RW or a DVD-RW in restricted + overwrite mode, will append data in merging the new session to + the existing one. The result will be a single-session disc. + This is the way used to add data after an initial write on these + medias. + + + Some space on the media is used between each session for + end and start of sessions. Therefore, one should add + sessions with large amount of data to optimize media space. + The number of sessions is limited to 154 for a DVD+R, + about 2000 for a DVD-R, and 127 for a DVD+R Double + Layer. + + + + + For More Information + + To obtain more information about a DVD, the + dvd+rw-mediainfo + /dev/cd0 command can be + ran with the disc in the drive. + + More information about the + dvd+rw-tools can be found in + the &man.growisofs.1; manual page, on the dvd+rw-tools + web site and in the cdwrite mailing + list archives. + + + The dvd+rw-mediainfo output of the + resulting recording or the media with issues is mandatory + for any problem report. Without this output, it will be + quite impossible to help you. + + + + + Using a DVD-RAM + + DVD + DVD-RAM + + + + Configuration + + DVD-RAM writers come with either SCSI or ATAPI + interface. DMA access for ATAPI devices has to be enabled, + this can be done by adding the following line to the + /boot/loader.conf file: + + hw.ata.atapi_dma="1" + + + + Preparing the Medium + + As previously mentioned in the chapter introduction, a + DVD-RAM can be seen as a removable hard drive. As any other + hard drive the DVD-RAM must be prepared + before the first use. In the example, the whole + disk space will be used with a standard UFS2 file system: + + &prompt.root; dd if=/dev/zero of=/dev/acd0 count=2 +&prompt.root; bsdlabel -Bw acd0 +&prompt.root; newfs /dev/acd0 + + The DVD device, acd0, must be + changed according to the configuration. + + + + Using the Medium + + Once the previous operations have been performed on the + DVD-RAM, it can be mounted as a normal hard drive: + + &prompt.root; mount /dev/acd0 /mnt + + After this the DVD-RAM will be both readable and writeable. + + + + + + + + + Julio + Merino + Original work by + + + + + + Martin + Karlsson + Rewritten by + + + + + + Creating and Using Floppy Disks + + Storing data on floppy disks is sometimes useful, for + example when one does not have any other removable storage media + or when one needs to transfer small amounts of data to another + computer. + + This section will explain how to use floppy disks in + FreeBSD. It will primarily cover formatting and usage of + 3.5inch DOS floppies, but the concepts are similar for other + floppy disk formats. + + + Formatting Floppies + + + The Device + + Floppy disks are accessed through entries in + /dev, just like other devices. To + access the raw floppy disk, simply use + /dev/fdN. + + + + Formatting + + A floppy disk needs to be low-level formated before it + can be used. This is usually done by the vendor, but + formatting is a good way to check media integrity. Although + it is possible to force larger (or smaller) disk sizes, + 1440kB is what most floppy disks are designed for. + + To low-level format the floppy disk you need to use + &man.fdformat.1;. This utility expects the device name as an + argument. + + Make note of any error messages, as these can help + determine if the disk is good or bad. + + + Formatting Floppy Disks + + Use the + /dev/fdN + devices to format the floppy. Insert a new 3.5inch floppy + disk in your drive and issue: + + &prompt.root; /usr/sbin/fdformat -f 1440 /dev/fd0 + + + + + + + The Disk Label + + After low-level formatting the disk, you will need to + place a disk label on it. This disk label will be destroyed + later, but it is needed by the system to determine the size of + the disk and its geometry later. + + The new disk label will take over the whole disk, and will + contain all the proper information about the geometry of the + floppy. The geometry values for the disk label are listed in + /etc/disktab. + + You can run now &man.bsdlabel.8; like so: + + &prompt.root; /sbin/bsdlabel -B -r -w /dev/fd0 fd1440 + + + + + The File System + + Now the floppy is ready to be high-level formated. This + will place a new file system on it, which will let FreeBSD read + and write to the disk. After creating the new file system, the + disk label is destroyed, so if you want to reformat the disk, you + will have to recreate the disk label. + + The floppy's file system can be either UFS or FAT. + FAT is generally a better choice for floppies. + + To put a new file system on the floppy, issue: + + &prompt.root; /sbin/newfs_msdos /dev/fd0 + + The disk is now ready for use. + + + + + Using the Floppy + + To use the floppy, mount it with &man.mount.msdosfs.8;. One can also use + emulators/mtools from the ports + collection. + + + + + Creating and Using Data Tapes + + tape media + The major tape media are the 4mm, 8mm, QIC, mini-cartridge and + DLT. + + + 4mm (DDS: Digital Data Storage) + + + tape media + DDS (4mm) tapes + + + tape media + QIC tapes + + 4mm tapes are replacing QIC as the workstation backup media of + choice. This trend accelerated greatly when Conner purchased Archive, + a leading manufacturer of QIC drives, and then stopped production of + QIC drives. 4mm drives are small and quiet but do not have the + reputation for reliability that is enjoyed by 8mm drives. The + cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51 + x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short + head life for the same reason, both use helical scan. + + Data throughput on these drives starts ~150 kB/s, peaking at ~500 kB/s. + Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware + compression, available with most of these drives, approximately + doubles the capacity. Multi-drive tape library units can have 6 + drives in a single cabinet with automatic tape changing. Library + capacities reach 240 GB. + + The DDS-3 standard now supports tape capacities up to 12 GB (or + 24 GB compressed). + + 4mm drives, like 8mm drives, use helical-scan. All the benefits + and drawbacks of helical-scan apply to both 4mm and 8mm drives. + + Tapes should be retired from use after 2,000 passes or 100 full + backups. + + + + 8mm (Exabyte) + + tape media + Exabyte (8mm) tapes + + + 8mm tapes are the most common SCSI tape drives; they are the best + choice of exchanging tapes. Nearly every site has an Exabyte 2 GB 8mm + tape drive. 8mm drives are reliable, convenient and quiet. Cartridges + are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). + One downside of 8mm tape is relatively short head and tape life due to + the high rate of relative motion of the tape across the heads. + + Data throughput ranges from ~250 kB/s to ~500 kB/s. Data sizes start + at 300 MB and go up to 7 GB. Hardware compression, available with + most of these drives, approximately doubles the capacity. These + drives are available as single units or multi-drive tape libraries + with 6 drives and 120 tapes in a single cabinet. Tapes are changed + automatically by the unit. Library capacities reach 840+ GB. + + The Exabyte Mammoth model supports 12 GB on one tape + (24 GB with compression) and costs approximately twice as much as + conventional tape drives. + + Data is recorded onto the tape using helical-scan, the heads are + positioned at an angle to the media (approximately 6 degrees). The + tape wraps around 270 degrees of the spool that holds the heads. The + spool spins while the tape slides over the spool. The result is a + high density of data and closely packed tracks that angle across the + tape from one edge to the other. + + + + QIC + + tape media + QIC-150 + + + QIC-150 tapes and drives are, perhaps, the most common tape drive + and media around. QIC tape drives are the least expensive serious + backup drives. The downside is the cost of media. QIC tapes are + expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB + data storage. But, if your needs can be satisfied with a half-dozen + tapes, QIC may be the correct choice. QIC is the + most common tape drive. Every site has a QIC + drive of some density or another. Therein lies the rub, QIC has a + large number of densities on physically similar (sometimes identical) + tapes. QIC drives are not quiet. These drives audibly seek before + they begin to record data and are clearly audible whenever reading, + writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 152 x + 102 x 17 mm). + + Data throughput ranges from ~150 kB/s to ~500 kB/s. Data capacity + ranges from 40 MB to 15 GB. Hardware compression is available on many + of the newer QIC drives. QIC drives are less frequently installed; + they are being supplanted by DAT drives. + + Data is recorded onto the tape in tracks. The tracks run along + the long axis of the tape media from one end to the other. The number + of tracks, and therefore the width of a track, varies with the tape's + capacity. Most if not all newer drives provide backward-compatibility + at least for reading (but often also for writing). QIC has a good + reputation regarding the safety of the data (the mechanics are simpler + and more robust than for helical scan drives). + + Tapes should be retired from use after 5,000 backups. + + + + DLT + + tape media + DLT + + + DLT has the fastest data transfer rate of all the drive types + listed here. The 1/2" (12.5mm) tape is contained in a single spool + cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a + swinging gate along one entire side of the cartridge. The drive + mechanism opens this gate to extract the tape leader. The tape leader + has an oval hole in it which the drive uses to hook the tape. The + take-up spool is located inside the tape drive. All the other tape + cartridges listed here (9 track tapes are the only exception) have + both the supply and take-up spools located inside the tape cartridge + itself. + + Data throughput is approximately 1.5 MB/s, three times the throughput of + 4mm, 8mm, or QIC tape drives. Data capacities range from 10 GB to 20 GB + for a single drive. Drives are available in both multi-tape changers + and multi-tape, multi-drive tape libraries containing from 5 to 900 + tapes over 1 to 20 drives, providing from 50 GB to 9 TB of + storage. + + With compression, DLT Type IV format supports up to 70 GB + capacity. + + Data is recorded onto the tape in tracks parallel to the direction + of travel (just like QIC tapes). Two tracks are written at once. + Read/write head lifetimes are relatively long; once the tape stops + moving, there is no relative motion between the heads and the + tape. + + + + AIT + + tape media + AIT + + + AIT is a new format from Sony, and can hold up to 50 GB (with + compression) per tape. The tapes contain memory chips which retain an + index of the tape's contents. This index can be rapidly read by the + tape drive to determine the position of files on the tape, instead of + the several minutes that would be required for other tapes. Software + such as SAMS:Alexandria can operate forty or more AIT tape libraries, + communicating directly with the tape's memory chip to display the + contents on screen, determine what files were backed up to which + tape, locate the correct tape, load it, and restore the data from the + tape. + + Libraries like this cost in the region of $20,000, pricing them a + little out of the hobbyist market. + + + + Using a New Tape for the First Time + + The first time that you try to read or write a new, completely + blank tape, the operation will fail. The console messages should be + similar to: + + sa0(ncr1:4:0): NOT READY asc:4,1 +sa0(ncr1:4:0): Logical unit is in process of becoming ready + + The tape does not contain an Identifier Block (block number 0). + All QIC tape drives since the adoption of QIC-525 standard write an + Identifier Block to the tape. There are two solutions: + + + + mt fsf 1 causes the tape drive to write an + Identifier Block to the tape. + + + + Use the front panel button to eject the tape. + + Re-insert the tape and dump data to + the tape. + + dump will report DUMP: End of tape + detected and the console will show: HARDWARE + FAILURE info:280 asc:80,96. + + rewind the tape using: mt rewind. + + Subsequent tape operations are successful. + + + + + + + + Backups to Floppies + + + Can I Use Floppies for Backing Up My Data? + backup floppies + floppy disks + + Floppy disks are not really a suitable media for + making backups as: + + + + The media is unreliable, especially over long periods of + time. + + + + Backing up and restoring is very slow. + + + + They have a very limited capacity (the days of backing up + an entire hard disk onto a dozen or so floppies has long since + passed). + + + + However, if you have no other method of backing up your data then + floppy disks are better than no backup at all. + + If you do have to use floppy disks then ensure that you use good + quality ones. Floppies that have been lying around the office for a + couple of years are a bad choice. Ideally use new ones from a + reputable manufacturer. + + + + So How Do I Backup My Data to Floppies? + + The best way to backup to floppy disk is to use + &man.tar.1; with the (multi + volume) option, which allows backups to span multiple + floppies. + + To backup all the files in the current directory and sub-directory + use this (as root): + + &prompt.root; tar Mcvf /dev/fd0 * + + When the first floppy is full &man.tar.1; will prompt you to + insert the next volume (because &man.tar.1; is media independent it + refers to volumes; in this context it means floppy disk). + + Prepare volume #2 for /dev/fd0 and hit return: + + This is repeated (with the volume number incrementing) until all + the specified files have been archived. + + + + Can I Compress My Backups? + + tar + + + gzip + + compression + + Unfortunately, &man.tar.1; will not allow the + option to be used for multi-volume archives. + You could, of course, &man.gzip.1; all the files, + &man.tar.1; them to the floppies, then + &man.gunzip.1; the files again! + + + + How Do I Restore My Backups? + + To restore the entire archive use: + + &prompt.root; tar Mxvf /dev/fd0 + + There are two ways that you can use to restore only + specific files. First, you can start with the first floppy + and use: + + &prompt.root; tar Mxvf /dev/fd0 filename + + The utility &man.tar.1; will prompt you to insert subsequent floppies until it + finds the required file. + + Alternatively, if you know which floppy the file is on then you + can simply insert that floppy and use the same command as above. Note + that if the first file on the floppy is a continuation from the + previous one then &man.tar.1; will warn you that it cannot + restore it, even if you have not asked it to! + + + + + + + + Lowell + Gilbert + Original work by + + + + + + Backup Strategies + + The first requirement in devising a backup plan is to make sure that + all of the following problems are covered: + + + + Disk failure + + + Accidental file deletion + + + Random file corruption + + + Complete machine destruction (e.g. fire), including destruction + of any on-site backups. + + + + It is perfectly possible that some systems will be best served by + having each of these problems covered by a completely different + technique. Except for strictly personal systems with very low-value + data, it is unlikely that one technique would cover all of them. + + Some of the techniques in the toolbox are: + + + + Archives of the whole system, backed up onto permanent media + offsite. This actually provides protection against all of the + possible problems listed above, but is slow and inconvenient to + restore from. You can keep copies of the backups onsite and/or + online, but there will still be inconveniences in restoring files, + especially for non-privileged users. + + + + Filesystem snapshots. This is really only helpful in the + accidental file deletion scenario, but it can be + very helpful in that case, and is quick and + easy to deal with. + + + + Copies of whole filesystems and/or disks (e.g. periodic rsync of + the whole machine). This is generally most useful in networks with + unique requirements. For general protection against disk failure, + it is usually inferior to RAID. For restoring + accidentally deleted files, it can be comparable to + UFS snapshots, but that depends on your + preferences. + + + + RAID. Minimizes or avoids downtime when a + disk fails. At the expense of having to deal with disk failures + more often (because you have more disks), albeit at a much lower + urgency. + + + + Checking fingerprints of files. The &man.mtree.8; utility is + very useful for this. Although it is not a backup technique, it + helps guarantee that you will notice when you need to resort to your + backups. This is particularly important for offline backups, and + should be checked periodically. + + + + It is quite easy to come up with even more techniques, many of them + variations on the ones listed above. Specialized requirements will + usually lead to specialized techniques (for example, backing up a live + database usually requires a method particular to the database software + as an intermediate step). The important thing is to know what dangers + you want to protect against, and how you will handle each. + + + + Backup Basics + + The three major backup programs are + &man.dump.8;, + &man.tar.1;, + and + &man.cpio.1;. + + + Dump and Restore + + backup software + dump / restore + + dump + restore + + The traditional &unix; backup programs are + dump and restore. They + operate on the drive as a collection of disk blocks, below the + abstractions of files, links and directories that are created by + the file systems. dump backs up an entire + file system on a device. It is unable to backup only part of a + file system or a directory tree that spans more than one + file system. dump does not write files and + directories to tape, but rather writes the raw data blocks that + comprise files and directories. + + If you use dump on your root directory, you + would not back up /home, + /usr or many other directories since + these are typically mount points for other file systems or + symbolic links into those file systems. + + dump has quirks that remain from its early days in + Version 6 of AT&T UNIX (circa 1975). The default + parameters are suitable for 9-track tapes (6250 bpi), not the + high-density media available today (up to 62,182 ftpi). These + defaults must be overridden on the command line to utilize the + capacity of current tape drives. + + .rhosts + It is also possible to backup data across the network to a + tape drive attached to another computer with rdump and + rrestore. Both programs rely upon &man.rcmd.3; and + &man.ruserok.3; to access the remote tape drive. Therefore, + the user performing the backup must be listed in the + .rhosts file on the remote computer. The + arguments to rdump and rrestore must be suitable + to use on the remote computer. When + rdumping from a FreeBSD computer to an + Exabyte tape drive connected to a Sun called + komodo, use: + + &prompt.root; /sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1 + + Beware: there are security implications to + allowing .rhosts authentication. Evaluate your + situation carefully. + + It is also possible to use dump and + restore in a more secure fashion over + ssh. + + + Using <command>dump</command> over <application>ssh</application> + + &prompt.root; /sbin/dump -0uan -f - /usr | gzip -2 | ssh -c blowfish \ + targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz + + + + Or using dump's built-in method, + setting the environment variable RSH: + + + Using <command>dump</command> over <application>ssh</application> with <envar>RSH</envar> set + + &prompt.root; RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0 /usr + + + + + + + <command>tar</command> + + backup software + tar + + + &man.tar.1; also dates back to Version 6 of AT&T UNIX + (circa 1975). tar operates in cooperation + with the file system; it writes files and + directories to tape. tar does not support the + full range of options that are available from &man.cpio.1;, but + it does not require the unusual command + pipeline that cpio uses. + + tar + + On FreeBSD 5.3 and later, both GNU tar + and the default bsdtar are available. The + GNU version can be invoked with gtar. It + supports remote devices using the same syntax as + rdump. To tar to an + Exabyte tape drive connected to a Sun called + komodo, use: + + &prompt.root; /usr/bin/gtar cf komodo:/dev/nsa8 . 2>&1 + + The same could be accomplished with + bsdtar by using a pipeline and + rsh to send the data to a remote tape + drive. + + &prompt.root; tar cf - . | rsh hostname dd of=tape-device obs=20b + + If you are worried about the security of backing up over a + network you should use the ssh command + instead of rsh. + + + + <command>cpio</command> + + backup software + cpio + + + &man.cpio.1; is the original &unix; file interchange tape + program for magnetic media. cpio has options + (among many others) to perform byte-swapping, write a number of + different archive formats, and pipe the data to other programs. + This last feature makes cpio an excellent + choice for installation media. cpio does not + know how to walk the directory tree and a list of files must be + provided through stdin. + cpio + + cpio does not support backups across + the network. You can use a pipeline and rsh + to send the data to a remote tape drive. + + &prompt.root; for f in directory_list; do +find $f >> backup.list +done +&prompt.root; cpio -v -o --format=newc < backup.list | ssh user@host "cat > backup_device" + + Where directory_list is the list of + directories you want to back up, + user@host is the + user/hostname combination that will be performing the backups, and + backup_device is where the backups should + be written to (e.g., /dev/nsa0). + + + + <command>pax</command> + + backup software + pax + + pax + POSIX + IEEE + + &man.pax.1; is IEEE/&posix;'s answer to + tar and cpio. Over the + years the various versions of tar and + cpio have gotten slightly incompatible. So + rather than fight it out to fully standardize them, &posix; + created a new archive utility. pax attempts + to read and write many of the various cpio + and tar formats, plus new formats of its own. + Its command set more resembles cpio than + tar. + + + + <application>Amanda</application> + + backup software + Amanda + + Amanda + + + Amanda (Advanced Maryland + Network Disk Archiver) is a client/server backup system, + rather than a single program. An Amanda server will backup to + a single tape drive any number of computers that have Amanda + clients and a network connection to the Amanda server. A + common problem at sites with a number of large disks is + that the length of time required to backup to data directly to tape + exceeds the amount of time available for the task. Amanda + solves this problem. Amanda can use a holding disk to + backup several file systems at the same time. Amanda creates + archive sets: a group of tapes used over a period of time to + create full backups of all the file systems listed in Amanda's + configuration file. The archive set also contains nightly + incremental (or differential) backups of all the file systems. + Restoring a damaged file system requires the most recent full + backup and the incremental backups. + + The configuration file provides fine control of backups and the + network traffic that Amanda generates. Amanda will use any of the + above backup programs to write the data to tape. Amanda is available + as either a port or a package, it is not installed by default. + + + + Do Nothing + + Do nothing is not a computer program, but it is the + most widely used backup strategy. There are no initial costs. There + is no backup schedule to follow. Just say no. If something happens + to your data, grin and bear it! + + If your time and your data is worth little to nothing, then + Do nothing is the most suitable backup program for your + computer. But beware, &unix; is a useful tool, you may find that within + six months you have a collection of files that are valuable to + you. + + Do nothing is the correct backup method for + /usr/obj and other directory trees that can be + exactly recreated by your computer. An example is the files that + comprise the HTML or &postscript; version of this Handbook. + These document formats have been created from SGML input + files. Creating backups of the HTML or &postscript; files is + not necessary. The SGML files are backed up regularly. + + + + Which Backup Program Is Best? + + LISA + + + &man.dump.8; Period. Elizabeth D. Zwicky + torture tested all the backup programs discussed here. The clear + choice for preserving all your data and all the peculiarities of &unix; + file systems is dump. Elizabeth created file systems containing + a large variety of unusual conditions (and some not so unusual ones) + and tested each program by doing a backup and restore of those + file systems. The peculiarities included: files with holes, files with + holes and a block of nulls, files with funny characters in their + names, unreadable and unwritable files, devices, files that change + size during the backup, files that are created/deleted during the + backup and more. She presented the results at LISA V in Oct. 1991. + See torture-testing + Backup and Archive Programs. + + + + Emergency Restore Procedure + + + Before the Disaster + + There are only four steps that you need to perform in + preparation for any disaster that may occur. + + bsdlabel + + + First, print the bsdlabel from each of your disks + (e.g. bsdlabel da0 | lpr), your file system table + (/etc/fstab) and all boot messages, + two copies of + each. + + fix-it floppies + Second, determine that the boot and fix-it floppies + (boot.flp and fixit.flp) + have all your devices. The easiest way to check is to reboot your + machine with the boot floppy in the floppy drive and check the boot + messages. If all your devices are listed and functional, skip on to + step three. + + Otherwise, you have to create two custom bootable + floppies which have a kernel that can mount all of your disks + and access your tape drive. These floppies must contain: + fdisk, bsdlabel, + newfs, mount, and + whichever backup program you use. These programs must be + statically linked. If you use dump, the + floppy must contain restore. + + Third, create backup tapes regularly. Any changes that you make + after your last backup may be irretrievably lost. Write-protect the + backup tapes. + + Fourth, test the floppies (either boot.flp + and fixit.flp or the two custom bootable + floppies you made in step two.) and backup tapes. Make notes of the + procedure. Store these notes with the bootable floppy, the + printouts and the backup tapes. You will be so distraught when + restoring that the notes may prevent you from destroying your backup + tapes (How? In place of tar xvf /dev/sa0, you + might accidentally type tar cvf /dev/sa0 and + over-write your backup tape). + + For an added measure of security, make bootable floppies and two + backup tapes each time. Store one of each at a remote location. A + remote location is NOT the basement of the same office building. A + number of firms in the World Trade Center learned this lesson the + hard way. A remote location should be physically separated from + your computers and disk drives by a significant distance. + + + A Script for Creating a Bootable Floppy + + /mnt/sbin/init +gzip -c -best /sbin/fsck > /mnt/sbin/fsck +gzip -c -best /sbin/mount > /mnt/sbin/mount +gzip -c -best /sbin/halt > /mnt/sbin/halt +gzip -c -best /sbin/restore > /mnt/sbin/restore + +gzip -c -best /bin/sh > /mnt/bin/sh +gzip -c -best /bin/sync > /mnt/bin/sync + +cp /root/.profile /mnt/root + +cp -f /dev/MAKEDEV /mnt/dev +chmod 755 /mnt/dev/MAKEDEV + +chmod 500 /mnt/sbin/init +chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt +chmod 555 /mnt/bin/sh /mnt/bin/sync +chmod 6555 /mnt/sbin/restore + +# +# create the devices nodes +# +cd /mnt/dev +./MAKEDEV std +./MAKEDEV da0 +./MAKEDEV da1 +./MAKEDEV da2 +./MAKEDEV sa0 +./MAKEDEV pty0 +cd / + +# +# create minimum file system table +# +cat > /mnt/etc/fstab < /mnt/etc/passwd < /mnt/etc/master.passwd < + + + + + + + After the Disaster + + The key question is: did your hardware survive? You have been + doing regular backups so there is no need to worry about the + software. + + If the hardware has been damaged, the parts should be replaced + before attempting to use the computer. + + If your hardware is okay, check your floppies. If you are using + a custom boot floppy, boot single-user (type -s + at the boot: prompt). Skip the following + paragraph. + + If you are using the boot.flp and + fixit.flp floppies, keep reading. Insert the + boot.flp floppy in the first floppy drive and + boot the computer. The original install menu will be displayed on + the screen. Select the Fixit--Repair mode with CDROM or + floppy. option. Insert the + fixit.flp when prompted. + restore and the other programs that you need are + located in /mnt2/rescue + (/mnt2/stand for + &os; versions older than 5.2). + + Recover each file system separately. + + + mount + + root partition + + bsdlabel + + + newfs + + Try to mount (e.g. mount /dev/da0a + /mnt) the root partition of your first disk. If the + bsdlabel was damaged, use bsdlabel to re-partition and + label the disk to match the label that you printed and saved. Use + newfs to re-create the file systems. Re-mount the root + partition of the floppy read-write (mount -u -o rw + /mnt). Use your backup program and backup tapes to + recover the data for this file system (e.g. restore vrf + /dev/sa0). Unmount the file system (e.g. umount + /mnt). Repeat for each file system that was + damaged. + + Once your system is running, backup your data onto new tapes. + Whatever caused the crash or data loss may strike again. Another + hour spent now may save you from further distress later. + + + + * I Did Not Prepare for the Disaster, What Now? + + + +]]> + + + + + + + + + Marc + Fonvieille + Reorganized and enhanced by + + + + Network, Memory, and File-Backed File Systems + virtual disks + + disks + virtual + + + Aside from the disks you physically insert into your computer: + floppies, CDs, hard drives, and so forth; other forms of disks + are understood by FreeBSD - the virtual + disks. + + NFS + Coda + + disks + memory + + These include network file systems such as the Network File System and Coda, memory-based + file systems and + file-backed file systems. + + According to the FreeBSD version you run, you will have to use + different tools for creation and use of file-backed and + memory-based file systems. + + + Use &man.devfs.5; to allocate device nodes transparently for the + user. + + + + File-Backed File System + + disks + file-backed + + + The utility &man.mdconfig.8; is used to configure and enable + memory disks, &man.md.4;, under FreeBSD. To use + &man.mdconfig.8;, you have to load &man.md.4; module or to add + the support in your kernel configuration file: + + device md + + The &man.mdconfig.8; command supports three kinds of + memory backed virtual disks: memory disks allocated with + &man.malloc.9;, memory disks using a file or swap space as + backing. One possible use is the mounting of floppy + or CD images kept in files. + + To mount an existing file system image: + + + Using <command>mdconfig</command> to Mount an Existing File System + Image + + &prompt.root; mdconfig -a -t vnode -f diskimage -u 0 +&prompt.root; mount /dev/md0 /mnt + + + To create a new file system image with &man.mdconfig.8;: + + + Creating a New File-Backed Disk with <command>mdconfig</command> + + &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k +5120+0 records in +5120+0 records out +&prompt.root; mdconfig -a -t vnode -f newimage -u 0 +&prompt.root; bsdlabel -w md0 auto +&prompt.root; newfs md0a +/dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048 + using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes. +super-block backups (for fsck -b #) at: + 160, 2720, 5280, 7840 +&prompt.root; mount /dev/md0a /mnt +&prompt.root; df /mnt +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md0a 4710 4 4330 0% /mnt + + + If you do not specify the unit number with the + option, &man.mdconfig.8; will use the + &man.md.4; automatic allocation to select an unused device. + The name of the allocated unit will be output on stdout like + md4. For more details about + &man.mdconfig.8;, please refer to the manual page. + + The utility &man.mdconfig.8; is very useful, however it + asks many command lines to create a file-backed file system. + FreeBSD also comes with a tool called &man.mdmfs.8;, + this program configures a &man.md.4; disk using + &man.mdconfig.8;, puts a UFS file system on it using + &man.newfs.8;, and mounts it using &man.mount.8;. For example, + if you want to create and mount the same file system image as + above, simply type the following: + + + Configure and Mount a File-Backed Disk with <command>mdmfs</command> + &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k +5120+0 records in +5120+0 records out +&prompt.root; mdmfs -F newimage -s 5m md0 /mnt +&prompt.root; df /mnt +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md0 4718 4 4338 0% /mnt + + + If you use the option without unit + number, &man.mdmfs.8; will use &man.md.4; auto-unit feature to + automatically select an unused device. For more details + about &man.mdmfs.8;, please refer to the manual page. + + + + + Memory-Based File System + + disks + memory file system + + + For a + memory-based file system the swap backing + should normally be used. Using swap backing does not mean + that the memory disk will be swapped out to disk by default, + but merely that the memory disk will be allocated from a + memory pool which can be swapped out to disk if needed. It is + also possible to create memory-based disk which are + &man.malloc.9; backed, but using malloc backed memory disks, + especially large ones, can result in a system panic if the + kernel runs out of memory. + + + Creating a New Memory-Based Disk with + <command>mdconfig</command> + + &prompt.root; mdconfig -a -t swap -s 5m -u 1 +&prompt.root; newfs -U md1 +/dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048 + using 4 cylinder groups of 1.27MB, 81 blks, 192 inodes. + with soft updates +super-block backups (for fsck -b #) at: + 160, 2752, 5344, 7936 +&prompt.root; mount /dev/md1 /mnt +&prompt.root; df /mnt +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md1 4718 4 4338 0% /mnt + + + + Creating a New Memory-Based Disk with + <command>mdmfs</command> + &prompt.root; mdmfs -s 5m md2 /mnt +&prompt.root; df /mnt +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md2 4846 2 4458 0% /mnt + + + + + Detaching a Memory Disk from the System + + disks + detaching a memory disk + + + When a memory-based or file-based file system + is not used, you should release all resources to the system. + The first thing to do is to unmount the file system, then use + &man.mdconfig.8; to detach the disk from the system and release + the resources. + + For example to detach and free all resources used by + /dev/md4: + + &prompt.root; mdconfig -d -u 4 + + It is possible to list information about configured + &man.md.4; devices in using the command mdconfig + -l. + + + + + + + + Tom + Rhodes + Contributed by + + + + + + File System Snapshots + + + file systems + snapshots + + + FreeBSD offers a feature in conjunction with + Soft Updates: File system snapshots. + + Snapshots allow a user to create images of specified file + systems, and treat them as a file. + Snapshot files must be created in the file system that the + action is performed on, and a user may create no more than 20 + snapshots per file system. Active snapshots are recorded + in the superblock so they are persistent across unmount and + remount operations along with system reboots. When a snapshot + is no longer required, it can be removed with the standard &man.rm.1; + command. Snapshots may be removed in any order, + however all the used space may not be acquired because another snapshot will + possibly claim some of the released blocks. + + The un-alterable file flag is set + by &man.mksnap.ffs.8; after initial creation of a snapshot file. + The &man.unlink.1; command makes an exception for snapshot files + since it allows them to be removed. + + Snapshots are created with the &man.mount.8; command. To place + a snapshot of /var in the file + /var/snapshot/snap use the following + command: + +&prompt.root; mount -u -o snapshot /var/snapshot/snap /var + + Alternatively, you can use &man.mksnap.ffs.8; to create + a snapshot: +&prompt.root; mksnap_ffs /var /var/snapshot/snap + + One can find snapshot files on a file system (e.g. /var) + by using the &man.find.1; command: +&prompt.root; find /var -flags snapshot + + Once a snapshot has been created, it has several + uses: + + + + Some administrators will use a snapshot file for backup purposes, + because the snapshot can be transfered to CDs or tape. + + + + The file system integrity checker, &man.fsck.8;, may be run on the snapshot. + Assuming that the file system was clean when it was mounted, you + should always get a clean (and unchanging) result. + This is essentially what the + background &man.fsck.8; process does. + + + + Run the &man.dump.8; utility on the snapshot. + A dump will be returned that is consistent with the + file system and the timestamp of the snapshot. &man.dump.8; + can also take a snapshot, create a dump image and then + remove the snapshot in one command using the + flag. + + + + &man.mount.8; the snapshot as a frozen image of the file system. + To &man.mount.8; the snapshot + /var/snapshot/snap run: + +&prompt.root; mdconfig -a -t vnode -f /var/snapshot/snap -u 4 +&prompt.root; mount -r /dev/md4 /mnt + + + + + You can now walk the hierarchy of your frozen /var + file system mounted at /mnt. Everything will + initially be in the same state it was during the snapshot creation time. + The only exception is that any earlier snapshots will appear + as zero length files. When the use of a snapshot has delimited, + it can be unmounted with: + +&prompt.root; umount /mnt +&prompt.root; mdconfig -d -u 4 + + For more information about and + file system snapshots, including technical papers, you can visit + Marshall Kirk McKusick's website at + . + + + + File System Quotas + + accounting + disk space + + disk quotas + + Quotas are an optional feature of the operating system that + allow you to limit the amount of disk space and/or the number of + files a user or members of a group may allocate on a per-file + system basis. This is used most often on timesharing systems where + it is desirable to limit the amount of resources any one user or + group of users may allocate. This will prevent one user or group + of users from consuming all of the available disk space. + + + Configuring Your System to Enable Disk Quotas + + Before attempting to use disk quotas, it is necessary to make + sure that quotas are configured in your kernel. This is done by + adding the following line to your kernel configuration + file: + + options QUOTA + + The stock GENERIC kernel does not have + this enabled by default, so you will have to configure, build and + install a custom kernel in order to use disk quotas. Please refer + to for more information on kernel + configuration. + + Next you will need to enable disk quotas in + /etc/rc.conf. This is done by adding the + line: + + enable_quotas="YES" + + disk quotas + checking + + For finer control over your quota startup, there is an + additional configuration variable available. Normally on bootup, + the quota integrity of each file system is checked by the + &man.quotacheck.8; program. The + &man.quotacheck.8; facility insures that the data in + the quota database properly reflects the data on the file system. + This is a very time consuming process that will significantly + affect the time your system takes to boot. If you would like to + skip this step, a variable in /etc/rc.conf + is made available for the purpose: + + check_quotas="NO" + + Finally you will need to edit /etc/fstab + to enable disk quotas on a per-file system basis. This is where + you can either enable user or group quotas or both for all of your + file systems. + + To enable per-user quotas on a file system, add the + option to the options field in the + /etc/fstab entry for the file system you want + to enable quotas on. For example: + + /dev/da1s2g /home ufs rw,userquota 1 2 + + Similarly, to enable group quotas, use the + option instead of + . To enable both user and + group quotas, change the entry as follows: + + /dev/da1s2g /home ufs rw,userquota,groupquota 1 2 + + By default, the quota files are stored in the root directory of + the file system with the names quota.user and + quota.group for user and group quotas + respectively. See &man.fstab.5; for more + information. Even though the &man.fstab.5; manual page says that + you can specify + an alternate location for the quota files, this is not recommended + because the various quota utilities do not seem to handle this + properly. + + At this point you should reboot your system with your new + kernel. /etc/rc will automatically run the + appropriate commands to create the initial quota files for all of + the quotas you enabled in /etc/fstab, so + there is no need to manually create any zero length quota + files. + + In the normal course of operations you should not be required + to run the &man.quotacheck.8;, + &man.quotaon.8;, or &man.quotaoff.8; + commands manually. However, you may want to read their manual pages + just to be familiar with their operation. + + + + Setting Quota Limits + + disk quotas + limits + + + Once you have configured your system to enable quotas, verify + that they really are enabled. An easy way to do this is to + run: + + &prompt.root; quota -v + + You should see a one line summary of disk usage and current + quota limits for each file system that quotas are enabled + on. + + You are now ready to start assigning quota limits with the + &man.edquota.8; command. + + You have several options on how to enforce limits on the + amount of disk space a user or group may allocate, and how many + files they may create. You may limit allocations based on disk + space (block quotas) or number of files (inode quotas) or a + combination of both. Each of these limits are further broken down + into two categories: hard and soft limits. + + hard limit + A hard limit may not be exceeded. Once a user reaches his + hard limit he may not make any further allocations on the file + system in question. For example, if the user has a hard limit of + 500 kbytes on a file system and is currently using 490 kbytes, the + user can only allocate an additional 10 kbytes. Attempting to + allocate an additional 11 kbytes will fail. + + soft limit + Soft limits, on the other hand, can be exceeded for a limited + amount of time. This period of time is known as the grace period, + which is one week by default. If a user stays over his or her + soft limit longer than the grace period, the soft limit will + turn into a hard limit and no further allocations will be allowed. + When the user drops back below the soft limit, the grace period + will be reset. + + The following is an example of what you might see when you run + the &man.edquota.8; command. When the + &man.edquota.8; command is invoked, you are placed into + the editor specified by the EDITOR environment + variable, or in the vi editor if the + EDITOR variable is not set, to allow you to edit + the quota limits. + + &prompt.root; edquota -u test + + Quotas for user test: +/usr: kbytes in use: 65, limits (soft = 50, hard = 75) + inodes in use: 7, limits (soft = 50, hard = 60) +/usr/var: kbytes in use: 0, limits (soft = 50, hard = 75) + inodes in use: 0, limits (soft = 50, hard = 60) + + You will normally see two lines for each file system that has + quotas enabled. One line for the block limits, and one line for + inode limits. Simply change the value you want updated to modify + the quota limit. For example, to raise this user's block limit + from a soft limit of 50 and a hard limit of 75 to a soft limit of + 500 and a hard limit of 600, change: + + /usr: kbytes in use: 65, limits (soft = 50, hard = 75) + + to: + + /usr: kbytes in use: 65, limits (soft = 500, hard = 600) + + The new quota limits will be in place when you exit the + editor. + + Sometimes it is desirable to set quota limits on a range of + UIDs. This can be done by use of the option + on the &man.edquota.8; command. First, assign the + desired quota limit to a user, and then run + edquota -p protouser startuid-enduid. For + example, if user test has the desired quota + limits, the following command can be used to duplicate those quota + limits for UIDs 10,000 through 19,999: + + &prompt.root; edquota -p test 10000-19999 + + For more information see &man.edquota.8; manual page. + + + + Checking Quota Limits and Disk Usage + + disk quotas + checking + + + You can use either the &man.quota.1; or the + &man.repquota.8; commands to check quota limits and + disk usage. The &man.quota.1; command can be used to + check individual user or group quotas and disk usage. A user + may only examine his own quota, and the quota of a group he + is a member of. Only the super-user may view all user and group + quotas. The + &man.repquota.8; command can be used to get a summary + of all quotas and disk usage for file systems with quotas + enabled. + + The following is some sample output from the + quota -v command for a user that has quota + limits on two file systems. + + Disk quotas for user test (uid 1002): + Filesystem usage quota limit grace files quota limit grace + /usr 65* 50 75 5days 7 50 60 + /usr/var 0 50 75 0 50 60 + + grace period + On the /usr file system in the above + example, this user is currently 15 kbytes over the soft limit of + 50 kbytes and has 5 days of the grace period left. Note the + asterisk * which indicates that the user is + currently over his quota limit. + + Normally file systems that the user is not using any disk + space on will not show up in the output from the + &man.quota.1; command, even if he has a quota limit + assigned for that file system. The option + will display those file systems, such as the + /usr/var file system in the above + example. + + + + Quotas over NFS + NFS + + Quotas are enforced by the quota subsystem on the NFS server. + The &man.rpc.rquotad.8; daemon makes quota information available + to the &man.quota.1; command on NFS clients, allowing users on + those machines to see their quota statistics. + + Enable rpc.rquotad in + /etc/inetd.conf like so: + + rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad + + Now restart inetd: + + &prompt.root; kill -HUP `cat /var/run/inetd.pid` + + + + + + + + + Lucky + Green + Contributed by + +
shamrock@cypherpunks.to
+ + + + + + + Encrypting Disk Partitions + + disks + encrypting + + FreeBSD offers excellent online protections against + unauthorized data access. File permissions and Mandatory + Access Control (MAC) (see ) help prevent + unauthorized third-parties from accessing data while the operating + system is active and the computer is powered up. However, + the permissions enforced by the operating system are irrelevant if an + attacker has physical access to a computer and can simply move + the computer's hard drive to another system to copy and analyze + the sensitive data. + + Regardless of how an attacker may have come into possession of + a hard drive or powered-down computer, both GEOM + Based Disk Encryption (gbde) and + geli cryptographic subsystems in &os; are able + to protect the data on the computer's file systems against even + highly-motivated attackers with significant resources. Unlike + cumbersome encryption methods that encrypt only individual files, + gbde and geli transparently + encrypt entire file systems. No cleartext ever touches the hard + drive's platter. + + + Disk Encryption with <application>gbde</application> + + + + Become <username>root</username> + + Configuring gbde requires + super-user privileges. + + &prompt.user; su - +Password: + + + + Add &man.gbde.4; Support to the Kernel Configuration File + + Add the following line to the kernel configuration + file: + + options GEOM_BDE + + Rebuild the kernel as described in . + + Reboot into the new kernel. + + + + + Preparing the Encrypted Hard Drive + + The following example assumes that you are adding a new hard + drive to your system that will hold a single encrypted partition. + This partition will be mounted as /private. + gbde can also be used to encrypt + /home and /var/mail, but + this requires more complex instructions which exceed the scope of + this introduction. + + + + Add the New Hard Drive + + Install the new drive to the system as explained in . For the purposes of this example, + a new hard drive partition has been added as + /dev/ad4s1c. The + /dev/ad0s1* + devices represent existing standard FreeBSD partitions on + the example system. + + &prompt.root; ls /dev/ad* +/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 +/dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c +/dev/ad0s1a /dev/ad0s1d /dev/ad4 + + + + Create a Directory to Hold gbde Lock Files + + &prompt.root; mkdir /etc/gbde + + The gbde lock file contains + information that gbde requires to + access encrypted partitions. Without access to the lock file, + gbde will not be able to decrypt + the data contained in the encrypted partition without + significant manual intervention which is not supported by the + software. Each encrypted partition uses a separate lock + file. + + + + Initialize the gbde Partition + + A gbde partition must be + initialized before it can be used. This initialization needs to + be performed only once: + + &prompt.root; gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c + + &man.gbde.8; will open your editor, permitting you to set + various configuration options in a template. For use with UFS1 + or UFS2, set the sector_size to 2048: + + $FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/20 11:16:13 phk Exp $ +# +# Sector size is the smallest unit of data which can be read or written. +# Making it too small decreases performance and decreases available space. +# Making it too large may prevent filesystems from working. 512 is the +# minimum and always safe. For UFS, use the fragment size +# +sector_size = 2048 +[...] + + + &man.gbde.8; will ask you twice to type the passphrase that + should be used to secure the data. The passphrase must be the + same both times. gbde's ability to + protect your data depends entirely on the quality of the + passphrase that you choose. + + For tips on how to select a secure passphrase that is easy + to remember, see the Diceware + Passphrase website. + + The gbde init command creates a lock + file for your gbde partition that in + this example is stored as + /etc/gbde/ad4s1c. + + + gbde lock files + must be backed up together with the + contents of any encrypted partitions. While deleting a lock + file alone cannot prevent a determined attacker from + decrypting a gbde partition, + without the lock file, the legitimate owner will be unable + to access the data on the encrypted partition without a + significant amount of work that is totally unsupported by + &man.gbde.8; and its designer. + + + + + Attach the Encrypted Partition to the Kernel + + &prompt.root; gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c + + You will be asked to provide the passphrase that you + selected during the initialization of the encrypted partition. + The new encrypted device will show up in + /dev as + /dev/device_name.bde: + + &prompt.root; ls /dev/ad* +/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 +/dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c +/dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde + + + + Create a File System on the Encrypted Device + + Once the encrypted device has been attached to the kernel, + you can create a file system on the device. To create a file + system on the encrypted device, use &man.newfs.8;. Since it is + much faster to initialize a new UFS2 file system than it is to + initialize the old UFS1 file system, using &man.newfs.8; with + the option is recommended. + + &prompt.root; newfs -U -O2 /dev/ad4s1c.bde + + + The &man.newfs.8; command must be performed on an + attached gbde partition which + is identified by a + *.bde + extension to the device name. + + + + + Mount the Encrypted Partition + + Create a mount point for the encrypted file system. + + &prompt.root; mkdir /private + + Mount the encrypted file system. + + &prompt.root; mount /dev/ad4s1c.bde /private + + + + Verify That the Encrypted File System is Available + + The encrypted file system should now be visible to + &man.df.1; and be available for use. + + &prompt.user; df -H +Filesystem Size Used Avail Capacity Mounted on +/dev/ad0s1a 1037M 72M 883M 8% / +/devfs 1.0K 1.0K 0B 100% /dev +/dev/ad0s1f 8.1G 55K 7.5G 0% /home +/dev/ad0s1e 1037M 1.1M 953M 0% /tmp +/dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr +/dev/ad4s1c.bde 150G 4.1K 138G 0% /private + + + + + + Mounting Existing Encrypted File Systems + + After each boot, any encrypted file systems must be + re-attached to the kernel, checked for errors, and mounted, before + the file systems can be used. The required commands must be + executed as user root. + + + + Attach the gbde Partition to the Kernel + + &prompt.root; gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c + + You will be asked to provide the passphrase that you + selected during initialization of the encrypted + gbde partition. + + + + Check the File System for Errors + + Since encrypted file systems cannot yet be listed in + /etc/fstab for automatic mounting, the + file systems must be checked for errors by running &man.fsck.8; + manually before mounting. + + &prompt.root; fsck -p -t ffs /dev/ad4s1c.bde + + + + Mount the Encrypted File System + + &prompt.root; mount /dev/ad4s1c.bde /private + + The encrypted file system is now available for use. + + + + + Automatically Mounting Encrypted Partitions + + It is possible to create a script to automatically attach, + check, and mount an encrypted partition, but for security reasons + the script should not contain the &man.gbde.8; password. Instead, + it is recommended that such scripts be run manually while + providing the password via the console or &man.ssh.1;. + + As of &os; 5.2-RELEASE, there is a new rc.d script + provided. Arguments for this script can be passed via + &man.rc.conf.5;, for example: + + gbde_autoattach_all="YES" +gbde_devices="ad4s1c" + + This will require that the gbde + passphrase be entered at boot time. After typing the correct + passphrase, the gbde encrypted + partition will be mounted automatically. This can be very + useful when using gbde on + notebooks. + + + + + Cryptographic Protections Employed by gbde + + &man.gbde.8; encrypts the sector payload using 128-bit AES in + CBC mode. Each sector on the disk is encrypted with a different + AES key. For more information on gbde's + cryptographic design, including how the sector keys are derived + from the user-supplied passphrase, see &man.gbde.4;. + + + + Compatibility Issues + + &man.sysinstall.8; is incompatible with + gbde-encrypted devices. All + *.bde devices must be detached from the + kernel before starting &man.sysinstall.8; or it will crash during + its initial probing for devices. To detach the encrypted device + used in our example, use the following command: + &prompt.root; gbde detach /dev/ad4s1c + + Also note that, as &man.vinum.4; does not use the + &man.geom.4; subsystem, you cannot use + gbde with + vinum volumes. + + + + + + + + + Daniel + Gerzo + Contributed by + + + + + + Disk Encryption with <command>geli</command> + + A new cryptographic GEOM class is available as of &os; 6.0 - + geli. It is currently being developed by + &a.pjd;. Geli is different to + gbde; it offers different features and uses + a different scheme for doing cryptographic work. + + The most important features of &man.geli.8; are: + + + + Utilizes the &man.crypto.9; framework — when + cryptographic hardware is available, geli + will use it automatically. + + + Supports multiple cryptographic algorithms (currently + AES, Blowfish, and 3DES). + + + Allows the root partition to be encrypted. The + passphrase used to access the encrypted root partition will + be requested during the system boot. + + + Allows the use of two independent keys (e.g. a + key and a company key). + + + geli is fast - performs simple + sector-to-sector encryption. + + + Allows backup and restore of Master Keys. When a user + has to destroy his keys, it will be possible to get access + to the data again by restoring keys from the backup. + + + Allows to attach a disk with a random, one-time key + — useful for swap partitions and temporary file + systems. + + + + More geli features can be found in the + &man.geli.8; manual page. + + The next steps will describe how to enable support for + geli in the &os; kernel and will explain how + to create a new geli encryption provider. At + the end it will be demonstrated how to create an encrypted swap + partition using features provided by geli. + + In order to use geli, you must be running + &os; 6.0-RELEASE or later. Super-user privileges will be + required since modifications to the kernel are necessary. + + + + Adding <command>geli</command> Support to the Kernel + Configuration File + + Add the following lines to the kernel configuration + file: + + options GEOM_ELI +device crypto + + Rebuild the kernel as described in . + + Alternatively, the geli module can + be loaded at boot time. Add the following line to the + /boot/loader.conf: + + geom_eli_load="YES" + + &man.geli.8; should now be supported by the kernel. + + + + Generating the Master Key + + The following example will describe how to generate a + key file, which will be used as part of the Master Key for + the encrypted provider mounted under + /private. The key + file will provide some random data used to encrypt the + Master Key. The Master Key will be protected by a + passphrase as well. Provider's sector size will be 4kB big. + Furthermore, the discussion will describe how to attach the + geli provider, create a file system on + it, how to mount it, how to work with it, and finally how to + detach it. + + It is recommended to use a bigger sector size (like 4kB) for + better performance. + + The Master Key will be protected with a passphrase and + the data source for key file will be + /dev/random. The sector size of + /dev/da2.eli, which we call provider, + will be 4kB. + + &prompt.root; dd if=/dev/random of=/root/da2.key bs=64 count=1 +&prompt.root; geli init -s 4096 -K /root/da2.key /dev/da2 +Enter new passphrase: +Reenter new passphrase: + + It is not mandatory that both a passphrase and a key + file are used; either method of securing the Master Key can + be used in isolation. + + If key file is given as -, standard + input will be used. This example shows how more than one + key file can be used. + + &prompt.root; cat keyfile1 keyfile2 keyfile3 | geli init -K - /dev/da2 + + + + Attaching the Provider with the generated Key + + &prompt.root; geli attach -k /root/da2.key /dev/da2 +Enter passphrase: + + The new plaintext device will be named + /dev/da2.eli. + + &prompt.root; ls /dev/da2* +/dev/da2 /dev/da2.eli + + + + Creating the new File System + + &prompt.root; dd if=/dev/random of=/dev/da2.eli bs=1m +&prompt.root; newfs /dev/da2.eli +&prompt.root; mount /dev/da2.eli /private + + The encrypted file system should be visible to &man.df.1; + and be available for use now. + + &prompt.root; df -H +Filesystem Size Used Avail Capacity Mounted on +/dev/ad0s1a 248M 89M 139M 38% / +/devfs 1.0K 1.0K 0B 100% /dev +/dev/ad0s1f 7.7G 2.3G 4.9G 32% /usr +/dev/ad0s1d 989M 1.5M 909M 0% /tmp +/dev/ad0s1e 3.9G 1.3G 2.3G 35% /var +/dev/da2.eli 150G 4.1K 138G 0% /private + + + + + Unmounting and Detaching the Provider + + Once the work on the encrypted partition is done, and + the /private partition + is no longer needed, it is prudent to consider unmounting + and detaching the geli encrypted + partition from the kernel. + + &prompt.root; umount /private +&prompt.root; geli detach da2.eli + + + + More information about the use of &man.geli.8; can be + found in the manual page. + + + Using the <filename>geli</filename> <filename>rc.d</filename> Script + + geli comes with a rc.d script which + can be used to simplify the usage of geli. + An example of configuring geli through + &man.rc.conf.5; follows: + + geli_devices="da2" +geli_da2_flags="-p -k /root/da2.key" + + This will configure /dev/da2 as a + geli provider of which the Master Key file + is located in /root/da2.key, and + geli will not use a passphrase when + attaching the provider (note that this can only be used if -P + was given during the geli init phase). The + system will detach the geli provider from + the kernel before the system shuts down. + + More information about configuring rc.d is provided in the + rc.d section of the + Handbook. + + + + + + + + + + Christian + Brüffer + Written by + + + + + Encrypting Swap Space + + swap + encrypting + + + Swap encryption in &os; is easy to configure and has been + available since &os; 5.3-RELEASE. Depending on which version + of &os; is being used, different options are available + and configuration can vary slightly. From &os; 6.0-RELEASE onwards, + the &man.gbde.8; or &man.geli.8; encryption systems can be used + for swap encryption. With earlier versions, only &man.gbde.8; is + available. Both systems use the encswap + rc.d script. + + The previous section, Encrypting + Disk Partitions, includes a short discussion on the different + encryption systems. + + + Why should Swap be Encrypted? + + Like the encryption of disk partitions, encryption of swap space + is done to protect sensitive information. Imagine an application + that e.g. deals with passwords. As long as these passwords stay in + physical memory, all is well. However, if the operating system starts + swapping out memory pages to free space for other applications, the + passwords may be written to the disk platters unencrypted and easy to + retrieve for an adversary. Encrypting swap space can be a solution for + this scenario. + + + + Preparation + + + For the remainder of this section, ad0s1b + will be the swap partition. + + + Up to this point the swap has been unencrypted. It is possible that + there are already passwords or other sensitive data on the disk platters + in cleartext. To rectify this, the data on the swap partition should be + overwritten with random garbage: + + &prompt.root; dd if=/dev/random of=/dev/ad0s1b bs=1m + + + + Swap Encryption with &man.gbde.8; + + If &os; 6.0-RELEASE or newer is being used, the + .bde suffix should be added to the device in the + respective /etc/fstab swap line: + + +# Device Mountpoint FStype Options Dump Pass# +/dev/ad0s1b.bde none swap sw 0 0 + + + For systems prior to &os; 6.0-RELEASE, the following line + in /etc/rc.conf is also needed: + + gbde_swap_enable="YES" + + + + Swap Encryption with &man.geli.8; + + Alternatively, the procedure for using &man.geli.8; for swap + encryption is similar to that of using &man.gbde.8;. The + .eli suffix should be added to the device in the + respective /etc/fstab swap line: + + +# Device Mountpoint FStype Options Dump Pass# +/dev/ad0s1b.eli none swap sw 0 0 + + + &man.geli.8; uses the AES algorithm with + a key length of 256 bit by default. + + Optionally, these defaults can be altered using the + geli_swap_flags option in + /etc/rc.conf. The following line tells the + encswap rc.d script to create &man.geli.8; swap + partitions using the Blowfish algorithm with a key length of 128 bit, + a sectorsize of 4 kilobytes and the detach on last close + option set: + + geli_swap_flags="-a blowfish -l 128 -s 4096 -d" + + Please refer to the description of the onetime command + in the &man.geli.8; manual page for a list of possible options. + + + + Verifying that it Works + + Once the system has been rebooted, proper operation of the + encrypted swap can be verified using the + swapinfo command. + + If &man.gbde.8; is being used: + + &prompt.user; swapinfo +Device 1K-blocks Used Avail Capacity +/dev/ad0s1b.bde 542720 0 542720 0% + + + If &man.geli.8; is being used: + + &prompt.user; swapinfo +Device 1K-blocks Used Avail Capacity +/dev/ad0s1b.eli 542720 0 542720 0% + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/eresources/Makefile b/pl_PL.ISO8859-2/books/handbook/eresources/Makefile new file mode 100644 index 0000000000..cb030a0162 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/eresources/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= eresources/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/eresources/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/eresources/chapter.sgml new file mode 100644 index 0000000000..4dceab8cdc --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/eresources/chapter.sgml @@ -0,0 +1,1781 @@ + + + + Resources on the Internet + + The rapid pace of FreeBSD progress makes print media impractical as a + means of following the latest developments. Electronic resources are the + best, if not often the only, way stay informed of the latest advances. + Since FreeBSD is a volunteer effort, the user community itself also + generally serves as a technical support department of sorts, + with electronic mail and USENET news being the most effective way of + reaching that community. + + The most important points of contact with the FreeBSD user community + are outlined below. If you are aware of other resources not mentioned + here, please send them to the &a.doc; so that they may also be + included. + + + Mailing Lists + + Though many of the FreeBSD development members read USENET, we + cannot always guarantee that we will get to your questions in a timely + fashion (or at all) if you post them only to one of the + comp.unix.bsd.freebsd.* groups. By addressing your + questions to the appropriate mailing list you will reach both us and a + concentrated FreeBSD audience, invariably assuring a better (or at least + faster) response. + + The charters for the various lists are given at the bottom of this + document. Please read the charter before joining or sending + mail to any list. Most of our list subscribers now receive + many hundreds of FreeBSD related messages every day, and by setting down + charters and rules for proper use we are striving to keep the + signal-to-noise ratio of the lists high. To do less would see the + mailing lists ultimately fail as an effective communications medium for + the project. + + When in doubt about what list to post a question to, see How to get best results from + the FreeBSD-questions mailing list. + + Before posting to any list, please learn about how to best use + the mailing lists, such as how to help avoid frequently-repeated + discussions, by reading the + Mailing List Frequently Asked Questions (FAQ) document. + + Archives are kept for all of the mailing lists and can be searched + using the FreeBSD World + Wide Web server. The keyword searchable archive offers an + excellent way of finding answers to frequently asked questions and + should be consulted before posting a question. + + + List Summary + + General lists: The following are general + lists which anyone is free (and encouraged) to join: + + + + + + List + Purpose + + + + + + &a.cvsall.name; + Changes made to the FreeBSD source tree + + + + &a.advocacy.name; + FreeBSD Evangelism + + + + &a.announce.name; + Important events and project milestones + + + + &a.arch.name; + Architecture and design discussions + + + + &a.bugbusters.name; + Discussions pertaining to the maintenance of the FreeBSD + problem report database and related tools + + + + &a.bugs.name; + Bug reports + + + + &a.chat.name; + Non-technical items related to the FreeBSD + community + + + + &a.current.name; + Discussion concerning the use of + &os.current; + + + + &a.isp.name; + Issues for Internet Service Providers using + FreeBSD + + + + &a.jobs.name; + FreeBSD employment and consulting + opportunities + + + + &a.policy.name; + FreeBSD Core team policy decisions. Low volume, and + read-only + + + + &a.questions.name; + User questions and technical support + + + + &a.security-notifications.name; + Security notifications + + + + &a.stable.name; + Discussion concerning the use of + &os.stable; + + + + &a.test.name; + Where to send your test messages instead of one of + the actual lists + + + + + + Technical lists: The following lists are for + technical discussion. You should read the charter for each list + carefully before joining or sending mail to one as there are firm + guidelines for their use and content. + + + + + + List + Purpose + + + + + + &a.acpi.name; + ACPI and power management development + + + + &a.afs.name; + Porting AFS to FreeBSD + + + + &a.aic7xxx.name; + Developing drivers for the &adaptec; AIC 7xxx + + + + &a.alpha.name; + Porting FreeBSD to the Alpha + + + + &a.amd64.name; + Porting FreeBSD to AMD64 systems + + + + &a.apache.name; + Discussion about Apache related ports + + + + &a.arm.name; + Porting FreeBSD to &arm; processors + + + + &a.atm.name; + Using ATM networking with FreeBSD + + + + &a.audit.name; + Source code audit project + + + + &a.binup.name; + Design and development of the binary update system + + + + &a.bluetooth.name; + Using &bluetooth; technology in FreeBSD + + + + &a.cluster.name; + Using FreeBSD in a clustered environment + + + + &a.cvsweb.name; + CVSweb maintenance + + + + &a.database.name; + Discussing database use and development under + FreeBSD + + + + &a.doc.name; + Creating FreeBSD related documents + + + + &a.drivers.name; + Writing device drivers for &os; + + + + &a.eclipse.name; + FreeBSD users of Eclipse IDE, tools, rich client + applications and ports. + + + + &a.embedded.name; + Using FreeBSD in embedded applications + + + + &a.emulation.name; + Emulation of other systems such as + Linux/&ms-dos;/&windows; + + + + &a.firewire.name; + FreeBSD &firewire; (iLink, IEEE 1394) technical + discussion + + + + &a.fs.name; + File systems + + + + &a.geom.name; + GEOM-specific discussions and implementations + + + + &a.gnome.name; + Porting GNOME and GNOME applications + + + + &a.hackers.name; + General technical discussion + + + + &a.hardware.name; + General discussion of hardware for running + FreeBSD + + + + &a.i18n.name; + FreeBSD Internationalization + + + + &a.ia32.name; + FreeBSD on the IA-32 (&intel; x86) platform + + + + &a.ia64.name; + Porting FreeBSD to &intel;'s upcoming IA64 systems + + + + &a.ipfw.name; + Technical discussion concerning the redesign of the IP + firewall code + + + + &a.isdn.name; + ISDN developers + + + + &a.java.name; + &java; developers and people porting &jdk;s to + FreeBSD + + + + &a.kde.name; + Porting KDE and KDE applications + + + + &a.lfs.name; + Porting LFS to FreeBSD + + + + &a.libh.name; + The second generation installation and package + system + + + + &a.mips.name; + Porting FreeBSD to &mips; + + + + &a.mobile.name; + Discussions about mobile computing + + + + &a.mozilla.name; + Porting Mozilla to FreeBSD + + + + &a.multimedia.name; + Multimedia applications + + + + &a.newbus.name; + Technical discussions about bus architecture + + + + &a.net.name; + Networking discussion and TCP/IP source code + + + + &a.openoffice.name; + Porting OpenOffice.org and + &staroffice; to FreeBSD + + + + &a.performance.name; + Performance tuning questions for high + performance/load installations + + + + &a.perl.name; + Maintenance of a number of + Perl-related ports + + + + &a.pf.name; + Discussion and questions about the packet filter + firewall system + + + + &a.platforms.name; + Concerning ports to non &intel; architecture + platforms + + + + &a.ports.name; + Discussion of the Ports Collection + + + + &a.ports-bugs.name; + Discussion of the ports bugs/PRs + + + + &a.ppc.name; + Porting FreeBSD to the &powerpc; + + + + &a.proliant.name; + Technical discussion of FreeBSD on HP ProLiant server platforms + + + + &a.python.name; + FreeBSD-specific Python issues + + + + &a.qa.name; + Discussion of Quality Assurance, usually pending a release + + + + &a.rc.name; + Discussion related to the rc.d system and its development + + + + &a.realtime.name; + Development of realtime extensions to FreeBSD + + + + &a.scsi.name; + The SCSI subsystem + + + + &a.security.name; + Security issues affecting FreeBSD + + + + &a.small.name; + Using FreeBSD in embedded applications + (obsolete; use &a.embedded.name; instead) + + + + &a.smp.name; + Design discussions for [A]Symmetric + MultiProcessing + + + + &a.sparc.name; + Porting FreeBSD to &sparc; based systems + + + + &a.standards.name; + FreeBSD's conformance to the C99 and the &posix; + standards + + + + &a.threads.name; + Threading in FreeBSD + + + + &a.testing.name; + FreeBSD Performance and Stability Tests + + + + &a.tokenring.name; + Support Token Ring in FreeBSD + + + + &a.usb.name; + Discussing &os; support for USB + + + + &a.vuxml.name; + Discussion on VuXML infrastructure + + + + &a.x11.name; + Maintenance and support of X11 on FreeBSD + + + + + + Limited lists: The following lists are for + more specialized (and demanding) audiences and are probably not of + interest to the general public. It is also a good idea to establish a + presence in the technical lists before joining one of these limited + lists so that you will understand the communications etiquette involved. + + + + + + List + Purpose + + + + + + &a.hubs.name; + People running mirror sites (infrastructural + support) + + + + &a.usergroups.name; + User group coordination + + + + &a.vendors.name; + Vendors pre-release coordination + + + + &a.www.name; + Maintainers of www.FreeBSD.org + + + + + + Digest lists: All of the above lists + are available in a digest format. Once subscribed to a list, + you can change your digest options in your account options + section. + + CVS lists: The following lists are for people + interested in seeing the log messages for changes to various areas of + the source tree. They are Read-Only lists and + should not have mail sent to them. + + + + + + List + Source area + Area Description (source for) + + + + + + &a.cvsall.name; + /usr/(CVSROOT|doc|ports|projects|src) + All changes to any place in the tree (superset of other CVS commit lists) + + + + &a.cvs-doc.name; + /usr/(doc|www) + All changes to the doc and www trees + + + + &a.cvs-ports.name; + /usr/ports + All changes to the ports tree + + + + &a.cvs-projects.name; + /usr/projects + All changes to the projects tree + + + + &a.cvs-src.name; + /usr/src + All changes to the src tree + + + + + + + + How to Subscribe + + To subscribe to a list, click on the list name above or + go to &a.mailman.lists.link; + and click on the list that you are interested in. The list + page should contain all of the necessary subscription + instructions. + + To actually post to a given list you simply send mail to + listname@FreeBSD.org. It will then + be redistributed to mailing list members world-wide. + + To unsubscribe yourself from a list, click on the URL + found at the bottom of every email received from the list. It + is also possible to send an email to + listname-unsubscribe@FreeBSD.org to unsubscribe + yourself. + + Again, we would like to request that you keep discussion in the + technical mailing lists on a technical track. If you are only + interested in important announcements then it is suggested that + you join the &a.announce;, which is intended only for infrequent + traffic. + + + + List Charters + + All FreeBSD mailing lists have certain basic + rules which must be adhered to by anyone using them. Failure to comply + with these guidelines will result in two (2) written warnings from the + FreeBSD Postmaster postmaster@FreeBSD.org, after which, + on a third offense, the poster will removed from all FreeBSD mailing + lists and filtered from further posting to them. We regret that such + rules and measures are necessary at all, but today's Internet is a + pretty harsh environment, it would seem, and many fail to appreciate + just how fragile some of its mechanisms are. + + Rules of the road: + + + + The topic of any posting should adhere to the basic charter of + the list it is posted to, e.g. if the list is about technical + issues then your posting should contain technical discussion. + Ongoing irrelevant chatter or flaming only detracts from the value + of the mailing list for everyone on it and will not be tolerated. + For free-form discussion on no particular topic, the &a.chat; + is freely available and should be used instead. + + + + No posting should be made to more than 2 mailing lists, and + only to 2 when a clear and obvious need to post to both lists + exists. For most lists, there is already a great deal of + subscriber overlap and except for the most esoteric mixes (say + -stable & -scsi), there really is no reason to post to more + than one list at a time. If a message is sent to you in such a + way that multiple mailing lists appear on the + Cc line then the Cc + line should also be trimmed before sending it out again. + You are still responsible for your + own cross-postings, no matter who the originator might have + been. + + + + Personal attacks and profanity (in the context of an argument) + are not allowed, and that includes users and developers alike. + Gross breaches of netiquette, like excerpting or reposting private + mail when permission to do so was not and would not be + forthcoming, are frowned upon but not specifically enforced. + However, there are also very few cases where + such content would fit within the charter of a list and it would + therefore probably rate a warning (or ban) on that basis + alone. + + + + Advertising of non-FreeBSD related products or services is + strictly prohibited and will result in an immediate ban if it is + clear that the offender is advertising by spam. + + + + Individual list charters: + + + + + &a.acpi.name; + + + ACPI and power management + development + + + + + &a.afs.name; + + + Andrew File System + + This list is for discussion on porting and using AFS from + CMU/Transarc + + + + + &a.announce.name; + + + Important events / milestones + + This is the mailing list for people interested only in + occasional announcements of significant FreeBSD events. This + includes announcements about snapshots and other releases. It + contains announcements of new FreeBSD capabilities. It may + contain calls for volunteers etc. This is a low volume, strictly + moderated mailing list. + + + + + &a.arch.name; + + + Architecture and design + discussions + + This list is for discussion of the FreeBSD + architecture. Messages will mostly be kept strictly + technical in nature. Examples of suitable topics + are: + + + + How to re-vamp the build system to have several + customized builds running at the same time. + + + + What needs to be fixed with VFS to make Heidemann layers + work. + + + + How do we change the device driver interface to be able + to use the same drivers cleanly on many buses and + architectures. + + + + How to write a network driver. + + + + + + + &a.audit.name; + + + Source code audit project + + This is the mailing list for the FreeBSD source code + audit project. Although this was originally intended for + security-related changes, its charter has been expanded to + review any code changes. + + This list is very heavy on patches, and is probably of no + interest to the average FreeBSD user. Security discussions + not related to a particular code change are held on + freebsd-security. Conversely, all developers are encouraged + to send their patches here for review, especially if they + touch a part of the system where a bug may adversely affect + the integrity of the system. + + + + + + + &a.binup.name; + + + FreeBSD Binary Update Project + + This list exists to provide discussion for the binary + update system, or binup. + Design issues, implementation details, + patches, bug reports, status reports, feature requests, commit + logs, and all other things related to + binup are fair game. + + + + + &a.bluetooth.name; + + + &bluetooth; in FreeBSD + + This is the forum where FreeBSD's &bluetooth; users + congregate. Design issues, implementation details, + patches, bug reports, status reports, feature requests, + and all matters related to &bluetooth; are fair + game. + + + + + &a.bugbusters.name; + + + Coordination of the Problem Report handling effort + + The purpose of this list is to serve as a coordination and + discussion forum for the Bugmeister, his Bugbusters, and any other + parties who have a genuine interest in the PR database. This list + is not for discussions about specific bugs, patches or PRs. + + + + + &a.bugs.name; + + + Bug reports + + This is the mailing list for reporting bugs in FreeBSD. + Whenever possible, bugs should be submitted using the + &man.send-pr.1; + command or the WEB + interface to it. + + + + + &a.chat.name; + + + Non technical items related to the FreeBSD + community + + This list contains the overflow from the other lists about + non-technical, social information. It includes discussion about + whether Jordan looks like a toon ferret or not, whether or not + to type in capitals, who is drinking too much coffee, where the + best beer is brewed, who is brewing beer in their basement, and + so on. Occasional announcements of important events (such as + upcoming parties, weddings, births, new jobs, etc) can be made + to the technical lists, but the follow ups should be directed to + this -chat list. + + + + + &a.core.name; + + + FreeBSD core team + + This is an internal mailing list for use by the core + members. Messages can be sent to it when a serious + FreeBSD-related matter requires arbitration or high-level + scrutiny. + + + + + &a.current.name; + + + Discussions about the use of + &os.current; + + This is the mailing list for users of &os.current;. It + includes warnings about new features coming out in -CURRENT that + will affect the users, and instructions on steps that must be + taken to remain -CURRENT. Anyone running CURRENT + must subscribe to this list. This is a technical mailing list + for which strictly technical content is expected. + + + + + &a.cvsweb.name; + + + FreeBSD CVSweb Project + + Technical discussions about use, development and maintenance + of FreeBSD-CVSweb. + + + + + &a.doc.name; + + + Documentation project + + This mailing list is for the discussion of issues and + projects related to the creation of documentation for FreeBSD. + The members of this mailing list are collectively referred to as + The FreeBSD Documentation Project. It is an open + list; feel free to join and contribute! + + + + + &a.drivers.name; + + + Writing device drivers for &os; + + This is a forum for technical discussions related to + device drivers on &os;. It is primarily a place + for device driver writers to ask questions about + how to write device drivers using the APIs in the + &os; kernel. + + + + + &a.eclipse.name; + + + &os; users of Eclipse IDE, tools, rich + client applications and ports. + + The intention of this list is to provide mutual + support for everything to do with choosing, installing, + using, developing and maintaining the Eclipse IDE, + tools, rich client applications on the &os; platform and + assisting with the porting of Eclipse IDE and plugins to + the &os; environment. + + The intention is also to facilitate exchange of + information between the Eclipse community and the &os; + community to the mutual benefit of both. + + Although this list is focused primarily on the needs + of Eclipse users it will also provide a forum for those + who would like to develop &os; specific applications + using the Eclipse framework. + + + + + + &a.embedded.name; + + + Using FreeBSD in embedded + applications + + This list discusses topics related to using FreeBSD in + embedded systems. This is a technical mailing list for which + strictly technical content is expected. For the purpose of + this list we define embedded systems as those computing + devices which are not desktops and which usually serve a + single purpose as opposed to being general computing + environments. Examples include, but are not limited to, + all kinds of phone handsets, network equipment such as + routers, switches and PBXs, remote measuring equipment, + PDAs, Point Of Sale systems, and so on. + + + + + &a.emulation.name; + + + Emulation of other systems such as + Linux/&ms-dos;/&windows; + + This is a forum for technical discussions related to + running programs written for other operating systems on &os;. + + + + + + &a.firewire.name; + + + &firewire; (iLink, IEEE 1394) + + This is a mailing list for discussion of the design + and implementation of a &firewire; (aka IEEE 1394 aka + iLink) subsystem for FreeBSD. Relevant topics + specifically include the standards, bus devices and + their protocols, adapter boards/cards/chips sets, and + the architecture and implementation of code for their + proper support. + + + + + &a.fs.name; + + + File systems + + Discussions concerning FreeBSD file systems. This is a + technical mailing list for which strictly technical content is + expected. + + + + + &a.geom.name; + + + GEOM + + Discussions specific to GEOM and related implementations. + This is a technical mailing list for which strictly technical + content is expected. + + + + + &a.gnome.name; + + + GNOME + + Discussions concerning The GNOME Desktop Environment for + FreeBSD systems. This is a technical mailing list for + which strictly technical content is expected. + + + + + &a.ipfw.name; + + + IP Firewall + + This is the forum for technical discussions concerning the + redesign of the IP firewall code in FreeBSD. This is a + technical mailing list for which strictly technical content is + expected. + + + + + &a.ia64.name; + + + Porting FreeBSD to IA64 + + This is a technical mailing list for individuals + actively working on porting FreeBSD to the IA-64 platform + from &intel;, to bring up problems or discuss alternative + solutions. Individuals interested in following the + technical discussion are also welcome. + + + + + &a.isdn.name; + + + ISDN Communications + + This is the mailing list for people discussing the + development of ISDN support for FreeBSD. + + + + + &a.java.name; + + + &java; Development + + This is the mailing list for people discussing the + development of significant &java; applications for FreeBSD and the + porting and maintenance of &jdk;s. + + + + + &a.jobs.name; + + + Jobs offered and sought + + This is a forum for posting employment notices and + resumes specifically related to &os;, e.g. if you are + seeking &os;-related employment or have a job involving + &os; to advertise then this is the right place. This is + not a mailing list for general + employment issues since adequate forums for that + already exist elsewhere. + + Note that this list, like other FreeBSD.org mailing + lists, is distributed worldwide. Thus, you need to be + clear about location and the extent to which + telecommuting or assistance with relocation is + available. + + Email should use open formats only — + preferably plain text, but basic Portable Document + Format (PDF), HTML, and a few others + are acceptable to many readers. Closed formats such as + µsoft; Word (.doc) will be + rejected by the mailing list server. + + + + + &a.kde.name; + + + KDE + + Discussions concerning KDE on + FreeBSD systems. This is a technical mailing list for + which strictly technical content is expected. + + + + + &a.hackers.name; + + + Technical discussions + + This is a forum for technical discussions related to + FreeBSD. This is the primary technical mailing list. It is for + individuals actively working on FreeBSD, to bring up problems or + discuss alternative solutions. Individuals interested in + following the technical discussion are also welcome. This is a + technical mailing list for which strictly technical content is + expected. + + + + + &a.hardware.name; + + + General discussion of FreeBSD + hardware + + General discussion about the types of hardware that FreeBSD + runs on, various problems and suggestions concerning what to buy + or avoid. + + + + + &a.hubs.name; + + + Mirror sites + + Announcements and discussion for people who run FreeBSD + mirror sites. + + + + + &a.isp.name; + + + Issues for Internet Service + Providers + + This mailing list is for discussing topics relevant to + Internet Service Providers (ISPs) using FreeBSD. This is a + technical mailing list for which strictly technical content is + expected. + + + + + &a.openoffice.name; + + + OpenOffice.org + + Discussions concerning the porting and maintenance + of OpenOffice.org and + &staroffice;. + + + + + &a.performance.name; + + + Discussions about tuning or speeding up FreeBSD + + This mailing list exists to provide a place for + hackers, administrators, and/or concerned parties to + discuss performance related topics pertaining to + FreeBSD. Acceptable topics includes talking about + FreeBSD installations that are either under high load, + are experiencing performance problems, or are pushing + the limits of FreeBSD. Concerned parties that are + willing to work toward improving the performance of + FreeBSD are highly encouraged to subscribe to this list. + This is a highly technical list ideally suited for + experienced FreeBSD users, hackers, or administrators + interested in keeping FreeBSD fast, robust, and + scalable. This list is not a question-and-answer list + that replaces reading through documentation, but it is a + place to make contributions or inquire about unanswered + performance related topics. + + + + + + &a.pf.name; + + + Discussion and questions about the packet filter + firewall system + + Discussion concerning the packet filter (pf) firewall + system in terms of FreeBSD. Technical discussion and user + questions are both welcome. This list is also a place to + discuss the ALTQ QoS framework. + + + + + + &a.platforms.name; + + + Porting to Non &intel; platforms + + Cross-platform FreeBSD issues, general discussion and + proposals for non &intel; FreeBSD ports. This is a technical + mailing list for which strictly technical content is + expected. + + + + + &a.policy.name; + + + Core team policy decisions + + This is a low volume, read-only mailing list for FreeBSD + Core Team Policy decisions. + + + + + &a.ports.name; + + + Discussion of + ports + + Discussions concerning FreeBSD's ports + collection (/usr/ports), ports infrastructure, and + general ports coordination efforts. This is a technical mailing list + for which strictly technical content is expected. + + + + + &a.ports-bugs.name; + + + Discussion of + ports bugs + + Discussions concerning problem reports for FreeBSD's ports + collection (/usr/ports), proposed + ports, or modifications to ports. This is a technical mailing list + for which strictly technical content is expected. + + + + + &a.proliant.name; + + + Technical discussion of FreeBSD on HP + ProLiant server platforms + + This mailing list is to be used for the technical + discussion of the usage of FreeBSD on HP ProLiant servers, + including the discussion of ProLiant-specific drivers, + management software, configuration tools, and BIOS + updates. As such, this is the primary place to discuss + the hpasmd, hpasmcli, and hpacucli modules. + + + + + &a.python.name; + + + Python on FreeBSD + + This is a list for discussions related to improving Python-support + on FreeBSD. This is a technical mailing list. It is for individuals + working on porting Python, its 3rd party modules and Zope stuff to + FreeBSD. Individuals interested in following the technical discussion + are also welcome. + + + + + &a.questions.name; + + + User questions + + This is the mailing list for questions about FreeBSD. You + should not send how to questions to the technical + lists unless you consider the question to be pretty + technical. + + + + + &a.scsi.name; + + + SCSI subsystem + + This is the mailing list for people working on the SCSI + subsystem for FreeBSD. This is a technical mailing list for + which strictly technical content is expected. + + + + + &a.security.name; + + + Security issues + + FreeBSD computer security issues (DES, Kerberos, known + security holes and fixes, etc). This is a technical mailing + list for which strictly technical discussion is expected. Note + that this is not a question-and-answer list, but that + contributions (BOTH question AND answer) to the FAQ are + welcome. + + + + + &a.security-notifications.name; + + + Security Notifications + + Notifications of FreeBSD security problems and + fixes. This is not a discussion list. The discussion + list is FreeBSD-security. + + + + + &a.small.name; + + + Using FreeBSD in embedded + applications + + This list discusses topics related to unusually small and + embedded FreeBSD installations. This is a technical mailing + list for which strictly technical content is expected. + + + This list has been obsoleted by &a.embedded.name;. + + + + + + + &a.stable.name; + + + Discussions about the use of + &os.stable; + + This is the mailing list for users of &os.stable;. It + includes warnings about new features coming out in -STABLE that + will affect the users, and instructions on steps that must be + taken to remain -STABLE. Anyone running STABLE + should subscribe to this list. This is a technical mailing list + for which strictly technical content is expected. + + + + + &a.standards.name; + + + C99 & POSIX Conformance + + This is a forum for technical discussions related to + FreeBSD Conformance to the C99 and the POSIX standards. + + + + + &a.usb.name; + + + Discussing &os; support for + USB + + This is a mailing list for technical discussions + related to &os; support for USB. + + + + + &a.usergroups.name; + + + User Group Coordination List + + This is the mailing list for the coordinators from each of + the local area Users Groups to discuss matters with each other + and a designated individual from the Core Team. This mail list + should be limited to meeting synopsis and coordination of + projects that span User Groups. + + + + + &a.vendors.name; + + + Vendors + + Coordination discussions between The FreeBSD Project and + Vendors of software and hardware for FreeBSD. + + + + + + + Filtering on the Mailing Lists + + The &os; mailing lists are filtered in multiple ways to + avoid the distribution of spam, viruses, and other unwanted emails. + The filtering actions described in this section do not include all + those used to protect the mailing lists. + + Only certain types of attachments are allowed on the + mailing lists. All attachments with a MIME content type not + found in the list below will be stripped before an email is + distributed on the mailing lists. + + + + application/octet-stream + + + + application/pdf + + + + application/pgp-signature + + + + application/x-pkcs7-signature + + + + message/rfc822 + + + + multipart/alternative + + + + multipart/related + + + + multipart/signed + + + + text/html + + + + text/plain + + + + text/x-diff + + + + text/x-patch + + + + + Some of the mailing lists might allow attachments of + other MIME content types, but the above list should be + applicable for most of the mailing lists. + + + If an email contains both an HTML and a plain text version, + the HTML version will be removed. If an email contains only an + HTML version, it will be converted to plain text. + + + + + Usenet Newsgroups + + In addition to two FreeBSD specific newsgroups, there are many + others in which FreeBSD is discussed or are otherwise relevant to + FreeBSD users. Keyword + searchable archives are available for some of these newsgroups + from courtesy of Warren Toomey wkt@cs.adfa.edu.au. + + + BSD Specific Newsgroups + + + + comp.unix.bsd.freebsd.announce + + + + comp.unix.bsd.freebsd.misc + + + + de.comp.os.unix.bsd (German) + + + + fr.comp.os.bsd (French) + + + + it.comp.os.freebsd (Italian) + + + + + + Other &unix; Newsgroups of Interest + + + + comp.unix + + + + comp.unix.questions + + + + comp.unix.admin + + + + comp.unix.programmer + + + + comp.unix.shell + + + + comp.unix.user-friendly + + + + comp.security.unix + + + + comp.sources.unix + + + + comp.unix.advocacy + + + + comp.unix.misc + + + + comp.bugs.4bsd + + + + comp.bugs.4bsd.ucb-fixes + + + + comp.unix.bsd + + + + + + X Window System + + + + comp.windows.x.i386unix + + + + comp.windows.x + + + + comp.windows.x.apps + + + + comp.windows.x.announce + + + + comp.windows.x.intrinsics + + + + comp.windows.x.motif + + + + comp.windows.x.pex + + + + comp.emulators.ms-windows.wine + + + + + + + World Wide Web Servers + + &chap.eresources.www.inc; + + + + Email Addresses + + The following user groups provide FreeBSD related email addresses + for their members. The listed administrator reserves the right to + revoke the address if it is abused in any way. + + + + + + Domain + Facilities + User Group + Administrator + + + + + + ukug.uk.FreeBSD.org + Forwarding only + freebsd-users@uk.FreeBSD.org + Lee Johnston + lee@uk.FreeBSD.org + + + + + + + + Shell Accounts + + The following user groups provide shell accounts for people who are + actively supporting the FreeBSD project. The listed administrator + reserves the right to cancel the account if it is abused in any + way. + + + + + + Host + Access + Facilities + Administrator + + + + + + dogma.freebsd-uk.eu.org + Telnet/FTP/SSH + Email, Web space, Anonymous FTP + Lee Johnston + lee@uk.FreeBSD.org + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/firewalls/Makefile b/pl_PL.ISO8859-2/books/handbook/firewalls/Makefile new file mode 100644 index 0000000000..331f5bf8ec --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/firewalls/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= firewalls/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/firewalls/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/firewalls/chapter.sgml new file mode 100644 index 0000000000..9b9e69fb6d --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/firewalls/chapter.sgml @@ -0,0 +1,3339 @@ + + + + + + + Joseph J. + Barbish + Contributed by + + + + + Brad + Davis + Converted to SGML and updated by + + + + + Firewalls + + firewall + + + security + + firewalls + + + + Introduction + + Firewalls make it possible to filter + incoming and outgoing traffic that flows through your system. + A firewall can use one or more sets of rules to + inspect the network packets as they come in or go out of your + network connections and either allows the traffic through or + blocks it. The rules of a firewall can inspect one or more + characteristics of the packets, including but not limited to the + protocol type, the source or destination host address, and the + source or destination port. + + Firewalls can greatly enhance the security of a host or a + network. They can be used to do one or more of + the following things: + + + + To protect and insulate the applications, services and + machines of your internal network from unwanted traffic + coming in from the public Internet. + + + + To limit or disable access from hosts of the internal + network to services of the public Internet. + + + + To support network address translation + (NAT), which allows your internal network + to use private IP addresses and share a + single connection to the public Internet (either with a + single IP address or by a shared pool of + automatically assigned public addresses). + + + + After reading this chapter, you will know: + + + + How to properly define packet filtering rules. + + + + The differences between the firewalls + built into &os;. + + + + How to use and configure the OpenBSD + PF firewall. + + + + How to use and configure + IPFILTER. + + + + How to use and configure + IPFW. + + + + Before reading this chapter, you should: + + + + Understand basic &os; and Internet concepts. + + + + + + Firewall Concepts + + + firewall + + rulesets + + + There are two basic ways to create firewall rulesets: + inclusive or exclusive. An + exclusive firewall allows all traffic through except for the + traffic matching the ruleset. An inclusive firewall does the + reverse. It only allows traffic matching the rules through and + blocks everything else. + + Inclusive firewalls are generally safer than exclusive + firewalls because they significantly reduce the risk of allowing + unwanted traffic to pass through the firewall. + + Security can be tightened further using a stateful + firewall. With a stateful firewall the firewall keeps + track of which connections are opened through the firewall and + will only allow traffic through which either matches an existing + connection or opens a new one. The disadvantage of a stateful + firewall is that it can be vulnerable to Denial of Service + (DoS) attacks if a lot of new connections are + opened very fast. With most firewalls it is possible to use a + combination of stateful and non-stateful behavior to make an + optimal firewall for the site. + + + + Firewall Packages + + &os; has three different firewall packages built + into the base system. They are: IPFILTER + (also known as IPF), + IPFIREWALL (also known as IPFW), + and OpenBSD's PacketFilter (also known as + PF). &os; also has two built in packages for + traffic shaping (basically controlling bandwidth usage): + &man.altq.4; and &man.dummynet.4;. Dummynet has traditionally been + closely tied with IPFW, and + ALTQ with + IPF/PF. IPF, + IPFW, and PF all use rules to control the access of packets to and + from your system, although they go about it different ways and + have different rule syntaxes. + + The reason that &os; has multiple built in firewall packages + is that different people have different requirements and + preferences. No single firewall package is the best. + + The author prefers IPFILTER because its stateful rules are + much less complicated to use in a NAT + environment and it has a built in ftp proxy that simplifies the + rules to allow secure outbound FTP usage. + + Since all firewalls are based on inspecting the values of + selected packet control fields, the creator of the firewall + rulesets must have an understanding of how + TCP/IP works, what the different values in + the packet control fields are and how these values are used in a + normal session conversation. For a good explanation go to: + . + + + + The OpenBSD Packet Filter (PF) and + <acronym>ALTQ</acronym> + + + firewall + + PF + + + As of July 2003 the OpenBSD firewall software application + known as PF was ported to &os; and was made + available in the &os; Ports Collection; the first release that + contained PF as an integrated part of the + base system was &os; 5.3 in November 2004. + PF is a complete, fully featured firewall + that has optional support for ALTQ (Alternate + Queuing). ALTQ provides Quality of Service + (QoS) bandwidth shaping that allows + guaranteeing bandwidth to different services based on filtering + rules. The OpenBSD Project does an outstanding job of + maintaining the PF User's Guide that it will not be made part of + this handbook firewall section as that would just be duplicated + effort. + + More info can be found at the PF for &os; web site: . + + + Enabling PF + + PF is included in the basic &os; install for versions newer + than 5.3 as a separate run time loadable module. The system + will dynamically load the PF kernel loadable module when the + rc.conf statement pf_enable="YES" is used. + The loadable module was created with &man.pflog.4; logging + enabled. + + + The module assumes the presence of options + INET and device bpf. Unless + NOINET6 for &os; prior to 6.0-RELEASE and + NO_INET6 for later releases (for example in + &man.make.conf.5;) was defined during the build, it also + requiresoptions INET6. + + + Once the kernel module is loaded or the kernel is statically + built with PF support, it is possible to enable or disable + pf with the pfctl + command. + + This example demonstrates how to enable + pf: + + &prompt.root; pfctl -e + + The pfctl command provides a way to work + with the pf firewall. It is a good + idea to check the &man.pfctl.8; manual page to find out more + information about using it. + + + + Kernel options + + + kernel options + + device pf + + + + kernel options + + device pflog + + + + kernel options + + device pfsync + + + It is not a mandatory requirement that you enable PF by + compiling the following options into the &os; kernel. It is + only presented here as background information. Compiling PF + into the kernel causes the loadable module to never be + used. + + Sample kernel config PF option statements are in the + /usr/src/sys/conf/NOTES kernel source and + are reproduced here: + + device pf +device pflog +device pfsync + + device pf enables support for the + Packet Filter firewall. + + device pflog enables the optional + &man.pflog.4; pseudo network device which can be used to log + traffic to a &man.bpf.4; descriptor. The &man.pflogd.8; daemon + can be used to store the logging information to disk. + + device pfsync enables the optional + &man.pfsync.4; pseudo network device that is used to monitor + state changes. As this is not part of the + loadable module one has to build a custom kernel to use + it. + + These settings will take effect only after you have built + and installed a kernel with them set. + + + + Available rc.conf Options + + You need the following statements in + /etc/rc.conf to activate PF at boot + time: + + pf_enable="YES" # Enable PF (load module if required) +pf_rules="/etc/pf.conf" # rules definition file for pf +pf_flags="" # additional flags for pfctl startup +pflog_enable="YES" # start pflogd(8) +pflog_logfile="/var/log/pflog" # where pflogd should store the logfile +pflog_flags="" # additional flags for pflogd startup + + If you have a LAN behind this firewall and have to forward + packets for the computers in the LAN or want to do NAT, you + have to enable the following option as well: + + gateway_enable="YES" # Enable as LAN gateway + + + + Enabling <acronym>ALTQ</acronym> + + ALTQ is only available by compiling the + options into the &os; Kernel. ALTQ is not + supported by all of the available network card drivers. Please + see the &man.altq.4; manual page for a list of drivers that are + supported in your release of &os;. The following options will + enable ALTQ and add additional + functionality. + + options ALTQ +options ALTQ_CBQ # Class Bases Queuing (CBQ) +options ALTQ_RED # Random Early Detection (RED) +options ALTQ_RIO # RED In/Out +options ALTQ_HFSC # Hierarchical Packet Scheduler (HFSC) +options ALTQ_PRIQ # Priority Queuing (PRIQ) +options ALTQ_NOPCC # Required for SMP build + + options ALTQ enables the + ALTQ framework. + + options ALTQ_CBQ enables Class Based + Queuing (CBQ). CBQ + allows you to divide a connection's bandwidth into different + classes or queues to prioritize traffic based on filter + rules. + + options ALTQ_RED enables Random Early + Detection (RED). RED is + used to avoid network congestion. RED does + this by measuring the length of the queue and comparing it to + the minimum and maximum thresholds for the queue. If the + queue is over the maximum all new packets will be dropped. + True to its name, RED drops packets from + different connections randomly. + + options ALTQ_RIO enables Random Early + Detection In and Out. + + options ALTQ_HFSC enables the + Hierarchical Fair Service Curve Packet Scheduler. For more + information about HFSC see: . + + options ALTQ_PRIQ enables Priority + Queuing (PRIQ). PRIQ + will always pass traffic that is in a higher queue + first. + + options ALTQ_NOPCC enables + SMP support for ALTQ. + This option is required on SMP + systems. + + + + Creating Filtering Rules + + The Packet Filter reads its configuration rules from the + &man.pf.conf.5; file and it modifies, drops or passes packets + according to the rules or definitions specified there. The &os; + installation comes with a default + /etc/pf.conf which contains useful examples + and explanations. + + Although &os; has its own /etc/pf.conf + the syntax is the same as one used in OpenBSD. A great + resource for configuring the pf + firewall has been written by OpenBSD team and is available at + . + + + When browsing the pf user's guide, please keep in mind that + different versions of &os; contain different versions of pf. The + pf firewall in &os; 5.X is at the level + of OpenBSD version 3.5 and in &os; 6.X is at the level of OpenBSD + version 3.7. + + + The &a.pf; is a good place to ask questions about + configuring and running the pf + firewall. Do not forget to check the mailing list archives + before asking questions. + + + + + The IPFILTER (IPF) Firewall + + + firewall + + IPFILTER + + + + This section is work in progress. The contents might + not be accurate at all times. + + + The author of IPFILTER is Darren Reed. IPFILTER is not + operating system dependent: it is an open source application and + has been ported to &os;, NetBSD, OpenBSD, &sunos;, HP/UX, and + &solaris; operating systems. IPFILTER is actively being + supported and maintained, with updated versions being released + regularly. + + IPFILTER is based on a kernel-side firewall and + NAT mechanism that can be controlled and + monitored by userland interface programs. The firewall rules can + be set or deleted with the &man.ipf.8; utility. The + NAT rules can be set or deleted with the + &man.ipnat.1; utility. The &man.ipfstat.8; utility can print + run-time statistics for the kernel parts of IPFILTER. The + &man.ipmon.8; program can log IPFILTER actions to the system log + files. + + IPF was originally written using a rule processing logic of + the last matching rule wins and used only + stateless type of rules. Over time IPF has been enhanced to + include a quick option and a stateful keep + state option which drastically modernized the rules + processing logic. IPF's official documentation covers the legacy + rule coding parameters and the legacy rule file processing + logic. The modernized functions are only included as additional + options, completely understating their benefits in producing a + far superior secure firewall. + + The instructions contained in this section are based on + using rules that contain the quick option and the + stateful keep state option. This is the basic + framework for coding an inclusive firewall rule set. + + + + An inclusive firewall only allows packets matching the rules + to pass through. This way you can control what services can + originate behind the firewall destined for the public Internet + and also control the services which can originate from the + public Internet accessing your private network. Everything else + is blocked and logged by default design. Inclusive firewalls are + much, much more secure than exclusive firewall rule sets and is + the only rule set type covered herein. + + For detailed explanation of the legacy rules processing + method see: + and . + + The IPF FAQ is at . + + A searchable archive of the open-source IPFilter mailing list is + available at . + + + Enabling IPF + + + IPFILTER + + enabling + + + IPF is included in the basic &os; install as a separate run + time loadable module. The system will dynamically load the IPF + kernel loadable module when the rc.conf statement + ipfilter_enable="YES" is used. The loadable + module was created with logging enabled and the + default pass all options. You do not need + to compile IPF into the &os; kernel just to change the default + to block all, you can do that by just coding + a block all rule at the end of your rule set. + + + + Kernel options + + + kernel options + + IPFILTER + + + + kernel options + + IPFILTER_LOG + + + + kernel options + + IPFILTER_DEFAULT_BLOCK + + + + IPFILTER + + kernel options + + + It is not a mandatory requirement that you enable IPF by + compiling the following options into the &os; kernel. It is + only presented here as background information. Compiling IPF + into the kernel causes the loadable module to never be + used. + + Sample kernel config IPF option statements are in the + /usr/src/sys/conf/NOTES kernel source + and are reproduced here: + + options IPFILTER +options IPFILTER_LOG +options IPFILTER_DEFAULT_BLOCK + + options IPFILTER enables support for the + IPFILTER firewall. + + options IPFILTER_LOG enables the option + to have IPF log traffic by writing to the + ipl packet logging pseudo—device + for every rule that has the log + keyword. + + options IPFILTER_DEFAULT_BLOCK changes + the default behavior so any packet not matching a firewall + pass rule gets blocked. + + These settings will take effect only after you have built + and installed a kernel with them set. + + + + Available rc.conf Options + + You need the following statements in + /etc/rc.conf to activate IPF at boot + time: + + ipfilter_enable="YES" # Start ipf firewall +ipfilter_rules="/etc/ipf.rules" # loads rules definition text file +ipmon_enable="YES" # Start IP monitor log +ipmon_flags="-Ds" # D = start as daemon + # s = log to syslog + # v = log tcp window, ack, seq + # n = map IP & port to names + + If you have a LAN behind this firewall that uses the + reserved private IP address ranges, then you need to add the + following to enable NAT + functionality: + + gateway_enable="YES" # Enable as LAN gateway +ipnat_enable="YES" # Start ipnat function +ipnat_rules="/etc/ipnat.rules" # rules definition file for ipnat + + + + IPF + + ipf + + The ipf command is used to load your rules file. Normally + you create a file containing your custom rules and use this + command to replace in mass the currently running firewall + internal rules: + + &prompt.root; ipf -Fa -f /etc/ipf.rules + + means flush all internal rules + tables. + + means this is the file to read for the + rules to load. + + This gives you the ability to make changes to your custom + rules file, run the above IPF command, and thus update the + running firewall with a fresh copy of all the rules without + having to reboot the system. This method is very convenient + for testing new rules as the procedure can be executed as many + times as needed. + + See the &man.ipf.8; manual page for details on the other + flags available with this command. + + The &man.ipf.8; command expects the rules file to be a + standard text file. It will not accept a rules file written as + a script with symbolic substitution. + + There is a way to build IPF rules that utilizes the power + of script symbolic substitution. For more information, see + . + + + + IPFSTAT + + ipfstat + + + IPFILTER + + statistics + + + The default behavior of &man.ipfstat.8; is to retrieve and + display the totals of the accumulated statistics gathered as a + result of applying the user coded rules against packets going + in and out of the firewall since it was last started, or since + the last time the accumulators were reset to zero by the + ipf -Z command. + + See the &man.ipfstat.8; manual page for details. + + The default &man.ipfstat.8; command output will look + something like this: + + input packets: blocked 99286 passed 1255609 nomatch 14686 counted 0 + output packets: blocked 4200 passed 1284345 nomatch 14687 counted 0 + input packets logged: blocked 99286 passed 0 + output packets logged: blocked 0 passed 0 + packets logged: input 0 output 0 + log failures: input 3898 output 0 + fragment state(in): kept 0 lost 0 + fragment state(out): kept 0 lost 0 + packet state(in): kept 169364 lost 0 + packet state(out): kept 431395 lost 0 + ICMP replies: 0 TCP RSTs sent: 0 + Result cache hits(in): 1215208 (out): 1098963 + IN Pullups succeeded: 2 failed: 0 + OUT Pullups succeeded: 0 failed: 0 + Fastroute successes: 0 failures: 0 + TCP cksum fails(in): 0 (out): 0 + Packet log flags set: (0) + + When supplied with either for inbound + or for outbound, it will retrieve and + display the appropriate list of filter rules currently + installed and in use by the kernel. + + ipfstat -in displays the inbound + internal rules table with rule number. + + ipfstat -on displays the outbound + internal rules table with the rule number. + + The output will look something like this: + + @1 pass out on xl0 from any to any +@2 block out on dc0 from any to any +@3 pass out quick on dc0 proto tcp/udp from any to any keep state + + ipfstat -ih displays the inbound + internal rules table, prefixing each rule with a count of how + many times the rule was matched. + + ipfstat -oh displays the outbound + internal rules table, prefixing each rule with a count of how + many times the rule was matched. + + The output will look something like this: + + 2451423 pass out on xl0 from any to any +354727 block out on dc0 from any to any +430918 pass out quick on dc0 proto tcp/udp from any to any keep state + + One of the most important functions of the + ipfstat command is the + flag which displays the state table in a way similar to the way + &man.top.1; shows the &os; running process table. When your + firewall is under attack this function gives you the ability to + identify, drill down to, and see the attacking packets. The + optional sub-flags give the ability to select the destination + or source IP, port, or protocol that you want to monitor in + real time. See the &man.ipfstat.8; manual page for + details. + + + + IPMON + + ipmon + + + IPFILTER + + logging + + + In order for ipmon to work properly, the + kernel option IPFILTER_LOG must be turned on. This command has + two different modes that it can be used in. Native mode is the + default mode when you type the command on the command line + without the flag. + + Daemon mode is for when you want to have a continuous + system log file available so that you can review logging of + past events. This is how &os; and IPFILTER are configured to + work together. &os; has a built in facility to automatically + rotate system logs. That is why outputting the log information + to syslogd is better than the default of outputting to a + regular file. In the default rc.conf file + you see the ipmon_flags statement uses the + flags: + + ipmon_flags="-Ds" # D = start as daemon + # s = log to syslog + # v = log tcp window, ack, seq + # n = map IP & port to names + + The benefits of logging are obvious. It provides the + ability to review, after the fact, information such as which + packets had been dropped, what addresses they came from and + where they were going. These all give you a significant edge + in tracking down attackers. + + Even with the logging facility enabled, IPF will not + generate any rule logging on its own. The firewall + administrator decides what rules in the rule set he wants to + log and adds the log keyword to those rules. Normally only + deny rules are logged. + + It is very customary to include a default deny everything + rule with the log keyword included as your last rule in the + rule set. This way you get to see all the packets that did not + match any of the rules in the rule set. + + + + IPMON Logging + + Syslogd uses its own special + method for segregation of log data. It uses special groupings + called facility and level. IPMON + in mode uses security + as the facility + name. All IPMON logged data goes to security + The following levels can be + used to further segregate the logged data if desired: + + LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block. +LOG_NOTICE - packets logged which are also passed +LOG_WARNING - packets logged which are also blocked +LOG_ERR - packets which have been logged and which can be considered short + + + + To setup IPFILTER to log all data to + /var/log/ipfilter.log, you will need to + create the file. The following command will do that: + + &prompt.root; touch /var/log/ipfilter.log + + The syslog function is controlled by definition statements + in the /etc/syslog.conf file. The + syslog.conf file offers considerable + flexibility in how syslog will deal with system messages issued + by software applications like IPF. + + Add the following statement to + /etc/syslog.conf: + + security.* /var/log/ipfilter.log + + Or add the following statement to + /etc/syslog.conf. + + The security.* + means to write all the logged messages to the coded + file location. + + To activate the changes to /etc/syslog.conf + you can reboot or bump the syslog task into + re-reading /etc/syslog.conf by running + /etc/rc.d/syslogd reload + + Do not forget to change + /etc/newsyslog.conf to rotate the new log + you just created above. + + + + The Format of Logged Messages + + Messages generated by ipmon consist of + data fields separated by white space. Fields common to all + messages are: + + + + The date of packet receipt. + + + + The time of packet receipt. This is in the form + HH:MM:SS.F, for hours, minutes, seconds, and fractions of a + second (which can be several digits long). + + + + The name of the interface the packet was processed on, + e.g. dc0. + + + + The group and rule number of the rule, e.g. + @0:17. + + + + These can be viewed with ipfstat + -in. + + + + The action: p for passed, b for blocked, S for a short + packet, n did not match any rules, L for a log rule. The + order of precedence in showing flags is: S, p, b, n, L. A + capital P or B means that the packet has been logged due to + a global logging setting, not a particular rule. + + + + The addresses. This is actually three fields: the + source address and port (separated by a comma), the -> + symbol, and the destination address and port. + 209.53.17.22,80 -> 198.73.220.17,1722. + + + + PR followed by the protocol name or + number, e.g. PR tcp. + + + + len followed by the header length + and total length of the packet, e.g. len 20 40. + + + + If the packet is a TCP packet, there + will be an additional field starting with a hyphen followed by + letters corresponding to any flags that were set. See the + &man.ipmon.8; manual page for a list of letters and their + flags. + + If the packet is an ICMP packet, there will be two fields + at the end, the first always being ICMP, and the + next being the ICMP message and sub-message type, separated by + a slash, e.g. ICMP 3/3 for a port unreachable message. + + + + Building the Rule Script with Symbolic + Substitution + + Some experienced IPF users create a file containing the + rules and code them in a manner compatible with running them as + a script with symbolic substitution. The major benefit of + doing this is that you only have to change the value associated + with the symbolic name and when the script is run all the rules + containing the symbolic name will have the value substituted in + the rules. Being a script, you can use symbolic substitution + to code frequently used values and substitute them in multiple + rules. You will see this in the following example. + + The script syntax used here is compatible with the sh, csh, + and tcsh shells. + + Symbolic substitution fields are prefixed with a dollar + sign: $. + + Symbolic fields do not have the $ prefix. + + The value to populate the symbolic field must be enclosed + with double quotes ("). + + Start your rule file with something like this: + + ############# Start of IPF rules script ######################## + +oif="dc0" # name of the outbound interface +odns="192.0.2.11" # ISP's DNS server IP address +myip="192.0.2.7" # my static IP address from ISP +ks="keep state" +fks="flags S keep state" + +# You can choose between building /etc/ipf.rules file +# from this script or running this script "as is". +# +# Uncomment only one line and comment out another. +# +# 1) This can be used for building /etc/ipf.rules: +#cat > /etc/ipf.rules << EOF +# +# 2) This can be used to run script "as is": +/sbin/ipf -Fa -f - << EOF + +# Allow out access to my ISP's Domain name server. +pass out quick on $oif proto tcp from any to $odns port = 53 $fks +pass out quick on $oif proto udp from any to $odns port = 53 $ks + +# Allow out non-secure standard www function +pass out quick on $oif proto tcp from $myip to any port = 80 $fks + +# Allow out secure www function https over TLS SSL +pass out quick on $oif proto tcp from $myip to any port = 443 $fks +EOF +################## End of IPF rules script ######################## + + That is all there is to it. The rules are not important in + this example; how the symbolic substitution fields are + populated and used are. If the above example was in a file + named /etc/ipf.rules.script, you could + reload these rules by entering the following command: + + &prompt.root; sh /etc/ipf.rules.script + + There is one problem with using a rules file with embedded + symbolics: IPF does not understand symbolic substitution, and + cannot read such scripts directly. + + This script can be used in one of two ways: + + + + Uncomment the line that begins with + cat, and comment out the line that + begins with /sbin/ipf. Place + ipfilter_enable="YES" into + /etc/rc.conf as usual, and run script + once after each modification to create or update + /etc/ipf.rules. + + + + Disable IPFILTER in system startup scripts by adding + ipfilter_enable="NO" (this is default + value) into /etc/rc.conf file. + + Add a script like the following to your + /usr/local/etc/rc.d/ startup + directory. The script should have an obvious name like + ipf.loadrules.sh. The + .sh extension is mandatory. + + #!/bin/sh +sh /etc/ipf.rules.script + + The permissions on this script file must be read, + write, execute for owner root. + + &prompt.root; chmod 700 /usr/local/etc/rc.d/ipf.loadrules.sh + + + + Now, when your system boots, your IPF rules will be + loaded. + + + + IPF Rule Sets + + + + A rule set is a group of ipf rules coded to pass or block + packets based on the values contained in the packet. The + bi-directional exchange of packets between hosts comprises a + session conversation. The firewall rule set processes the + packet two times, once on its arrival from the public Internet + host and again as it leaves for its return trip back to the + public Internet host. Each TCP/IP service (i.e. telnet, www, + mail, etc.) is predefined by its protocol, source and + destination IP address, or the source and destination port + number. This is the basic selection criteria used to create + rules which will pass or block services. + + + IPFILTER + + rule processing order + + + IPF was originally written using a rules processing logic + of the last matching rule wins and used only + stateless rules. Over time IPF has been enhanced to include a + quick option and a stateful keep + state option which drastically modernized the rule + processing logic. + + The instructions contained in this section are based on + using rules that contain the quick option and + the stateful keep state option. This is the + basic framework for coding an inclusive firewall rule + set. + + + + An inclusive firewall only allows services matching the + rules through. This way you can control what services can + originate behind the firewall destined for the public Internet + and also control the services which can originate from the + public Internet accessing your private network. Everything + else is blocked and logged by default design. Inclusive + firewalls are much, much securer than exclusive firewall rule + sets and is the only rule set type covered herein. + + + When working with the firewall rules, be very + careful. Some configurations will + lock you out of the server. To be on the safe + side, you may wish to consider performing the initial + firewall configuration from the local console rather than + doing it remotely e.g. via + ssh. + + + + + Rule Syntax + + + IPFILTER + + rule syntax + + + The rule syntax presented here has been simplified to only + address the modern stateful rule context and first + matching rule wins logic. For the complete legacy rule + syntax description see the &man.ipf.8; manual page. + + A # character is used to mark the start + of a comment and may appear at the end of a rule line or on its + own line. Blank lines are ignored. + + Rules contain keywords. These keywords have to be coded in + a specific order from left to right on the line. Keywords are + identified in bold type. Some keywords have sub-options which + may be keywords themselves and also include more sub-options. + Each of the headings in the below syntax has a bold section + header which expands on the content. + + + + + ACTION IN-OUT OPTIONS SELECTION STATEFUL PROTO + SRC_ADDR,DST_ADDR OBJECT PORT_NUM TCP_FLAG + STATEFUL + + ACTION = block | pass + + IN-OUT = in | out + + OPTIONS = log | quick | on + interface-name + + SELECTION = proto value | + source/destination IP | port = number | flags + flag-value + + PROTO = tcp/udp | udp | tcp | + icmp + + SRC_ADD,DST_ADDR = all | from + object to object + + OBJECT = IP address | any + + PORT_NUM = port number + + TCP_FLAG = S + + STATEFUL = keep state + + + ACTION + + The action indicates what to do with the packet if it + matches the rest of the filter rule. Each rule + must have a action. The following + actions are recognized: + + block indicates that the packet should + be dropped if the selection parameters match the + packet. + + pass indicates that the packet should + exit the firewall if the selection parameters match the + packet. + + + + IN-OUT + + A mandatory requirement is that each filter rule + explicitly state which side of the I/O it is to be used on. + The next keyword must be either in or out and one or the + other has to be coded or the rule will not pass syntax + checks. + + in means this rule is being applied + against an inbound packet which has just been received on the + interface facing the public Internet. + + out means this rule is being applied + against an outbound packet destined for the interface facing + the public Internet. + + + + OPTIONS + + + These options must be used in the order shown + here. + + + log indicates that the packet header + will be written to + + + + the ipl log (as described in the + LOGGING section below) if the selection parameters match the + packet. + + quick indicates that if the selection + parameters match the packet, this rule will be the last rule + checked, allowing a short-circuit path to avoid processing + any following rules for this packet. This option is a + mandatory requirement for the modernized rules processing + logic. + + on indicates the interface name to be + incorporated into the selection parameters. Interface names + are as displayed by &man.ifconfig.8;. Using this option, the + rule will only match if the packet is going through that + interface in the specified direction (in/out). This option + is a mandatory requirement for the modernized rules + processing logic. + + When a packet is logged, the headers of the packet are + written to the IPL packet logging pseudo-device. + Immediately following the log keyword, the following + qualifiers may be used (in this order): + + body indicates that the first 128 + bytes of the packet contents will be logged after the + headers. + + first If the log + keyword is being used in conjunction with a keep + state option, it is recommended that this option is + also applied so that only the triggering packet is logged and + not every packet which thereafter matches the keep + state information. + + + + SELECTION + + The keywords described in this section are used to + describe attributes of the packet to be interrogated when + determining whether rules match or not. There is a + keyword subject, and it has sub-option keywords, one of + which has to be selected. The following general-purpose + attributes are provided for matching, and must be used in + this order: + + + + PROTO + + proto is the subject keyword and must + be coded along with one of its corresponding keyword + sub-option values. The value allows a specific protocol to + be matched against. This option is a mandatory requirement + for the modernized rules processing logic. + + tcp/udp | udp | tcp | icmp or any + protocol names found in /etc/protocols + are recognized and may be used. The special protocol keyword + tcp/udp may be used to match either a + TCP or a UDP packet, and has been added as + a convenience to save duplication of otherwise identical + rules. + + + + SRC_ADDR/DST_ADDR + + The all keyword is essentially a + synonym for from any to any with no other + match parameters. + + from src to dst: the from and to + keywords are used to match against IP addresses. Rules must + specify BOTH source and destination parameters. + any is a special keyword that matches any + IP address. Examples of use: from any to any + or from 0.0.0.0/0 to any or from any to + 0.0.0.0/0 or from 0.0.0.0 to any or + from any to 0.0.0.0. + + + + IP addresses may be specified as a dotted IP address + numeric form/mask-length, or as single dotted IP address + numeric form. + + There is no way to match ranges of IP addresses which + do not express themselves easily as mask-length. See this + web page for help on writing mask-length: . + + + + PORT + + If a port match is included, for either or both of source + and destination, then it is only applied to + TCP and UDP packets. When composing port + comparisons, either the service name from + /etc/services or an integer port number + may be used. When the port appears as part of the from + object, it matches the source port number; when it appears + as part of the to object, it matches the destination port + number. The use of the port option with the + to object is a mandatory requirement for + the modernized rules processing logic. Example of use: + from any to any port = 80 + + + + Port comparisons may be done in a number of forms, with + a number of comparison operators, or port ranges may be + specified. + + port "=" | "!=" | "<" | ">" | "<=" | ">=" | + "eq" | "ne" | "lt" | "gt" | "le" | "ge". + + To specify port ranges, port "<>" | + "><" + + + Following the source and destination matching + parameters, the following two parameters are mandatory + requirements for the modernized rules processing + logic. + + + + + <acronym>TCP</acronym>_FLAG + + Flags are only effective for TCP + filtering. The letters represents one of the possible flags + that can be interrogated in the TCP packet + header. + + The modernized rules processing logic uses the + flags S parameter to identify the tcp + session start request. + + + + STATEFUL + + keep state indicates that on a pass + rule, any packets that match the rules selection parameters + should activate the stateful filtering facility. + + + This option is a mandatory requirement for the + modernized rules processing logic. + + + + + + Stateful Filtering + + + IPFILTER + + stateful filtering + + + + + Stateful filtering treats traffic as a bi-directional + exchange of packets comprising a session conversation. When + activated, keep-state dynamically generates internal rules for + each anticipated packet being exchanged during the + bi-directional session conversation. It has the interrogation + abilities to determine if the session conversation between the + originating sender and the destination are following the valid + procedure of bi-directional packet exchange. Any packets that + do not properly fit the session conversation template are + automatically rejected as impostors. + + Keep state will also allow ICMP packets related to a + TCP or UDP session through. So if you get + ICMP type 3 code 4 in response to some web surfing allowed out + by a keep state rule, they will be automatically allowed in. + Any packet that IPF can be certain is part of an active + session, even if it is a different protocol, will be let + in. + + What happens is: + + Packets destined to go out the interface connected to the + public Internet are first checked against the dynamic state + table, if the packet matches the next expected packet + comprising in a active session conversation, then it exits the + firewall and the state of the session conversation flow is + updated in the dynamic state table, the remaining packets get + checked against the outbound rule set. + + Packets coming in to the interface connected to the public + Internet are first checked against the dynamic state table, if + the packet matches the next expected packet comprising a + active session conversation, then it exits the firewall and + the state of the session conversation flow is updated in the + dynamic state table, the remaining packets get checked against + the inbound rule set. + + When the conversation completes it is removed from the + dynamic state table. + + Stateful filtering allows you to focus on blocking/passing + new sessions. If the new session is passed, all its subsequent + packets will be allowed through automatically and any impostors + automatically rejected. If a new session is blocked, none of + its subsequent packets will be allowed through. Stateful + filtering has technically advanced interrogation abilities + capable of defending against the flood of different attack + methods currently employed by attackers. + + + + + + Inclusive Rule Set Example + + The following rule set is an example of how to code a very + secure inclusive type of firewall. An inclusive firewall only + allows services matching pass rules through and blocks all + other by default. All firewalls have at the minimum two + interfaces which have to have rules to allow the firewall to + function. + + All &unix; flavored systems including &os; are designed to + use interface lo0 and IP address + 127.0.0.1 for internal + communication within the operating system. The firewall rules + must contain rules to allow free unmolested movement of these + special internally used packets. + + The interface which faces the public Internet is the one + where you place your rules to authorize and control access out + to the public Internet and access requests arriving from the + public Internet. This can be your user PPP + tun0 interface or your NIC that is + connected to your DSL or cable modem. + + In cases where one or more NICs are cabled to private LANs + behind the firewall, those interfaces must have a rule coded to + allow free unmolested movement of packets originating from + those LAN interfaces. + + The rules should be first organized into three major + sections: all the free unmolested interfaces, the public + interface outbound, and the public interface inbound. + + The rules in each of the public interface sections should + have the most frequently matched rules placed before less + commonly matched rules, with the last rule in the section + blocking and logging all packets on that interface and + direction. + + The Outbound section in the following rule set only + contains 'pass' rules which contain selection values that + uniquely identify the service that is authorized for public + Internet access. All the rules have the 'quick', 'on', + 'proto', 'port', and 'keep state' option coded. The 'proto + tcp' rules have the 'flag' option included to identify the + session start request as the triggering packet to activate the + stateful facility. + + The Inbound section has all the blocking of undesirable + packets first, for two different reasons. The first is that + these things being blocked may be part of an otherwise valid + packet which may be allowed in by the later authorized service + rules. The second reason is that by having a rule that + explicitly blocks selected packets that I receive on an + infrequent basis and that I do not want to see in the log, they + will not be caught by the last rule in the section which blocks + and logs all packets which have fallen through the rules. The + last rule in the section which blocks and logs all packets is + how you create the legal evidence needed to prosecute the + people who are attacking your system. + + Another thing you should take note of, is there is no + response returned for any of the undesirable stuff, their + packets just get dropped and vanish. This way the attacker + has no knowledge if his packets have reached your system. The + less the attackers can learn about your system, the more + time they must invest before actually doing something bad. + The inbound 'nmap OS fingerprint' attempts rule I log + + + + the first occurrence because this is something a attacker + would do. + + Any time you see log messages on a rule with 'log first'. + You should do an ipfstat -hio command to see + the number of times the rule has been matched so you know if + you are being flooded, i.e. under attack. + + When you log packets with port numbers you do not + recognize, look it up in /etc/services or + go to + and do a port number lookup to find what the purpose of that + port number is. + + Check out this link for port numbers used by Trojans . + + The following rule set is a complete very secure + 'inclusive' type of firewall rule set that I have used on my + system. You can not go wrong using this rule set for your own. + Just comment out any pass rules for services that you do not + want to authorize. + + If you see messages in your log that you want to stop + seeing just add a block rule in the inbound section. + + You have to change the dc0 + interface name in every rule to the interface name of the Nic + card that connects your system to the public Internet. For + user PPP it would be tun0. + + Add the following statements to + /etc/ipf.rules: + + ################################################################# +# No restrictions on Inside LAN Interface for private network +# Not needed unless you have LAN +################################################################# + +#pass out quick on xl0 all +#pass in quick on xl0 all + +################################################################# +# No restrictions on Loopback Interface +################################################################# +pass in quick on lo0 all +pass out quick on lo0 all + +################################################################# +# Interface facing Public Internet (Outbound Section) +# Interrogate session start requests originating from behind the +# firewall on the private network +# or from this gateway server destine for the public Internet. +################################################################# + +# Allow out access to my ISP's Domain name server. +# xxx must be the IP address of your ISP's DNS. +# Dup these lines if your ISP has more than one DNS server +# Get the IP addresses from /etc/resolv.conf file +pass out quick on dc0 proto tcp from any to xxx port = 53 flags S keep state +pass out quick on dc0 proto udp from any to xxx port = 53 keep state + +# Allow out access to my ISP's DHCP server for cable or DSL networks. +# This rule is not needed for 'user ppp' type connection to the +# public Internet, so you can delete this whole group. +# Use the following rule and check log for IP address. +# Then put IP address in commented out rule & delete first rule +pass out log quick on dc0 proto udp from any to any port = 67 keep state +#pass out quick on dc0 proto udp from any to z.z.z.z port = 67 keep state + + +# Allow out non-secure standard www function +pass out quick on dc0 proto tcp from any to any port = 80 flags S keep state + +# Allow out secure www function https over TLS SSL +pass out quick on dc0 proto tcp from any to any port = 443 flags S keep state + +# Allow out send & get email function +pass out quick on dc0 proto tcp from any to any port = 110 flags S keep state +pass out quick on dc0 proto tcp from any to any port = 25 flags S keep state + +# Allow out Time +pass out quick on dc0 proto tcp from any to any port = 37 flags S keep state + +# Allow out nntp news +pass out quick on dc0 proto tcp from any to any port = 119 flags S keep state + +# Allow out gateway & LAN users non-secure FTP ( both passive & active modes) +# This function uses the IPNAT built in FTP proxy function coded in +# the nat rules file to make this single rule function correctly. +# If you want to use the pkg_add command to install application packages +# on your gateway system you need this rule. +pass out quick on dc0 proto tcp from any to any port = 21 flags S keep state + +# Allow out secure FTP, Telnet, and SCP +# This function is using SSH (secure shell) +pass out quick on dc0 proto tcp from any to any port = 22 flags S keep state + +# Allow out non-secure Telnet +pass out quick on dc0 proto tcp from any to any port = 23 flags S keep state + +# Allow out FBSD CVSUP function +pass out quick on dc0 proto tcp from any to any port = 5999 flags S keep state + +# Allow out ping to public Internet +pass out quick on dc0 proto icmp from any to any icmp-type 8 keep state + +# Allow out whois for LAN PC to public Internet +pass out quick on dc0 proto tcp from any to any port = 43 flags S keep state + +# Block and log only the first occurrence of everything +# else that's trying to get out. +# This rule enforces the block all by default logic. +block out log first quick on dc0 all + +################################################################# +# Interface facing Public Internet (Inbound Section) +# Interrogate packets originating from the public Internet +# destine for this gateway server or the private network. +################################################################# + +# Block all inbound traffic from non-routable or reserved address spaces +block in quick on dc0 from 192.168.0.0/16 to any #RFC 1918 private IP +block in quick on dc0 from 172.16.0.0/12 to any #RFC 1918 private IP +block in quick on dc0 from 10.0.0.0/8 to any #RFC 1918 private IP +block in quick on dc0 from 127.0.0.0/8 to any #loopback +block in quick on dc0 from 0.0.0.0/8 to any #loopback +block in quick on dc0 from 169.254.0.0/16 to any #DHCP auto-config +block in quick on dc0 from 192.0.2.0/24 to any #reserved for docs +block in quick on dc0 from 204.152.64.0/23 to any #Sun cluster interconnect +block in quick on dc0 from 224.0.0.0/3 to any #Class D & E multicast + +##### Block a bunch of different nasty things. ############ +# That I do not want to see in the log + +# Block frags +block in quick on dc0 all with frags + +# Block short tcp packets +block in quick on dc0 proto tcp all with short + +# block source routed packets +block in quick on dc0 all with opt lsrr +block in quick on dc0 all with opt ssrr + +# Block nmap OS fingerprint attempts +# Log first occurrence of these so I can get their IP address +block in log first quick on dc0 proto tcp from any to any flags FUP + +# Block anything with special options +block in quick on dc0 all with ipopts + +# Block public pings +block in quick on dc0 proto icmp all icmp-type 8 + +# Block ident +block in quick on dc0 proto tcp from any to any port = 113 + +# Block all Netbios service. 137=name, 138=datagram, 139=session +# Netbios is MS/Windows sharing services. +# Block MS/Windows hosts2 name server requests 81 +block in log first quick on dc0 proto tcp/udp from any to any port = 137 +block in log first quick on dc0 proto tcp/udp from any to any port = 138 +block in log first quick on dc0 proto tcp/udp from any to any port = 139 +block in log first quick on dc0 proto tcp/udp from any to any port = 81 + +# Allow traffic in from ISP's DHCP server. This rule must contain +# the IP address of your ISP's DHCP server as it's the only +# authorized source to send this packet type. Only necessary for +# cable or DSL configurations. This rule is not needed for +# 'user ppp' type connection to the public Internet. +# This is the same IP address you captured and +# used in the outbound section. +pass in quick on dc0 proto udp from z.z.z.z to any port = 68 keep state + +# Allow in standard www function because I have apache server +pass in quick on dc0 proto tcp from any to any port = 80 flags S keep state + +# Allow in non-secure Telnet session from public Internet +# labeled non-secure because ID/PW passed over public Internet as clear text. +# Delete this sample group if you do not have telnet server enabled. +#pass in quick on dc0 proto tcp from any to any port = 23 flags S keep state + +# Allow in secure FTP, Telnet, and SCP from public Internet +# This function is using SSH (secure shell) +pass in quick on dc0 proto tcp from any to any port = 22 flags S keep state + +# Block and log only first occurrence of all remaining traffic +# coming into the firewall. The logging of only the first +# occurrence stops a .denial of service. attack targeted +# at filling up your log file space. +# This rule enforces the block all by default logic. +block in log first quick on dc0 all +################### End of rules file ##################################### + + + + <acronym>NAT</acronym> + + NAT + + + IP masquerading + + NAT + + + + network address translation + + NAT + + + NAT stands for Network Address + Translation. To those familiar with &linux;, this concept is + called IP Masquerading; NAT and IP + Masquerading are the same thing. One of the many things the + IPF NAT function enables is the ability to + have a private Local Area Network (LAN) behind the firewall + sharing a single ISP assigned IP address on the public + Internet. + + You may ask why would someone want to do this. ISPs + normally assign a dynamic IP address to their non-commercial + users. Dynamic means that the IP address can be different each + time you dial in and log on to your ISP, or for cable and DSL + modem users when you power off and then power on your modems + you can get assigned a different IP address. This IP address + is how you are known to the public Internet. + + Now lets say you have five PCs at home and each one needs + Internet access. You would have to pay your ISP for an + individual Internet account for each PC and have five phone + lines. + + With NAT you only need a single account + with your ISP, then cable your other four PCs to a switch and + the switch to the NIC in your &os; system which is going to + service your LAN as a gateway. NAT will + automatically translate the private LAN IP address for each + separate PC on the LAN to the single public IP address as it + exits the firewall bound for the public Internet. It also does + the reverse translation for returning packets. + + NAT is most often accomplished without + the approval, or knowledge, of your ISP and in most cases is + grounds for your ISP terminating your account if found out. + Commercial users pay a lot more for their Internet connection + and usually get assigned a block of static IP address which + never change. The ISP also expects and consents to their + Commercial customers using NAT for their + internal private LANs. + + There is a special range of IP addresses reserved for + NATed private LAN IP address. According to + RFC 1918, you can use the following IP ranges for private nets + which will never be routed directly to the public + Internet: + + + + + + + + + + + + Start IP 10.0.0.0 + + - + + Ending IP 10.255.255.255 + + + + Start IP 172.16.0.0 + + - + + Ending IP 172.31.255.255 + + + + Start IP 192.168.0.0 + + - + + Ending IP 192.168.255.255 + + + + + + + + IP<acronym>NAT</acronym> + + + NAT + + and IPFILTER + + + ipnat + + NAT rules are loaded by using the + ipnat command. Typically the + NAT rules are stored in + /etc/ipnat.rules. See &man.ipnat.1; for + details. + + When changing the NAT rules after + NAT has been started, make your changes to + the file containing the NAT rules, then run ipnat command with + the flags to delete the internal in use + NAT rules and flush the contents of the + translation table of all active entries. + + To reload the NAT rules issue a command + like this: + + &prompt.root; ipnat -CF -f /etc/ipnat.rules + + To display some statistics about your + NAT, use this command: + + &prompt.root; ipnat -s + + To list the NAT table's current + mappings, use this command: + + &prompt.root; ipnat -l + + To turn verbose mode on, and display information relating + to rule processing and active rules/table entries: + + &prompt.root; ipnat -v + + + + IP<acronym>NAT</acronym> Rules + + NAT rules are very flexible and can + accomplish many different things to fit the needs of commercial + and home users. + + The rule syntax presented here has been simplified to what + is most commonly used in a non-commercial environment. For a + complete rule syntax description see the &man.ipnat.5; manual + page. + + The syntax for a NAT rule looks + something like this: + + map IF LAN_IP_RANGE -> PUBLIC_ADDRESS + + The keyword map starts the rule. + + Replace IF with the external + interface. + + The LAN_IP_RANGE is what your + internal clients use for IP Addressing, usually this is + something like 192.168.1.0/24. + + The PUBLIC_ADDRESS can either + be the external IP address or the special keyword + 0/32, which means to use the IP address + assigned to IF. + + + + How <acronym>NAT</acronym> works + + A packet arrives at the firewall from the LAN with a public + destination. It passes through the outbound filter rules, + NAT gets his turn at the packet and applies + its rules top down, first matching rule wins. + NAT tests each of its rules against the + packets interface name and source IP address. When a packets + interface name matches a NAT rule then the + [source IP address, i.e. private LAN IP address] of the packet + is checked to see if it falls within the IP address range + specified to the left of the arrow symbol on the + NAT rule. On a match the packet has its + source IP address rewritten with the public IP address + obtained by the 0/32 keyword. + NAT posts a entry in its internal + NAT table so when the packet returns from + the public Internet it can be mapped back to its original + private IP address and then passed to the filter rules for + processing. + + + + Enabling IP<acronym>NAT</acronym> + + To enable IPNAT add these statements to + /etc/rc.conf. + + To enable your machine to route traffic between + interfaces: + + gateway_enable="YES" + + To start IPNAT automatically each + time: + + ipnat_enable="YES" + + To specify where to load the IPNAT rules + from: + + ipnat_rules="/etc/ipnat.rules" + + + + <acronym>NAT</acronym> for a very large LAN + + For networks that have large numbers of PC's on the LAN or + networks with more than a single LAN, the process of funneling + all those private IP addresses into a single public IP address + becomes a resource problem that may cause problems with the + same port numbers being used many times across many + NATed LAN PC's, causing collisions. There + are two ways to relieve this resource problem. + + + Assigning Ports to Use + + + + + A normal NAT rule would look like: + + map dc0 192.168.1.0/24 -> 0/32 + + In the above rule the packet's source port is unchanged + as the packet passes through IPNAT. By + adding the portmap keyword you can tell + IPNAT to only use source ports in a range. + For example the following rule will tell + IPNAT to modify the source port to be + within that range: + + map dc0 192.168.1.0/24 -> 0/32 portmap tcp/udp 20000:60000 + + Additionally we can make things even easier by using the + auto keyword to tell + IPNAT to determine by itself which ports + are available to use: + + map dc0 192.168.1.0/24 -> 0/32 portmap tcp/udp auto + + + + Using a pool of public addresses + + In very large LANs there comes a point where there are just too + many LAN addresses to fit into a single public address. If a block + of public IP addresses is available, you can use these addresses as + a pool, and let IPNAT pick one of + the public IP addresses as packet-addresses are mapped on their way + out. + + For example, instead of mapping all packets through a single + public IP address, as in: + + map dc0 192.168.1.0/24 -> 204.134.75.1 + + A range of public IP addresses can be specified either with a + netmask: + + map dc0 192.168.1.0/24 -> 204.134.75.0/255.255.255.0 + + or using CIDR notation: + + map dc0 192.168.1.0/24 -> 204.134.75.0/24 + + + + + Port Redirection + + A very common practice is to have a web server, email + server, database server and DNS server each segregated to a + different PC on the LAN. In this case the traffic from these + servers still have to be NATed, but there + has to be some way to direct the inbound traffic to the + correct LAN PCs. IPNAT has the redirection + facilities of NAT to solve this problem. + Lets say you have your web server on LAN address 10.0.10.25 and your single public IP + address is 20.20.20.5 you would + code the rule like this: + + rdr dc0 20.20.20.5/32 port 80 -> 10.0.10.25 port 80 + + or: + + rdr dc0 0/32 port 80 -> 10.0.10.25 port 80 + + or for a LAN DNS Server on LAN address of 10.0.10.33 that needs to receive + public DNS requests: + + rdr dc0 20.20.20.5/32 port 53 -> 10.0.10.33 port 53 udp + + + + FTP and <acronym>NAT</acronym> + + FTP is a dinosaur left over from the time before the + Internet as it is known today, when research universities were + leased lined together and FTP was used to share files among + research Scientists. This was a time when data security was + not a consideration. Over the years the FTP protocol became + buried into the backbone of the emerging Internet and its + username and password being sent in clear text was never + changed to address new security concerns. FTP has two flavors, + it can run in active mode or passive mode. The difference is + in how the data channel is acquired. Passive mode is more + secure as the data channel is acquired be the ordinal ftp + session requester. For a real good explanation of FTP and the + different modes see . + + + IP<acronym>NAT</acronym> Rules + + IPNAT has a special built in FTP proxy + option which can be specified on the NAT + map rule. It can monitor all outbound packet traffic for FTP + active or passive start session requests and dynamically + create temporary filter rules containing only the port number + really in use for the data channel. This eliminates the + security risk FTP normally exposes the firewall to from + having large ranges of high order port numbers open. + + This rule will handle all the traffic for the internal + LAN: + + map dc0 10.0.10.0/29 -> 0/32 proxy port 21 ftp/tcp + + This rule handles the FTP traffic from the + gateway: + + map dc0 0.0.0.0/0 -> 0/32 proxy port 21 ftp/tcp + + This rule handles all non-FTP traffic from the internal + LAN: + + map dc0 10.0.10.0/29 -> 0/32 + + The FTP map rule goes before our regular map rule. All + packets are tested against the first rule from the top. + Matches on interface name, then private LAN source IP + address, and then is it a FTP packet. If all that matches + then the special FTP proxy creates temp filter rules to let + the FTP session packets pass in and out, in addition to also + NATing the FTP packets. All LAN packets + that are not FTP do not match the first rule and fall + through to the third rule and are tested, matching on + interface and source IP, then are + NATed. + + + + IP<acronym>NAT</acronym> FTP Filter Rules + + Only one filter rule is needed for FTP if the + NAT FTP proxy is used. + + Without the FTP Proxy you will need the following three + rules: + + # Allow out LAN PC client FTP to public Internet +# Active and passive modes +pass out quick on rl0 proto tcp from any to any port = 21 flags S keep state + +# Allow out passive mode data channel high order port numbers +pass out quick on rl0 proto tcp from any to any port > 1024 flags S keep state + +# Active mode let data channel in from FTP server +pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state + + + + FTP <acronym>NAT</acronym> Proxy Bug + + As of IPFILTER version 3.4.31 + the FTP proxy works as documented during the FTP session + until the session is told to close. When the close happens + packets returning from the remote FTP server are blocked and + logged coming in on port 21. The NAT + FTP/proxy appears to remove its temp rules prematurely, + before receiving the response from the remote FTP server + acknowledging the close. A problem report was posted to the + IPF mailing list. + + The solution is to add a filter rule to get rid of these + unwanted log messages or do nothing and ignore FTP inbound + error messages in your log. Most people do not use outbound + FTP too often. + + block in quick on rl0 proto tcp from any to any port = 21 + + + + + + IPFW + + + firewall + + IPFW + + + + This section is work in progress. The contents might + not be accurate at all times. + + + The IPFIREWALL (IPFW) is a &os; sponsored firewall software + application authored and maintained by &os; volunteer staff + members. It uses the legacy stateless rules and a legacy rule + coding technique to achieve what is referred to as Simple + Stateful logic. + + The IPFW sample rule set (found in + /etc/rc.firewall) in the standard &os; + install is rather simple and it is not expected that it used + directly without modifications. The example does not use + stateful filtering, which is beneficial in most setups, so it + will not be used as base for this section. + + The IPFW stateless rule syntax is empowered with technically + sophisticated selection capabilities which far surpasses the + knowledge level of the customary firewall installer. IPFW is + targeted at the professional user or the advanced technical + computer hobbyist who have advanced packet selection + requirements. A high degree of detailed knowledge into how + different protocols use and create their unique packet header + information is necessary before the power of the IPFW rules can + be unleashed. Providing that level of explanation is out of the + scope of this section of the handbook. + + IPFW is composed of seven components, the primary component + is the kernel firewall filter rule processor and its integrated + packet accounting facility, the logging facility, the 'divert' + rule which triggers the NAT facility, and the + advanced special purpose facilities, the dummynet traffic shaper + facilities, the 'fwd rule' forward facility, the bridge + facility, and the ipstealth facility. + + + Enabling IPFW + + + IPFW + + enabling + + + IPFW is included in the basic &os; install as a separate + run time loadable module. The system will dynamically load the + kernel module when the rc.conf statement + firewall_enable="YES" is used. You do not + need to compile IPFW into the &os; kernel unless you want + NAT function enabled. + + After rebooting your system with + firewall_enable="YES" in + rc.conf the following white highlighted + message is displayed on the screen as part of the boot + process: + + ipfw2 initialized, divert disabled, rule-based forwarding disabled, default to deny, logging disabled + + The loadable module does have logging ability + compiled in. To enable logging and set the verbose logging + limit, there is a knob you can set in + /etc/sysctl.conf by adding these + statements, logging will be enabled on future reboots: + + net.inet.ip.fw.verbose=1 +net.inet.ip.fw.verbose_limit=5 + + + + Kernel Options + + + kernel options + + IPFIREWALL + + + + kernel options + + IPFIREWALL_VERBOSE + + + + kernel options + + IPFIREWALL_VERBOSE_LIMIT + + + + IPFW + + kernel options + + + It is not a mandatory requirement that you enable IPFW by + compiling the following options into the &os; kernel unless + you need NAT function. It is presented here + as background information. + + options IPFIREWALL + + This option enables IPFW as part of the kernel + + options IPFIREWALL_VERBOSE + + Enables logging of packets that pass through IPFW and have + the 'log' keyword specified in the rule set. + + options IPFIREWALL_VERBOSE_LIMIT=5 + + Limits the number of packets logged through &man.syslogd.8; + on a per entry basis. You may wish to use this option in + hostile environments which you want to log firewall activity. + This will close a possible denial of service attack via syslog + flooding. + + + kernel options + + IPFIREWALL_DEFAULT_TO_ACCEPT + + + options IPFIREWALL_DEFAULT_TO_ACCEPT + + This option will allow everything to pass through the + firewall by default, which is a good idea when you are first + setting up your firewall. + + options IPV6FIREWALL +options IPV6FIREWALL_VERBOSE +options IPV6FIREWALL_VERBOSE_LIMIT +options IPV6FIREWALL_DEFAULT_TO_ACCEPT + + These options are exactly the same as the IPv4 options but + they are for IPv6. If you do not use IPv6 you might want to + use IPV6FIREWALL without any rules to block all IPv6 + + + kernel options + + IPDIVERT + + + options IPDIVERT + + This enables the use of NAT + functionality. + + + If you do not include IPFIREWALL_DEFAULT_TO_ACCEPT or set + your rules to allow incoming packets you will block all + packets going to and from this machine. + + + + + <filename>/etc/rc.conf</filename> Options + + If you do not have IPFW compiled into your kernel you will + need to load it with the following statement in your + /etc/rc.conf: + + firewall_enable="YES" + + To select one of the default firewall types provided by + &os;, select one by reading the + /etc/rc.firewall file and place it in + the following: + + firewall_type="open" + + Or load custom rules by setting the following variable to the + file containing them: + + firewall_script="/etc/ipfw.rules" + + Enable logging: + + firewall_logging="YES" + + + The only thing that the + firewall_logging variable will do is + setting the net.inet.ip.fw.verbose sysctl + variable to the value of 1 (see ). There is no + rc.conf variable to set log limitations, + but it can be set via sysctl variable, manually or from the + /etc/sysctl.conf file: + + net.inet.ip.fw.verbose_limit=5 + + + If your machine is acting as a gateway, i.e. providing + Network Address Translation (NAT) via &man.natd.8;, please + refer to for information + regarding the required /etc/rc.conf + options. + + + + The IPFW Command + + ipfw + + The ipfw command is the normal vehicle for making manual + single rule additions or deletions to the firewall active + internal rules while it is running. The problem with using + this method is once your system is shutdown or halted all the + rules you added or changed or deleted are lost. Writing all + your rules in a file and using that file to load the rules at + boot time, or to replace in mass the currently running firewall + rules with changes you made to the files content is the + recommended method used here. + + The ipfw command is still a very useful to display the + running firewall rules to the console screen. The IPFW + accounting facility dynamically creates a counter for each + rule that counts each packet that matches the rule. During the + process of testing a rule, listing the rule with its counter + is the one of the ways of determining if the rule is + functioning. + + To list all the rules in sequence: + + &prompt.root; ipfw list + + To list all the rules with a time stamp of when the last + time the rule was matched: + + &prompt.root; ipfw -t list + + To list the accounting information, packet count for + matched rules along with the rules themselves. The first + column is the rule number, followed by the number of outgoing + matched packets, followed by the number of incoming matched + packets, and then the rule itself. + + &prompt.root; ipfw -a list + + List the dynamic rules in addition to the static + rules: + + &prompt.root; ipfw -d list + + Also show the expired dynamic rules: + + &prompt.root; ipfw -d -e list + + Zero the counters: + + &prompt.root; ipfw zero + + Zero the counters for just rule + NUM: + + &prompt.root; ipfw zero NUM + + + + IPFW Rule Sets + + + + A rule set is a group of ipfw rules coded to allow or deny + packets based on the values contained in the packet. The + bi-directional exchange of packets between hosts comprises a + session conversation. The firewall rule set processes the + packet twice: once on its arrival from the public Internet host + and again as it leaves for its return trip back to the public + Internet host. Each tcp/ip service (i.e. telnet, www, mail, + etc.) is predefined by its protocol, and port number. This is + the basic selection criteria used to create rules which will + allow or deny services. + + + IPFW + + rule processing order + + + + + When a packet enters the firewall it is compared against + the first rule in the rule set and progress one rule at a time + moving from top to bottom of the set in ascending rule number + sequence order. When the packet matches a rule selection + parameters, the rules action field value is executed and the + search of the rule set terminates for that packet. This is + referred to as the first match wins search + method. If the packet does not match any of the rules, it gets + caught by the mandatory ipfw default rule, number 65535 which + denies all packets and discards them without any reply back to + the originating destination. + + + The search continues after count, + skipto and tee + rules. + + + The instructions contained here are based on using rules + that contain the stateful 'keep state', 'limit', 'in'/'out', + and via options. This is the basic framework for coding an + inclusive type firewall rule set. + + + + An inclusive firewall only allows services matching the + rules through. This way you can control what services can + originate behind the firewall destine for the public Internet + and also control the services which can originate from the + public Internet accessing your private network. Everything + else is denied by default design. Inclusive firewalls are + much, much more secure than exclusive firewall rule sets and + is the only rule set type covered here in. + + + When working with the firewall rules be careful, you can + end up locking your self out. + + + + Rule Syntax + + + IPFW + + rule syntax + + + The rule syntax presented here has been simplified to + what is necessary to create a standard inclusive type + firewall rule set. For a complete rule syntax description + see the &man.ipfw.8; manual page. + + Rules contain keywords: these keywords have to be coded + in a specific order from left to right on the line. Keywords + are identified in bold type. Some keywords have sub-options + which may be keywords them selves and also include more + sub-options. + + # is used to mark the start of a + comment and may appear at the end of a rule line or on its + own lines. Blank lines are ignored. + + CMD RULE_NUMBER ACTION LOGGING SELECTION + STATEFUL + + + CMD + + Each new rule has to be prefixed with + add to add the + rule to the internal table. + + + + RULE_NUMBER + + Each rule has to have a rule number to go with + it. + + + + ACTION + + A rule can be associated with one of the following + actions, which will be executed when the packet matches + the selection criterion of the rule. + + allow | accept | pass | + permit + + These all mean the same thing which is to allow packets + that match the rule to exit the firewall rule processing. + The search terminates at this rule. + + check-state + + Checks the packet against the dynamic rules table. If + a match is found, execute the action associated with the + rule which generated this dynamic rule, otherwise move to + the next rule. The check-state rule does not have + selection criterion. If no check-state rule is present in + the rule set, the dynamic rules table is checked at the + first keep-state or limit rule. + + deny | drop + + Both words mean the same thing which is to discard + packets that match this rule. The search + terminates. + + + + Logging + + log or + logamount + + When a packet matches a rule with the log keyword, a + message will be logged to syslogd with a facility name of + SECURITY. The logging only occurs if the number of + packets logged so far for that particular rule does not + exceed the logamount parameter. If no logamount is + specified, the limit is taken from the sysctl variable + net.inet.ip.fw.verbose_limit. In both cases, a value of + zero removes the logging limit. Once the limit is + reached, logging can be re-enabled by clearing the + logging counter or the packet counter for that rule, see + the ipfw reset log command. + + + Logging is done after + all other packet matching conditions have been + successfully verified, and before performing the final + action (accept, deny) on the packet. It is up to you to + decide which rules you want to enable logging on. + + + + + Selection + + The keywords described in this section are used to + describe attributes of the packet to be interrogated when + determining whether rules match the packet or not. + The following general-purpose attributes are provided for + matching, and must be used in this order: + + udp | tcp | icmp + + or any protocol names found in + /etc/protocols are recognized and may + be used. The value specified is protocol to be matched + against. This is a mandatory requirement. + + from src to dst + + The from and to keywords are used to match against IP + addresses. Rules must specify BOTH source and destination + parameters. any is a special keyword + that matches any IP address. me is a + special keyword that matches any IP address configured on + an interface in your &os; system to represent the PC the + firewall is running on (i.e. this box) as in 'from me to + any' or 'from any to me' or 'from 0.0.0.0/0 to any' or + 'from any to 0.0.0.0/0' or 'from 0.0.0.0 to any' or 'from + any to 0.0.0.0' or 'from me to 0.0.0.0'. IP addresses are + specified as a dotted IP address numeric form/mask-length, + or as single dotted IP address numeric form. This is a + mandatory requirement. See this link for help on writing + mask-lengths. + + port number + + For protocols which support port numbers (such as + TCP and UDP). It is mandatory that you + code the port number of the service you want to match + on. Service names (from + /etc/services) may be used instead of + numeric port values. + + in | out + + Matches incoming or outgoing packets, respectively. + The in and out are keywords and it is mandatory that you + code one or the other as part of your rule matching + criterion. + + via IF + + Matches packets going through the interface specified + by exact name. The via keyword causes + the interface to always be checked as part of the match + process. + + setup + + This is a mandatory keyword that identifies the session + start request for TCP packets. + + keep-state + + This is a mandatory> keyword. Upon a match, the + firewall will create a dynamic rule, whose default behavior + is to match bidirectional traffic between source and + destination IP/port using the same protocol. + + limit {src-addr | src-port | dst-addr | + dst-port} + + The firewall will only allow + N connections with the same set + of parameters as specified in the rule. One or more of + source and destination addresses and ports can be + specified. The 'limit' and 'keep-state' can not be used on + same rule. Limit provides the same stateful function as + 'keep-state' plus its own functions. + + + + + Stateful Rule Option + + + IPFW + + stateful filtering + + + + + Stateful filtering treats traffic as a bi-directional + exchange of packets comprising a session conversation. It + has the interrogation abilities to determine if the session + conversation between the originating sender and the + destination are following the valid procedure of + bi-directional packet exchange. Any packets that do not + properly fit the session conversation template are + automatically rejected as impostors. + + 'check-state' is used to identify where in the IPFW rules + set the packet is to be tested against the dynamic rules + facility. On a match the packet exits the firewall to + continue on its way and a new rule is dynamic created for + the next anticipated packet being exchanged during this + bi-directional session conversation. On a no match the + packet advances to the next rule in the rule set for + testing. + + The dynamic rules facility is vulnerable to resource + depletion from a SYN-flood attack which would open a huge + number of dynamic rules. To counter this attack, &os; + added another new option named limit. This + option is used to limit the number of simultaneous session + conversations by interrogating the rules source or + destinations fields as directed by the limit option and + using the packet's IP address found there, in a search of + the open dynamic rules counting the number of times this + rule and IP address combination occurred, if this count is + greater that the value specified on the limit option, the + packet is discarded. + + + + Logging Firewall Messages + + + IPFW + + logging + + + The benefits of logging are obvious: it provides the + ability to review after the fact the rules you activated + logging on which provides information like, what packets had + been dropped, what addresses they came from, where they were + going, giving you a significant edge in tracking down + attackers. + + Even with the logging facility enabled, IPFW will not + generate any rule logging on it's own. The firewall + administrator decides what rules in the rule set he wants + to log and adds the log verb to those rules. Normally only + deny rules are logged, like the deny rule for incoming + ICMP pings. It is very customary to + duplicate the ipfw default deny everything rule with the + log verb included as your last rule in the rule set. This + way you get to see all the packets that did not match any + of the rules in the rule set. + + Logging is a two edged sword, if you are not careful, you + can lose yourself in the over abundance of log data and fill + your disk up with growing log files. DoS attacks that fill + up disk drives is one of the oldest attacks around. These + log message are not only written to syslogd, but also are + displayed on the root console screen and soon become very + annoying. + + The IPFIREWALL_VERBOSE_LIMIT=5 + kernel option limits the number of consecutive messages + sent to the system logger syslogd, concerning the packet + matching of a given rule. When this option is enabled in + the kernel, the number of consecutive messages concerning + a particular rule is capped at the number specified. There + is nothing to be gained from 200 log messages saying the + same identical thing. For instance, five consecutive + messages concerning a particular rule would be logged to + syslogd, the remainder identical consecutive messages would + be counted and posted to the syslogd with a phrase like + this: + + last message repeated 45 times + + All logged packets messages are written by default to + /var/log/security file, which is defined + in the /etc/syslog.conf file. + + + + Building a Rule Script + + Most experienced IPFW users create a file containing the + rules and code them in a manner compatible with running them + as a script. The major benefit of doing this is the firewall + rules can be refreshed in mass without the need of rebooting + the system to activate the new rules. This method is very + convenient in testing new rules as the procedure can be + executed as many times as needed. Being a script, you can + use symbolic substitution to code frequent used values and + substitution them in multiple rules. You will see this in + the following example. + + The script syntax used here is compatible with the 'sh', + 'csh', 'tcsh' shells. Symbolic substitution fields are + prefixed with a dollar sign $. Symbolic fields do not + have the $ prefix. The value to populate the Symbolic + field must be enclosed to "double quotes". + + Start your rules file like this: + + ############### start of example ipfw rules script ############# +# +ipfw -q -f flush # Delete all rules +# Set defaults +oif="tun0" # out interface +odns="192.0.2.11" # ISP's DNS server IP address +cmd="ipfw -q add " # build rule prefix +ks="keep-state" # just too lazy to key this each time +$cmd 00500 check-state +$cmd 00502 deny all from any to any frag +$cmd 00501 deny tcp from any to any established +$cmd 00600 allow tcp from any to any 80 out via $oif setup $ks +$cmd 00610 allow tcp from any to $odns 53 out via $oif setup $ks +$cmd 00611 allow udp from any to $odns 53 out via $oif $ks +################### End of example ipfw rules script ############ + + That is all there is to it. The rules are not important + in this example, how the Symbolic substitution field are + populated and used are. + + If the above example was in + /etc/ipfw.rules file, you could reload + these rules by entering on the command line. + + &prompt.root; sh /etc/ipfw.rules + + The /etc/ipfw.rules file could be + located anywhere you want and the file could be named any + thing you would like. + + The same thing could also be accomplished by running + these commands by hand: + + &prompt.root; ipfw -q -f flush +&prompt.root; ipfw -q add check-state +&prompt.root; ipfw -q add deny all from any to any frag +&prompt.root; ipfw -q add deny tcp from any to any established +&prompt.root; ipfw -q add allow tcp from any to any 80 out via tun0 setup keep-state +&prompt.root; ipfw -q add allow tcp from any to 192.0.2.11 53 out via tun0 setup keep-state +&prompt.root; ipfw -q add 00611 allow udp from any to 192.0.2.11 53 out via tun0 keep-state + + + + Stateful Ruleset + + The following non-NATed rule set is an + example of how to code a very secure 'inclusive' type of + firewall. An inclusive firewall only allows services + matching pass rules through and blocks all other by default. + All firewalls have at the minimum two interfaces which have + to have rules to allow the firewall to function. + + All &unix; flavored operating systems, &os; included, are + designed to use interface lo0 and IP + address 127.0.0.1 for internal + communication with in the operating system. The firewall + rules must contain rules to allow free unmolested movement of + these special internally used packets. + + The interface which faces the public Internet, is the one + which you code your rules to authorize and control access out + to the public Internet and access requests arriving from the + public Internet. This can be your ppp + tun0 interface or your NIC that is + connected to your DSL or cable modem. + + In cases where one or more than one NIC are connected to + a private LANs behind the firewall, those interfaces must + have rules coded to allow free unmolested movement of + packets originating from those LAN interfaces. + + The rules should be first organized into three major + sections, all the free unmolested interfaces, public + interface outbound, and the public interface inbound. + + The order of the rules in each of the public interface + sections should be in order of the most used rules being + placed before less often used rules with the last rule in + the section being a block log all packets on that interface + and direction. + + The Outbound section in the following rule set only + contains 'allow' rules which contain selection values that + uniquely identify the service that is authorized for public + Internet access. All the rules have the, proto, port, + in/out, via and keep state option coded. The 'proto tcp' + rules have the 'setup' option included to identify the start + session request as the trigger packet to be posted to the + keep state stateful table. + + The Inbound section has all the blocking of undesirable + packets first for two different reasons. First is these + things being blocked may be part of an otherwise valid packet + which may be allowed in by the later authorized service + rules. Second reason is that by having a rule that + explicitly blocks selected packets that I receive on an + infrequent bases and do not want to see in the log, this + keeps them from being caught by the last rule in the section + which blocks and logs all packets which have fallen through + the rules. The last rule in the section which blocks and + logs all packets is how you create the legal evidence needed + to prosecute the people who are attacking your system. + + Another thing you should take note of, is there is no + response returned for any of the undesirable stuff, their + packets just get dropped and vanish. This way the attackers + has no knowledge if his packets have reached your system. + The less the attackers can learn about your system the more + secure it is. When you log packets with port numbers you do + not recognize, look the numbers up in + /etc/services/ or go to + and do a port number lookup to find what the purpose of that + port number is. Check out this link for port numbers used by + Trojans: . + + + + An Example Inclusive Ruleset + + The following non-NATed rule set is a + complete inclusive type ruleset. You can not go wrong using + this rule set for you own. Just comment out any pass rules + for services you do not want. If you see messages in your + log that you want to stop seeing just add a deny rule in the + inbound section. You have to change the 'dc0' interface name + in every rule to the interface name of the NIC that connects + your system to the public Internet. For user ppp it would be + 'tun0'. + + You will see a pattern in the usage of these + rules. + + + + All statements that are a request to start a session + to the public Internet use keep-state. + + + + All the authorized services that originate from the + public Internet have the limit option to stop + flooding. + + + + All rules use in or out to clarify direction. + + + + All rules use via interface name to specify the + interface the packet is traveling over. + + + + The following rules go into + /etc/ipfw.rules. + + ################ Start of IPFW rules file ############################### +# Flush out the list before we begin. +ipfw -q -f flush + +# Set rules command prefix +cmd="ipfw -q add" +pif="dc0" # public interface name of NIC + # facing the public Internet + +################################################################# +# No restrictions on Inside LAN Interface for private network +# Not needed unless you have LAN. +# Change xl0 to your LAN NIC interface name +################################################################# +#$cmd 00005 allow all from any to any via xl0 + +################################################################# +# No restrictions on Loopback Interface +################################################################# +$cmd 00010 allow all from any to any via lo0 + +################################################################# +# Allow the packet through if it has previous been added to the +# the "dynamic" rules table by a allow keep-state statement. +################################################################# +$cmd 00015 check-state + +################################################################# +# Interface facing Public Internet (Outbound Section) +# Interrogate session start requests originating from behind the +# firewall on the private network or from this gateway server +# destine for the public Internet. +################################################################# + +# Allow out access to my ISP's Domain name server. +# x.x.x.x must be the IP address of your ISP.s DNS +# Dup these lines if your ISP has more than one DNS server +# Get the IP addresses from /etc/resolv.conf file +$cmd 00110 allow tcp from any to x.x.x.x 53 out via $pif setup keep-state +$cmd 00111 allow udp from any to x.x.x.x 53 out via $pif keep-state + +# Allow out access to my ISP's DHCP server for cable/DSL configurations. +# This rule is not needed for .user ppp. connection to the public Internet. +# so you can delete this whole group. +# Use the following rule and check log for IP address. +# Then put IP address in commented out rule & delete first rule +$cmd 00120 allow log udp from any to any 67 out via $pif keep-state +#$cmd 00120 allow udp from any to x.x.x.x 67 out via $pif keep-state + +# Allow out non-secure standard www function +$cmd 00200 allow tcp from any to any 80 out via $pif setup keep-state + +# Allow out secure www function https over TLS SSL +$cmd 00220 allow tcp from any to any 443 out via $pif setup keep-state + +# Allow out send & get email function +$cmd 00230 allow tcp from any to any 25 out via $pif setup keep-state +$cmd 00231 allow tcp from any to any 110 out via $pif setup keep-state + +# Allow out FBSD (make install & CVSUP) functions +# Basically give user root "GOD" privileges. +$cmd 00240 allow tcp from me to any out via $pif setup keep-state uid root + +# Allow out ping +$cmd 00250 allow icmp from any to any out via $pif keep-state + +# Allow out Time +$cmd 00260 allow tcp from any to any 37 out via $pif setup keep-state + +# Allow out nntp news (i.e. news groups) +$cmd 00270 allow tcp from any to any 119 out via $pif setup keep-state + +# Allow out secure FTP, Telnet, and SCP +# This function is using SSH (secure shell) +$cmd 00280 allow tcp from any to any 22 out via $pif setup keep-state + +# Allow out whois +$cmd 00290 allow tcp from any to any 43 out via $pif setup keep-state + +# deny and log everything else that.s trying to get out. +# This rule enforces the block all by default logic. +$cmd 00299 deny log all from any to any out via $pif + +################################################################# +# Interface facing Public Internet (Inbound Section) +# Interrogate packets originating from the public Internet +# destine for this gateway server or the private network. +################################################################# + +# Deny all inbound traffic from non-routable reserved address spaces +$cmd 00300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP +$cmd 00301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP +$cmd 00302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP +$cmd 00303 deny all from 127.0.0.0/8 to any in via $pif #loopback +$cmd 00304 deny all from 0.0.0.0/8 to any in via $pif #loopback +$cmd 00305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config +$cmd 00306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs +$cmd 00307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster interconnect +$cmd 00308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast + +# Deny public pings +$cmd 00310 deny icmp from any to any in via $pif + +# Deny ident +$cmd 00315 deny tcp from any to any 113 in via $pif + +# Deny all Netbios service. 137=name, 138=datagram, 139=session +# Netbios is MS/Windows sharing services. +# Block MS/Windows hosts2 name server requests 81 +$cmd 00320 deny tcp from any to any 137 in via $pif +$cmd 00321 deny tcp from any to any 138 in via $pif +$cmd 00322 deny tcp from any to any 139 in via $pif +$cmd 00323 deny tcp from any to any 81 in via $pif + +# Deny any late arriving packets +$cmd 00330 deny all from any to any frag in via $pif + +# Deny ACK packets that did not match the dynamic rule table +$cmd 00332 deny tcp from any to any established in via $pif + +# Allow traffic in from ISP's DHCP server. This rule must contain +# the IP address of your ISP.s DHCP server as it.s the only +# authorized source to send this packet type. +# Only necessary for cable or DSL configurations. +# This rule is not needed for .user ppp. type connection to +# the public Internet. This is the same IP address you captured +# and used in the outbound section. +#$cmd 00360 allow udp from any to x.x.x.x 67 in via $pif keep-state + +# Allow in standard www function because I have apache server +$cmd 00400 allow tcp from any to me 80 in via $pif setup limit src-addr 2 + +# Allow in secure FTP, Telnet, and SCP from public Internet +$cmd 00410 allow tcp from any to me 22 in via $pif setup limit src-addr 2 + +# Allow in non-secure Telnet session from public Internet +# labeled non-secure because ID & PW are passed over public +# Internet as clear text. +# Delete this sample group if you do not have telnet server enabled. +$cmd 00420 allow tcp from any to me 23 in via $pif setup limit src-addr 2 + +# Reject & Log all incoming connections from the outside +$cmd 00499 deny log all from any to any in via $pif + +# Everything else is denied by default +# deny and log all packets that fell through to see what they are +$cmd 00999 deny log all from any to any +################ End of IPFW rules file ############################### + + + + An Example <acronym>NAT</acronym> and Stateful + Ruleset + + + NAT + + and IPFW + + + There are some additional configuration statements that + need to be enabled to activate the NAT + function of IPFW. The kernel source needs 'option divert' + statement added to the other IPFIREWALL statements compiled + into a custom kernel. + + In addition to the normal IPFW options in + /etc/rc.conf, the following are + needed. + + natd_enable="YES" # Enable NATD function +natd_interface="rl0" # interface name of public Internet NIC +natd_flags="-dynamic -m" # -m = preserve port numbers if possible + + Utilizing stateful rules with divert natd rule (Network + Address Translation) greatly complicates the rule set coding + logic. The positioning of the check-state, and 'divert natd' + rules in the rule set becomes very critical. This is no + longer a simple fall-through logic flow. A new action type + is used, called 'skipto'. To use the skipto command it is + mandatory that you number each rule so you know exactly + where the skipto rule number is you are really jumping + to. + + The following is an uncommented example of one coding + method, selected here to explain the sequence of the packet + flow through the rule sets. + + The processing flow starts with the first rule from the + top of the rule file and progress one rule at a time deeper + into the file until the end is reach or the packet being + tested to the selection criteria matches and the packet is + released out of the firewall. It is important to take notice + of the location of rule numbers 100 101, 450, 500, and 510. + These rules control the translation of the outbound and + inbound packets so their entries in the keep-state dynamic + table always register the private LAN IP address. Next + notice that all the allow and deny rules specified the + direction the packet is going (IE outbound or inbound) and + the interface. Also notice that all the start outbound + session requests all skipto rule 500 for the network address + translation. + + Lets say a LAN user uses their web browser to get a web + page. Web pages use port 80 to communicate over. So the + packet enters the firewall, It does not match 100 because it + is headed out not in. It passes rule 101 because this is the + first packet so it has not been posted to the keep-state + dynamic table yet. The packet finally comes to rule 125 a + matches. It is outbound through the NIC facing the public + Internet. The packet still has it's source IP address as a + private LAN IP address. On the match to this rule, two + actions take place. The keep-state option will post this + rule into the keep-state dynamic rules table and the + specified action is executed. The action is part of the info + posted to the dynamic table. In this case it is "skipto rule + 500". Rule 500 NATs the packet IP address + and out it goes. Remember this, this is very important. + This packet makes its way to the destination and returns and + enters the top of the rule set. This time it does match rule + 100 and has it destination IP address mapped back to its + corresponding LAN IP address. It then is processed by the + check-state rule, it's found in the table as an existing + session conversation and released to the LAN. It goes to the + LAN PC that sent it and a new packet is sent requesting + another segment of the data from the remote server. This + time it gets checked by the check-state rule and its outbound + entry is found, the associated action, 'skipto 500', is + executed. The packet jumps to rule 500 gets + NATed and released on it's way out. + + On the inbound side, everything coming in that is part + of an existing session conversation is being automatically + handled by the check-state rule and the properly placed + divert natd rules. All we have to address is denying all the + bad packets and only allowing in the authorized services. + Lets say there is a apache server running on the firewall box + and we want people on the public Internet to be able to + access the local web site. The new inbound start request + packet matches rule 100 and its IP address is mapped to LAN + IP for the firewall box. The packet is them matched against + all the nasty things we want to check for and finally matches + against rule 425. On a match two things occur. The packet + rule is posted to the keep-state dynamic table but this time + any new session requests originating from that source IP + address is limited to 2. This defends against DoS attacks of + service running on the specified port number. The action is + allow so the packet is released to the LAN. On return the + check-state rule recognizes the packet as belonging to an + existing session conversation sends it to rule 500 for + NATing and released to outbound + interface. + + Example Ruleset #1: + + #!/bin/sh +cmd="ipfw -q add" +skip="skipto 500" +pif=rl0 +ks="keep-state" +good_tcpo="22,25,37,43,53,80,443,110,119" + +ipfw -q -f flush + +$cmd 002 allow all from any to any via xl0 # exclude LAN traffic +$cmd 003 allow all from any to any via lo0 # exclude loopback traffic + +$cmd 100 divert natd ip from any to any in via $pif +$cmd 101 check-state + +# Authorized outbound packets +$cmd 120 $skip udp from any to xx.168.240.2 53 out via $pif $ks +$cmd 121 $skip udp from any to xx.168.240.5 53 out via $pif $ks +$cmd 125 $skip tcp from any to any $good_tcpo out via $pif setup $ks +$cmd 130 $skip icmp from any to any out via $pif $ks +$cmd 135 $skip udp from any to any 123 out via $pif $ks + + +# Deny all inbound traffic from non-routable reserved address spaces +$cmd 300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP +$cmd 301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP +$cmd 302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP +$cmd 303 deny all from 127.0.0.0/8 to any in via $pif #loopback +$cmd 304 deny all from 0.0.0.0/8 to any in via $pif #loopback +$cmd 305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config +$cmd 306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs +$cmd 307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster +$cmd 308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast + +# Authorized inbound packets +$cmd 400 allow udp from xx.70.207.54 to any 68 in $ks +$cmd 420 allow tcp from any to me 80 in via $pif setup limit src-addr 1 + + +$cmd 450 deny log ip from any to any + +# This is skipto location for outbound stateful rules +$cmd 500 divert natd ip from any to any out via $pif +$cmd 510 allow ip from any to any + +######################## end of rules ################## + + The following is pretty much the same as above, but uses + a self documenting coding style full of description comments + to help the inexperienced IPFW rule writer to better + understand what the rules are doing. + + Example Ruleset #2: + + #!/bin/sh +################ Start of IPFW rules file ############################### +# Flush out the list before we begin. +ipfw -q -f flush + +# Set rules command prefix +cmd="ipfw -q add" +skip="skipto 800" +pif="rl0" # public interface name of NIC + # facing the public Internet + +################################################################# +# No restrictions on Inside LAN Interface for private network +# Change xl0 to your LAN NIC interface name +################################################################# +$cmd 005 allow all from any to any via xl0 + +################################################################# +# No restrictions on Loopback Interface +################################################################# +$cmd 010 allow all from any to any via lo0 + +################################################################# +# check if packet is inbound and nat address if it is +################################################################# +$cmd 014 divert natd ip from any to any in via $pif + +################################################################# +# Allow the packet through if it has previous been added to the +# the "dynamic" rules table by a allow keep-state statement. +################################################################# +$cmd 015 check-state + +################################################################# +# Interface facing Public Internet (Outbound Section) +# Interrogate session start requests originating from behind the +# firewall on the private network or from this gateway server +# destine for the public Internet. +################################################################# + +# Allow out access to my ISP's Domain name server. +# x.x.x.x must be the IP address of your ISP's DNS +# Dup these lines if your ISP has more than one DNS server +# Get the IP addresses from /etc/resolv.conf file +$cmd 020 $skip tcp from any to x.x.x.x 53 out via $pif setup keep-state + + +# Allow out access to my ISP's DHCP server for cable/DSL configurations. +$cmd 030 $skip udp from any to x.x.x.x 67 out via $pif keep-state + +# Allow out non-secure standard www function +$cmd 040 $skip tcp from any to any 80 out via $pif setup keep-state + +# Allow out secure www function https over TLS SSL +$cmd 050 $skip tcp from any to any 443 out via $pif setup keep-state + +# Allow out send & get email function +$cmd 060 $skip tcp from any to any 25 out via $pif setup keep-state +$cmd 061 $skip tcp from any to any 110 out via $pif setup keep-state + +# Allow out FreeBSD (make install & CVSUP) functions +# Basically give user root "GOD" privileges. +$cmd 070 $skip tcp from me to any out via $pif setup keep-state uid root + +# Allow out ping +$cmd 080 $skip icmp from any to any out via $pif keep-state + +# Allow out Time +$cmd 090 $skip tcp from any to any 37 out via $pif setup keep-state + +# Allow out nntp news (i.e. news groups) +$cmd 100 $skip tcp from any to any 119 out via $pif setup keep-state + +# Allow out secure FTP, Telnet, and SCP +# This function is using SSH (secure shell) +$cmd 110 $skip tcp from any to any 22 out via $pif setup keep-state + +# Allow out whois +$cmd 120 $skip tcp from any to any 43 out via $pif setup keep-state + +# Allow ntp time server +$cmd 130 $skip udp from any to any 123 out via $pif keep-state + +################################################################# +# Interface facing Public Internet (Inbound Section) +# Interrogate packets originating from the public Internet +# destine for this gateway server or the private network. +################################################################# + +# Deny all inbound traffic from non-routable reserved address spaces +$cmd 300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP +$cmd 301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP +$cmd 302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP +$cmd 303 deny all from 127.0.0.0/8 to any in via $pif #loopback +$cmd 304 deny all from 0.0.0.0/8 to any in via $pif #loopback +$cmd 305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config +$cmd 306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs +$cmd 307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster +$cmd 308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast + +# Deny ident +$cmd 315 deny tcp from any to any 113 in via $pif + +# Deny all Netbios service. 137=name, 138=datagram, 139=session +# Netbios is MS/Windows sharing services. +# Block MS/Windows hosts2 name server requests 81 +$cmd 320 deny tcp from any to any 137 in via $pif +$cmd 321 deny tcp from any to any 138 in via $pif +$cmd 322 deny tcp from any to any 139 in via $pif +$cmd 323 deny tcp from any to any 81 in via $pif + +# Deny any late arriving packets +$cmd 330 deny all from any to any frag in via $pif + +# Deny ACK packets that did not match the dynamic rule table +$cmd 332 deny tcp from any to any established in via $pif + +# Allow traffic in from ISP's DHCP server. This rule must contain +# the IP address of your ISP's DHCP server as it's the only +# authorized source to send this packet type. +# Only necessary for cable or DSL configurations. +# This rule is not needed for 'user ppp' type connection to +# the public Internet. This is the same IP address you captured +# and used in the outbound section. +$cmd 360 allow udp from x.x.x.x to any 68 in via $pif keep-state + +# Allow in standard www function because I have Apache server +$cmd 370 allow tcp from any to me 80 in via $pif setup limit src-addr 2 + +# Allow in secure FTP, Telnet, and SCP from public Internet +$cmd 380 allow tcp from any to me 22 in via $pif setup limit src-addr 2 + +# Allow in non-secure Telnet session from public Internet +# labeled non-secure because ID & PW are passed over public +# Internet as clear text. +# Delete this sample group if you do not have telnet server enabled. +$cmd 390 allow tcp from any to me 23 in via $pif setup limit src-addr 2 + +# Reject & Log all unauthorized incoming connections from the public Internet +$cmd 400 deny log all from any to any in via $pif + +# Reject & Log all unauthorized out going connections to the public Internet +$cmd 450 deny log all from any to any out via $pif + +# This is skipto location for outbound stateful rules +$cmd 800 divert natd ip from any to any out via $pif +$cmd 801 allow ip from any to any + +# Everything else is denied by default +# deny and log all packets that fell through to see what they are +$cmd 999 deny log all from any to any +################ End of IPFW rules file ############################### + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/geom/Makefile b/pl_PL.ISO8859-2/books/handbook/geom/Makefile new file mode 100644 index 0000000000..59e5759cdc --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/geom/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= geom/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/geom/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/geom/chapter.sgml new file mode 100644 index 0000000000..ca84a765f3 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/geom/chapter.sgml @@ -0,0 +1,466 @@ + + + + + + + Tom + Rhodes + Written by + + + + + GEOM: Modular Disk Transformation Framework + + + Synopsis + + + GEOM + + + GEOM Disk Framework + GEOM + + + This chapter covers the use of disks under the GEOM + framework in &os;. This includes the major RAID + control utilities which use the framework for configuration. + This chapter will not go into in depth discussion on how GEOM + handles or controls I/O, the underlying subsystem, or code. + This information is provided through the &man.geom.4; manual + page and its various SEE ALSO references. This chapter is also + not a definitive guide to RAID + configurations. Only GEOM-supported RAID + classifications will be discussed. + + After reading this chapter, you will know: + + + + What type of RAID support is available + through GEOM. + + + + How to use the base utilities to configure, maintain, + and manipulate the various RAID + levels. + + + + How to mirror, stripe, encrypt, and remotely connect disk + devices through GEOM. + + + + How to troubleshoot disks attached to the GEOM + framework. + + + + Before reading this chapter, you should: + + + + Understand how &os; treats disk devices + (). + + Know how to configure and install a new &os; kernel + (). + + + + + + GEOM Introduction + + GEOM permits access and control to classes — Master Boot + Records, BSD labels, etc — through the + use of providers, or the special files in + /dev. Supporting various + software RAID configurations, GEOM will + transparently provide access to the operating system and + operating system utilities. + + + + + + + Tom + Rhodes + Written by + + + Murray + Stokely + + + + + RAID0 - Striping + + + GEOM + + + Striping + + + Striping is a method used to combine several disk drives into + a single volume. In many cases, this is done through the use of + hardware controllers. The GEOM disk subsystem provides + software support for RAID0, also known as + disk striping. + + In a RAID0 system, data are split up in + blocks that get written across all the drives in the array. + Instead of having to wait on the system to write 256k to one + disk, a RAID0 system can simultaneously write + 64k to each of four different disks, offering superior I/O + performance. This performance can be enhanced further by using + multiple disk controllers. + + Each disk in a RAID0 stripe must be of + the same size, since I/O requests are interleaved to read or + write to multiple disks in parallel. + + + + + + + + Disk Striping Illustration + + + + + Creating a stripe of unformatted ATA disks + + Load the geom_stripe + module: + + &prompt.root; kldload geom_stripe.ko + + + Ensure that a suitable mount point exists. If this + volume will become a root partition, then temporarily use + another mount point such as /mnt: + + &prompt.root; mkdir /mnt + + + Determine the device names for the disks which will + be striped, and create the new stripe device. For example, + the following command could be used to stripe two unused, + unpartitioned ATA disks: + /dev/ad2 and + /dev/ad3. + + &prompt.root; gstripe label -v st0 /dev/ad2 /dev/ad3 + + + + + A partition table must be created on the new volume + with the following command: + + &prompt.root; bsdlabel -wB /dev/stripe/st0 + + + + This process should have created two other devices + in the /dev/stripe + directory in addition to the st0 device. + Those include st0a and + st0c. A file system must now be created + on the st0a device using the following + newfs command: + + &prompt.root; newfs -U /dev/stripe/st0a + + Many numbers will glide across the screen, and after a few + seconds, the process will be complete. The volume has been + created and is ready to be mounted. + + + + The following command can be used to manually mount a newly + created disk stripe: + + &prompt.root; mount /dev/stripe/st0a /mnt + + To mount this striped file system automatically during the boot + process, place the volume information in + /etc/fstab file: + + &prompt.root; echo "/dev/stripe/st0a /mnt ufs rw 2 2" \ + >> /etc/fstab + + The geom_stripe module must also be automatically loaded during + system initialization, by adding a line to + /boot/loader.conf: + + &prompt.root; echo 'geom_stripe_load="YES"' >> /boot/loader.conf + + + + + RAID1 - Mirroring + + + GEOM + + + Disk Mirroring + + + Mirroring is a technology used by many corporations and home + users to back up data without interruption. When a mirror exists, + it simply means that diskB replicates diskA. Or, perhaps diskC+D + replicates diskA+B. Regardless of the disk configuration, the + important aspect is that information on one disk or partition is + being replicated. Later, that information could be more easily + restored, backed up without causing service or access + interruption, and even be physically stored in a data + safe. + + To begin, ensure the system has two disk drives of equal size, + this exercise assumes they are direct access (&man.da.4;) + SCSI disks. + + Begin by installing &os; on the first disk with only two + partitions. One should be a swap partition, double the + RAM size and all remaining space devoted to + the root (/) file system. + It is possible to have separate partitions for other mount points; + however, this will increase the difficulty level ten fold due to + manual alteration of the &man.bsdlabel.8; and &man.fdisk.8; + settings. + + Reboot and wait for the system to fully initialize. Once this + process has completed, log in as the root + user. + + Create the /dev/mirror/gm device and link + it with /dev/da1: + + &prompt.root; gmirror label -vnb round-robin gm0 /dev/da1 + + The system should respond with: + +Metadata value stored on /dev/da1. +Done. + + Initialize GEOM, this will load the + /boot/kernel/geom_mirror.ko kernel + module: + + &prompt.root; gmirror load + + + This command should have created the + gm0, device node under the + /dev/mirror + directory. + + + Install a generic fdisk label and boot code + to newly created gm0 device: + + &prompt.root; fdisk -vBI /dev/mirror/gm0 + + Now install generic bsdlabel + information: + + &prompt.root; bsdlabel -wB /dev/mirror/gm0s1 + + + If multiple slices and partitions exist, the flags for the + previous two commands will require alteration. They must match + the slice and partition size of the other disk. + + + Use the &man.newfs.8; utility to create a default file + system on the gm0s1a device node: + + &prompt.root; newfs -U /dev/mirror/gm0s1a + + This should have caused the system to spit out some + information and a bunch of numbers. This is good. Examine the + screen for any error messages and mount the device to the + /mnt mount point: + + &prompt.root; mount /dev/mirror/gm0s1a /mnt + + Now move all data from the boot disk over to this new file + system. This example uses the &man.dump.8; and &man.restore.8; + commands; however, &man.dd.1; would also work with this + scenario. + + &prompt.root; dump -L -0 -f- / |(cd /mnt && restore -r -v -f-) + + This must be done for each file system. Simply place the + appropriate file system in the correct location when running the + aforementioned command. + + Now edit the replicated /mnt/etc/fstab + file and remove or comment out the swap file + + It should be noted that commenting out the swap file entry + in fstab will most likely require you to + re-establish a different way of enabling swap space. Please + refer to for more + information. + . Change the other file system information to use the + new disk. See the following example: + + # Device Mountpoint FStype Options Dump Pass# +#/dev/da0s2b none swap sw 0 0 +/dev/mirror/gm0s1a / ufs rw 1 1 + + Now create a boot.conf file on both the + current and new root partitions. This file will + help the system BIOS + boot the correct drive: + + &prompt.root; echo "1:da(1,a)/boot/loader" > /boot.config + + &prompt.root; echo "1:da(1,a)/boot/loader" > /mnt/boot.config + + + We have placed it on both root partitions to ensure proper + boot up. If for some reason the system cannot read from the + new root partition, a failsafe is available. + + + Now add the following line to the new + /boot/loader.conf: + + &prompt.root; echo 'geom_mirror_load="YES"' >> /mnt/boot/loader.conf + + This will instruct &man.loader.8; utility to load the + geom_mirror.ko module during system + initialization. + + Reboot the system: + + &prompt.root; shutdown -r now + + If all has gone well, the system should have booted from the + gm0s1a device and a login + prompt should be waiting. If something went wrong, see review + the forthcoming troubleshooting section. Now add the + da0 disk to gm0 + device: + + &prompt.root; gmirror configure -a gm0 +&prompt.root; gmirror insert gm0 /dev/da0 + + The flag tells &man.gmirror.8; to use + automatic synchronization; i.e., mirror the disk writes + automatically. The manual page explains how to rebuild and + replace disks, although it uses data + in place of gm0. + + + Troubleshooting + + + System refuses to boot + + If the system boots up to a prompt similar to: + + ffs_mountroot: can't find rootvp +Root mount failed: 6 +mountroot> + + Reboot the machine using the power or reset button. At + the boot menu, select option six (6). This will drop the + system to a &man.loader.8; prompt. Load the kernel module + manually: + + OK? load geom_mirror.ko +OK? boot + + If this works then for whatever reason the module was not + being loaded properly. Place: + + options GEOM_MIRROR + + in the kernel configuration file, rebuild and reinstall. + That should remedy this issue. + + + + + + GEOM Gate Network Devices + + GEOM supports the remote use of devices, such as disks, + CD-ROMs, files, etc. through the use of the gate utilities. + This is similar to NFS. + + To begin, an exports file must be created. This file + specifies who is permitted to access the exported resources and + what level of access they are offered. For example, to export + the forth slice on the first SCSI disk, the + following /etc/gg.exports is more than + adequate: + + 192.168.1.0/24 RW /dev/da0s4d + + It will allow all hosts inside the private network access + the file system on the da0s4d + partition. + + To export this device, ensure it is not currently mounted, + and start the &man.ggated.8; server daemon: + + &prompt.root; ggated + + Now to mount the device on the client + machine, issue the following commands: + + &prompt.root; ggatec create -o rw 192.168.1.1 /dev/da0s4d + ggate0 + &prompt.root; mount /dev/ggate0 /mnt + + From here on, the device may be accessed through the + /mnt mount point. + + + It should be pointed out that this will fail if the device + is currently mounted on either the server machine or any other + machine on the network. + + + When the device is no longer needed, it may be safely + unmounted with the &man.umount.8; command, similar to any other + disk device. + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/install/Makefile b/pl_PL.ISO8859-2/books/handbook/install/Makefile new file mode 100644 index 0000000000..738cdb647d --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= install/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/install/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/install/chapter.sgml new file mode 100644 index 0000000000..4d3b44d9e0 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/chapter.sgml @@ -0,0 +1,5393 @@ + + + + + + + Jim + Mock + Restructured, reorganized, and parts + rewritten by + + + + + + Randy + Pratt + The sysinstall walkthrough, screenshots, and general + copy by + + + + + + Instalacja FreeBSD + + + Strzeszczenie + + installation + + FreeBSD is provided with a text-based, easy to use installation + program called sysinstall. This is the + default installation program for FreeBSD, although vendors are free to + provide their own installation suite if they wish. This chapter + describes how to use sysinstall to install + FreeBSD. + + After reading this chapter, you will know: + + + + How to create the FreeBSD installation disks. + + + + How FreeBSD refers to, and subdivides, your hard disks. + + + + How to start sysinstall. + + + + The questions sysinstall will ask + you, what they mean, and how to answer them. + + + + Before reading this chapter, you should: + + + + Read the supported hardware list that shipped with the version + of FreeBSD you are installing, and verify that your hardware is + supported. + + + + + In general, these installation instructions are written + for &i386; (PC compatible) architecture + computers. Where applicable, instructions specific to other + platforms (for example, Alpha) will be listed. Although this + guide is kept as up to date as possible, you may find minor + differences between the installer and what is shown here. It is + suggested that you use this chapter as a general guide rather + than a literal installation manual. + + + + + + Pre-installation Tasks + + + Inventory Your Computer + + Before installing FreeBSD you should attempt to inventory the + components in your computer. The FreeBSD installation routines will + show you the components (hard disks, network cards, CDROM drives, and + so forth) with their model number and manufacturer. FreeBSD will also + attempt to determine the correct configuration for these devices, + which includes information about IRQ and IO port usage. Due to the + vagaries of PC hardware this process is not always completely + successful, and you may need to correct FreeBSD's determination of + your configuration. + + If you already have another operating system installed, such as + &windows; or Linux, it is a good idea to use the facilities provided + by those operating systems to see how your hardware is already + configured. If you are not sure what settings an expansion + card is using, you may find it printed on the card itself. Popular IRQ + numbers are 3, 5, and 7, and IO port addresses are normally written as + hexadecimal numbers, such as 0x330. + + We recommend you print or write down this information before + installing FreeBSD. It may help to use a table, like this: + + + Sample Device Inventory + + + + + + + + + Device Name + + IRQ + + IO port(s) + + Notes + + + + + + First hard disk + + N/A + + N/A + + 40 GB, made by Seagate, first IDE master + + + + CDROM + + N/A + + N/A + + First IDE slave + + + + Second hard disk + + N/A + + N/A + + 20 GB, made by IBM, second IDE master + + + + First IDE controller + + 14 + + 0x1f0 + + + + + + Network card + + N/A + + N/A + + &intel; 10/100 + + + + Modem + + N/A + + N/A + + &tm.3com; 56K faxmodem, on COM1 + + + + … + + + +
+ + + + Backup Your Data + + If the computer you will be installing FreeBSD on contains + valuable data, then ensure you have it backed up, and that you have + tested the backups before installing FreeBSD. The FreeBSD + installation routine will prompt you before writing any + data to your disk, but once that process has started it cannot be + undone. + + + + Decide Where to Install FreeBSD + + If you want FreeBSD to use your entire hard disk, then there is nothing + more to concern yourself with at this point — you can skip this + section. + + However, if you need FreeBSD to co-exist with other operating + systems then you need to have a rough understanding of how data is + laid out on the disk, and how this affects you. + + + Disk Layouts for the &i386; + + A PC disk can be divided into discrete chunks. These chunks are + called partitions. By design, the PC only + supports four partitions per disk. These partitions are called + primary partitions. To work around this + limitation and allow more than four partitions, a new partition type + was created, the extended partition. A disk + may contain only one extended partition. Special partitions, called + logical partitions, can be created inside this + extended partition. + + Each partition has a partition ID, which is + a number used to identify the type of data on the partition. FreeBSD + partitions have the partition ID of 165. + + In general, each operating system that you use will identify + partitions in a particular way. For example, DOS, and its + descendants, like &windows;, assign each primary and logical partition a + drive letter, starting with + C:. + + FreeBSD must be installed into a primary partition. FreeBSD can + keep all its data, including any files that you create, on this one + partition. However, if you have multiple disks, then you can create a + FreeBSD partition on all, or some, of them. When you install FreeBSD, + you must have one partition available. This might be a blank + partition that you have prepared, or it might be an existing partition + that contains data that you no longer care about. + + If you are already using all the partitions on all your disks, then + you will have to free one of them for FreeBSD using the tools + provided by the other operating systems you use (e.g., + fdisk on DOS or &windows;). + + If you have a spare partition then you can use that. However, you + may need to shrink one or more of your existing partitions + first. + + A minimal installation of FreeBSD takes as little as 100 MB of disk + space. However, that is a very minimal install, + leaving almost no space for your own files. A more realistic minimum + is 250 MB without a graphical environment, and 350 MB or more if you + want a graphical user interface. If you intend to install a lot of + third party software as well, then you will need more space. + + You can use a commercial tool such as &partitionmagic; + to resize your partitions to make space for + FreeBSD. The tools directory on the CDROM + contains two free software tools which can carry out this task, namely + FIPS and + PResizer. Documentation for both + of these is available in the same directory. + FIPS, + PResizer, and + &partitionmagic; can resize + FAT16 and FAT32 + partitions — used in &ms-dos; through &windows; ME. + &partitionmagic; is the only one of + the above applications that can resize NTFS + partitions. + + + Incorrect use of these tools can delete the data on your disk. + Be sure that you have recent, working backups before using + them. + + + + Using an Existing Partition Unchanged + + Suppose that you have a computer with a single 4 GB disk that + already has a version of &windows; installed, and you have split the + disk into two drive letters, C: and + D:, each of which is 2 GB in size. You have + 1 GB of data on C:, and 0.5 GB of data on + D:. + + This means that your disk has two partitions on it, one per + drive letter. You can copy all your existing data from + D: to C:, which + will free up the second partition, ready for FreeBSD. + + + + Shrinking an Existing Partition + + Suppose that you have a computer with a single 4 GB disk that + already has a version of &windows; installed. When you installed + &windows; you created one large partition, giving you a + C: drive that is 4 GB in size. You are + currently using 1.5 GB of space, and want FreeBSD to have 2 GB of + space. + + In order to install FreeBSD you will need to either: + + + + Backup your &windows; data, and then reinstall &windows;, + asking for a 2 GB partition at install time. + + + + Use one of the tools such as &partitionmagic;, + described above, to shrink your &windows; + partition. + + + + + + + + Disk Layouts for the Alpha + + Alpha + + You will need a dedicated disk for FreeBSD on the + Alpha. It is not possible to share a disk with another + operating system at this time. Depending on the specific + Alpha machine you have, this disk can either be a SCSI disk + or an IDE disk, as long as your machine is capable of + booting from it. + + Following the conventions of the Digital / Compaq + manuals all SRM input is shown in uppercase. SRM is case + insensitive. + + To find the names and types of disks in your machine, use + the SHOW DEVICE command from the SRM + console prompt: + + >>>SHOW DEVICE +dka0.0.0.4.0 DKA0 TOSHIBA CD-ROM XM-57 3476 +dkc0.0.0.1009.0 DKC0 RZ1BB-BS 0658 +dkc100.1.0.1009.0 DKC100 SEAGATE ST34501W 0015 +dva0.0.0.0.1 DVA0 +ewa0.0.0.3.0 EWA0 00-00-F8-75-6D-01 +pkc0.7.0.1009.0 PKC0 SCSI Bus ID 7 5.27 +pqa0.0.0.4.0 PQA0 PCI EIDE +pqb0.0.1.4.0 PQB0 PCI EIDE + + This example is from a Digital Personal Workstation + 433au and shows three disks attached to the machine. The + first is a CDROM drive called DKA0 and + the other two are disks and are called + DKC0 and + DKC100 respectively. + + Disks with names of the form DKx + are SCSI disks. For example DKA100 + refers to a SCSI disk with SCSI target ID 1 on the first SCSI bus (A), + whereas DKC300 refers to a SCSI disk + with SCSI ID 3 on the third SCSI bus (C). Devicename + PKx refers to the SCSI host bus adapter. As + seen in the SHOW DEVICE output SCSI + CDROM drives are treated as any other SCSI hard disk drive. + + IDE disks have names similar to DQx, + while PQx is the associated IDE + controller. + + + + + + Collect Your Network Configuration Details + + If you intend to connect to a network as part of your FreeBSD + installation (for example, if you will be installing from an FTP + site or an + NFS server), then you need to know your network configuration. You + will be prompted for this information during the installation so that + FreeBSD can connect to the network to complete the install. + + + Connecting to an Ethernet Network or Cable/DSL Modem + + If you connect to an Ethernet network, or you have an Internet + connection using an Ethernet adapter via cable or DSL, then you will need the following + information: + + + + IP address + + + + IP address of the default gateway + + + + Hostname + + + + DNS server IP addresses + + + + Subnet Mask + + + + If you do not know this information, then ask your system + administrator or service provider. They may say that this + information is assigned automatically, using + DHCP. If so, make a note of this. + + + + Connecting Using a Modem + + If you dial up to an ISP using a regular modem then you can + still install FreeBSD over the Internet, it will just take a very + long time. + + You will need to know: + + + + The phone number to dial for your ISP + + + + The COM: port your modem is connected to + + + + The username and password for your ISP account + + + + + + Check for FreeBSD Errata + + Although the FreeBSD project strives to ensure that each release + of FreeBSD is as stable as possible, bugs do occasionally creep into + the process. On very rare occasions those bugs affect the + installation process. As these problems are discovered and fixed, they + are noted in the FreeBSD Errata, which is found on the FreeBSD web site. You + should check the errata before installing to make sure that there are + no late-breaking problems which you should be aware of. + + Information about all the releases, including the errata for each + release, can be found on the + release + information section of the + FreeBSD web site. + + + + Obtain the FreeBSD Installation Files + + The FreeBSD installation process can install FreeBSD from files + located in any of the following places: + + + Local Media + + + A CDROM or DVD + + + + A DOS partition on the same computer + + + + A SCSI or QIC tape + + + + Floppy disks + + + + + Network + + + An FTP site, going through a firewall, or using an HTTP proxy, + as necessary + + + + An NFS server + + + + A dedicated parallel or serial connection + + + + If you have purchased FreeBSD on CD or DVD then you already have + everything you need, and should proceed to the next section + (). + + If you have not obtained the FreeBSD installation files you should + skip ahead to which explains how + to prepare to install FreeBSD from any of the above. After reading + that section, you should come back here, and read on to + . + + + + Prepare the Boot Media + + The FreeBSD installation process is started by booting your + computer into the FreeBSD installer—it is not a program you run + within another operating system. Your computer normally boots using + the operating system installed on your hard disk, but it can also be + configured to use a bootable floppy disk. + Most modern computers can also + boot from a CDROM in the CDROM drive. + + + If you have FreeBSD on CDROM or DVD (either one you purchased + or you prepared yourself), and your computer allows you to boot from + the CDROM or DVD (typically a BIOS option called Boot + Order or similar), then you can skip this section. The + FreeBSD CDROM and DVD images are bootable and can be used to install + FreeBSD without any other special preparation. + + + To create boot floppy images, follow these steps: + + + + Acquire the Boot Floppy Images + + The boot disks are available on your installation media + in the floppies/ directory, and + can also be downloaded from the floppies directory, ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<arch>/<version>-RELEASE/floppies/. + Replace <arch> and + <version> + with the architecture and the version number + which you want to install, respectively. + For example, the boot floppy images for + &os; &rel.current;-RELEASE for &i386; are available + from . + + The floppy images have a .flp extension. + The floppies/ directory contains a number of + different images, and the ones you will need to use depends on the + version of FreeBSD you are installing, and in some cases, the + hardware you are installing to. + In most cases you will need three + floppies, boot.flp, + kern1.flp, and + kern2.flp. Check + README.TXT in the same directory for the + most up to date information about these floppy images. + + Additional device drivers may + be necessary for 5.X systems older than &os; 5.3. + These drivers are provided on the + drivers.flp image. + + + Your FTP program must use binary mode + to download these disk images. Some web browsers have been + known to use text (or + ASCII) mode, which will be apparent if you + cannot boot from the disks. + + + + + Prepare the Floppy Disks + + You must prepare one floppy disk per image file you had to + download. It is imperative that these disks are free from + defects. The easiest way to test this is to format the disks + for yourself. Do not trust pre-formatted floppies. The format + utility in &windows; will not tell about the presence of + bad blocks, it simply marks them as bad + and ignores them. It is advised that you use brand new + floppies if choosing this installation route. + + + If you try to install FreeBSD and the installation + program crashes, freezes, or otherwise misbehaves, one of + the first things to suspect is the floppies. Try writing + the floppy image files to new disks and try + again. + + + + + Write the Image Files to the Floppy Disks + + The .flp files are + not regular files you copy to the disk. + They are images of the complete contents of the + disk. This means that you cannot simply + copy files from one disk to another. + Instead, you must use specific tools to write the + images directly to the disk. + + DOS + If you are creating the floppies on a computer running + &ms-dos;/&windows;, then we provide a tool to do + this called fdimage. + + If you are using the floppies from the CDROM, and your + CDROM is the E: drive, then you would + run this: + + E:\> tools\fdimage floppies\kern.flp A: + + Repeat this command for each .flp + file, replacing the floppy disk each time, being sure to label + the disks with the name of the file that you copied to them. + Adjust the command line as necessary, depending on where you have + placed the .flp files. If you do not have + the CDROM, then fdimage can be downloaded from + the tools + directory on the FreeBSD FTP site. + + If you are writing the floppies on a &unix; system (such as + another FreeBSD system) you can use the &man.dd.1; command to + write the image files directly to disk. On FreeBSD, you would + run: + + &prompt.root; dd if=kern.flp of=/dev/fd0 + + On FreeBSD, /dev/fd0 refers to the + first floppy disk (the A: drive). + /dev/fd1 would be the + B: drive, and so on. Other &unix; + variants might have different names for the floppy disk + devices, and you will need to check the documentation for the + system as necessary. + + + + You are now ready to start installing FreeBSD. + + + + + Starting the Installation + + + By default, the installation will not make any changes to your + disk(s) until you see the following message: + + Last Chance: Are you SURE you want continue the installation? + +If you're running this on a disk with data you wish to save then WE +STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! + +We can take no responsibility for lost disk contents! + + The install can be exited at any time prior to the final + warning without changing the contents of the hard drive. If you are + concerned that you have configured something incorrectly you can just + turn the computer off before this point, and no damage will be + done. + + + + Booting + + + Booting for the &i386; + + + + Start with your computer turned off. + + + + Turn on the computer. As it starts it should display an + option to enter the system set up menu, or BIOS, commonly reached + by keys like F2, F10, + Del, or + + Alt + S + . Use whichever keystroke is indicated on screen. In + some cases your computer may display a graphic while it starts. + Typically, pressing Esc will dismiss the graphic + and allow you to see the necessary messages. + + + + Find the setting that controls which devices the system boots + from. This is usually labeled as the Boot Order + and commonly shown as a list of devices, such as + Floppy, CDROM, + First Hard Disk, and so on. + + If you needed to prepare boot floppies, then make sure that the + floppy disk is selected. If you are booting from the CDROM then + make sure that that is selected instead. In case of doubt, you + should consult the manual that came with your computer, and/or its + motherboard. + + Make the change, then save and exit. The computer should now + restart. + + + + If you needed to prepare boot floppies, as described in + , then one of them will be the + first boot disc, probably the one containing + kern.flp. Put this disc in your floppy + drive. + + If you are booting from CDROM, then you will need to turn on + the computer, and insert the CDROM at the first + opportunity. + + If your computer starts up as normal and loads your existing + operating system, then either: + + + + The disks were not inserted early enough in the boot + process. Leave them in, and try restarting your + computer. + + + + The BIOS changes earlier did not work correctly. You + should redo that step until you get the right option. + + + + Your particular BIOS does not support booting from + the desired media. + + + + + + FreeBSD will start to boot. If you are booting from CDROM you + will see a display similar to this (version information omitted): + + Verifying DMI Pool Data ........ +Boot from ATAPI CD-ROM : + 1. FD 2.88MB System Type-(00) +Uncompressing ... done + +BTX loader 1.00 BTX version is 1.01 +Console: internal video/keyboard +BIOS drive A: is disk0 +BIOS drive B: is disk1 +BIOS drive C: is disk2 +BIOS drive D: is disk3 +BIOS 639kB/261120kB available memory + +FreeBSD/i386 bootstrap loader, Revision 0.8 + +/kernel text=0x277391 data=0x3268c+0x332a8 | + +| +Hit [Enter] to boot immediately, or any other key for command prompt. +Booting [kernel] in 9 seconds... _ + + If you are booting from floppy disc, you will see a display + similar to this (version information omitted): + + Verifying DMI Pool Data ........ + +BTX loader 1.00 BTX version is 1.01 +Console: internal video/keyboard +BIOS drive A: is disk0 +BIOS drive C: is disk1 +BIOS 639kB/261120kB available memory + +FreeBSD/i386 bootstrap loader, Revision 0.8 + +/kernel text=0x277391 data=0x3268c+0x332a8 | + +Please insert MFS root floppy and press enter: + + Follow these instructions by removing the + kern.flp disc, insert the + mfsroot.flp disc, and press + Enter. &os; 5.3 + and above provide other floppy disks set, as described + in previous + section. Boot from first floppy; + when prompted, insert the other disks as required. + + + + Whether you booted from floppy or CDROM, the + boot process will then get to this point: + + Hit [Enter] to boot immediately, or any other key for command prompt. +Booting [kernel] in 9 seconds... _ + + Either wait ten seconds, or press Enter + + + + + + Booting for the Alpha + + Alpha + + + + Start with your computer turned off. + + + + Turn on the computer and wait for a boot monitor + prompt. + + + + If you needed to prepare boot floppies, as described in + then one of them will be the + first boot disc, probably the one containing + kern.flp. Put this disc in your floppy + drive and type the following command to boot the disk + (substituting the name of your floppy drive if + necessary): + + >>>BOOT DVA0 -FLAGS '' -FILE '' + + If you are booting from CDROM, insert the CDROM into + the drive and type the following command to start the + installation (substituting the name of the appropriate + CDROM drive if necessary): + + >>>BOOT DKA0 -FLAGS '' -FILE '' + + + + FreeBSD will start to boot. If you are booting from a + floppy disc, at some point you will see the message: + + Please insert MFS root floppy and press enter: + + Follow these instructions by removing the + kern.flp disc, insert the + mfsroot.flp disc, and press + Enter. + + + + Whether you booted from floppy or CDROM, the + boot process will then get to this point: + + Hit [Enter] to boot immediately, or any other key for command prompt. +Booting [kernel] in 9 seconds... _ + + Either wait ten seconds, or press Enter. This + will then launch the kernel configuration menu. + + + + + + + + + Reviewing the Device Probe Results + + The last few hundred lines that have been displayed on screen are + stored and can be reviewed. + + To review the buffer, press Scroll Lock. This + turns on scrolling in the display. You can then use the arrow keys, or + PageUp and PageDown to view the + results. Press Scroll Lock again to stop + scrolling. + + Do this now, to review the text that scrolled off the screen when + the kernel was carrying out the device probes. You will see text + similar to , although the precise + text will differ depending on the devices that you have in your + computer. + +
+ Typical Device Probe Results + + avail memory = 253050880 (247120K bytes) +Preloaded elf kernel "kernel" at 0xc0817000. +Preloaded mfs_root "/mfsroot" at 0xc0817084. +md0: Preloaded image </mfsroot> 4423680 bytes at 0xc03ddcd4 + +md1: Malloc disk +Using $PIR table, 4 entries at 0xc00fde60 +npx0: <math processor> on motherboard +npx0: INT 16 interface +pcib0: <Host to PCI bridge> on motherboard +pci0: <PCI bus> on pcib0 +pcib1:<VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0 +pci1: <PCI bus> on pcib1 +pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11 +isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0 +isa0: <iSA bus> on isab0 +atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0 +ata0: at 0x1f0 irq 14 on atapci0 +ata1: at 0x170 irq 15 on atapci0 +uhci0 <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci +0 +usb0: <VIA 83572 USB controller> on uhci0 +usb0: USB revision 1.0 +uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1 +uhub0: 2 ports with 2 removable, self powered +pci0: <unknown card> (vendor=0x1106, dev=0x3040) at 7.3 +dc0: <ADMtek AN985 10/100BaseTX> port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir +q 11 at device 8.0 on pci0 +dc0: Ethernet address: 00:04:5a:74:6b:b5 +miibus0: <MII bus> on dc0 +ukphy0: <Generic IEEE 802.3u media interface> on miibus0 +ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto +ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xec00-0xec1f irq 9 at device 10. +0 on pci0 +ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit) +isa0: too many dependant configs (8) +isa0: unexpected small tag 14 +orm0: <Option ROM> at iomem 0xc0000-0xc7fff on isa0 +fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0 +fdc0: FIFO enabled, 8 bytes threshold +fd0: <1440-KB 3.5" drive> on fdc0 drive 0 +atkbdc0: <Keyboard controller (i8042)> at port 0x60,0x64 on isa0 +atkbd0: <AT Keyboard> flags 0x1 irq1 on atkbdc0 +kbd0 at atkbd0 +psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: model Generic PS/@ mouse, device ID 0 +vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 +sc0: <System console> at flags 0x100 on isa0 +sc0: VGA <16 virtual consoles, flags=0x300> +sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 +sio0: type 16550A +sio1 at port 0x2f8-0x2ff irq 3 on isa0 +sio1: type 16550A +ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 +pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode +ppc0: FIFO with 16/16/15 bytes threshold +plip0: <PLIP network interface> on ppbus0 +ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master UDMA33 +acd0: CD-RW <LITE-ON LTR-1210B> at ata1-slave PIO4 +Mounting root from ufs:/dev/md0c +/stand/sysinstall running as init on vty0 +
+ + Check the probe results carefully to make sure that FreeBSD found + all the devices you expected. If a device was not found, then it will + not be listed. If the device's driver required configuring + with the IRQ and port address then you should check that you entered + them correctly. + + If you need to make changes to the UserConfig device probing, + it is easy to exit the sysinstall program + and start over again. It is also a good way to become more familiar + with the process. + +
+ Select Sysinstall Exit + + + + + + +
+ + Use the arrow keys to select + Exit Install from the Main + Install Screen menu. The following message will display: + + + User Confirmation Requested + Are you sure you wish to exit? The system will reboot + (be sure to remove any floppies from the drives). + + [ Yes ] No + + The install program will start again if the CDROM is left + in the drive and &gui.yes; is selected. + + If you are booting from floppies it will be necessary to remove + the mfsroot.flp floppy and replace it with + kern.flp before rebooting. + + + + + Introducing Sysinstall + + The sysinstall utility is the installation + application provided by the FreeBSD Project. It is console based and is + divided into a number of menus and screens that you can use to + configure and control the installation process. + + The sysinstall menu system is controlled + by the arrow keys, Enter, Space, and + other keys. A detailed description of these keys and what they do is + contained in sysinstall's usage + information. + + To review this information, ensure that the + Usage entry is highlighted and that the + [Select] button is selected, as shown in , then press Enter. + + The instructions for using the menu system will be displayed. After + reviewing them, press Enter to return to the Main + Menu. + +
+ Selecting Usage from Sysinstall Main Menu + + + + + + +
+ + + Selecting the Documentation Menu + + From the Main Menu, select Doc with + the arrow keys and + press Enter. + +
+ Selecting Documentation Menu + + + + + + +
+ + This will display the Documentation Menu. + +
+ Sysinstall Documentation Menu + + + + + + +
+ + It is important to read the documents provided. + + To view a document, select it with the arrow keys and + press Enter. When finished reading a document, + pressing Enter will return to the Documentation + Menu. + + To return to the Main Installation Menu, select + Exit with the + arrow keys and press Enter. + + + + Selecting the Keymap Menu + + To change the keyboard mapping, use the arrow keys to select + Keymap from the menu and press + Enter. This is only required if you are + using a non-standard or non-US keyboard. + +
+ Sysinstall Main Menu + + + + + + +
+ + A different keyboard mapping may be chosen by selecting the + menu item using up/down arrow keys and pressing Space. + Pressing Space again will unselect the item. + When finished, choose the &gui.ok; using the arrow keys and press + Enter. + + Only a partial list is shown in this screen representation. + Selecting &gui.cancel; by pressing Tab will use the default + keymap and return to the Main Install Menu. + +
+ Sysinstall Keymap Menu + + + + + + +
+ + + + + Installation Options Screen + + Select Options and press + Enter. + +
+ Sysinstall Main Menu + + + + + + +
+ +
+ Sysinstall Options + + + + + + +
+ + The default values are usually fine for most users and do + not need to be changed. The release name will vary according + to the version being installed. + + The description of the selected item will appear at the + bottom of the screen highlighted in blue. Notice that one of the + options is Use Defaults to reset all + values to startup defaults. + + Press F1 to read the help screen about the + various options. + + Pressing Q will return to the Main Install + menu. + + + + Begin a Standard Installation + + The Standard installation is the + option recommended for those new to &unix; or FreeBSD. Use the arrow + keys to select Standard and + then press Enter to start the installation. + +
+ Begin Standard Installation + + + + + + +
+ + + + + Allocating Disk Space + + Your first task is to allocate disk space for FreeBSD, and label + that space so that sysinstall can prepare + it. In order to do this you need to know how FreeBSD expects to find + information on the disk. + + + BIOS Drive Numbering + + Before you install and configure FreeBSD on your system, there is an + important subject that you should be aware of, especially if you have + multiple hard drives. + + DOS + Microsoft Windows + In a PC running a BIOS-dependent operating system such as + &ms-dos; or µsoft.windows;, the BIOS is able to abstract the + normal disk drive order, and + the operating system goes along with the change. This allows the user + to boot from a disk drive other than the so-called primary + master. This is especially convenient for some users who have + found that the simplest and cheapest way to keep a system backup is to + buy an identical second hard drive, and perform routine copies of the + first drive to the second drive using + Ghost or XCOPY + . Then, if the + first drive fails, or is attacked by a virus, or is scribbled upon by an + operating system defect, he can easily recover by instructing the BIOS + to logically swap the drives. It is like switching the cables on the + drives, but without having to open the case. + + SCSI + BIOS + More expensive systems with SCSI controllers often include BIOS + extensions which allow the SCSI drives to be re-ordered in a similar + fashion for up to seven drives. + + A user who is accustomed to taking advantage of these features may + become surprised when the results with FreeBSD are not as expected. + FreeBSD does not use the BIOS, and does not know the logical BIOS + drive mapping. This can lead to very perplexing situations, + especially when drives are physically identical in geometry, and have + also been made as data clones of one another. + + When using FreeBSD, always restore the BIOS to natural drive + numbering before installing FreeBSD, and then leave it that way. If you + need to switch drives around, then do so, but do it the hard way, and + open the case and move the jumpers and cables. + + + An Illustration from the Files of Bill and Fred's Exceptional + Adventures: + + Bill breaks-down an older Wintel box to make another FreeBSD box + for Fred. Bill installs a single SCSI drive as SCSI unit zero and + installs FreeBSD on it. + + Fred begins using the system, but after several days notices that + the older SCSI drive is reporting numerous soft errors and reports + this fact to Bill. + + After several more days, Bill decides it is time to address the + situation, so he grabs an identical SCSI drive from the disk drive + archive in the back room. An initial surface scan + indicates that + this drive is functioning well, so Bill installs this drive as SCSI + unit four and makes an image copy from drive zero to drive four. Now + that the new drive is installed and functioning nicely, Bill decides + that it is a good idea to start using it, so he uses features in the + SCSI BIOS to re-order the disk drives so that the system boots from + SCSI unit four. FreeBSD boots and runs just fine. + + Fred continues his work for several days, and soon Bill and Fred + decide that it is time for a new adventure — time to upgrade to a + newer version of FreeBSD. Bill removes SCSI unit zero because it was + a bit flaky and replaces it with another identical disk drive from + the archive. Bill then installs the new version of + FreeBSD onto the new SCSI unit zero using Fred's magic Internet FTP + floppies. The installation goes well. + + Fred uses the new version of FreeBSD for a few days, and certifies + that it is good enough for use in the engineering department. It is + time to copy all of his work from the old version. So Fred mounts + SCSI unit four (the latest copy of the older FreeBSD version). Fred + is dismayed to find that none of his precious work is present on SCSI + unit four. + + Where did the data go? + + When Bill made an image copy of the original SCSI unit zero onto + SCSI unit four, unit four became the new clone. + When Bill re-ordered the SCSI BIOS so that he could boot from + SCSI unit four, he was only fooling himself. + FreeBSD was still running on SCSI unit zero. + Making this kind of BIOS change will cause some or all of the Boot and + Loader code to be fetched from the selected BIOS drive, but when the + FreeBSD kernel drivers take-over, the BIOS drive numbering will be + ignored, and FreeBSD will transition back to normal drive numbering. + In the illustration at hand, the system continued to operate on the + original SCSI unit zero, and all of Fred's data was there, not on SCSI + unit four. The fact that the system appeared to be running on SCSI + unit four was simply an artifact of human expectations. + + We are delighted to mention that no data bytes were killed or + harmed in any way by our discovery of this phenomenon. The older SCSI + unit zero was retrieved from the bone pile, and all of Fred's work was + returned to him, (and now Bill knows that he can count as high as + zero). + + Although SCSI drives were used in this illustration, the concepts + apply equally to IDE drives. + + + + + Creating Slices Using FDisk + + + No changes you make at this point will be written to the disk. + If you think you have made a mistake and want to start again you can + use the menus to exit sysinstall and try + again or press U to use the Undo option. + If you get confused and can not see how to exit you can + always turn your computer off. + + + After choosing to begin a standard installation in + sysinstall you will be shown this + message: + + Message + In the next menu, you will need to set up a DOS-style ("fdisk") + partitioning scheme for your hard disk. If you simply wish to devote + all disk space to FreeBSD (overwriting anything else that might be on + the disk(s) selected) then use the (A)ll command to select the default + partitioning scheme followed by a (Q)uit. If you wish to allocate only + free space to FreeBSD, move to a partition marked "unused" and use the + (C)reate command. + [ OK ] + + [ Press enter or space ] + + Press Enter as instructed. You will then be + shown a list of all the hard drives that the kernel found when it + carried out the device probes. + shows an example from a + system with two IDE disks. They have been called + ad0 and ad2. + +
+ Select Drive for FDisk + + + + + + +
+ + You might be wondering why ad1 is not + listed here. Why has it been missed? + + Consider what would happen if you had two IDE hard disks, one + as the master on the first IDE controller, and one as the master on + the second IDE controller. If FreeBSD numbered these as it found + them, as ad0 and + ad1 then everything would work. + + But if you then added a third disk, as the slave device on the + first IDE controller, it would now be ad1, + and the previous ad1 would become + ad2. Because device names (such as + ad1s1a) are used to find filesystems, you + may suddenly discover that some of your filesystems no longer + appear correctly, and you would need to change your FreeBSD + configuration. + + To work around this, the kernel can be configured to name IDE + disks based on where they are, and not the order in which they were + found. With this scheme the master disk on the second IDE + controller will always be + ad2, even if there are no + ad0 or ad1 + devices. + + This configuration is the default for the FreeBSD kernel, which + is why this display shows ad0 and + ad2. The machine on which this screenshot + was taken had IDE disks on both master channels of the IDE + controllers, and no disks on the slave channels. + + You should select the disk on which you want to install FreeBSD, + and then press &gui.ok;. + FDisk will start, with a display similar to + that shown in . + + The FDisk display is broken into three + sections. + + The first section, covering the first two lines of the display, + shows details about the currently selected disk, including its FreeBSD + name, the disk geometry, and the total size of the disk. + + The second section shows the slices that are currently on the + disk, where they start and end, how large they are, the name FreeBSD + gives them, and their description and sub-type. This example shows two + small unused slices, which are artifacts of disk layout schemes on the + PC. It also shows one large FAT slice, which almost certainly appears + as C: in &ms-dos; / &windows;, and an extended + slice, which may contain other drive letters for &ms-dos; / &windows;. + + The third section shows the commands that are available in + FDisk. + +
+ Typical Fdisk Partitions before Editing + + + + + + +
+ + What you do now will depend on how you want to slice up your + disk. + + If you want to use FreeBSD for the entire disk (which will delete + all the other data on this disk when you confirm that you want + sysinstall to continue later in the + installation process) then you can press A, which + corresponds to the Use Entire Disk option. + The existing slices will be removed, and replaced with a small area + flagged as unused (again, an artifact of PC disk + layout), and then one large slice for FreeBSD. If you do this, then + you should select the newly created FreeBSD slice using the arrow + keys, and press S to mark the slice as being + bootable. The screen will then look very similar to + . Note the + A in the Flags column, which + indicates that this slice is active, and will be + booted from. + + If you will be deleting an existing slice to make space for + FreeBSD then you should select the slice using the arrow keys, and + then press D. You can then press C, + and be prompted for size of slice you want to create. Enter the + appropriate figure and press Enter. The default + value in this box represents the largest possible slice you can + make, which could be the largest contiguous block of unallocated + space or the size of the entire hard disk. + + If you have already made space for FreeBSD (perhaps by using a + tool such as &partitionmagic;) then you can + press C to create a new slice. Again, you will be + prompted for the size of slice you would like to create. + +
+ Fdisk Partition Using Entire Disk + + + + + + +
+ + When finished, press Q. Your changes will be + saved in sysinstall, but will not yet be + written to disk. + + + + Install a Boot Manager + + You now have the option to install a boot manager. In general, + you should choose to install the FreeBSD boot manager if: + + + + You have more than one drive, and have installed FreeBSD onto + a drive other than the first one. + + + + You have installed FreeBSD alongside another operating system + on the same disk, and you want to choose whether to start FreeBSD + or the other operating system when you start the computer. + + + + If FreeBSD is going to be the only operating system on + this machine, installed on the first hard disk, then the + Standard boot manager will suffice. + Choose None if you are using a + third-party boot manager capable of booting FreeBSD. + + Make your choice and press Enter. + +
+ Sysinstall Boot Manager Menu + + + + + + +
+ + The help screen, reached by pressing F1, + discusses the problems that can be encountered when trying to share + the hard disk between operating systems. + + + + Creating Slices on Another Drive + + If there is more than one drive, it will return to the + Select Drives screen after the boot manager selection. If you wish to + install FreeBSD on to more than one disk, then you can select another + disk here and repeat the slice process using + FDisk. + + + If you are installing FreeBSD on a drive other than your + first, then the FreeBSD boot manager needs to be installed on + both drives. + + +
+ Exit Select Drive + + + + + + +
+ + The Tab key toggles between the last drive + selected, &gui.ok;, and + &gui.cancel;. + + Press the Tab once to toggle to the + &gui.ok;, then + press Enter + to continue with the installation. + + + + Creating Partitions Using + <application>Disklabel</application> + + You must now create some partitions inside each slice that you + have just created. Remember that each partition is lettered, from + a through to h, and that + partitions b, c, and + d have conventional meanings that you should adhere + to. + + Certain applications can benefit from particular partition + schemes, especially if you are laying out partitions across more than + one disk. However, for this, your first FreeBSD installation, you do + not need to give too much thought to how you partition the disk. It + is more important that you install FreeBSD and start learning how to + use it. You can always re-install FreeBSD to change your partition + scheme when you are more familiar with the operating system. + + This scheme features four partitions—one for swap space, and + three for filesystems. + + + Partition Layout for First Disk + + + + + + + + + + Partition + + Filesystem + + Size + + Description + + + + + + a + + / + + 100 MB + + This is the root filesystem. Every other filesystem + will be mounted somewhere under this one. 100 MB is a + reasonable size for this filesystem. You will not be storing + too much data on it, as a regular FreeBSD install will put + about 40 MB of data here. The remaining space is for temporary + data, and also leaves expansion space if future versions of + FreeBSD need more space in /. + + + + b + + N/A + + 2-3 x RAM + + The system's swap space is kept on this partition. + Choosing the right amount of swap space can be a bit of an + art. A good rule of thumb is that your swap + space should be two or three times as much as the + available physical memory (RAM). + You should also have at least 64 MB of swap, so if you have + less than 32 MB of RAM in your computer then set the swap + amount to 64 MB. + + If you have more than one disk then you can put swap + space on each disk. FreeBSD will then use each disk for + swap, which effectively speeds up the act of swapping. In + this case, calculate the total amount of swap you need + (e.g., 128 MB), and then divide this by the number of disks + you have (e.g., two disks) to give the amount of swap you + should put on each disk, in this example, 64 MB of swap per + disk. + + + + e + + /var + + 50 MB + + The /var directory contains + files that are constantly varying; + log files, and other administrative files. Many + of these files are read-from or written-to extensively during + FreeBSD's day-to-day running. Putting these files on another + filesystem allows FreeBSD to optimize the access of these + files without affecting other files in other directories that + do not have the same access pattern. + + + + f + + /usr + + Rest of disk + + All your other files will typically be stored in + /usr and its subdirectories. + + + +
+ + If you will be installing FreeBSD on to more than one disk then + you must also create partitions in the other slices that you + configured. The easiest way to do this is to create two partitions on + each disk, one for the swap space, and one for a filesystem. + + + Partition Layout for Subsequent Disks + + + + + + + + + + Partition + + Filesystem + + Size + + Description + + + + + + b + + N/A + + See description + + As already discussed, you can split swap space across + each disk. Even though the a partition is + free, convention dictates that swap space stays on the + b partition. + + + + e + + /diskn + + Rest of disk + + The rest of the disk is taken up with one big partition. + This could easily be put on the a + partition, instead of the e partition. + However, convention says that the a + partition on a slice is reserved for the filesystem that will + be the root (/) filesystem. You do not + have to follow this convention, but + sysinstall does, so following it + yourself makes the installation slightly cleaner. You can + choose to mount this filesystem anywhere; this example + suggests that you mount them as directories + /diskn, where + n is a number that changes for each + disk. But you can use another scheme if you prefer. + + + +
+ + Having chosen your partition layout you can now create it using + sysinstall. You will see this + message: + + Message + Now, you need to create BSD partitions inside of the fdisk + partition(s) just created. If you have a reasonable amount of disk + space (200MB or more) and don't have any special requirements, simply + use the (A)uto command to allocate space automatically. If you have + more specific needs or just don't care for the layout chosen by + (A)uto, press F1 for more information on manual layout. + + [ OK ] + [ Press enter or space ] + + Press Enter to start the FreeBSD partition + editor, called Disklabel. + + shows the display when you first + start Disklabel. The display is divided in + to three sections. + + The first few lines show the name of the disk you are currently + working on, and the slice that contains the partitions you are + creating (at this point Disklabel calls + this the Partition name rather than slice name). + This display also shows the amount of free space within the slice; + that is, space that was set aside in the slice, but that has not yet + been assigned to a partition. + + The middle of the display shows the partitions that have been + created, the name of the filesystem that each partition contains, + their size, and some options pertaining to the creation of the + filesystem. + + The bottom third of the screen shows the keystrokes that are valid + in Disklabel. + +
+ Sysinstall Disklabel Editor + + + + + + +
+ + Disklabel can automatically create + partitions for you and assign them default sizes. Try this now, by + Pressing A. You will see a display similar to that + shown in . Depending on the size of + the disk you are using, the defaults may or may not be appropriate. + This does not matter, as you do not have to accept the + defaults. + + + The default partitioning assigns + the /tmp directory its own partition instead + of being part of the / partition. This + helps avoid filling the / partition with + temporary files. + + +
+ Sysinstall Disklabel Editor with Auto Defaults + + + + + + +
+ + If you choose to not use the default partitions and wish to + replace them with your + own, use the arrow keys to select the first partition, and press + D to delete it. Repeat this to delete all the + suggested partitions. + + To create the first partition (a, mounted as + / — root), make sure the proper disk slice at the top of + the screen is selected and press C. A dialog box + will appear prompting you for the size of the new partition (as shown + in ). You can enter the size as + the number of disk blocks you want to use, or as a + number followed by either M for megabytes, + G for gigabytes, or C for + cylinders. + + Beginning with FreeBSD 5.X, users can: select + UFS2 (which is default on &os; 5.1 and + above) using the Custom Newfs + (Z) option, create labels with + Auto Defaults and modify them with the Custom Newfs option or + add during the regular creation period. + Do not forget to add for SoftUpdates if you use the Custom Newfs + option! + +
+ Free Space for Root Partition + + + + + + +
+ + The default size shown will create a partition that takes up the + rest of the slice. If you are using the partition sizes described + in the earlier example, then delete the existing figure using + Backspace, and then type in + 64M, as shown in + . Then press + &gui.ok;. + +
+ Edit Root Partition Size + + + + + + +
+ + Having chosen the partition's size you will then be asked whether + this partition will contain a filesystem or swap space. The dialog + box is shown in . This first + partition will contain a filesystem, so check that + FS is selected and press + Enter. + +
+ Choose the Root Partition Type + + + + + + +
+ + Finally, because you are creating a filesystem, you must tell + Disklabel where the filesystem is to be + mounted. The dialog box is shown in + . The root filesystem's mount + point is /, so type /, and + then press Enter. + +
+ Choose the Root Mount Point + + + + + + +
+ + The display will then update to show you the newly created + partition. You should repeat this procedure for the other + partitions. When you create the swap partition, you will not be + prompted for the filesystem mount point, as swap partitions are never + mounted. When you create the final partition, + /usr, you can leave the suggested size as is, to + use the rest of the slice. + + Your final FreeBSD DiskLabel Editor screen will appear similar to + , although your values chosen may + be different. Press Q to finish. + +
+ Sysinstall Disklabel Editor + + + + + + +
+ + + + + Choosing What to Install + + + Select the Distribution Set + + Deciding which distribution set to install will depend largely + on the intended use of the system and the amount of disk space + available. The predefined options range from installing the + smallest possible configuration to everything. Those who are + new to &unix; and/or FreeBSD should almost certainly select one + of these canned options. Customizing a distribution set is + typically for the more experienced user. + + Press F1 for more information on the + distribution set options and what they contain. When finished + reviewing the help, pressing Enter will return + to the Select Distributions Menu. + + If a graphical user interface is desired then a distribution + set that is preceded by an X should be + chosen. The configuration of the X server and selection of a default + desktop must be done after the installation of &os;. More + information regarding the configuration of a X server can be + found in . + + The default version of X11 that is installed depends on the + version of FreeBSD that you are installing. For FreeBSD versions + prior to 5.3, &xfree86; 4.X is installed. For &os; 5.3 and later, + &xorg; is the default. + + If compiling a custom kernel is anticipated, select an option + which includes the source code. For more information on why a + custom kernel should be built or how to build a custom kernel, see + . + + Obviously, the most versatile system is one that includes + everything. If there is adequate disk space, select + All as shown in + by using the arrow keys and + press Enter. If there is a concern about disk + space consider using an option that is more suitable for the + situation. + Do not fret over the perfect choice, as other distributions can be + added after installation. + +
+ Choose Distributions + + + + + + +
+ + + + Installing the Ports Collection + + After selecting the desired distribution, an opportunity to + install the FreeBSD Ports Collection is presented. The ports + collection is an easy and convenient way to install software. + The Ports Collection does not contain the source code necessary + to compile the software. Instead, it is a collection of files which + automates the downloading, compiling and installation + of third-party software packages. + discusses how to use the ports + collection. + + The installation program does not check to see if you have + adequate space. Select this option only if you have + adequate hard disk space. As of FreeBSD &rel.current;, the FreeBSD + Ports Collection takes up about &ports.size; of disk space. + You can safely assume a larger value for more recent versions + of FreeBSD. + + User Confirmation Requested + Would you like to install the FreeBSD ports collection? + + This will give you ready access to over &os.numports; ported software packages, + at a cost of around &ports.size; of disk space when "clean" and possibly much + more than that if a lot of the distribution tarballs are loaded + (unless you have the extra CDs from a FreeBSD CD/DVD distribution + available and can mount it on /cdrom, in which case this is far less + of a problem). + + The Ports Collection is a very valuable resource and well worth having + on your /usr partition, so it is advisable to say Yes to this option. + + For more information on the Ports Collection & the latest ports, + visit: + http://www.FreeBSD.org/ports + + [ Yes ] No + + Select &gui.yes; with the arrow keys to + install the Ports Collection or &gui.no; to + skip this option. Press Enter to continue. + The Choose Distributions menu will redisplay. + +
+ Confirm Distributions + + + + + + +
+ + If satisfied with the options, select + Exit with the arrow keys, ensure that + &gui.ok; is highlighted, and pressing + Enter to continue. + + + + + + Choosing Your Installation Media + + If Installing from a CDROM or DVD, use the arrow keys to highlight + Install from a FreeBSD CD/DVD. Ensure + that &gui.ok; is highlighted, then press + Enter to proceed with the installation. + + For other methods of installation, select the appropriate + option and follow the instructions. + + Press F1 to display the Online Help for + installation media. Press Enter to return + to the media selection menu. + +
+ Choose Installation Media + + + + + + +
+ + + FTP Installation Modes + + + installation + network + FTP + + + There are three FTP installation modes you can choose from: + active FTP, passive FTP, or via a HTTP proxy. + + + + FTP Active: Install from an FTP + server + + + This option will make all FTP transfers + use Active + mode. This will not work through firewalls, but will + often work with older FTP servers that do not support + passive mode. If your connection hangs with passive + mode (the default), try active! + + + + + FTP Passive: Install from an FTP server through a + firewall + + + + FTP + passive mode + + + This option instructs sysinstall to use + Passive mode for all FTP operations. + This allows the user to pass through firewalls + that do not allow incoming connections on random TCP ports. + + + + + + FTP via a HTTP proxy: Install from an FTP server + through a http proxy + + + + FTP + via a HTTP proxy + + + This option instructs sysinstall to use the HTTP + protocol (like a web browser) to connect to a proxy + for all FTP operations. The proxy will translate + the requests and send them to the FTP server. + This allows the user to pass through firewalls + that do not allow FTP at all, but offer a HTTP + proxy. + In this case, you have to specify the proxy in + addition to the FTP server. + + + + + For a proxy FTP server, you should usually give the name of the + server you really want as a part of the username, after an + @ sign. The proxy server then fakes + the real server. For example, assuming you want to install from + ftp.FreeBSD.org, using the proxy FTP + server foo.example.com, listening on port + 1024. + + In this case, you go to the options menu, set the FTP username + to ftp@ftp.FreeBSD.org, and the password to your + email address. As your installation media, you specify FTP (or + passive FTP, if the proxy supports it), and the URL + ftp://foo.example.com:1234/pub/FreeBSD. + + Since /pub/FreeBSD from + ftp.FreeBSD.org is proxied under + foo.example.com, you are able to install + from that machine (which will fetch the files + from ftp.FreeBSD.org as your + installation requests them). + + + + + Committing to the Installation + + The installation can now proceed if desired. This is also + the last chance for aborting the installation to prevent changes + to the hard drive. + + User Confirmation Requested + Last Chance! Are you SURE you want to continue the installation? + + If you're running this on a disk with data you wish to save then WE + STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! + + We can take no responsibility for lost disk contents! + + [ Yes ] No + + Select &gui.yes; and press + Enter to proceed. + + The installation time will vary according to the distribution + chosen, installation media, and the speed of the computer. + There will be a series of + messages displayed indicating the status. + + The installation is complete when the following message is + displayed: + + Message + +Congratulations! You now have FreeBSD installed on your system. + +We will now move on to the final configuration questions. +For any option you do not wish to configure, simply select No. + +If you wish to re-enter this utility after the system is up, you may +do so by typing: /stand/sysinstall . + + [ OK ] + + [ Press enter to continue ] + + Press Enter to proceed with post-installation + configurations. + + Selecting &gui.no; and pressing + Enter will abort + the installation so no changes will be made to your system. The + following message will appear: + + Message +Installation complete with some errors. You may wish to scroll +through the debugging messages on VTY1 with the scroll-lock feature. +You can also choose "No" at the next prompt and go back into the +installation menus to retry whichever operations have failed. + + [ OK ] + + This message is generated because nothing was installed. + Pressing Enter will return to the + Main Installation Menu to exit the installation. + + + + Post-installation + + Configuration of various options follows the successful + installation. An option can be configured by re-entering the + configuration options before booting the new FreeBSD + system or after installation using + sysinstall (/stand/sysinstall + in &os; versions older than 5.2) and selecting + Configure. + + + Network Device Configuration + + If you previously configured PPP for an FTP install, this screen + will not display and can be configured later as described + above. + + For detailed information on Local Area Networks and + configuring FreeBSD as a gateway/router refer to the + Advanced Networking + chapter. + + User Confirmation Requested + Would you like to configure any Ethernet or SLIP/PPP network devices? + + [ Yes ] No + + To configure a network device, select + &gui.yes; and press Enter. + Otherwise, select &gui.no; to continue. + +
+ Selecting an Ethernet Device + + + + + + +
+ + Select the interface to be configured with the arrow keys and press + Enter. + + User Confirmation Requested + Do you want to try IPv6 configuration of the interface? + + Yes [ No ] + + In this private local area network, the current Internet + type protocol (IPv4) was sufficient and &gui.no; + was selected with the arrow keys and Enter + pressed. + + If you are connected to an existing IPv6 network + with an RA server, then choose + &gui.yes; and press Enter. + It will take several seconds to scan for RA servers. + + User Confirmation Requested + Do you want to try DHCP configuration of the interface? + + Yes [ No ] + + If DHCP (Dynamic Host Configuration Protocol) is not required + select &gui.no; with the arrow keys and press + Enter. + + Selecting &gui.yes; will execute + dhclient, and if successful, will fill + in the network configuration information automatically. Refer to + for more information. + + The following Network Configuration screen shows the + configuration of the Ethernet device for a system that will act + as the gateway for a Local Area Network. + +
+ Set Network Configuration for ed0 + + + + + + +
+ + Use Tab to select the information fields and + fill in appropriate information: + + + + Host + + + The fully-qualified hostname, such as k6-2.example.com in + this case. + + + + + Domain + + + The name of the domain that your machine is + in, such as example.com for this case. + + + + + IPv4 Gateway + + + IP address of host forwarding packets to non-local + destinations. You must fill this in if the machine is a node + on the network. Leave this field blank + if the machine is the gateway to the Internet for the + network. The IPv4 Gateway is also known as the default + gateway or default route. + + + + + Name server + + + IP address of your local DNS server. There is no local + DNS server on this private local area network so the IP + address of the provider's DNS server + (208.163.10.2) was used. + + + + + IPv4 address + + + The IP address to be used for this interface was + 192.168.0.1 + + + + + Netmask + + + The address block being used for this local area + network is a Class C block + (192.168.0.0 - + 192.168.255.255). + The default netmask is for a Class C network + (255.255.255.0). + + + + + Extra options to ifconfig + + + Any interface-specific options to ifconfig + you would like to add. There were none in this case. + + + + + + Use Tab to select &gui.ok; + when finished and press Enter. + + + User Confirmation Requested + Would you like to Bring Up the ed0 interface right now? + + [ Yes ] No + + Choosing &gui.yes; and pressing + Enter will bring + the machine up on the network and be ready for use. However, + this does not accomplish much during installation, since + the machine still needs to be rebooted. + + + + Configure Gateway + + User Confirmation Requested + Do you want this machine to function as a network gateway? + + [ Yes ] No + + If the machine will be acting as the gateway for a local area + network and forwarding packets between other machines then select + &gui.yes; and press Enter. + If the machine is a node on a network then + select &gui.no; and press + Enter to continue. + + + + Configure Internet Services + + User Confirmation Requested +Do you want to configure inetd and the network services that it provides? + + Yes [ No ] + + If &gui.no; is selected, various services + such telnetd will not be enabled. This + means that remote users will not be able to + telnet into this machine. Local users + will be still be able to access remote machines with + telnet. + + These services can be enabled after installation by editing + /etc/inetd.conf with your favorite text editor. + See for more information. + + Select &gui.yes; if you wish to + configure these services during install. An additional + confirmation will display: + + User Confirmation Requested +The Internet Super Server (inetd) allows a number of simple Internet +services to be enabled, including finger, ftp and telnetd. Enabling +these services may increase risk of security problems by increasing +the exposure of your system. + +With this in mind, do you wish to enable inetd? + + [ Yes ] No + + Select &gui.yes; to continue. + + User Confirmation Requested +inetd(8) relies on its configuration file, /etc/inetd.conf, to determine +which of its Internet services will be available. The default FreeBSD +inetd.conf(5) leaves all services disabled by default, so they must be +specifically enabled in the configuration file before they will +function, even once inetd(8) is enabled. Note that services for +IPv6 must be separately enabled from IPv4 services. + +Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to +use the current settings. + + [ Yes ] No + + Selecting &gui.yes; will allow adding + services by deleting the # at the beginning + of a line. + +
+ Editing <filename>inetd.conf</filename> + + + + + + +
+ + After adding the desired services, pressing Esc + will display a menu which will allow exiting and saving + the changes. + + + + + Anonymous FTP + + + FTP + anonymous + + + User Confirmation Requested + Do you want to have anonymous FTP access to this machine? + + Yes [ No ] + + + Deny Anonymous FTP + + Selecting the default &gui.no; and pressing + Enter will still allow users who have accounts + with passwords to use FTP to access the machine. + + + + Allow Anonymous FTP + + Anyone can access your machine if you elect to allow + anonymous FTP connections. The security implications should be + considered before enabling this option. For more information + about security see . + + To allow anonymous FTP, use the arrow keys to select + &gui.yes; and press Enter. + The following screen (or similar) will display: + +
+ Default Anonymous FTP Configuration + + + + + + +
+ + Pressing F1 will display the help: + + This screen allows you to configure the anonymous FTP user. + +The following configuration values are editable: + +UID: The user ID you wish to assign to the anonymous FTP user. + All files uploaded will be owned by this ID. + +Group: Which group you wish the anonymous FTP user to be in. + +Comment: String describing this user in /etc/passwd + + +FTP Root Directory: + + Where files available for anonymous FTP will be kept. + +Upload subdirectory: + + Where files uploaded by anonymous FTP users will go. + + The ftp root directory will be put in /var + by default. If you do not have enough room there for the + anticipated FTP needs, the /usr directory + could be used by setting the FTP Root Directory to + /usr/ftp. + + When you are satisfied with the values, press + Enter to continue. + + User Confirmation Requested + Create a welcome message file for anonymous FTP users? + + [ Yes ] No + + If you select &gui.yes; and press + Enter, an editor will automatically start + allowing you to edit the message. + +
+ Edit the FTP Welcome Message + + + + + + +
+ + This is a text editor called ee. Use the + instructions to change the message or change the message later + using a text editor of your choice. Note the file name/location + at the bottom of the editor screen. + + Press Esc and a pop-up menu will default + to a) leave editor. Press + Enter to exit and continue. Press + Enter again to save changes if you made + any. + + + + + Configure Network File System + + Network File System (NFS) allows sharing of files across a + network. A machine can be configured as a server, a client, or + both. Refer to for a more information. + + + NFS Server + + User Confirmation Requested + Do you want to configure this machine as an NFS server? + + Yes [ No ] + + If there is no need for a Network File System server, + select &gui.no; and press + Enter. + + If &gui.yes; is chosen, a message will + pop-up indicating that the exports file must be + created. + + Message +Operating as an NFS server means that you must first configure an +/etc/exports file to indicate which hosts are allowed certain kinds of +access to your local filesystems. +Press [Enter] now to invoke an editor on /etc/exports + [ OK ] + + Press Enter to continue. A text editor will + start allowing the exports file to be created + and edited. + +
+ Editing <filename>exports</filename> + + + + + + +
+ + Use the instructions to add the actual exported filesystems + now or later using a text editor of your choice. Note the + file name/location at the bottom of the editor screen. + + Press Esc and a pop-up menu will default to + a) leave editor. Press + Enter to exit and continue. + + + + NFS Client + + The NFS client allows your machine to access NFS servers. + + User Confirmation Requested + Do you want to configure this machine as an NFS client? + + Yes [ No ] + + With the arrow keys, select &gui.yes; + or &gui.no; as appropriate and + press Enter. + + + + + Security Profile + + 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 Profiles + + + + + + + Extreme + + Moderate + + + + + + + &man.sendmail.8; + + NO + + YES + + + + &man.sshd.8; + + NO + + YES + + + + &man.portmap.8; + + NO + + MAYBE + + The portmapper is enabled if the machine has + been configured as an NFS client or server earlier + in the installation. + + + + + + NFS server + + NO + + YES + + + + &man.securelevel.8; + + YES + + If you choose a security profile that sets the + securelevel to 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 + + + +
+ + User Confirmation Requested + Do you want to select a default security profile for this host (select + No for "medium" security)? + + [ Yes ] No + + Selecting &gui.no; and pressing + Enter will set the security profile to medium. + + Selecting &gui.yes; and pressing + Enter will allow selecting a different security + profile. + +
+ Security Profile Options + + + + + + +
+ + Press F1 to display the help. Press + Enter to return to selection menu. + + Use the arrow keys to choose Medium + unless your are sure that another level is required for your needs. + With &gui.ok; highlighted, press + Enter. + + An appropriate confirmation message will display depending on + which security setting was chosen. + + Message + +Moderate security settings have been selected. + +Sendmail and SSHd have been enabled, securelevels are +disabled, and NFS server setting have been left intact. +PLEASE NOTE that this still does not save you from having +to properly secure your system in other ways or exercise +due diligence in your administration, this simply picks +a standard set of out-of-box defaults to start with. + +To change any of these settings later, edit /etc/rc.conf + + [OK] + + Message + +Extreme security settings have been selected. + +Sendmail, SSHd, and NFS services have been disabled, and +securelevels have been enabled. +PLEASE NOTE that this still does not save you from having +to properly secure your system in other ways or exercise +due diligence in your administration, this simply picks +a more secure set of out-of-box defaults to start with. + +To change any of these settings later, edit /etc/rc.conf + + [OK] + + Press Enter to continue with the + post-installation configuration. + + + 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. + + + + + + System Console Settings + + There are several options available to customize the system + console. + + User Confirmation Requested + Would you like to customize your system console settings? + + [ Yes ] No + + To view and configure the options, select + &gui.yes; and press + Enter. + +
+ System Console Configuration Options + + + + + + +
+ + A commonly used option is the screen saver. Use the arrow keys + to select Saver and then press + Enter. + +
+ Screen Saver Options + + + + + + +
+ + Select the desired screen saver using the arrow keys + and then press Enter. The System Console + Configuration menu will redisplay. + + The default time interval is 300 seconds. To change the time + interval, select Saver again. At the + Screen Saver Options menu, select Timeout + using the arrow keys and press Enter. A pop-up + menu will appear: + +
+ Screen Saver Timeout + + + + + + +
+ + The value can be changed, then select &gui.ok; + and press Enter to return to the System Console + Configuration menu. + +
+ System Console Configuration Exit + + + + + + +
+ + Selecting Exit and pressing + Enter will continue with the post-installation + configurations. + + + + Setting the Time Zone + + Setting the time zone for your machine will allow it to + automatically correct for any regional time changes and perform + other time zone related functions properly. + + The example shown is for a machine located in the Eastern + time zone of the United States. Your selections will vary according + to your geographical location. + + User Confirmation Requested + Would you like to set this machine's time zone now? + + [ Yes ] No + + Select &gui.yes; and press + Enter to set the time zone. + + User Confirmation Requested + Is this machine's CMOS clock set to UTC? If it is set to local time + or you don't know, please choose NO here! + + Yes [ No ] + + Select &gui.yes; + or &gui.no; according to how the machine's + clock is configured and press Enter. + +
+ Select Your Region + + + + + + +
+ + The appropriate region is selected using the arrow keys + and then pressing Enter. + +
+ Select Your Country + + + + + + +
+ + Select the appropriate country using the arrow keys + and press Enter. + +
+ Select Your Time Zone + + + + + + +
+ + The appropriate time zone is selected using the arrow + keys and pressing Enter. + + Confirmation + Does the abbreviation 'EDT' look reasonable? + + [ Yes ] No + + Confirm the abbreviation for the time zone is correct. + If it looks okay, press Enter to continue with + the post-installation configuration. + + + + Linux Compatibility + + User Confirmation Requested + Would you like to enable Linux binary compatibility? + + [ Yes ] No + + Selecting &gui.yes; and pressing + Enter will allow + running Linux software on FreeBSD. The install will add + the appropriate packages for Linux compatibility. + + If installing by FTP, the machine will need to be connected to + the Internet. Sometimes a remote ftp site will not have all the + distributions like the Linux binary compatibility. This can + be installed later if necessary. + + + + Mouse Settings + + This option will allow you to cut and paste text in the + console and user programs with a 3-button mouse. If using a 2-button + mouse, refer to manual page, &man.moused.8;, after installation for + details on emulating the 3-button style. This example depicts a + non-USB mouse configuration (such as a PS/2 or COM port mouse): + + User Confirmation Requested + Does this system have a non-USB mouse attached to it? + + [ Yes ] No + + Select &gui.yes; for a non-USB mouse or + &gui.no; for a USB mouse and press + Enter. + +
+ Select Mouse Protocol Type + + + + + + +
+ + Use the arrow keys to select Type and + press Enter. + +
+ Set Mouse Protocol + + + + + + +
+ + The mouse used in this example is a PS/2 type, so the default + Auto was appropriate. To change protocol, + use the arrow keys to select another option. Ensure that &gui.ok; is + highlighted and press Enter to exit this menu. + +
+ Configure Mouse Port + + + + + + +
+ + Use the arrow keys to select Port and + press Enter. + +
+ Setting the Mouse Port + + + + + + +
+ + This system had a PS/2 mouse, so the default + PS/2 was appropriate. To change the port, + use the arrow keys and then press Enter. + +
+ Enable the Mouse Daemon + + + + + + +
+ + Last, use the arrow keys to select + Enable, and press + Enter to enable and test the mouse + daemon. + + +
+ Test the Mouse Daemon + + + + + + +
+ + Move the mouse around the screen and verify the cursor + shown responds properly. If it does, select + &gui.yes; and press Enter. If + not, the mouse has not been configured correctly — select + &gui.no; and try using different configuration + options. + + Select Exit with the arrow keys + and press Enter to return to continue with the + post-installation configuration. + + + + + + + Tom + Rhodes + Contributed by + + + + Configure Additional Network Services + + Configuring network services can be a daunting + task for new users if they lack previous + knowledge in this area. Networking, including the Internet, + is critical to all modern operating systems including &os;; + as a result, it is very useful to have some understanding + &os;'s extensive networking capabilities. Doing this + during the installation will ensure users have some + understanding of the various services available to them. + + Network services are programs that accept input from + anywhere on the network. Every effort is made to make sure + these programs will not do anything harmful. + Unfortunately, programmers are not perfect and through time + there have been cases where bugs in network services have been + exploited by attackers to do bad things. It is important that + you only enable the network services you know that you need. If + in doubt it is best if you do not enable a network service until + you find out that you do need it. You can always enable it + later by re-running sysinstall or by + using the features provided by the + /etc/rc.conf file. + + Selecting the Networking option will display + a menu similar to the one below: + +
+ Network Configuration Upper-level + + + + + + +
+ + The first option, Interfaces, was previously covered during + the , thus this option can + safely be ignored. + + Selecting the AMD option adds + support for the BSD automatic mount utility. + This is usually used in conjunction with the + NFS protocol (see below) + for automatically mounting remote file systems. + No special configuration is required here. + + Next in line is the AMD Flags + option. When selected, a menu will pop up for you + to enter specific AMD flags. + The menu already contains a set of default options: + + -a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map + + The option sets the default mount + location which is specified here as + /.amd_mnt. The + option specifies the default log file; + however, when syslogd is used all log + activity will be sent to the system log daemon. The + /host directory is used + to mount an exported file system from a remote + host, while /net + directory is used to mount an exported file system from an + IP address. The + /etc/amd.map file defines the default + options for AMD exports. + + + FTP + anonymous + + + The Anon FTP option permits anonymous + FTP connections. Select this option to + make this machine an anonymous FTP server. + Be aware of the security risks involved with this option. + Another menu will be displayed to explain the security risks + and configuration in depth. + + The Gateway configuration menu will set + the machine up to be a gateway as explained previously. This + can be used to unset the Gateway option if you accidentally + selected it during the installation process. + + The Inetd option can be used to configure + or completely disable the &man.inetd.8; daemon as discussed + above. + + The Mail option is used to configure the system's + default MTA or Mail Transfer Agent. + Selecting this option will bring up the following menu: + +
+ Select a default MTA + + + + + + +
+ + Here you are offered a choice as to which + MTA to install + and set as the default. An MTA is nothing + more than a mail server which delivers email to users on the + system or the Internet. + + Selecting Sendmail will install + the popular sendmail server which + is the &os; default. The Sendmail local option + will set sendmail to be the default + MTA, but disable its ability to receive + incoming email from the Internet. The other options here, + Postfix and + Exim act similar to + Sendmail. They both deliver + email; however, some users prefer these alternatives to the + sendmail + MTA. + + After selecting an MTA, or choosing + not to select an MTA, the network configuration menu will appear + with the next option being NFS client. + + The NFS client option will + configure the system to communicate with a server via + NFS. An NFS server + makes file systems available to other machines on the + network via the NFS protocol. If this is + a stand alone machine, this option can remain unselected. + The system may require more configuration later; see + for more + information about client and server configuration. + + Below that option is the NFS server + option, permitting you to set the system up as an + NFS server. This adds the required + information to start up the RPC remote + procedure call services. RPC is used to + coordinate connections between hosts and programs. + + Next in line is the Ntpdate option, + which deals with time synchronization. When selected, a menu + like the one below shows up: + +
+ Ntpdate Configuration + + + + + + +
+ + From this menu, select the server which is the closest + to your location. Selecting a close one will make the time + synchronization more accurate as a server further from your + location may have more connection latency. + + The next option is the PCNFSD selection. + This option will install the + net/pcnfsd package from + the Ports Collection. This is a useful utility which provides + NFS authentication services for systems which + are unable to provide their own, such as Microsoft's + &ms-dos; operating system. + + Now you must scroll down a bit to see the other + options: + +
+ Network Configuration Lower-level + + + + + + +
+ + The &man.rpcbind.8;, &man.rpc.statd.8;, and + &man.rpc.lockd.8; utilities are all used for Remote Procedure + Calls (RPC). + The rpcbind utility manages communication + between NFS servers and clients, and is + required for NFS servers to operate + correctly. The rpc.statd daemon interacts + with the rpc.statd daemon on other hosts to + provide status monitoring. The reported status is usually held + in the /var/db/statd.status file. The + next option listed here is the rpc.lockd + option, which, when selected, will provide file locking + services. This is usually used with + rpc.statd to monitor what hosts are + requesting locks and how frequently they request them. + While these last two options are marvelous for debugging, they + are not required for NFS servers and clients + to operate correctly. + + As you progress down the list the next item here is + Routed, which is the routing daemon. The + &man.routed.8; utility manages network routing tables, + discovers multicast routers, and supplies a copy of the routing + tables to any physically connected host on the network upon + request. This is mainly used for machines which act as a + gateway for the local network. When selected, a menu will be + presented requesting the default location of the utility. + The default location is already defined for you and can be + selected with the Enter key. You will then + be presented with yet another menu, this time asking for the + flags you wish to pass on to routed. The + default is and it should already appear + on the screen. + + Next in line is the Rwhod option which, + when selected, will start the &man.rwhod.8; daemon + during system initialization. The rwhod + utility broadcasts system messages across the network + periodically, or collects them when in consumer + mode. More information can be found in the &man.ruptime.1; and + &man.rwho.1; manual pages. + + The next to the last option in the list is for the + &man.sshd.8; daemon. This is the secure shell server for + OpenSSH and it is highly recommended + over the standard telnet and + FTP servers. The sshd + server is used to create a secure connection from one host to + another by using encrypted connections. + + Finally there is the TCP Extensions + option. This enables the TCP Extensions + defined in RFC 1323 and + RFC 1644. While on many hosts this can + speed up connections, it can also cause some connections to be + dropped. It is not recommended for servers, but may be + beneficial for stand alone machines. + + Now that you have configured the network services, you can + scroll up to the very top item which is Exit + and continue on to the next configuration section. + + + + + Configure X Server + + + As of &os; 5.3-RELEASE, the X server configuration + facility has been removed from + sysinstall, you have to install + and configure the X server after the installation of &os;. + More information regarding the installation and the + configuration of a X server can be found in . You can skip this section if you are not + installing a &os; version prior to 5.3-RELEASE. + + + In order to use a graphical user interface such as + KDE, GNOME, + or others, the X server will need to be configured. + + + In order to run &xfree86; as a + non root user you will need to + have x11/wrapper installed. + This is installed by default beginning with FreeBSD 4.7. For + earlier versions this can be added + from the Package Selection menu. + + + To see whether your video card is supported, check the + &xfree86; web site. + + User Confirmation Requested + Would you like to configure your X server at this time? + + [ Yes ] No + + + It is necessary to know your monitor specifications and + video card information. Equipment damage can occur if settings + are incorrect. If you do not have this information, select + &gui.no; and perform the configuration + after installation when you have the information using + sysinstall (/stand/sysinstall + in &os; versions older than 5.2), selecting + Configure and then + XFree86. Improper configuration + of the X server at this time can leave the machine in a + frozen state. It is often advised to configure the X server + once the installation has completed. + + + + If you have graphics card and monitor information, select + &gui.yes; and press Enter + to proceed with configuring the X server. + +
+ Select Configuration Method Menu + + + + + + +
+ + There are several ways to configure the X server. + Use the arrow keys to select one of the methods and press + Enter. Be sure to read all instructions + carefully. + + The xf86cfg and + xf86cfg -textmode methods may make the screen + go dark and take a few seconds to start. Be patient. + + + The following will illustrate the use of the + xf86config configuration tool. The + configuration choices you make will depend on the hardware in the + system so your choices will probably be different than those + shown: + + Message + You have configured and been running the mouse daemon. + Choose "/dev/sysmouse" as the mouse port and "SysMouse" or + "MouseSystems" as the mouse protocol in the X configuration utility. + + [ OK ] + + [ Press enter to continue ] + + This indicates that the mouse daemon previously configured has been + detected. + Press Enter to continue. + + Starting xf86config will display + a brief introduction: + + This program will create a basic XF86Config file, based on menu selections you +make. + +The XF86Config file usually resides in /usr/X11R6/etc/X11 or /etc/X11. A sample +XF86Config file is supplied with XFree86; it is configured for a standard +VGA card and monitor with 640x480 resolution. This program will ask for a +pathname when it is ready to write the file. + +You can either take the sample XF86Config as a base and edit it for your +configuration, or let this program produce a base XF86Config file for your +configuration and fine-tune it. + +Before continuing with this program, make sure you know what video card +you have, and preferably also the chipset it uses and the amount of video +memory on your video card. SuperProbe may be able to help with this. + +Press enter to continue, or ctrl-c to abort. + + Pressing Enter will start the mouse + configuration. Be sure to follow the instructions and use + Mouse Systems as the mouse protocol and + /dev/sysmouse as the mouse port even if + using a PS/2 mouse is shown as an illustration. + + First specify a mouse protocol type. Choose one from the following list: + + 1. Microsoft compatible (2-button protocol) + 2. Mouse Systems (3-button protocol) & FreeBSD moused protocol + 3. Bus Mouse + 4. PS/2 Mouse + 5. Logitech Mouse (serial, old type, Logitech protocol) + 6. Logitech MouseMan (Microsoft compatible) + 7. MM Series + 8. MM HitTablet + 9. Microsoft IntelliMouse + +If you have a two-button mouse, it is most likely of type 1, and if you have +a three-button mouse, it can probably support both protocol 1 and 2. There are +two main varieties of the latter type: mice with a switch to select the +protocol, and mice that default to 1 and require a button to be held at +boot-time to select protocol 2. Some mice can be convinced to do 2 by sending +a special sequence to the serial port (see the ClearDTR/ClearRTS options). + +Enter a protocol number: 2 + +You have selected a Mouse Systems protocol mouse. If your mouse is normally +in Microsoft-compatible mode, enabling the ClearDTR and ClearRTS options +may cause it to switch to Mouse Systems mode when the server starts. + +Please answer the following question with either 'y' or 'n'. +Do you want to enable ClearDTR and ClearRTS? n + +You have selected a three-button mouse protocol. It is recommended that you +do not enable Emulate3Buttons, unless the third button doesn't work. + +Please answer the following question with either 'y' or 'n'. +Do you want to enable Emulate3Buttons? y + +Now give the full device name that the mouse is connected to, for example +/dev/tty00. Just pressing enter will use the default, /dev/mouse. +On FreeBSD, the default is /dev/sysmouse. + +Mouse device: /dev/sysmouse + + The keyboard is the next item to be configured. A generic + 101-key model is shown for illustration. Any name may be used + for the variant or simply press Enter to accept + the default value. + + Please select one of the following keyboard types that is the better +description of your keyboard. If nothing really matches, +choose 1 (Generic 101-key PC) + + 1 Generic 101-key PC + 2 Generic 102-key (Intl) PC + 3 Generic 104-key PC + 4 Generic 105-key (Intl) PC + 5 Dell 101-key PC + 6 Everex STEPnote + 7 Keytronic FlexPro + 8 Microsoft Natural + 9 Northgate OmniKey 101 + 10 Winbook Model XP5 + 11 Japanese 106-key + 12 PC-98xx Series + 13 Brazilian ABNT2 + 14 HP Internet + 15 Logitech iTouch + 16 Logitech Cordless Desktop Pro + 17 Logitech Internet Keyboard + 18 Logitech Internet Navigator Keyboard + 19 Compaq Internet + 20 Microsoft Natural Pro + 21 Genius Comfy KB-16M + 22 IBM Rapid Access + 23 IBM Rapid Access II + 24 Chicony Internet Keyboard + 25 Dell Internet Keyboard + +Enter a number to choose the keyboard. + +1 + + +Please select the layout corresponding to your keyboard + + + 1 U.S. English + 2 U.S. English w/ ISO9995-3 + 3 U.S. English w/ deadkeys + 4 Albanian + 5 Arabic + 6 Armenian + 7 Azerbaidjani + 8 Belarusian + 9 Belgian + 10 Bengali + 11 Brazilian + 12 Bulgarian + 13 Burmese + 14 Canadian + 15 Croatian + 16 Czech + 17 Czech (qwerty) + 18 Danish + +Enter a number to choose the country. +Press enter for the next page + +1 + + +Please enter a variant name for 'us' layout. Or just press enter +for default variant + +us + + +Please answer the following question with either 'y' or 'n'. +Do you want to select additional XKB options (group switcher, +group indicator, etc.)? n + + Next, we proceed to the configuration for the monitor. Do not + exceed the ratings of your monitor. Damage could occur. If you + have any doubts, do the configuration after you have the + information. + + Now we want to set the specifications of the monitor. The two critical +parameters are the vertical refresh rate, which is the rate at which the +whole screen is refreshed, and most importantly the horizontal sync rate, +which is the rate at which scanlines are displayed. + +The valid range for horizontal sync and vertical sync should be documented +in the manual of your monitor. If in doubt, check the monitor database +/usr/X11R6/lib/X11/doc/Monitors to see if your monitor is there. + +Press enter to continue, or ctrl-c to abort. + + + +You must indicate the horizontal sync range of your monitor. You can either +select one of the predefined ranges below that correspond to industry- +standard monitor types, or give a specific range. + +It is VERY IMPORTANT that you do not specify a monitor type with a horizontal +sync range that is beyond the capabilities of your monitor. If in doubt, +choose a conservative setting. + + hsync in kHz; monitor type with characteristic modes + 1 31.5; Standard VGA, 640x480 @ 60 Hz + 2 31.5 - 35.1; Super VGA, 800x600 @ 56 Hz + 3 31.5, 35.5; 8514 Compatible, 1024x768 @ 87 Hz interlaced (no 800x600) + 4 31.5, 35.15, 35.5; Super VGA, 1024x768 @ 87 Hz interlaced, 800x600 @ 56 Hz + 5 31.5 - 37.9; Extended Super VGA, 800x600 @ 60 Hz, 640x480 @ 72 Hz + 6 31.5 - 48.5; Non-Interlaced SVGA, 1024x768 @ 60 Hz, 800x600 @ 72 Hz + 7 31.5 - 57.0; High Frequency SVGA, 1024x768 @ 70 Hz + 8 31.5 - 64.3; Monitor that can do 1280x1024 @ 60 Hz + 9 31.5 - 79.0; Monitor that can do 1280x1024 @ 74 Hz +10 31.5 - 82.0; Monitor that can do 1280x1024 @ 76 Hz +11 Enter your own horizontal sync range + +Enter your choice (1-11): 6 + +You must indicate the vertical sync range of your monitor. You can either +select one of the predefined ranges below that correspond to industry- +standard monitor types, or give a specific range. For interlaced modes, +the number that counts is the high one (e.g. 87 Hz rather than 43 Hz). + + 1 50-70 + 2 50-90 + 3 50-100 + 4 40-150 + 5 Enter your own vertical sync range + +Enter your choice: 2 + +You must now enter a few identification/description strings, namely an +identifier, a vendor name, and a model name. Just pressing enter will fill +in default names. + +The strings are free-form, spaces are allowed. +Enter an identifier for your monitor definition: Hitachi + + The selection of a video card driver from a list is + next. If you pass your card on the list, continue to press + Enter and the list will repeat. Only an + excerpt from the list is shown: + + Now we must configure video card specific settings. At this point you can +choose to make a selection out of a database of video card definitions. +Because there can be variation in Ramdacs and clock generators even +between cards of the same model, it is not sensible to blindly copy +the settings (e.g. a Device section). For this reason, after you make a +selection, you will still be asked about the components of the card, with +the settings from the chosen database entry presented as a strong hint. + +The database entries include information about the chipset, what driver to +run, the Ramdac and ClockChip, and comments that will be included in the +Device section. However, a lot of definitions only hint about what driver +to run (based on the chipset the card uses) and are untested. + +If you can't find your card in the database, there's nothing to worry about. +You should only choose a database entry that is exactly the same model as +your card; choosing one that looks similar is just a bad idea (e.g. a +GemStone Snail 64 may be as different from a GemStone Snail 64+ in terms of +hardware as can be). + +Do you want to look at the card database? y + + + +288 Matrox Millennium G200 8MB mgag200 +289 Matrox Millennium G200 SD 16MB mgag200 +290 Matrox Millennium G200 SD 4MB mgag200 +291 Matrox Millennium G200 SD 8MB mgag200 +292 Matrox Millennium G400 mgag400 +293 Matrox Millennium II 16MB mga2164w +294 Matrox Millennium II 4MB mga2164w +295 Matrox Millennium II 8MB mga2164w +296 Matrox Mystique mga1064sg +297 Matrox Mystique G200 16MB mgag200 +298 Matrox Mystique G200 4MB mgag200 +299 Matrox Mystique G200 8MB mgag200 +300 Matrox Productiva G100 4MB mgag100 +301 Matrox Productiva G100 8MB mgag100 +302 MediaGX mediagx +303 MediaVision Proaxcel 128 ET6000 +304 Mirage Z-128 ET6000 +305 Miro CRYSTAL VRX Verite 1000 + +Enter a number to choose the corresponding card definition. +Press enter for the next page, q to continue configuration. + +288 + +Your selected card definition: + +Identifier: Matrox Millennium G200 8MB +Chipset: mgag200 +Driver: mga +Do NOT probe clocks or use any Clocks line. + +Press enter to continue, or ctrl-c to abort. + + + +Now you must give information about your video card. This will be used for +the "Device" section of your video card in XF86Config. + +You must indicate how much video memory you have. It is probably a good +idea to use the same approximate amount as that detected by the server you +intend to use. If you encounter problems that are due to the used server +not supporting the amount memory you have (e.g. ATI Mach64 is limited to +1024K with the SVGA server), specify the maximum amount supported by the +server. + +How much video memory do you have on your video card: + + 1 256K + 2 512K + 3 1024K + 4 2048K + 5 4096K + 6 Other + +Enter your choice: 6 + +Amount of video memory in Kbytes: 8192 + +You must now enter a few identification/description strings, namely an +identifier, a vendor name, and a model name. Just pressing enter will fill +in default names (possibly from a card definition). + +Your card definition is Matrox Millennium G200 8MB. + +The strings are free-form, spaces are allowed. +Enter an identifier for your video card definition: + + Next, the video modes are set for the resolutions + desired. Typically, useful ranges are 640x480, 800x600, and 1024x768 + but those are a function of video card capability, monitor size, + and eye comfort. When selecting a color depth, select the highest + mode that your card will support. + + For each depth, a list of modes (resolutions) is defined. The default +resolution that the server will start-up with will be the first listed +mode that can be supported by the monitor and card. +Currently it is set to: + +"640x480" "800x600" "1024x768" "1280x1024" for 8-bit +"640x480" "800x600" "1024x768" "1280x1024" for 16-bit +"640x480" "800x600" "1024x768" "1280x1024" for 24-bit + +Modes that cannot be supported due to monitor or clock constraints will +be automatically skipped by the server. + + 1 Change the modes for 8-bit (256 colors) + 2 Change the modes for 16-bit (32K/64K colors) + 3 Change the modes for 24-bit (24-bit color) + 4 The modes are OK, continue. + +Enter your choice: 2 + +Select modes from the following list: + + 1 "640x400" + 2 "640x480" + 3 "800x600" + 4 "1024x768" + 5 "1280x1024" + 6 "320x200" + 7 "320x240" + 8 "400x300" + 9 "1152x864" + a "1600x1200" + b "1800x1400" + c "512x384" + +Please type the digits corresponding to the modes that you want to select. +For example, 432 selects "1024x768" "800x600" "640x480", with a +default mode of 1024x768. + +Which modes? 432 + +You can have a virtual screen (desktop), which is screen area that is larger +than the physical screen and which is panned by moving the mouse to the edge +of the screen. If you don't want virtual desktop at a certain resolution, +you cannot have modes listed that are larger. Each color depth can have a +differently-sized virtual screen + +Please answer the following question with either 'y' or 'n'. +Do you want a virtual screen that is larger than the physical screen? n + + + +For each depth, a list of modes (resolutions) is defined. The default +resolution that the server will start-up with will be the first listed +mode that can be supported by the monitor and card. +Currently it is set to: + +"640x480" "800x600" "1024x768" "1280x1024" for 8-bit +"1024x768" "800x600" "640x480" for 16-bit +"640x480" "800x600" "1024x768" "1280x1024" for 24-bit + +Modes that cannot be supported due to monitor or clock constraints will +be automatically skipped by the server. + + 1 Change the modes for 8-bit (256 colors) + 2 Change the modes for 16-bit (32K/64K colors) + 3 Change the modes for 24-bit (24-bit color) + 4 The modes are OK, continue. + +Enter your choice: 4 + + + +Please specify which color depth you want to use by default: + + 1 1 bit (monochrome) + 2 4 bits (16 colors) + 3 8 bits (256 colors) + 4 16 bits (65536 colors) + 5 24 bits (16 million colors) + +Enter a number to choose the default depth. + +4 + + Finally, the configuration needs to be saved. Be sure + to enter /etc/X11/XF86Config as the location + for saving the configuration. + + I am going to write the XF86Config file now. Make sure you don't accidently +overwrite a previously configured one. + +Shall I write it to /etc/X11/XF86Config? y + + If the configuration fails, you can try the configuration again + by selecting &gui.yes; when the following + message appears: + + User Confirmation Requested +The XFree86 configuration process seems to have +failed. Would you like to try again? + + [ Yes ] No + + If you have trouble configuring &xfree86;, select + &gui.no; and press Enter + and continue with the installation process. After installation + you can use xf86cfg -textmode or + xf86config to access the command line + configuration utilities as root. There is + an additional method for configuring &xfree86; described in + . If you choose not to configure + &xfree86; at this time the next menu will be for package + selection. + + The default setting which allows the server to be killed + is the hotkey sequence + CtrlAlt + Backspace. This + can be executed if something is wrong with the server settings and + prevent hardware damage. + + The default setting that allows video mode switching will + permit changing of the mode while running X with the hotkey + sequence + + CtrlAlt+ + or + + CtrlAlt- + . + + + After you have &xfree86; + running, the display can be adjusted for height, width, + or centering by using xvidtune. + + There are warnings that improper settings can + damage your equipment. Heed them. If in doubt, do not do + it. Instead, use the monitor controls to adjust the display for + X Window. There may be some display differences when switching + back to text mode, but it is better than damaging equipment. + + Read the &man.xvidtune.1; manual page before making + any adjustments. + + Following a successful &xfree86; configuration, it will proceed + to the selection of a default desktop. + + + + Select Default X Desktop + + + As of &os; 5.3-RELEASE, the X desktop selection + facility has been removed from + sysinstall, you have to configure + the X desktop after the installation of &os;. More + information regarding the installation and the configuration + of a X desktop can be found in . You + can skip this section if you are not installing a &os; + version prior to 5.3-RELEASE. + + + There are a variety of window managers available. They range + from very basic environments to full desktop environments with a + large suite of software. Some require only minimal disk space and + low memory while others with more features require much more. The + best way to determine which is most suitable for you is to try a few + different ones. Those are available from the Ports Collection or as + packages and can be added after installation. + + You can select one of the popular desktops to be installed + and configured as the default desktop. This will allow you + to start it right after installation. + +
+ Select Default Desktop + + + + + + +
+ + Use the arrow keys to select a desktop and press + Enter. Installation of the selected desktop will + proceed. + + + + Install Packages + + Packages are pre-compiled binaries and are a convenient + way to install software. + + Installation of one package is shown for purposes of + illustration. Additional packages can also be added at this + time if desired. After installation + sysinstall (/stand/sysinstall + in &os; versions older than 5.2) can be used to add additional + packages. + + User Confirmation Requested + The FreeBSD package collection is a collection of hundreds of + ready-to-run applications, from text editors to games to WEB servers + and more. Would you like to browse the collection now? + + [ Yes ] No + + Selecting &gui.yes; and pressing + Enter will be + followed by the Package Selection screens: + +
+ Select Package Category + + + + + + +
+ + Only packages on the current installation media are + available for installation at any given time. + + All packages available will be displayed if + All is selected or you can select a + particular category. Highlight your selection with the arrow + keys and press Enter. + + A menu will display showing all the packages available for + the selection made: + +
+ Select Packages + + + + + + +
+ + The bash shell is shown selected. + Select as many as desired by highlighting the package and pressing the + Space key. A short description of each package will + appear in the lower left corner of the screen. + + Pressing the Tab key will toggle between the last + selected package, &gui.ok;, and &gui.cancel;. + + When you have finished marking the packages for installation, + press Tab once to toggle to the &gui.ok; and press + Enter to return to the Package Selection menu. + + The left and right arrow keys will also toggle between &gui.ok; + and &gui.cancel;. This method can also be used to select &gui.ok; and + press Enter to return to the Package Selection + menu. + +
+ Install Packages + + + + + + +
+ + Use the Tab and arrow keys to select [ Install ] + and press Enter. You will then need to confirm + that you want to install the packages: + +
+ Confirm Package Installation + + + + + + +
+ + Selecting &gui.ok; and pressing Enter will start + the package installation. Installing messages will appear until + completed. Make note if there are any error messages. + + The final configuration continues after packages are + installed. If you end up not selecting any packages, and wish + to return to the final configuration, select + Install anyways. + + + + Add Users/Groups + + You should add at least one user during the installation so + that you can use the system without being logged in as + root. The root partition is generally small + and running applications as root can quickly + fill it. A bigger danger is noted below: + + User Confirmation Requested + Would you like to add any initial user accounts to the system? Adding + at least one account for yourself at this stage is suggested since + working as the "root" user is dangerous (it is easy to do things which + adversely affect the entire system). + + [ Yes ] No + + Select &gui.yes; and press + Enter to continue with adding a user. + +
+ Select User + + + + + + +
+ + Select User with the arrow keys + and press Enter. + +
+ Add User Information + + + + + + +
+ + The following descriptions will appear in the lower part of + the screen as the items are selected with Tab + to assist with entering the required information: + + + + Login ID + + + The login name of the new user (mandatory). + + + + + UID + + + The numerical ID for this user (leave blank for + automatic choice). + + + + + Group + + + The login group name for this user (leave blank for + automatic choice). + + + + + Password + + + The password for this user (enter this field with + care!). + + + + + Full name + + + The user's full name (comment). + + + + + Member groups + + + The groups this user belongs to (i.e. gets access + rights for). + + + + + Home directory + + + The user's home directory (leave blank for + default). + + + + + Login shell + + The user's login shell (leave blank for + default, e.g. /bin/sh). + + + + + The login shell was changed from /bin/sh to + /usr/local/bin/bash to use the + bash shell that was previously installed as + a package. Do not try to use a shell that does not exist or you will + not be able to login. The most common shell used in the + BSD-world is the C shell, which can be indicated as + /bin/tcsh. + + The user was also added to the wheel group + to be able to become a superuser with root + privileges. + + When you are satisfied, press &gui.ok; and + the User and Group Management menu will redisplay: + +
+ Exit User and Group Management + + + + + + +
+ + Groups can also be added at this time if specific needs + are known. Otherwise, this may be accessed through using + sysinstall (/stand/sysinstall + in &os; versions older than 5.2) after installation is + completed. + + When you are finished adding users, select + Exit with the arrow keys and press + Enter to continue the installation. + + + + Set the <username>root</username> Password + + Message + Now you must set the system manager's password. + This is the password you'll use to log in as "root". + + [ OK ] + + [ Press enter to continue ] + + Press Enter to set the root + password. + + The password will need to be typed in twice correctly. Needless to + say, make sure you have a way of finding the password if you + forget. Notice that the password you type in is not echoed, nor + are asterisks displayed. + + Changing local password for root. +New password : +Retype new password : + + The installation will continue after the password is + successfully entered. + + + + Exiting Install + + If you need to configure additional network devices or + any other configuration, you can do it at this point or + after installation with sysinstall + (/stand/sysinstall in &os; versions older + than 5.2). + + User Confirmation Requested + Visit the general configuration menu for a chance to set any last + options? + + Yes [ No ] + + Select &gui.no; with the arrow keys + and press Enter to return to the Main + Installation Menu. + +
+ Exit Install + + + + + + +
+ + Select [X Exit Install] with the arrow + keys and press Enter. You will be asked to + confirm exiting the installation: + + User Confirmation Requested + Are you sure you wish to exit? The system will reboot (be sure to + remove any floppies from the drives). + + [ Yes ] No + + Select &gui.yes; and remove the floppy if + booting from the floppy. The CDROM drive is locked until the machine + starts to reboot. The CDROM drive is then unlocked and the disk can + be removed from drive (quickly). + + The system will reboot so watch for any error messages that + may appear. + + + + FreeBSD Bootup + + + FreeBSD Bootup on the &i386; + + If everything went well, you will see messages scroll + off the screen and you will arrive at a login prompt. You can view + the content of the messages by pressing Scroll-Lock + and using PgUp and PgDn. + Pressing Scroll-Lock again will return + to the prompt. + + The entire message may not display (buffer limitation) but + it can be viewed from the command line after logging in by typing + dmesg at the prompt. + + Login using the username/password you set during installation + (rpratt, in this example). Avoid logging in as + root except when necessary. + + Typical boot messages (version information omitted): + +Copyright (c) 1992-2002 The FreeBSD Project. +Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 + The Regents of the University of California. All rights reserved. + +Timecounter "i8254" frequency 1193182 Hz +CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU) + Origin = "AuthenticAMD" Id = 0x580 Stepping = 0 + Features=0x8001bf<FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX> + AMD Features=0x80000800<SYSCALL,3DNow!> +real memory = 268435456 (262144K bytes) +config> di sn0 +config> di lnc0 +config> di le0 +config> di ie0 +config> di fe0 +config> di cs0 +config> di bt0 +config> di aic0 +config> di aha0 +config> di adv0 +config> q +avail memory = 256311296 (250304K bytes) +Preloaded elf kernel "kernel" at 0xc0491000. +Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c. +md0: Malloc disk +Using $PIR table, 4 entries at 0xc00fde60 +npx0: <math processor> on motherboard +npx0: INT 16 interface +pcib0: <Host to PCI bridge> on motherboard +pci0: <PCI bus> on pcib0 +pcib1: <VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0 +pci1: <PCI bus> on pcib1 +pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11 +isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0 +isa0: <ISA bus> on isab0 +atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0 +ata0: at 0x1f0 irq 14 on atapci0 +ata1: at 0x170 irq 15 on atapci0 +uhci0: <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci0 +usb0: <VIA 83C572 USB controller> on uhci0 +usb0: USB revision 1.0 +uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1 +uhub0: 2 ports with 2 removable, self powered +chip1: <VIA 82C586B ACPI interface> at device 7.3 on pci0 +ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xe800-0xe81f irq 9 at +device 10.0 on pci0 +ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit) +isa0: too many dependant configs (8) +isa0: unexpected small tag 14 +fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0 +fdc0: FIFO enabled, 8 bytes threshold +fd0: <1440-KB 3.5" drive> on fdc0 drive 0 +atkbdc0: <keyboard controller (i8042)> at port 0x60-0x64 on isa0 +atkbd0: <AT Keyboard> flags 0x1 irq 1 on atkbdc0 +kbd0 at atkbd0 +psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: model Generic PS/2 mouse, device ID 0 +vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 +sc0: <System console> at flags 0x1 on isa0 +sc0: VGA <16 virtual consoles, flags=0x300> +sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 +sio0: type 16550A +sio1 at port 0x2f8-0x2ff irq 3 on isa0 +sio1: type 16550A +ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 +ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode +ppc0: FIFO with 16/16/15 bytes threshold +ppbus0: IEEE1284 device found /NIBBLE +Probing for PnP devices on ppbus0: +plip0: <PLIP network interface> on ppbus0 +lpt0: <Printer> on ppbus0 +lpt0: Interrupt-driven port +ppi0: <Parallel I/O> on ppbus0 +ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master using UDMA33 +ad2: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata1-master using UDMA33 +acd0: CDROM <DELTA OTC-H101/ST3 F/W by OIPD> at ata0-slave using PIO4 +Mounting root from ufs:/dev/ad0s1a +swapon: adding /dev/ad0s1b as swap device +Automatic boot in progress... +/dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS +/dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation) +/dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS +/dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation) +/dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS +/dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation) +/dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS +/dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation) +Doing initial network setup: hostname. +ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1 + ether 52:54:05:de:73:1b +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8 + inet6 ::1 prefixlen 128 + inet 127.0.0.1 netmask 0xff000000 +Additional routing options: IP gateway=YES TCP keepalive=YES +routing daemons:. +additional daemons: syslogd. +Doing additional network setup:. +Starting final network daemons: creating ssh RSA host key +Generating public/private rsa1 key pair. +Your identification has been saved in /etc/ssh/ssh_host_key. +Your public key has been saved in /etc/ssh/ssh_host_key.pub. +The key fingerprint is: +cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com + creating ssh DSA host key +Generating public/private dsa key pair. +Your identification has been saved in /etc/ssh/ssh_host_dsa_key. +Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. +The key fingerprint is: +f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com. +setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib +/usr/local/lib +a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout +starting standard daemons: inetd cron sshd usbd sendmail. +Initial rc.i386 initialization:. +rc.i386 configuring syscons: blank_time screensaver moused. +Additional ABI support: linux. +Local package initialization:. +Additional TCP options:. + +FreeBSD/i386 (k6-2.example.com) (ttyv0) + +login: rpratt +Password: + + Generating the RSA and DSA keys may take some time on slower + machines. This happens only on the initial boot-up of a new + installation. Subsequent boots will be faster. + + If the X server has been configured and a Default Desktop + chosen, it can be started by typing startx at + the command line. + + + + + Bootup of FreeBSD on the Alpha + + Alpha + + Once the install procedure has finished, you will be + able to start FreeBSD by typing something like this to the + SRM prompt: + + >>>BOOT DKC0 + + This instructs the firmware to boot the specified + disk. To make FreeBSD boot automatically in the future, use + these commands: + + >>> SET BOOT_OSFLAGS A +>>> SET BOOT_FILE '' +>>> SET BOOTDEF_DEV DKC0 +>>> SET AUTO_ACTION BOOT + + The boot messages will be similar (but not identical) to + those produced by FreeBSD booting on the &i386;. + + + + + FreeBSD Shutdown + + It is important to properly shutdown the operating + system. Do not just turn off power. First, become a superuser by + typing su at the command line and entering the + root password. This will work only if the user + is a member of the wheel group. + Otherwise, login as root and use + shutdown -h now. + + The operating system has halted. +Please press any key to reboot. + + It is safe to turn off the power after the shutdown command + has been issued and the message Please press any key to reboot + appears. If any key is pressed instead of turning off the power + switch, the system will reboot. + + You could also use the + + Ctrl + Alt + Del + + key combination to reboot the system, however this is not recommended + during normal operation. + + + + + + Supported Hardware + + hardware + FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and PCI + bus-based PCs with Intel, AMD, Cyrix, or NexGen x86 + processors, as well as a number of machines based on the Compaq Alpha + processor. Support for generic IDE or ESDI drive configurations, + various SCSI controllers, PCMCIA cards, USB devices, and network and + serial cards is also provided. FreeBSD also supports IBM's microchannel + (MCA) bus. + + A list of supported hardware is provided with each FreeBSD release + in the FreeBSD Hardware Notes. This document can usually be found in a + file named HARDWARE.TXT, in the top-level directory + of a CDROM or FTP distribution or in + sysinstall's documentation menu. It lists, + for a given architecture, what hardware devices are known to be + supported by each release of FreeBSD. Copies of the supported + hardware list for various releases and architectures can also be + found on the Release + Information page of the FreeBSD Web site. + + + + Troubleshooting + + + installation + troubleshooting + + The following section covers basic installation troubleshooting, + such as common problems people have reported. There are also a few + questions and answers for people wishing to dual-boot FreeBSD with + &ms-dos;. + + + What to Do If Something Goes Wrong + + Due to various limitations of the PC architecture, it is + impossible for probing to be 100% reliable, however, there are a + few things you can do if it fails. + + Check the Hardware Notes document for your version of + FreeBSD to make sure your hardware is + supported. + + If your hardware is supported and you still experience + lock-ups or other problems, reset your computer, and when the + visual kernel configuration option is given, choose it. This will + allow you to go through your hardware and supply information to the + system about it. The kernel on the boot disks is configured + assuming that most hardware devices are in their factory default + configuration in terms of IRQs, IO addresses, and DMA channels. If + your hardware has been reconfigured, you will most likely need to + use the configuration editor to tell FreeBSD where to find + things. + + It is also possible that a probe for a device not present will + cause a later probe for another device that is present to fail. In + that case, the probes for the conflicting driver(s) should be + disabled. + + + Some installation problems can be avoided or alleviated + by updating the firmware on various hardware components, most notably + the motherboard. The motherboard firmware may also be referred to + as BIOS and most of the motherboard or computer + manufactures have a website where the upgrades and upgrade information + may be located. + + Most manufacturers strongly advise against upgrading the motherboard + BIOS unless there is a good reason for doing so, which + could possibly be a critical update of sorts. The upgrade process + can go wrong, causing permanent damage to the + BIOS chip. + + + + Do not disable any drivers you will need during the + installation, such as your screen (sc0). + If the installation wedges or fails mysteriously after leaving + the configuration editor, you have probably removed or changed + something you should not have. Reboot and try again. + + + In configuration mode, you can: + + + + List the device drivers installed in the kernel. + + + + Disable device drivers for hardware that is not present in + your system. + + + + Change IRQs, DRQs, and IO port addresses used by a device + driver. + + + + After adjusting the kernel to match your hardware + configuration, type Q to boot with the new + settings. Once the installation has completed, any changes you + made in the configuration mode will be permanent so you do not have + to reconfigure every time you boot. It is still highly likely that + you will eventually want to build a custom kernel. + + + + Dealing with Existing &ms-dos; Partitions + + DOS + Many users wish to install &os; on PCs inhabited by + µsoft; based operating systems. For those instances, &os; has a + utility known as FIPS. This utility can be found + in the tools directory on the install CD-ROM, or downloaded + from one of various &os; mirrors. + + The FIPS utility allows you to split an + existing &ms-dos; partition into two pieces, preserving the original + partition and allowing you to install onto the second free piece. + You first need to defragment your &ms-dos; partition using the &windows; + Disk Defragmenter utility (go into Explorer, right-click on + the hard drive, and choose to defrag your hard drive), or use + Norton Disk Tools. Now you can run the + FIPS utility. It will prompt you for the rest of + the information, just follow the on screen instructions. Afterwards, you can + reboot and install &os; on the new free slice. See the Distributions menu + for an estimate of how much free space you will need for the kind of + installation you want. + + There is also a very useful product from PowerQuest + (http://www.powerquest.com) called + &partitionmagic;. This application has far more + functionality than FIPS, and is highly recommended + if you plan to add/remove operating systems often. It does cost money, so if you + plan to install &os; and keep it installed, FIPS + will probably be fine for you. + + + + Using &ms-dos; and &windows; File Systems + + At this time, &os; does not support file systems compressed with the + Double Space™ application. Therefore the file + system will need to be uncompressed before &os; can access the data. This + can be done by running the Compression Agent + located in the Start> Programs > + System Tools menu. + + &os; can support &ms-dos; based file systems. This requires you use + the &man.mount.msdos.8; command (in &os; 5.X, the command is &man.mount.msdosfs.8;) + with the required parameters. The utilities most common usage is: + + &prompt.root; mount_msdos /dev/ad0s1 /mnt + + In this example, the &ms-dos; file system is located on the first partition of + the primary hard disk. Your situation may be different, check the output from + the dmesg, and mount commands. They should + produce enough information to give an idea of the partition layout. + + Extended &ms-dos; file systems are usually mapped after the &os; + partitions. In other words, the slice number may be higher than the ones + &os; is using. For instance, the first &ms-dos; partition may be + /dev/ad0s1, the &os; partition may be + /dev/ad0s2, with the extended &ms-dos; partition being + located on /dev/ad0s3. To some, this can be confusing + at first. + + NTFS partitions can also be mounted in a similar manner + using the &man.mount.ntfs.8; command. + + + + Alpha User's Questions and Answers + + Alpha + + This section answers some commonly asked questions about + installing FreeBSD on Alpha systems. + + + + + Can I boot from the ARC or Alpha BIOS Console? + + + ARC + Alpha BIOS + SRM + + + No. &os;, like Compaq Tru64 and VMS, will only boot + from the SRM console. + + + + + + Help, I have no space! Do I need to delete + everything first? + + + + Unfortunately, yes. + + + + + + Can I mount my Compaq Tru64 or VMS filesystems? + + + + No, not at this time. + + + + + + + + + + + Valentino + Vaschetto + Contributed by + + + + + + Advanced Installation Guide + + This section describes how to install FreeBSD in exceptional + cases. + + + Installing FreeBSD on a System without a Monitor or + Keyboard + + + installation + headless (serial console) + + serial console + This type of installation is called a headless + install, because the machine that you are trying to install + FreeBSD on either does not have a monitor attached to it, or does not + even have a VGA output. How is this possible you ask? Using a + serial console. A serial console is basically using another + machine to act as the main display and keyboard for a + system. To do this, just follow the steps to create + installation floppies, explained in . + + To modify these floppies to boot into a serial console, follow + these steps: + + + + Enabling the Boot Floppies to Boot into a Serial Console + + mount + + If you were to boot into the floppies that you just + made, FreeBSD would boot into its normal install mode. We + want FreeBSD to boot into a serial console for our + install. To do this, you have to mount the + kern.flp floppy onto your FreeBSD + system using the &man.mount.8; command. + + &prompt.root; mount /dev/fd0 /mnt + + Now that you have the floppy mounted, you must + change into the /mnt directory: + + &prompt.root; cd /mnt + + Here is where you must set the floppy to boot into a + serial console. You have to make a file called + boot.config containing + /boot/loader -h. All this does is pass a flag to the bootloader to + boot into a serial console. + + &prompt.root; echo "/boot/loader -h" > boot.config + + Now that you have your floppy configured correctly, + you must unmount the floppy using the &man.umount.8; + command: + + &prompt.root; cd / +&prompt.root; umount /mnt + + Now you can remove the floppy from the floppy + drive. + + + + Connecting Your Null-modem Cable + + null-modem cable + You now need to connect a + null-modem cable between + the two machines. Just connect the cable to the serial + ports of the 2 machines. A normal serial cable + will not work here, you need a null-modem + cable because it has some of the wires inside crossed + over. + + + + Booting Up for the Install + + It is now time to go ahead and start the install. Put + the kern.flp floppy in the floppy + drive of the machine you are doing the headless install + on, and power on the machine. + + + + Connecting to Your Headless Machine + + cu + + Now you have to connect to that machine with + &man.cu.1;: + + &prompt.root; cu -l /dev/cuaa0 + + + + That's it! You should now be able to control the headless machine + through your cu session. It will ask you to + put in the mfsroot.flp, and then it will come up + with a selection of what kind of terminal to use. Select the + FreeBSD color console and proceed with your install! + + + + + + Preparing Your Own Installation Media + + + To prevent repetition, FreeBSD disc in this context + means a FreeBSD CDROM or DVD that you have purchased or produced + yourself. + + + There may be some situations in which you need to create your own + FreeBSD installation media and/or source. This might be physical media, + such as a tape, or a source that sysinstall + can use to retrieve the files, such as a local FTP site, or an &ms-dos; + partition. + + For example: + + + + You have many machines connected to your local network, and one + FreeBSD disc. You want to create a local FTP site using the + contents of the FreeBSD disc, and then have your machines use this + local FTP site instead of needing to connect to the Internet. + + + + You have a FreeBSD disc, and FreeBSD does not recognize your CD/DVD + drive, but &ms-dos;/&windows; does. You want to copy the FreeBSD + installation files to a DOS partition on the same computer, and + then install FreeBSD using those files. + + + + The computer you want to install on does not have a CD/DVD + drive or a network card, but you can connect a + Laplink-style serial or parallel cable to a computer + that does. + + + + You want to create a tape that can be used to install + FreeBSD. + + + + + Creating an Installation CDROM + + As part of each release, the FreeBSD project makes available two + CDROM images (ISO images). These images can be written + (burned) to CDs if you have a CD writer, and then used + to install FreeBSD. If you have a CD writer, and bandwidth is cheap, + then this is the easiest way to install FreeBSD. + + + + Download the Correct ISO Images + + The ISO images for each release can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-arch/version or the closest mirror. + Substitute arch and + version as appropriate. + + That directory will normally contain the following images: + + + FreeBSD 4.<replaceable>X</replaceable> ISO Image Names and Meanings + + + + + Filename + + Contains + + + + + + version-RELEASE-arch-miniinst.iso + + Everything you need to install FreeBSD. + + + + version-RELEASE-arch-disc1.iso + + Everything you need to install FreeBSD, and as many + additional third party packages as would fit on the + disc. + + + + version-RELEASE-arch-disc2.iso + + A live filesystem, which is used in + conjunction with the Repair facility in + sysinstall. A copy of the + FreeBSD CVS tree. As many additional third party packages + as would fit on the disc. + + + +
+ + + FreeBSD 5.<replaceable>X</replaceable> ISO Image Names and Meanings + + + + + Filename + + Contains + + + + + + version-RELEASE-arch-bootonly.iso + + Everything you need to boot into a FreeBSD + kernel and start the installation interface. + The installable files have to be pulled over FTP + or some other supported source. + + + + version-RELEASE-arch-miniinst.iso + + Everything you need to install FreeBSD. + + + + version-RELEASE-arch-disc1.iso + + Everything you need to install &os; and a + live filesystem, which is used in + conjunction with the Repair facility + in sysinstall. + + + + version-RELEASE-arch-disc2.iso + + &os; documentation and as many third party packages as + would fit on the disc. + + + +
+ + You must download one of either the miniinst + ISO image, or the image of disc one. Do not download both of them, + since the disc one image contains everything that the miniinst ISO + image contains. + + + The miniinst ISO image is only available for releases prior + to 5.4-RELEASE. + + + Use the miniinst ISO if Internet access is cheap for you. It will + let you install FreeBSD, and you can then install third party + packages by downloading them using the ports/packages system (see + ) as + necessary. + + Use the image of disc one if you want to install a &os; + release and want + a reasonable selection of third party packages on the disc + as well. + + The additional disc images are useful, but not essential, + especially if you have high-speed access to the Internet. + + + + Write the CDs + + You must then write the CD images to disc. If you will be + doing this on another FreeBSD system then see + for more information (in + particular, and + ). + + If you will be doing this on another platform then you will + need to use whatever utilities exist to control your CD writer on + that platform. The images provided are in the standard ISO format, + which many CD writing applications support. + + + + If you are interested in building a customized + release of FreeBSD, please see the Release Engineering + Article. + + + + + Creating a Local FTP Site with a FreeBSD Disc + + + installation + network + FTP + + + FreeBSD discs are laid out in the same way as the FTP site. This + makes it very easy for you to create a local FTP site that can be used + by other machines on your network when installing FreeBSD. + + + + On the FreeBSD computer that will host the FTP site, ensure + that the CDROM is in the drive, and mounted on + /cdrom. + + &prompt.root; mount /cdrom + + + + Create an account for anonymous FTP in + /etc/passwd. Do this by editing + /etc/passwd using &man.vipw.8; and adding + this line: + + ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent + + + + Ensure that the FTP service is enabled in + /etc/inetd.conf. + + + + Anyone with network connectivity to your machine can now + chose a media type of FTP and type in + ftp://your machine + after picking Other in the FTP sites menu during + the install. + + + If the boot media (floppy disks, usually) for your FTP + clients is not precisely the same version as that provided + by the local FTP site, then sysinstall will not let you + complete the installation. If the versions are not similar and + you want to override this, you must go into the Options menu + and change distribution name to + any. + + + + This approach is OK for a machine that is on your local network, + and that is protected by your firewall. Offering up FTP services to + other machines over the Internet (and not your local network) + exposes your computer to the attention of crackers and other + undesirables. We strongly recommend that you follow good security + practices if you do this. + + + + + Creating Installation Floppies + + + installation + floppies + + + If you must install from floppy disk (which we suggest you + do not do), either due to unsupported + hardware or simply because you insist on doing things the hard + way, you must first prepare some floppies for the installation. + + At a minimum, you will need as many 1.44 MB or 1.2 MB floppies + as it takes to hold all the files in the + bin (binary distribution) directory. If + you are preparing the floppies from DOS, then they + must be formatted using the &ms-dos; + FORMAT command. If you are using &windows;, + use Explorer to format the disks (right-click on the + A: drive, and select Format). + + Do not trust factory pre-formatted + floppies. Format them again yourself, just to be sure. Many + problems reported by our users in the past have resulted from + the use of improperly formatted media, which is why we are + making a point of it now. + + If you are creating the floppies on another FreeBSD machine, + a format is still not a bad idea, though you do not need to put + a DOS filesystem on each floppy. You can use the + bsdlabel and newfs + commands to put a UFS filesystem on them instead, as the + following sequence of commands (for a 3.5" 1.44 MB floppy) + illustrates: + + &prompt.root; fdformat -f 1440 fd0.1440 +&prompt.root; bsdlabel -w -r fd0.1440 floppy3 +&prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0 + + + Use fd0.1200 and + floppy5 for 5.25" 1.2 MB disks. + + + Then you can mount and write to them like any other + filesystem. + + After you have formatted the floppies, you will need to copy + the files to them. The distribution files are split into chunks + conveniently sized so that five of them will fit on a conventional + 1.44 MB floppy. Go through all your floppies, packing as many + files as will fit on each one, until you have all of the + distributions you want packed up in this fashion. Each + distribution should go into a subdirectory on the floppy, e.g.: + a:\bin\bin.aa, + a:\bin\bin.ab, and so on. + + Once you come to the Media screen during the install + process, select Floppy and you + will be prompted for the rest. + + + + Installing from an &ms-dos; Partition + + + installation + from MS-DOS + + To prepare for an installation from an &ms-dos; partition, + copy the files from the distribution into a directory + called freebsd in the root directory of the + partition. For example, c:\freebsd. The + directory structure of the CDROM or FTP site must be partially + reproduced within this directory, so we suggest using the DOS + xcopy command if you are copying it from a CD. + For example, to prepare for a minimal installation of + FreeBSD: + + C:\> md c:\freebsd +C:\> xcopy e:\bin c:\freebsd\bin\ /s +C:\> xcopy e:\manpages c:\freebsd\manpages\ /s + + Assuming that C: is where you have + free space and E: is where your CDROM + is mounted. + + If you do not have a CDROM drive, you can download the + distribution from ftp.FreeBSD.org. + Each distribution is in its own directory; for example, the + base distribution can be found in the &rel.current;/base/ + directory. + + For as many distributions you wish to install from an &ms-dos; + partition (and you have the free space for), install each one + under c:\freebsd — the + BIN distribution is the only one required for + a minimum installation. + + + + Creating an Installation Tape + + + installation + from QIC/SCSI Tape + + Installing from tape is probably the easiest method, short + of an online FTP install or CDROM install. The installation + program expects the files to be simply tarred onto the tape. + After getting all of the distribution files you are interested + in, simply tar them onto the tape: + + &prompt.root; cd /freebsd/distdir +&prompt.root; tar cvf /dev/rwt0 dist1 ... dist2 + + When you perform the installation, you should make + sure that you leave enough room in some temporary directory + (which you will be allowed to choose) to accommodate the + full contents of the tape you have created. + Due to the non-random access nature of tapes, this method of + installation requires quite a bit of temporary storage. + + + When starting the installation, the tape must be in the + drive before booting from the boot + floppy. The installation probe may otherwise fail to find + it. + + + + + Before Installing over a Network + + + installation + network + serial (SLIP or PPP) + + + installation + network + parallel (PLIP) + + + installation + network + Ethernet + + There are three types of network installations available. + Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)), + or Ethernet (a standard Ethernet controller (includes some + PCMCIA)). + + The SLIP support is rather primitive, and limited primarily + to hard-wired links, such as a serial cable running between a + laptop computer and another computer. The link should be + hard-wired as the SLIP installation does not currently offer a + dialing capability; that facility is provided with the PPP + utility, which should be used in preference to SLIP whenever + possible. + + If you are using a modem, then PPP is almost certainly + your only choice. Make sure that you have your service + provider's information handy as you will need to know it fairly + early in the installation process. + + If you use PAP or CHAP to connect your ISP (in other words, if + you can connect to the ISP in &windows; without using a script), then + all you will need to do is type in dial at the + ppp prompt. Otherwise, you will need to + know how to dial your ISP using the AT commands + specific to your modem, as the PPP dialer provides only a very + simple terminal emulator. Please refer to the user-ppp handbook and FAQ entries for further information. + If you have problems, logging can be directed to the screen using + the command set log local .... + + If a hard-wired connection to another FreeBSD (2.0-R or + later) machine is available, you might also consider installing + over a laplink parallel port cable. The data rate + over the parallel port is much higher than what is typically + possible over a serial line (up to 50 kbytes/sec), thus resulting + in a quicker installation. + + Finally, for the fastest possible network installation, an + Ethernet adapter is always a good choice! FreeBSD supports most + common PC Ethernet cards; a table of supported cards (and their + required settings) is provided in the Hardware Notes for each + release of FreeBSD. If you are using one of the supported PCMCIA + Ethernet cards, also be sure that it is plugged in + before the laptop is powered on! FreeBSD does + not, unfortunately, currently support hot insertion of PCMCIA cards + during installation. + + You will also need to know your IP address on the network, + the netmask value for your address class, and the name of your + machine. If you are installing over a PPP connection and do not + have a static IP, fear not, the IP address can be dynamically + assigned by your ISP. Your system administrator can tell you + which values to use for your particular network setup. If you + will be referring to other hosts by name rather than IP address, + you will also need a name server and possibly the address of a + gateway (if you are using PPP, it is your provider's IP address) + to use in talking to it. If you want to install by FTP via a + HTTP proxy, you will also need the proxy's address. + If you do not know the answers to all or most of these questions, + then you should really probably talk to your system administrator + or ISP before trying this type of + installation. + + + Before Installing via NFS + + + installation + network + NFS + + The NFS installation is fairly straight-forward. Simply + copy the FreeBSD distribution files you want onto an NFS server + and then point the NFS media selection at it. + + If this server supports only privileged port + (as is generally the default for Sun workstations), you will + need to set the option NFS Secure in the + Options menu before installation can proceed. + + If you have a poor quality Ethernet card which suffers + from very slow transfer rates, you may also wish to toggle the + NFS Slow flag. + + In order for NFS installation to work, the server must + support subdir mounts, for example, if your FreeBSD &rel.current; distribution + directory lives on: + ziggy:/usr/archive/stuff/FreeBSD, then + ziggy will have to allow the direct mounting + of /usr/archive/stuff/FreeBSD, not just + /usr or + /usr/archive/stuff. + + In FreeBSD's /etc/exports file, this + is controlled by the options. Other NFS + servers may have different conventions. If you are getting + permission denied messages from the + server, then it is likely that you do not have this enabled + properly. + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir1.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir1.dot new file mode 100644 index 0000000000..f259e8377d --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir1.dot @@ -0,0 +1,7 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir2.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir2.dot new file mode 100644 index 0000000000..b846c82399 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir2.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "B1/"; + "A1/" -> "B2/"; + root -> "A2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir3.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir3.dot new file mode 100644 index 0000000000..178a3a91bb --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir3.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir4.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir4.dot new file mode 100644 index 0000000000..82d12b421a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir4.dot @@ -0,0 +1,9 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/" -> "C1/"; + "B1/" -> "C2/"; + "A2/" -> "B2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir5.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir5.dot new file mode 100644 index 0000000000..f5aa6e01dc --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir5.dot @@ -0,0 +1,9 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "C1/"; + "A1/" -> "C2/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/pl_PL.ISO8859-2/books/handbook/introduction/Makefile b/pl_PL.ISO8859-2/books/handbook/introduction/Makefile new file mode 100644 index 0000000000..4c22f7ce8a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/introduction/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= introduction/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/introduction/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/introduction/chapter.sgml new file mode 100644 index 0000000000..96f5d4db86 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/introduction/chapter.sgml @@ -0,0 +1,971 @@ + + + + + + + Jim + Mock + Rozdzia³ zreorganizowa³ i czê¶ciowo + napisa³ od nowa + + + + + + Cezary + Morga + T³umaczy³ + + + + + Wprowadzenie + + + Strzeszczenie + + Dziêkujemy za zainteresowanie FreeBSD! W niniejszym rozdziale + opisane zostan± ró¿ne aspekty Projektu FreeBSD, takie jak jego historia, + obrany cel, czy model rozwoju. + + Czytaj±c ten rozdzia³ poznamy: + + + + Zale¿no¶ci istniej±ce miêdzy FreeBSD i innymi systemami operacyjnymi. + + + Historiê Projektu FreeBSD. + + + Cele stawiane przed Projektem FreeBSD. + + + Podstawowe zagadnienia zwi±zane z modelem rozwoju otwartego oprogramowania + (ang. open source) FreeBSD. + + + I oczywi¶cie, dowiemy siê sk±d pochodzi nazwa FreeBSD. + + + + + + + Witamy w ¶wiecie FreeBSD! + 4.4BSD-Lite + + FreeBSD jest systemem operacyjnym bazuj±cym na 4.4BSD-Lite, a + przeznaczonym dla komputerów pracuj±cych na platformach Intela (x86 i + &itanium;), AMD64, Alpha oraz Sun &ultrasparc;. + Przygotowywane s± równie¿ wersje dla innych platform. Wiêcej informacji + dostêpnych jest w historii FreeBSD b±d¼ + w nocie o aktualnym wydaniu. Je¶li chcia³by¶ + wspomóc rozwój Projektu (np. kod ¼ród³owy, sprzêt, nieoznakowane banknoty) + przeczytaj artyku³ o wspó³pracy z Projektem + FreeBSD (ang.). + + + + + + Aleksander + Fafu³a + T³umaczy³ + + + + + Cezary + Morga + Przek³ad uzupe³ni³ + + + + + Co potrafi FreeBSD? + + FreeBSD posiada mnóstwo zalet. Oto niektóre z nich: + + + wielozadaniowo¶æ z wyw³aszczaniem + + Wielozadaniowo¶æ z wyw³aszczaniem, wraz z + dynamiczn± regulacj± priorytetów, by zapewniæ sprawne i bezkonfliktowe + wspó³dzielenie zasobów komputera przez aplikacje oraz u¿ytkowników, + nawet w sytuacjach najwiêkszego obci±¿enia systemu. + + + wielou¿ytkownikowo¶æ + + Wielou¿ytkownikowo¶æ pozwalaj±ca na + jednoczesne wykorzystanie komputera z systemem FreeBSD przez + wielu u¿ytkowników. Oznacza to, np. prawid³owe dzielenie dostêpu + do urz±dzeñ zewnêtrznych jak np. do drukarki, pomiêdzy wszystkich + u¿ytkowników lokalnych jak i sieciowych. Ograniczenia dostêpu do + zasobów mog± byæ definiowane dla konkretnych u¿ytkowników b±d¼ grup + u¿ytkowników, co z kolei pozwala na zabezpieczenie krytycznych + zasobów systemowych przed nadu¿yciami. + + + sieci TCP/IP + + Pe³na obs³uga sieci TCP/IP, oraz innych + sieciowych standardów jak SLIP, PPP, NFS, DHCP czy NIS. Oznacza + to, ¿e twój system FreeBSD mo¿e bez problemów wspó³pracowaæ z + dowolnymi innymi systemami operacyjnymi, jak równie¿ pracowaæ w + roli serwera w przedsiêbiorstwie, dostarczaj±c niezbêdnych funkcji + jak np. NFS (zdalny dostêp do plików) wraz z obs³ug± emaila, b±d¼ + pozwoli na umieszczenie internetowej wizytówki twojej organizacji + na stronie WWW czy dokumentów na serwerze FTP. Mo¿e równie¿ realizowaæ + przekierowywanie (ruting) pakietów, a tak¿e pe³niæ rolê zapory + ogniowej (firewall). + + + ochrona pamiêci + + Ochrona pamiêci gwarantuje, ¿e programy + (b±d¼ u¿ytkownicy) nie mog± ingerowaæ w pracê innych aplikacji. + Innymi s³owy, awaria danego programu w ¿aden sposób nie wp³ywa + na dzia³anie pozosta³ych. + + + + FreeBSD jest 32-bitowym systemem operacyjnym + (64-bitowym na platformach Alpha, &itanium;, AMD64 i &ultrasparc;) + i w³a¶nie jako taki projektowany by³ od pocz±tku. + + + + System okien X + XFree86 + + + + Obecnie standardowy System okien X + (X11R6; X Window System) dostarcza interfejsu graficznego (GUI) + w cenie zwyk³ej karty VGA i monitora. Ponadto dostêpny jest z + pe³nym kodem ¼ród³owym. + + + + kompatybilno¶æ binarna + Linux + + + kompatybilno¶æ binarna + SCO + + + kompatybilno¶æ binarna + SVR4 + + + kompatybilno¶æ binarna + BSD/OS + + + kompatybilno¶æ binarna + NetBSD + + + Kompatybilno¶æ binarn± z wieloma systemami + typu &unix;. FreeBSD posiada mo¿liwo¶æ uruchamiania programów + skompilowanych dla Linuksa, SCO, SVR4, BSDI i NetBSD. + + + + Tysi±ce aplikacji gotowych do pracy, + dostêpnych z kolekcji portów i + pakietów FreeBSD. Czemu szukaæ + w sieci, skoro wszystko mo¿na znale¼æ w³a¶nie tutaj? + + + + Tysi±ce dodatkowych i + ³atwych do przeniesienia programów dostêpnych + w Internecie. FreeBSD jest kompatybilny z wieloma popularnymi, + nawet komercyjnymi systemami typu &unix; i tym samym wiêkszo¶æ + programów wymaga zaledwie kilku, je¶li w ogóle, zmian w kodzie + aby poprawnie skompilowaæ i uruchomiæ. + + + pamiêæ wirtualna + + Stronicowana pamiêæ wirtualna oraz + wspó³dzielona pamiêæ podrêczna VM/buffer cache + zaprojektowane by efektywnie zaspokajaæ potrzeby aplikacji z + du¿ym apetytem na pamiêæ, przy jednoczesnym zapewnieniu ci±g³ej + interakcji systemu z u¿ytkownikami. + + + + Symmetric Multi-Processing (SMP) + + + Wsparcie dla technologii SMP, dla maszyn + z wieloma procesorami. + + + + kompilatory + C + + + kompilatory + C++ + + + kompilatory + FORTRAN + + + Kompletne ¶rodowiska programistyczne dla jêzyków C, + C++ i Fortran. FreeBSD posiada + równie¿ wiele dodatkowych ¶rodowisk dla innych jêzyków programowania + dostêpnych w kolekcji portów i pakietów. + + + kod ¼ród³owy + + Dostêpno¶æ kodu ¼ród³owego dla ca³ego + systemu oznacza, i¿ to w³a¶nie ty posiadasz najwiêksz± kontrolê + nad swoim ¶rodowiskiem pracy. Czemu zamykaæ siê w krêgu + rozwi±zañ w³asno¶ciowych i byæ skazanym na ³askê dostarczyciela + systemu, kiedy mo¿na mieæ prawdziwie otwarty system? + + + + Obszern± dokumentacjê dostêpn± + w Internecie.. + + + + I wiele wiêcej! + + + + 4.4BSD-Lite + + Computer Systems Research Group (CSRG) + + Uniwersytet Kalifornijski w Berkeley + FreeBSD jest oparty na systemie 4.4BSD-Lite pochodz±cym + z Computer Systems Research Group (CSRG) z Uniwersytetu + Kalifornijskiego w Berkeley. Podtrzymuje dostojn± tradycjê + trendu rozwojowego systemów BSD. Oprócz doskona³ej pracy + wykonanej przez CSRG równie¿ programi¶ci z Projektu FreeBSD + spêdzili dodatkowe tysi±ce godzin, aby udoskonaliæ go i + przygotowaæ na trudne, ¿yciowe sytuacje. W czasie gdy wielu + z komercyjnych gigantów bran¿y komputerów PC stara siê + wyposa¿yæ swoje systemy operacyjne w podobne cechy, by + osi±gn±æ takie same wyniki i poziom niezawodno¶ci, FreeBSD + oferuje to ju¿ teraz! + + Liczba aplikacji z którymi mo¿e wspó³pracowaæ FreeBSD + jest ograniczona jedynie przez nasz± wyobra¼niê. Od projektów + programistycznych, poprzez automatyzacjê produkcji w fabrykach, + kontrolê stanu magazynów, po regulacjê azymutu anteny satelitarnej; + je¶li jest to mo¿liwe w komercyjnych systemach UNIX jest to wiêcej + ni¿ prawdopodobne, ¿e mo¿esz to zrobiæ równie¿ we FreeBSD! On sam + korzysta z dos³ownie tysiêcy doskonale dopracowanych aplikacji, + nierzadko pochodz±cych z komercyjnych centrów projektowych b±d¼ + laboratoriów uniwersyteckich, dostêpnych niemal¿e b±d¼ ca³kowicie + za darmo. Dostêpne jest równie¿ oprogramowanie komercyjne, którego + liczba ro¶nie równie szybko, jak oprogramowania bezp³atnego. + + Jako, ¿e kod ¼ród³owy FreeBSD jest publicznie dostêpny, + system mo¿e zostaæ dostosowany do wielu specjalistycznych + projektów oraz zastosowañ, co jest niemo¿liwe w przypadku + wielu systemów komercyjnych. Oto krótka lista aplikacji, + z którymi najczê¶ciej u¿ywany jest FreeBSD: + + + + Us³ugi internetowe: doskona³a obs³uga + TCP/IP wbudowana we FreeBSD, czyni go idealn± platform± dla + szeregu us³ug internetowych, na przyk³ad: + + + serwery FTP + + Serwery FTP + + + serwery WWW + + Serwery witryn WWW (standardowe b±d¼ zabezpieczone + [SSL]) + + + zapora ogniowa + NAT + + Zapory ogniowe i bramy NAT (maskarada + IP) + + + + poczta elektroniczna + email + + + email + + + Serwery poczty elektronicznej + + + USENET + + USerwery USENET b±d¼ systemy Forum + + + + I wiêcej... + + + + Wraz z FreeBSD mo¿esz zacz±æ ¶wiadczyæ us³ugi + internetowe ju¿ na niedrogim komputerze PC klasy 386 + i rozwijaæ bazê sprzêtow± swojego przedsiêbiorstwa a¿ do + cztero-procesorowego Xeona z macierz± RAID. + + + + Edukacja: jeste¶ studentem + informatyki b±d¼ pokrewnej dziedziny techniki? Nie ma + lepszego sposobu na poznanie systemu operacyjnego, + architektury komputerów oraz zagadnieñ sieciowych ni¿ + poprzez do¶wiadczenie, które daje praca z FreeBSD. Du¿a + liczba darmowych programów typu CAD, matematycznych czy + graficznych bêdzie wysoce u¿yteczna dla tych, których + g³ównym zainteresowaniem w komputerach jest aby zmusiæ je do pracy + za nas! + + + + Badania: oferuj±c dostêp do kodu + ¼ród³owego ca³ego systemu, FreeBSD stanowi doskona³± platformê + dla prowadzenia badañ nad systemami operacyjnymi oraz innymi + dziedzinami nauk komputerowych. Idea otwartego ¼ród³a wspomaga + tak¿e ca³e grupy wspó³pracuj±ce zdalnie nad ró¿nymi zadaniami, + pomagaj±c zapomnieæ im o problemach zwi±zanych ze specjalnymi + warunkami licencyjnymi oraz ograniczeniami. + + + ruter + Serwer DNS + + Sieæ: potrzebujesz nowego rutera? + Serwera nazw (DNS)? Zapory ogniowej (firewalla), by wystrzec + siê niepowo³anych u¿ytkowników w swojej sieci wewnêtrznej? + FreeBSD mo¿e w ³atwy sposób zamieniæ bezu¿ytecznego 486 lub + nawet 386, stoj±cego w k±cie, w zaawansowany router z + wyszukanymi opcjami filtrowania pakietów. + + + + System okien X + XFree86 + + + System okien X + Akceleracja X-ów + + + ¦rodowisko graficzne: FreeBSD stanowi + dobre rozwi±zanie dla niedrogiego terminala graficznego. W tym + celu mo¿na wykorzystaæ dostêpny serwer X11, b±d¼ jeden z doskona³ych + komercyjnych serwerów Xi Graphics. W przeciwieñstwie do + typowych terminali graficznych, FreeBSD pozwala na uruchamianie + wielu aplikacji lokalnie je¶li zajdzie taka potrzeba, odci±¿aj±c + tym samym g³ówny serwer. FreeBSD mo¿e byæ równie¿ uruchamiany w + systemach bezydskowych zmniejszaj±c tym samym cenê + komputerów s³u¿±cych za terminale. + + + Kolekcja kompilatorów GNU + + Programowanie: system FreeBSD zaopatrzony + jest w pe³en zestaw narzêdzi programistycznych, w³±czaj±c w to + s³awny kompilator oraz debugger GNU C/C++. + + + + FreeBSD jest dostêpny zarówno w postaci kodu ¼ród³owego jak i + skompilowanych binariów dostêpnych na p³ytach CDROM, DVD i poprzez + anonimowy serwer FTP. zawiera wiêcej informacji + nt. sposobów uzyskania FreeBSD. + + + + Kto u¿ywa FreeBSD? + + + u¿ytkownicy + du¿e witryny WWW pracuj±ce na FreeBSD + + + FreeBSD zasila niektóre z najwiêkszych witryn w Internecie, + m.in: + + + Yahoo! + + Yahoo! + + + Apache + + Apache + + + Blue Mountain Arts + + Blue Mountain + Arts + + + Pair Networks + + Pair + Networks + + + Sony Japan + + Sony + Japan + + + Netcraft + + Netcraft + + + + Weathernews + + Weathernews + + + Supervalu + + Supervalu + + + TELEHOUSE America + + TELEHOUSE + America + + + Sophos Anti-Virus + + Sophos + Anti-Virus + + + JMA Wired + + JMA Wired + + + + i wiele wiêcej. + + + + + + O Projekcie FreeBSD + + Niniejszy podrozdzia³ zawiera podstawowe informacje o projekcie, + m.in. krótk± historiê, cele stawiane przed projektem i stosowany + model rozwoju. + + + + + + Jordan + Hubbard + Napisa³ + + + + + Krótka historia FreeBSD + + 386BSD Patchkit + Hubbard, Jordan + Williams, Nate + Grimes, Rod + + FreeBSD Project + history + + Genezy projektu FreeBSD nale¿y doszukiwaæ siê w pierwszej + po³owie roku 1993. Wyrós³ on czê¶ciowo z Nieoficjalnego + zestawu ³at dla 386BSD (patchkit). Stworzony zosta³ przez + trzech ostatnich koordynatorów zestawu: Nate'a Williamsa, Roda + Grimesa i mnie. + + 386BSD + Naszym pierwotnym celem by³o przygotowanie migawki z rozwoju + 386BSD, wprowadzaj±cej szereg poprawek, których mechanizm zestawu + ³at nie by³ w stanie zrealizowaæ. Niektórzy z czytaj±cych mog± + pamiêtaæ wczesn± nazwê projektu 386BSD 0.5 b±d¼ + 386BSD Interim. + + Jolitz, Bill + 386BSD by³ systemem operacyjnym Billa Jolitza, cierpi±cym w + tym okresie z powodu przesz³o rocznego zastoju. W wyniku puchniêcia + zestawu ³at z dnia na dzieñ coraz bardziej, jednomy¶lnie postanowili¶my + spróbowaæ naprawiæ sytuacjê. Zdecydowali¶my siê wspomóc Billa + dostarczaj±c owej porz±dkuj±cej migawki. Niestety + plan spali³ na panewce gdy Bill Jolitz nagle zdecydowa³ cofn±æ swoje + poparcie dla projektu, nie informuj±c co zamierza wprowadziæ + w jego miejsce. + + Greenman, David + Walnut Creek CDROM + Szybko stwierdzili¶my, ¿e rozpoczête zadanie jest warte ¶wieczki + nawet bez wsparcia Billa. Tym samym przyjêli¶my nazwê + FreeBSD ukut± przez Davida Greenmana. Cele + projektu zosta³y wstêpnie okre¶lone po rozmowach z ówczesnymi + u¿ytkownikami systemu. Gdy sta³o siê jasne, ¿e projekt zmierza + w kierunku stania siê rzeczywisto¶ci±, skontaktowa³em siê z + firm± Walnut Creek CDROM w celu usprawnienia metod dystrybucji + FreeBSD, szczególnie z my¶l± o tych nieszczê¶nikach, którzy mieli + utrudniony dostêp do Internetu. Walnut Creek CDROM nie tylko wspar³ + pomys³ dystrybucji FreeBSD na p³ytach CD, ale równie¿ wyszed³ nam + na przeciw oferuj±c projektowi maszynê do pracy i szybkie ³±cze + z Internetem. Jest ma³o prawdopodobne, ¿e projekt zaszed³ by a¿ + tak daleko bez niespotykanej wrêcz wiary Walnut Creek CDROM w + kompletnie ma³o znany projekt, którym w owym czasie by³ + FreeBSD. + + 4.3BSD-Lite + Net/2 + Uniwersytet Kalifornijski w Berkeley + 386BSD + Free Software Foundation + Pierwsz± wersj± rozprowadzan± na p³ytach CD (a tak¿e w + Internecie) by³ FreeBSD 1.0, wydany w grudniu 1993 r. + Oparty by³ on bezpo¶rednio na 4.3BSD-Lite (Net/2) + z Uniwersytetu Kalifornijskiego w Berkeley. Zawiera³ równie¿ wiele + dodatkowych aplikacji pochodoz±cych z 386BSD oraz Free Software + Foundation. Mo¿na przyj±æ, i¿ osi±gna³ on ca³kiem rozs±dny sukces + jak na pierwsz± wersjê. Nastêpuj±ce po nim wydanie FreeBSD 1.1 + w maju 1994 r. by³o pe³nym sukcesem. + + Novell + Uniwersytet Kalifornijski w Berkeley + Net/2 + AT&T + Mniej wiêcej w tym w³a¶nie czasie czarne chmury niespodzianie + pojawi³y siê nad horyzontem. Powodem tego by³a ugoda w + przeci±gaj±cym siê procesie pomiêdzy Novellem i Uniwersytetem + w Berkeley odno¶nie legalno¶ci kalifornijskiego Net/2. Jednym z + warunków ugody by³o ustêpstwo Berkeley stwierdzaj±ce, i¿ znaczne + czê¶ci kodu Net/2 zosta³y powielone z kodu systemu &unix;, + bêd±cego w³asno¶ci± Novella, który z kolei naby³ go wcze¶niej od AT&T. + W zamian Berkley uzyska³o b³ogos³awieñstwo Novella w + pracach nad 4.4BSD-Lite i zapewnienie, ¿e gdy siê w koñcu pojawi nie + bêdzie okre¶lane jako kopia kodu Novella. Ponadto wszyscy u¿ytkownicy + Net/2 mieli byæ gor±co zachêciani do aktualizacji systemu. Ugoda ta + dotyczy³a równie¿ FreeBSD, bowiem projekt mia³ wstrzymaæ dystrybucjê + swoich produktów bazuj±cych na Net/2 do koñca lipca 1994 r. Zgodnie + z warunkami porozumienia, pozwolono projektowi na jedno ostatnie + wydanie przed tym terminem. By³o to FreeBSD 1.1.5.1. + + Rozpoczê³a siê ¿mudna praca nad ponownym stworzeniem FreeBSD + z czê¶ci ca³kowicie nowego i raczej niekompletnego 4.4BSD-Lite. + Wydanie Lite by³o w rzeczy samej lekkie; + czê¶ciowo w wyniku usuniêcia przez CSRG Uniwersytetu w Berkeley + wielkich partii kodu (z uwagi na pewne wymogi prawne), które odpowiada³y + za przygotowanie samodzielnie uruchamiajacego siê systemu, oraz z faktu, + ¿e wersja 4.4 nie byla jeszcze gotowa na platformê Intela. Prace potrwa³y + do listopada 1994 r., kiedy to wydany zosta³ FreeBSD 2.0, rozprowadzany + zarówno przez sieæ jak i na p³ytach CD (w pó¼nym grudniu). Pomimo kilku + niedoci±gniêæ wydanie osi±gne³o znacz±cy sukces. Przy czym ju¿ w + styczniu 1995 r. zosta³o zast±pione stabilniejszym i ³atwiejszym w + instalacji FreeBSD 2.0.5. + + FreeBSD 2.1.5 wydali¶my w sierpniu 1996. Wersja ta zyska³a + popularno¶æ szczególnie po¶ród dostawców us³ug internetowych (ISP) + oraz szerokopojêtej spo³eczno¶ci komercyjnej. Docenione zosta³o + równie¿ kolejne wydanie w ga³êzi 2.1-STABLE. Mowa tu o + FreeBSD 2.1.7.1, wydanym w lutym 1997 r., a zamykaj±cym g³ówne + prace nad 2.1-STABLE. Od tej pory trwa³y jedynie prace nad utrzymaniem + ga³êzi (RELENG_2_1_0); dodawane by³y ³aty bezpieczeñstwa i naprawiane + krytyczne luki./para> + + Z g³ównego nurtu rozwojowu (-CURRENT) w listopadzie + 1996 r. odga³êzi³ siê FreeBSD 2.2 jako ga³±¼ RELENG_2_2. + Piersze pe³ne wydanie (2.2.1) pojawi³o siê w kwietniu 1997 r. + Kolejne wydania z ga³êzi 2.2 ujrza³y ¶wiat³o dzienne w lecie i na + jesieni 1997 r., przy czym ostatnie (2.2.8) pojawi³o siê w listopadzie + 1998 r. Pierwsze oficjalne wydanie 3.0 pochodzi z pa¼dziernika + 1998 r. i stanowi³o pocz±tek koñca ga³êzi 2.2. + + Drzewo ewolucji FreeBSD ponownie rozdzieli³o siê 20 stycznia + 1999 r., prowadz±c do 4.0-CURRENT i 3.X-STABLE. Wersja 3.1 z 3.X-STABLE + wydana zosta³a 15 lutego 1999, wersja 3.2 dnia 15 maja 1999, 3.3 w dniu + 16 wrze¶nia 1999, 3.4 - 20 grudnia 1999 oraz 3.5 dnia 24 stycznia 2000. + Wkrótce pojawi³o siê równie¿ pomniejsze wydanie 3.5.1, które zawiera³o + kilka poprawek z ostatniej chwili do systemu Kerberos. By³o to ostatnie + wydanie ga³êzi 3.X. + + Kolejne rozga³êzienie mia³o miejsce 13 marca 2000 r. w wyniku czego + pojawi³a siê ga³±¼ 4.X-STABLE: 4.0-RELEASE w marcu 2000 i ostatnie + wydanie 4.11-RELEASE w styczniu 2005. + + Pojawienie siê d³ugo oczekiwanej ga³êzi 5.0-RELEASE zosta³o og³oszone + 19 stycznia 2003 r. Stanowi³a ona punkt kulminacyjny prawie + trzyletniego wysi³ku. Wydanie te wprowadzi³o FreeBSD na ¶cie¿kê ku + wspó³pracy z komputerami multiprocesorowymi oraz zaawansowanej + obs³ugi w±tków aplikacji. Oferowa³a równie¿ wsparcie dla platform + &ultrasparc; i ia64. Wydanie 5.1 pojawi³o siê w + czerwcu 2003 r. Ostatnie wydanie 5.X z ga³êzi -CURRENT stanowi³o + 5.2.1-RELEASE, wprowadzone w lutym 2004. + + Ga³±¼ RELENG_5 powsta³a w sierpniu 2004 r., a tak¿e wydanie + 5.3-RELEASE, stanowi pocz±tek wydañ ga³êzi 5-STABLE. Najnowsze wydanie + &rel2.current;-RELEASE pojawi³o siê w maju 2006. Wydawane bêd± + wci±¿ kolejne wersje z ga³êzi RELENG_5. + + Kolejne rozga³êzienie nast±pi³o w czerwcu 2005: powsta³a ga³±¼ + RELENG_6. Wydanie 6.0-RELEASE, pierwsze z ga³êzi 6.X, pojawi³o siê + w listopadzie 2005. Najnowsze wydanie &rel.current;-RELEASE ujrza³o + ¶wiat³o dzienne w maju 2006 r. Bêd± pojawiaæ siê równie¿ kolejne + wydania z ga³êzi RELENG_6. + + Na chwilê obecn± projekty d³ugoterminowe prowadzone s± w ga³êzi + 7.X-CURRENT. Migawki wydañ 7.X, obrazuj±ce postêp prac, s± ca³y + czas dostêpne z + serwera + migawkowego jak równie¿ na p³ytach CD. + + + + + + + Jordan + Hubbard + Napisa³ + + + + + Cele Projektu FreeBSD + + + FreeBSD Project + goals + + G³ównym celem Projektu FreeBSD jest dostarczanie + oprogramowania, które mo¿e byæ wykorzystane w dowolny sposób + i bez dodatkowych zobowi±zañ. Wielu z nas ma du¿y wk³ad w tworzenie + kodu (i rozwój projektu w ogóle) i z pewno¶ci± nie mia³oby nic + przeciw drobnemu wsparciu finansowemu. Tym nie mniej nie wywieramy + ¿adnego nacisku. Wierzymy, ¿e nasz± pierwsz± i najwa¿niejsz± + misj± jest dostarczanie kodu wszystkim tym, ktorzy + go potrzebuj± bez wzglêdu na to do czego go wykorzystaj±, by zyska³ + on mo¿liwie najszersz± bazê u¿ytkowników dostarczaj±c mo¿liwie + najwiêkszych korzy¶ci. W moim przekonaniu jest to jeden z najbardziej + fundamentalnych celów stawianych przed ca³ym Wolnym Oprogramowaniem, + a przez nas entuzjastycznie wspierany. + + + GNU General Public License (GPL) + + + GNU Lesser General Public License (LGPL) + + BSD Copyright + Te czê¶ci kodu w naszym drzewie ¼ród³owym, które udostêpniane + s± na licencji GNU General Public License (GPL) b±d¼ Library General + Public License (LGPL) posiadaj± kilka dodatkowych zobowi±zañ, choæ + zwi±zanych raczej z wymogiem udostêpnienia kodu ¼ród³owego. Z uwagi + na dodatkowe komplikacje, które mog± pojawiæ siê w przypadku + komercyjnego zastosowania aplikacji na licencji GPL, osobi¶cie + sk³aniamy siê - kiedy jest to mo¿liwe - ku oprogramowaniu + dystrybuowanemu przy wykorzystaniu mniej restrykcyjnej licencji + BSD. + + + + + + + Satoshi + Asami + Napisa³ + + + + + Model rozwoju FreeBSD + + + Projekt FreeBSD + model rozwoju + + Rozwój FreeBSD jest otwartym i elastycznym procesem + realizowanym przez setki ludzi na ca³ym ¶wiecie (patrz + Lista + wspó³pracowników). Infrastruktura systemu rozwoju + FreeBSD pozwala tym¿e setkom projektantów wspó³pracowaæ przez + Internet. Tym nie mniej nieustannie poszukujemy nowych + projektantów, a tak¿e nowych pomys³ów. Osoby zainteresowane + nawi±zaniem bli¿szej wspó³pracy z projektem mog± kontaktowaæ + siê z nami bezpo¶rednio poprzez &a.pl.hackers.b;. Natomiast + &a.pl.announce.m; jest równie¿ dostêpna dla osób chc±cych + poinformowaæ innych u¿ytkowników FreeBSD o g³ównych + obszarach prowadzonych prac. + + Oto gar¶æ informacji o projekcie FreeBSD i jego procesie + rozwoju, przydatnych zarówno niezale¿nym projektantom jak + i bliskim wspó³pracownikom: + + + + Repozytorium CVS + + + CVS + repozytorium + + + Concurrent Versions System + CVS + + + G³ówne drzewo ¼ród³owe FreeBSD utrzymywane jest w systemie + CVS + (Concurrent Versions System) - wolnodostêpnym narzêdziu + kontroli wersji kodu ¼ród³owego, dostêpnym we FreeBSD. + Podstawowe repozytorium + CVS znajduje siê na maszynie zlokalizowanej w Santa Clara w Kalifornii, + USA, sk±d replikowane jest na serwery lustrzane, rozrzucone po + ca³ym ¶wiecie. G³ówne drzewo CVS, zawieraj±ce zarówno drzewo + -CURRENT jak i -STABLE, mo¿na ³atwo skopiowaæ równie¿ + na swój w³asny komputer. Proces ten zosta³ dok³adniej opisany + w podro¼dziale Synchronizacja w³asnego + drzewa kodu ¼ród³owego. + + + + + Lista twórców + + twórcy + + Twórcy s± lud¼mi, którzy posiadaj± prawa + zapisu do drzewa CVS i posiadaj± upowa¿nienie do wprowadzania + modyfikacji do kodu ¼ród³owego FreeBSD. Angielski odpowiednik + terminu twórca (ang. committer) pochodzi od + polecenia commit systemu &man.cvs.1;, + stosowanego do wprowadzania zmian do repozytorium CVS. + Najlepszym sposobem przedstawienia w³asnych propozycji na li¶cie + dyskusyjnej twórców jest wykorzystanie polecenia &man.send-pr.1;. + Je¶li system sprawia wra¿enie zablokowanego mo¿na równie¿ wys³aæ + e-mail bezpo¶rednio na &a.pl.committers.b;. + + + + + G³ówni projektanci FreeBSD + + zespó³ g³ówny + + Porównuj±c Projekt FreeBSD z przedsiêbiorstwem, + zespó³ g³ówny nale¿a³oby porównaæ + z zarz±dem firmy. Podstawowym zadaniem tej¿e grupy jest + czuwanie nad prawid³owym rozwojem projektu jako ca³o¶ci. + Jedn± z funkcji grupy jest zapraszanie oddanych i odpowiedzialnych + projektantów w szeregi twórców systemu, podobnie jak przyjmowanie + w szeregi samej grupy. Obecna grupa zosta³a wybrana spo¶ród + wszystkich twórców w czerwcu 2004 r. Wybory maj± miejsce co + dwa lata. + + Niektórzy z cz³onków grupy posiadaj± równie¿ dodatkowy + zakres obowi±zków, tj. czuwaj± nad zapewnieniem poprawnego + funkcjonowania wybranych czê¶ci systemu. Pe³na lista projektantów + FreeBSD i ich obowi±zków dostêpna jest w artykule Lista + wspó³pracowników. + + + Wiêkszo¶æ cz³onków grupy jest ochotnikami, je¶li + chodzi o rozwój FreeBSD, i nie otrzymuj± ¿adnego wynagrodzenia + finansowwego z projektu. Nie nale¿y zatem b³êdnie + interpretowaæ wspó³pracy z projektem jako + gwarancji wsparcia. W tym ¶wietle, powy¿sze + porównanie z zarz±dem nie jest do koñca celne. + Bardziej odpowiednim by³oby powiedzieæ, ¿e s± to ludzie, + którzy z w³asnego wyboru oddali swój wolny czas dla + FreeBSD! + + + + + + Zewnêtrzni wspó³pracownicy + + wspó³pracownicy + + Co prawda jako ostatnia, ale zdecydowanie nie jako + najmniej istotna, omówiona zostanie grupa wspó³pracowników + zewnêtrznych, czyli samych u¿ytkowników, którzy dostarczaj± + na bie¿±co informacji o funkcjonowaniu systemu oraz poprawek + wykrytych b³êdów. Najlepszym sposobem na udzia³ w rozwoju + FreeBSD jest subskrypcja &a.pl.hackers.d;. zawiera wiêcej informacji o ró¿norodnych + listach dyskusyjnych FreeBSD. + + Lista wspó³pracowników + FreeBSD ca³y czas ro¶nie. Czemu by nie do³±czyæ + do listy pomagaj±c w pracy nad FreeBSD ju¿ dzisiaj? + + Pisanie kodu nie jest jedyn± form± wspó³pracy z projektem: + kompletna lista rzeczy, które trzeba zrobiæ dostêpna jest na + stronie Projektu + FreeBSD. + + + + + Reasumuj±c, nasz model rozwoju zorganizowany jest jako niezale¿ne, + wspó³centryczne okrêgi. Zcentralizowany model ma za zadanie u³atwiæ + u¿ytkownikom FreeBSD ¶ledzenie zmian w kodzie. + Odstraszanie potencjalnych wspó³pracowników nie jest naszym celem! + Pragniemy dostarczaæ stabilny system operacyjny z du¿± baz± ³atwych + do instalacji i wykorzystania programów + — ten model doskonale siê w tym spisuje. + + Jedyne o co prosimy tych, którzy mieliby wst±piæ w szeregi + projektantów FreeBSD, jest oddanie takie same jakie cechuje ich + obecnych twórców. + + + + Aktualne wydanie FreeBSD + + NetBSD + OpenBSD + 386BSD + Free Software Foundation + Uniwersytet Kalifornijski w Berkeley + + Computer Systems Research Group (CSRG) + + FreeBSD jest ³atwo dostêpnym systemem operacyjnym, bazuj±cym + na kodzie 4.4BSD-Lite, dla nastêpuj±cych platform sprzêtowych: + Intel &i386;, &i486;, &pentium;, + &pentium; Pro, + &celeron;, + &pentium; II, + &pentium; III, + &pentium; 4 (b±d¼ inny zgodny), + &xeon;, DEC Alpha + oraz Sun &ultrasparc;. Opiera siê on przede wszystkim na oprogramowaniu + grupy CSRG z Uniwersytetu Kalifornijskiego w Berkeley, rozszerzonym o dodatkowe + elementy z NetBSD, OpenBSD, 386BSD i Free Software Foundation. + + Pocz±wszy od wydania FreeBSD 2.0 w koñcu 1994 r., nast±pi³a + dramatyczna poprawa wydajno¶ci, mo¿liwo¶ci i stabilno¶ci systemu. + + + Najwiêksz± zmian± by³a ca³kowita reformacja systemu wirtualnej pamiêci + wraz ze wspó³dzielon± pamiêci± podrêczn± VM/buffer cache, + która nie tylko wp³ynê³a na wzrost wydajno¶ci ale równie¿ zmniejszenie + minimalnego miejsca zajmowanego w pamiêci przez FreeBSD — + 5 MB jest ju¿ akceptowalnym minimum. Inne rozszerzenia to m.in. + kompletna obs³uga klienta i serwera NIS, wsparcie dla transakcji TCP, + wdzwanianie na ¿±danie PPP, zintegrowana obs³uga DHCP, usprawniony + podsystem SCSI, obs³uga ISDN, ATM, FDDI, Fast i Gigabit Ethernet + (100 i 1000 Mbit). Usprawniona obs³uga najnowszych kontrolerów + Adaptec i tysi±ce poprawionych b³êdów. + + Oprócz podstawowej grupy aplikacji dystrybuowanych wraz z + systemem, FreeBSD oferuje kolekcjê tysiêcy dodatkowych programów. + W momencie pisania niniejszego tekstu ich lista obejmuje ponad &os.numports; + pozycji! Od serwerów http (WWW) poprzez gry po edytory i prawie wszystko + pomiêdzy. Ca³a Kolekcja Portów zajmuje oko³o &ports.size; na dysku, przy + czym ka¿dy port to zaledwie u³amek oryginalnej objêto¶ci ¼róde³. Takie + rozwi±zanie u³atwia man aktualizacjê portów i zdecydowanie zmniejsza + zajmowan± przestrzeñ na dysku. Kompilacja portu sprowadza siê do zmiany + katalogu na zawieraj±cy port wybranego programu i wpisanie + make install. Reszt± zajmuje siê system. Oryginalne + pakiety ¼róde³ dla ka¿dego kompilowanego portu pobierane s± dynamicznie z + p³yty CDROM b±d¼ lokalnego serwera FTP. Wystarczy zadbaæ o dostateczn± + ilo¶æ wolnego miejsca na dysku. Dla osób nie maj±cych ochoty kompilowaæ + programów w³asnorêcznie, wiêkszo¶æ portów jest równie¿ dostêpna w + skompilowanej postaci jako pakiety, które mog± byæ + instalowane przy pomocy prostego polecenia pkg_add. + Wiêcej informacji o systemie pakietów i portów zawiera . + + Dodatkowe dokumenty pomocne przy instalacji i u¿ytkowaniu FreeBSD + znajduj± siê równie¿ w katalogu /usr/share/doc + na maszynach z najnowszymi wersjami FreeBSD. Mog± byæ przegl±dane + lokalnie za pomoc± przegl±darki internetowej przy wykorzystaniu + poni¿szych odno¶ników: + + + + Podrêczki FreeBSD (ang.) + + + /usr/share/doc/handbook/index.html + + + + + FAQ FreeBSD (ang.) + + + /usr/share/doc/faq/index.html + + + + + G³ówne i najczê¶ciej aktualizowane wersje dokumentów dostêpne + s± na stronie . + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/kernelconfig/Makefile b/pl_PL.ISO8859-2/books/handbook/kernelconfig/Makefile new file mode 100644 index 0000000000..95839d340a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/kernelconfig/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= kernelconfig/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/kernelconfig/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/kernelconfig/chapter.sgml new file mode 100644 index 0000000000..f0b1569432 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/kernelconfig/chapter.sgml @@ -0,0 +1,1432 @@ + + + + + + + Jim + Mock + Updated and restructured by + + + + + + Jake + Hamby + Originally contributed by + + + + + + Configuring the FreeBSD Kernel + + + Synopsis + + + kernel + building a custom kernel + + + The kernel is the core of the &os; operating system. It is + responsible for managing memory, enforcing security controls, + networking, disk access, and much more. While more and more of &os; + becomes dynamically configurable it is still occasionally necessary to + reconfigure and recompile your kernel. + + After reading this chapter, you will know: + + + + Why you might need to build a custom kernel. + + + + How to write a kernel configuration file, or alter an existing + configuration file. + + + + How to use the kernel configuration file to create and build a + new kernel. + + + + How to install the new kernel. + + + + How to troubleshoot if things go wrong. + + + + All of the commands listed within this chapter by way of example + should be executed as root in order to + succeed. + + + + Why Build a Custom Kernel? + + Traditionally, &os; has had what is called a + monolithic kernel. This means that the kernel was one + large program, supported a fixed list of devices, and if you wanted to + change the kernel's behavior then you had to compile a new kernel, and + then reboot your computer with the new kernel. + + Today, &os; is rapidly moving to a model where much of the + kernel's functionality is contained in modules which can be + dynamically loaded and unloaded from the kernel as necessary. + This allows the kernel to adapt to new hardware suddenly + becoming available (such as PCMCIA cards in a laptop), or for + new functionality to be brought into the kernel that was not + necessary when the kernel was originally compiled. This is + known as a modular kernel. + + Despite this, it is still necessary to carry out some static kernel + configuration. In some cases this is because the functionality is so + tied to the kernel that it can not be made dynamically loadable. In + others it may simply be because no one has yet taken the time to write a + dynamic loadable kernel module for that functionality. + + Building a custom kernel is one of the most important rites of + passage nearly every BSD user must endure. This process, while + time consuming, will provide many benefits to your &os; system. + Unlike the GENERIC kernel, which must support a + wide range of hardware, a custom kernel only contains support for + your PC's hardware. This has a number of + benefits, such as: + + + + Faster boot time. Since the kernel will only probe the + hardware you have on your system, the time it takes your system to + boot can decrease dramatically. + + + + Lower memory usage. A custom kernel often uses less memory + than the GENERIC kernel, which is important + because the kernel must always be present in real + memory. For this reason, a custom kernel is especially useful + on a system with a small amount of RAM. + + + + Additional hardware support. A custom kernel allows you to + add in support for devices which are not + present in the GENERIC kernel, such as + sound cards. + + + + + + Building and Installing a Custom Kernel + + kernel + building / installing + + + First, let us take a quick tour of the kernel build directory. + All directories mentioned will be relative to the main + /usr/src/sys directory, which is also + accessible through the path name /sys. There are a number of + subdirectories here representing different parts of the kernel, but + the most important for our purposes are + arch/conf, where you + will edit your custom kernel configuration, and + compile, which is the staging area where your + kernel will be built. arch represents + one of i386, alpha, + amd64, ia64, + powerpc, sparc64, or + pc98 (an alternative development branch of PC + hardware, popular in Japan). Everything inside a particular + architecture's directory deals with that architecture only; the rest + of the code is machine independent code common to all platforms to which &os; could + potentially be ported. Notice the logical organization of the + directory structure, with each supported device, file system, and + option in its own subdirectory. + + This chapter assumes that you are using the i386 architecture + in the examples. If this is not the case for your situation, + make appropriate adjustments to the path names for your system's + architecture. + + + If there is not a + /usr/src/sys directory on your system, + then the kernel source has not been installed. The easiest + way to do this is by running + sysinstall as + root, choosing + Configure, then + Distributions, then + src, then + sys. If you have an aversion to + sysinstall and you have access to + an official &os; CDROM, then you can also + install the source from the command line: + + &prompt.root; mount /cdrom +&prompt.root; mkdir -p /usr/src/sys +&prompt.root; ln -s /usr/src/sys /sys +&prompt.root; cat /cdrom/src/ssys.[a-d]* | tar -xzvf - + + + Next, move to the + arch/conf directory + and copy the GENERIC configuration file to the + name you want to give your kernel. For example: + + &prompt.root; cd /usr/src/sys/i386/conf +&prompt.root; cp GENERIC MYKERNEL + + Traditionally, this name is in all capital letters and, if you + are maintaining multiple &os; machines with different hardware, + it is a good idea to name it after your machine's hostname. We will + call it MYKERNEL for the purpose of this + example. + + + Storing your kernel configuration file directly under + /usr/src can be a bad idea. If you are + experiencing problems it can be tempting to just delete + /usr/src and start again. After doing this, + it usually only takes a few seconds for + you to realize that you have deleted your custom kernel + configuration file. Also, do not edit GENERIC + directly, as it may get overwritten the next time you + update your source tree, and + your kernel modifications will be lost. + + You might want to keep your kernel configuration file + elsewhere, and then create a symbolic link to the file in + the i386 + directory. + + For example: + + &prompt.root; cd /usr/src/sys/i386/conf +&prompt.root; mkdir /root/kernels +&prompt.root; cp GENERIC /root/kernels/MYKERNEL +&prompt.root; ln -s /root/kernels/MYKERNEL + + + Now, edit MYKERNEL with your favorite text + editor. If you are just starting out, the only editor available + will probably be vi, which is too complex to + explain here, but is covered well in many books in the bibliography. However, &os; does + offer an easier editor called ee which, if + you are a beginner, should be your editor of choice. Feel free to + change the comment lines at the top to reflect your configuration or + the changes you have made to differentiate it from + GENERIC. + SunOS + + If you have built a kernel under &sunos; or some other BSD + operating system, much of this file will be very familiar to you. + If you are coming from some other operating system such as DOS, on + the other hand, the GENERIC configuration file + might seem overwhelming to you, so follow the descriptions in the + Configuration File + section slowly and carefully. + + + If you sync your source tree with the + latest sources of the &os; project, + be sure to always check the file + /usr/src/UPDATING before you perform any update + steps. This file describes any important issues or areas + requiring special attention within the updated source code. + /usr/src/UPDATING always matches + your version of the &os; source, and is therefore more up to date + with new information than this handbook. + + + You must now compile the source code for the kernel. There are two + procedures you can use to do this, and the one you will use depends on + why you are rebuilding the kernel and the version of &os; that you are + running. + + + + If you have installed only the kernel + source code, use procedure 1. + + + + If you are building a new kernel without updating the source + code (perhaps just to add a new option, such as + IPFIREWALL) you can use either procedure. + + + + If you are rebuilding the kernel as part of a + make buildworld process, use procedure 2. + + + + + + cvsup + + CTM + + CVS + anonymous + + + If you have not upgraded your source + tree in any way since the last time you successfully completed + a buildworld-installworld cycle + (you have not run CVSup, + CTM, or used + anoncvs), then it is safe to use the + config, make depend, + make, make install sequence. + + + + Procedure 1. Building a Kernel the <quote>Traditional</quote> Way + + + Run &man.config.8; to generate the kernel source code. + + &prompt.root; /usr/sbin/config MYKERNEL + + + + Change into the build directory. &man.config.8; will print + the name of this directory after being run as above. + + &prompt.root; cd ../compile/MYKERNEL + + + + Compile the kernel. + + &prompt.root; make depend +&prompt.root; make + + + + Install the new kernel. + + &prompt.root; make install + + + + + Procedure 2. Building a Kernel the <quote>New</quote> + Way + + + Change to the /usr/src directory. + + &prompt.root; cd /usr/src + + + + Compile the kernel. + + &prompt.root; make buildkernel KERNCONF=MYKERNEL + + + + Install the new kernel. + + &prompt.root; make installkernel KERNCONF=MYKERNEL + + + + + This method of kernel building requires full source files. If you + only installed the kernel source, use the traditional method, as + described above. + + + + By default, when you build a custom kernel, + all kernel modules will be rebuilt as well. + If you want to update a kernel faster or to build only custom + modules, you should edit /etc/make.conf + before starting to build the kernel: + + MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs + + This variable sets up a list of modules to build instead + of all of them. For other variables which you may find useful + in the process of building kernel, refer to &man.make.conf.5; + manual page. + + + + /boot/kernel.old + + + The new kernel will be copied to the /boot/kernel directory as + /boot/kernel/kernel and the old kernel will be moved to + /boot/kernel.old/kernel. Now, shutdown the system and + reboot to use your new kernel. If something goes wrong, there are + some troubleshooting + instructions at the end of this chapter that you may find useful. Be sure to read the + section which explains how to recover in case your new kernel does not boot. + + + Other files relating to the boot process, such as the boot + &man.loader.8; and configuration are stored in + /boot. Third party or custom modules + can be placed in /boot/kernel, although + users should be aware that keeping modules in sync with the + compiled kernel is very important. Modules not intended + to run with the compiled kernel may result in instability + or incorrectness. + + + + + + + + Joel + Dahl + Updated for &os; 6.X by + + + + The Configuration File + + kernel + NOTES + + NOTES + + kernel + configuration file + + + The general format of a configuration file is quite simple. + Each line contains a keyword and one or more arguments. For + simplicity, most lines only contain one argument. Anything + following a # is considered a comment and + ignored. The following sections describe each keyword, in + the order they are listed in GENERIC. + For an exhaustive list of architecture + dependent options and devices, see the NOTES + file in the same directory as the GENERIC file. For + architecture independent options, see + /usr/src/sys/conf/NOTES. + + + To build a file which contains all available options, + as normally done for testing purposes, run the following + command as root: + + &prompt.root; cd /usr/src/sys/i386/conf && make LINT + + + + kernel + configuration file + + + The following is an example of the GENERIC kernel + configuration file with various additional comments where needed for + clarity. This example should match your copy in + /usr/src/sys/i386/conf/GENERIC + fairly closely. + + + kernel options + machine + + + machine i386 + + This is the machine architecture. It must be either + alpha, amd64, + i386, ia64, + pc98, powerpc, or + sparc64. + + + kernel options + cpu + + cpu I486_CPU +cpu I586_CPU +cpu I686_CPU + + The above option specifies the type of CPU you have in your + system. You may have multiple instances of the CPU line (if, for + example, you are not sure whether you should use + I586_CPU or I686_CPU), + but for a custom kernel it is best to specify only the CPU + you have. If you are unsure of your CPU type, you can check the + /var/run/dmesg.boot file to view your boot + messages. + + + kernel options + ident + + + ident GENERIC + + This is the identification of the kernel. You should change + this to whatever you named your kernel, + i.e. MYKERNEL if you have followed the + instructions of the previous examples. The value you put in the + ident string will print when you boot up the + kernel, so it is useful to give the new kernel a different name if you + want to keep it separate from your usual kernel (e.g., you want to + build an experimental kernel). + + #To statically compile in device wiring instead of /boot/device.hints +#hints "GENERIC.hints" # Default places to look for devices. + + The &man.device.hints.5; is + used to configure options of the device drivers. The default + location that &man.loader.8; will check at boot time is + /boot/device.hints. Using the + hints option you can compile these hints + statically into your kernel. Then there is no need to create a + device.hints file in + /boot. + + + + makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols + + The normal build process of &os; includes + debugging information when building the kernel with the + the option, which enables debugging + information when passed to &man.gcc.1;. The same can be + accomplished by the &man.config.8; option, if + you are using the traditional way for building your + kernels (see + for more information). + + options SCHED_4BSD # 4BSD scheduler + + The traditional and default system scheduler for &os;. Keep this. + + options PREEMPTION # Enable kernel thread preemption + + Allows threads that are in the kernel to be preempted + by higher priority threads. It helps with interactivity and + allows interrupt threads to run sooner rather than waiting. + + options INET # InterNETworking + + Networking support. Leave this in, even if you do not plan to + be connected to a network. Most programs require at least loopback + networking (i.e., making network connections within your PC), so + this is essentially mandatory. + + options INET6 # IPv6 communications protocols + + This enables the IPv6 communication protocols. + + options FFS # Berkeley Fast Filesystem + + This is the basic hard drive file system. Leave it in if you + boot from the hard disk. + + options SOFTUPDATES # Enable FFS Soft Updates support + + This option enables Soft Updates in the kernel, this will + help speed up write access on the disks. Even when this + functionality is provided by the kernel, it must be turned on + for specific disks. Review the output from &man.mount.8; to see + if Soft Updates is enabled for your system disks. If you do not + see the soft-updates option then you will + need to activate it using the &man.tunefs.8; (for existing + file systems) or &man.newfs.8; (for new file systems) + commands. + + options UFS_ACL # Support for access control lists + + This option enables kernel support + for access control lists. This relies on the use of extended + attributes and UFS2, and the feature is described + in detail in . ACLs are + enabled by default and should not be + disabled in the kernel if they have been used previously on a file + system, as this will remove the access control lists, changing the + way files are protected in unpredictable ways. + + options UFS_DIRHASH # Improve performance on big directories + + This option includes functionality to speed up disk + operations on large directories, at the expense of using + additional memory. You would normally keep this for a large + server, or interactive workstation, and remove it if you are + using &os; on a smaller system where memory is at a premium and + disk access speed is less important, such as a firewall. + + options MD_ROOT # MD is a potential root device + + This option enables support for a memory backed virtual disk + used as a root device. + + + kernel options + NFS + + + kernel options + NFS_ROOT + + options NFSCLIENT # Network Filesystem Client +options NFSSERVER # Network Filesystem Server +options NFS_ROOT # NFS usable as /, requires NFSCLIENT + + The network file system. Unless you plan to mount partitions + from a &unix; file server over TCP/IP, you can comment these + out. + + + kernel options + MSDOSFS + + options MSDOSFS # MSDOS Filesystem + + The &ms-dos; file system. Unless you plan to mount a DOS formatted + hard drive partition at boot time, you can safely comment this out. + It will be automatically loaded the first time you mount a DOS + partition, as described above. Also, the excellent + emulators/mtools software + allows you to access DOS floppies without having to mount and + unmount them (and does not require MSDOSFS at + all). + + options CD9660 # ISO 9660 Filesystem + + The ISO 9660 file system for CDROMs. Comment it out if you do + not have a CDROM drive or only mount data CDs occasionally (since it + will be dynamically loaded the first time you mount a data CD). + Audio CDs do not need this file system. + + options PROCFS # Process filesystem (requires PSEUDOFS) + + The process file system. This is a pretend + file system mounted on /proc which allows + programs like &man.ps.1; to give you more information on what + processes are running. Use of PROCFS + is not required under most circumstances, as most + debugging and monitoring tools have been adapted to run without + PROCFS: installs will not mount this file + system by default. + + options PSEUDOFS # Pseudo-filesystem framework + + 6.X kernels making use of PROCFS must also + include support for PSEUDOFS. + + options GEOM_GPT # GUID Partition Tables. + + This option brings the ability to have a large number of + partitions on a single disk. + + options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!] + + Compatibility with 4.3BSD. Leave this in; some programs will + act strangely if you comment this out. + + options COMPAT_FREEBSD4 # Compatible with &os;4 + + This option is required on &os; 5.X &i386; and Alpha systems + to support applications compiled on older versions of &os; + that use older system call interfaces. It is recommended that + this option be used on all &i386; and Alpha systems that may + run older applications; platforms that gained support only in + 5.X, such as ia64 and &sparc64;, do not require this option. + + options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI + + This causes the kernel to pause for 5 seconds before probing + each SCSI device in your system. If you only have IDE hard drives, + you can ignore this, otherwise you can try to lower this + number, to speed up booting. Of course, if + you do this and &os; has trouble recognizing your SCSI devices, + you will have to raise it again. + + options KTRACE # ktrace(1) support + + This enables kernel process tracing, which is useful in + debugging. + + options SYSVSHM # SYSV-style shared memory + + This option provides for System V shared memory. The most + common use of this is the XSHM extension in X, which many + graphics-intensive programs will automatically take advantage of for + extra speed. If you use X, you will definitely want to include + this. + + options SYSVMSG # SYSV-style message queues + + Support for System V messages. This option only adds + a few hundred bytes to the kernel. + + options SYSVSEM # SYSV-style semaphores + + Support for System V semaphores. Less commonly used but only + adds a few hundred bytes to the kernel. + + + The option of the &man.ipcs.1; command will + list any processes using each of these System V facilities. + + + options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions + + Real-time extensions added in the 1993 &posix;. Certain + applications in the Ports Collection use these + (such as &staroffice;). + + options KBD_INSTALL_CDEV # install a CDEV entry in /dev + + This option is related to the keyboard. It installs a CDEV entry + in /dev. + + options AHC_REG_PRETTY_PRINT # Print register bitfields in debug + # output. Adds ~128k to driver. +options AHD_REG_PRETTY_PRINT # Print register bitfields in debug + # output. Adds ~215k to driver. + + This helps debugging by printing easier register definitions for + reading. + + options ADAPTIVE_GIANT # Giant mutex is adaptive. + + Giant is the name of a mutual exclusion mechanism (a sleep mutex) + that protects a large set of kernel resources. Today, this is an + unacceptable performance bottleneck which is actively being replaced + with locks that protect individual resources. The + ADAPTIVE_GIANT option causes Giant to be included + in the set of mutexes adaptively spun on. That is, when a thread + wants to lock the Giant mutex, but it is already locked by a thread + on another CPU, the first thread will keep running and wait for the + lock to be released. Normally, the thread would instead go back to + sleep and wait for its next chance to run. If you are not sure, + leave this in. + + + kernel options + SMP + + device apic # I/O APIC + + The apic device enables the use of the I/O APIC for interrupt + delivery. The apic device can be used in both UP and SMP kernels, but + is required for SMP kernels. Add options SMP to + include support for multiple processors. + + device eisa + + Include this if you have an EISA motherboard. This enables + auto-detection and configuration support for all devices on the EISA + bus. + + device pci + + Include this if you have a PCI motherboard. This enables + auto-detection of PCI cards and gatewaying from the PCI to ISA + bus. + + # Floppy drives +device fdc + + This is the floppy drive controller. + + # ATA and ATAPI devices +device ata + + This driver supports all ATA and ATAPI devices. You only need + one device ata line for the kernel to detect all + PCI ATA/ATAPI devices on modern machines. + + device atadisk # ATA disk drives + + This is needed along with device ata for + ATA disk drives. + + device ataraid # ATA RAID drives + + This is needed along with device ata for ATA + RAID drives. + + +device atapicd # ATAPI CDROM drives + + This is needed along with device ata for + ATAPI CDROM drives. + + device atapifd # ATAPI floppy drives + + This is needed along with device ata for + ATAPI floppy drives. + + device atapist # ATAPI tape drives + + This is needed along with device ata for + ATAPI tape drives. + + options ATA_STATIC_ID # Static device numbering + + This makes the controller number static; without this, + the device numbers are dynamically allocated. + + # SCSI Controllers +device ahb # EISA AHA1742 family +device ahc # AHA2940 and onboard AIC7xxx devices +device ahd # AHA39320/29320 and onboard AIC79xx devices +device amd # AMD 53C974 (Teckram DC-390(T)) +device isp # Qlogic family +#device ispfw # Firmware for QLogic HBAs- normally a module +device mpt # LSI-Logic MPT-Fusion +#device ncr # NCR/Symbios Logic +device sym # NCR/Symbios Logic (newer chipsets) +device trm # Tekram DC395U/UW/F DC315U adapters + +device adv # Advansys SCSI adapters +device adw # Advansys wide SCSI adapters +device aha # Adaptec 154x SCSI adapters +device aic # Adaptec 15[012]x SCSI adapters, AIC-6[23]60. +device bt # Buslogic/Mylex MultiMaster SCSI adapters + +device ncv # NCR 53C500 +device nsp # Workbit Ninja SCSI-3 +device stg # TMC 18C30/18C50 + + SCSI controllers. Comment out any you do not have in your + system. If you have an IDE only system, you can remove these + altogether. + + # SCSI peripherals +device scbus # SCSI bus (required for SCSI) +device ch # SCSI media changers +device da # Direct Access (disks) +device sa # Sequential Access (tape etc) +device cd # CD +device pass # Passthrough device (direct SCSI access) +device ses # SCSI Environmental Services (and SAF-TE) + + SCSI peripherals. Again, comment out any you do not have, or if + you have only IDE hardware, you can remove them completely. + + + The USB &man.umass.4; driver and a few other drivers use + the SCSI subsystem even though they are not real SCSI devices. + Therefore make sure not to remove SCSI support, if any such + drivers are included in the kernel configuration. + + + # RAID controllers interfaced to the SCSI subsystem +device amr # AMI MegaRAID +device arcmsr # Areca SATA II RAID +device asr # DPT SmartRAID V, VI and Adaptec SCSI RAID +device ciss # Compaq Smart RAID 5* +device dpt # DPT Smartcache III, IV - See NOTES for options +device hptmv # Highpoint RocketRAID 182x +device rr232x # Highpoint RocketRAID 232x +device iir # Intel Integrated RAID +device ips # IBM (Adaptec) ServeRAID +device mly # Mylex AcceleRAID/eXtremeRAID +device twa # 3ware 9000 series PATA/SATA RAID + +# RAID controllers +device aac # Adaptec FSA RAID +device aacp # SCSI passthrough for aac (requires CAM) +device ida # Compaq Smart RAID +device mfi # LSI MegaRAID SAS +device mlx # Mylex DAC960 family +device pst # Promise Supertrak SX6000 +device twe # 3ware ATA RAID + + Supported RAID controllers. If you do not have any of these, + you can comment them out or remove them. + + # atkbdc0 controls both the keyboard and the PS/2 mouse +device atkbdc # AT keyboard controller + + The keyboard controller (atkbdc) provides I/O + services for the AT keyboard and PS/2 style pointing devices. This + controller is required by the keyboard driver + (atkbd) and the PS/2 pointing device driver + (psm). + + device atkbd # AT keyboard + + The atkbd driver, together with + atkbdc controller, provides access to the AT 84 + keyboard or the AT enhanced keyboard which is connected to the AT + keyboard controller. + + device psm # PS/2 mouse + + Use this device if your mouse plugs into the PS/2 mouse + port. + + device kbdmux # keyboard multiplexer + + Basic support for keyboard multiplexing. + + device vga # VGA video card driver + + The video card driver. + + +device splash # Splash screen and screen saver support + + Splash screen at start up! Screen savers require this + too. + + # syscons is the default console driver, resembling an SCO console +device sc + + sc is the default console driver and + resembles a SCO console. Since most full-screen programs access the + console through a terminal database library like + termcap, it should not matter whether you use + this or vt, the VT220 + compatible console driver. When you log in, set your + TERM variable to scoansi if + full-screen programs have trouble running under this console. + + # Enable this for the pcvt (VT220 compatible) console driver +#device vt +#options XSERVER # support for X server on a vt console +#options FAT_CURSOR # start with block cursor + + This is a VT220-compatible console driver, backward compatible to + VT100/102. It works well on some laptops which have hardware + incompatibilities with sc. Also set your + TERM variable to vt100 or + vt220 when you log in. This driver might also + prove useful when connecting to a large number of different machines + over the network, where termcap or + terminfo entries for the sc + device are often not available — vt100 + should be available on virtually any platform. + + device agp + + Include this if you have an AGP card in the system. This + will enable support for AGP, and AGP GART for boards which + have these features. + + + APM + + + # Power management support (see NOTES for more options) +#device apm + + Advanced Power Management support. Useful for laptops, + although in &os; 5.X and above this is disabled in + GENERIC by default. + + # Add suspend/resume support for the i8254. +device pmtimer + + Timer device driver for power management events, such as APM and + ACPI. + + # PCCARD (PCMCIA) support +# PCMCIA and cardbus bridge support +device cbb # cardbus (yenta) bridge +device pccard # PC Card (16-bit) bus +device cardbus # CardBus (32-bit) bus + + PCMCIA support. You want this if you are using a + laptop. + + # Serial (COM) ports +device sio # 8250, 16[45]50 based serial ports + + These are the serial ports referred to as + COM ports in the &ms-dos;/&windows; + world. + + + If you have an internal modem on COM4 + and a serial port at COM2, you will have + to change the IRQ of the modem to 2 (for obscure technical reasons, + IRQ2 = IRQ 9) in order to access it + from &os;. If you have a multiport serial card, check the + manual page for &man.sio.4; for more information on the proper + values to add to your /boot/device.hints. + Some video cards (notably those based on + S3 chips) use IO addresses in the form of + 0x*2e8, and since many cheap serial cards do + not fully decode the 16-bit IO address space, they clash with + these cards making the COM4 port + practically unavailable. + + Each serial port is required to have a unique IRQ (unless you + are using one of the multiport cards where shared interrupts are + supported), so the default IRQs for COM3 + and COM4 cannot be used. + + + # Parallel port +device ppc + + This is the ISA-bus parallel port interface. + + device ppbus # Parallel port bus (required) + + Provides support for the parallel port bus. + + device lpt # Printer + + Support for parallel port printers. + + + All three of the above are required to enable parallel printer + support. + + + device plip # TCP/IP over parallel + + This is the driver for the parallel network interface. + + device ppi # Parallel port interface device + + The general-purpose I/O (geek port) + IEEE1284 + I/O. + + #device vpo # Requires scbus and da + + zip drive + This is for an Iomega Zip drive. It requires + scbus and da support. Best + performance is achieved with ports in EPP 1.9 mode. + + #device puc + + Uncomment this device if you have a dumb serial + or parallel PCI card that is supported by the &man.puc.4; glue + driver. + + # PCI Ethernet NICs. +device de # DEC/Intel DC21x4x (Tulip) +device em # Intel PRO/1000 adapter Gigabit Ethernet Card +device ixgb # Intel PRO/10GbE Ethernet Card +device txp # 3Com 3cR990 (Typhoon) +device vx # 3Com 3c590, 3c595 (Vortex) + + Various PCI network card drivers. Comment out or remove any of + these not present in your system. + + # PCI Ethernet NICs that use the common MII bus controller code. +# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs! +device miibus # MII bus support + + MII bus support is required for some PCI 10/100 Ethernet NICs, + namely those which use MII-compliant transceivers or implement + transceiver control interfaces that operate like an MII. Adding + device miibus to the kernel config pulls in + support for the generic miibus API and all of the PHY drivers, + including a generic one for PHYs that are not specifically handled + by an individual driver. + + device bce # Broadcom BCM5706/BCM5708 Gigabit Ethernet +device bfe # Broadcom BCM440x 10/100 Ethernet +device bge # Broadcom BCM570xx Gigabit Ethernet +device dc # DEC/Intel 21143 and various workalikes +device fxp # Intel EtherExpress PRO/100B (82557, 82558) +device lge # Level 1 LXT1001 gigabit ethernet +device nge # NatSemi DP83820 gigabit ethernet +device nve # nVidia nForce MCP on-board Ethernet Networking +device pcn # AMD Am79C97x PCI 10/100 (precedence over 'lnc') +device re # RealTek 8139C+/8169/8169S/8110S +device rl # RealTek 8129/8139 +device sf # Adaptec AIC-6915 (Starfire) +device sis # Silicon Integrated Systems SiS 900/SiS 7016 +device sk # SysKonnect SK-984x & SK-982x gigabit Ethernet +device ste # Sundance ST201 (D-Link DFE-550TX) +device ti # Alteon Networks Tigon I/II gigabit Ethernet +device tl # Texas Instruments ThunderLAN +device tx # SMC EtherPower II (83c170 EPIC) +device vge # VIA VT612x gigabit ethernet +device vr # VIA Rhine, Rhine II +device wb # Winbond W89C840F +device xl # 3Com 3c90x (Boomerang, Cyclone) + + Drivers that use the MII bus controller code. + + # ISA Ethernet NICs. pccard NICs included. +device cs # Crystal Semiconductor CS89x0 NIC +# 'device ed' requires 'device miibus' +device ed # NE[12]000, SMC Ultra, 3c503, DS8390 cards +device ex # Intel EtherExpress Pro/10 and Pro/10+ +device ep # Etherlink III based cards +device fe # Fujitsu MB8696x based cards +device ie # EtherExpress 8/16, 3C507, StarLAN 10 etc. +device lnc # NE2100, NE32-VL Lance Ethernet cards +device sn # SMC's 9000 series of Ethernet chips +device xe # Xircom pccard Ethernet + +# ISA devices that use the old ISA shims +#device le + + ISA Ethernet drivers. See + /usr/src/sys/i386/conf/NOTES for details +of which cards are + supported by which driver. + + # Wireless NIC cards +device wlan # 802.11 support +device an # Aironet 4500/4800 802.11 wireless NICs. +device awi # BayStack 660 and others +device ral # Ralink Technology RT2500 wireless NICs. +device wi # WaveLAN/Intersil/Symbol 802.11 wireless NICs. +#device wl # Older non 802.11 Wavelan wireless NIC. + + Support for various wireless cards. + + # Pseudo devices +device loop # Network loopback + + This is the generic loopback device for TCP/IP. If you telnet + or FTP to localhost (a.k.a. 127.0.0.1) it will come back at you through + this device. This is mandatory. + + device random # Entropy device + + Cryptographically secure random number generator. + + device ether # Ethernet support + + ether is only needed if you have an Ethernet + card. It includes generic Ethernet protocol code. + + device sl # Kernel SLIP + + sl is for SLIP support. This has been almost + entirely supplanted by PPP, which is easier to set up, better suited + for modem-to-modem connection, and more powerful. + + device ppp # Kernel PPP + + This is for kernel PPP support for dial-up connections. There + is also a version of PPP implemented as a userland application that + uses tun and offers more flexibility and features + such as demand dialing. + + device tun # Packet tunnel. + + This is used by the userland PPP software. + See + the PPP section of this book for more + information. + + +device pty # Pseudo-ttys (telnet etc) + + This is a pseudo-terminal or simulated login port. + It is used by incoming telnet and + rlogin sessions, + xterm, and some other applications such + as Emacs. + + device md # Memory disks + + Memory disk pseudo-devices. + + device gif # IPv6 and IPv4 tunneling + + This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, + IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. The + gif device is + auto-cloning, and will create device nodes as + needed. + + device faith # IPv6-to-IPv4 relaying (translation) + + This pseudo-device captures packets that are sent to it and + diverts them to the IPv4/IPv6 translation daemon. + + # The `bpf' device enables the Berkeley Packet Filter. +# Be aware of the administrative consequences of enabling this! +# Note that 'bpf' is required for DHCP. +device bpf # Berkeley packet filter + + This is the Berkeley Packet Filter. This pseudo-device allows + network interfaces to be placed in promiscuous mode, capturing every + packet on a broadcast network (e.g., an Ethernet). These packets + can be captured to disk and or examined with the &man.tcpdump.1; + program. + + + The &man.bpf.4; device is also used by + &man.dhclient.8; to obtain the IP address of the default router + (gateway) and so on. If you use DHCP, leave this + uncommented. + + + # USB support +device uhci # UHCI PCI->USB interface +device ohci # OHCI PCI->USB interface +#device ehci # EHCI PCI->USB interface (USB 2.0) +device usb # USB Bus (required) +#device udbp # USB Double Bulk Pipe devices +device ugen # Generic +device uhid # Human Interface Devices +device ukbd # Keyboard +device ulpt # Printer +device umass # Disks/Mass storage - Requires scbus and da +device ums # Mouse +device urio # Diamond Rio 500 MP3 player +device uscanner # Scanners +# USB Ethernet, requires mii +device aue # ADMtek USB Ethernet +device axe # ASIX Electronics USB Ethernet +device cdce # Generic USB over Ethernet +device cue # CATC USB Ethernet +device kue # Kawasaki LSI USB Ethernet +device rue # RealTek RTL8150 USB Ethernet + + Support for various USB devices. + + # FireWire support +device firewire # FireWire bus code +device sbp # SCSI over FireWire (Requires scbus and da) +device fwe # Ethernet over FireWire (non-standard!) + + Support for various Firewire devices. + + For more information and additional devices supported by + &os;, see + /usr/src/sys/i386/conf/NOTES. + + + Large Memory Configurations (<acronym>PAE</acronym>) + + Physical Address Extensions + (PAE) + large memory + + + Large memory configuration machines require access to + more than the 4 gigabyte limit on User+Kernel Virtual + Address (KVA) space. Due to this + limitation, Intel added support for 36-bit physical address + space access in the &pentium; Pro and later line of CPUs. + + The Physical Address Extension (PAE) + capability of the &intel; &pentium; Pro and later CPUs + allows memory configurations of up to 64 gigabytes. + &os; provides support for this capability via the + kernel configuration option, available + in all current release versions of &os;. Due to + the limitations of the Intel memory architecture, no distinction + is made for memory above or below 4 gigabytes. Memory allocated + above 4 gigabytes is simply added to the pool of available + memory. + + To enable PAE support in the kernel, + simply add the following line to your kernel configuration + file: + + options PAE + + + The PAE support in &os; is only + available for &intel; IA-32 processors. It should also be + noted, that the PAE support in &os; has + not received wide testing, and should be considered beta + quality compared to other stable features of &os;. + + + PAE support in &os; has a few limitations: + + + + A process is not able to access more than 4 + gigabytes of VM space. + + + + KLD modules cannot be loaded into + a PAE enabled kernel, due to the + differences in the build framework of a module and the + kernel. + + + + Device drivers that do not use the &man.bus.dma.9; + interface will cause data corruption in a + PAE enabled kernel and are not + recommended for use. For this reason, a + PAE kernel + configuration file is provided in &os; which + excludes all drivers not known to work in a PAE enabled + kernel. + + + + Some system tunables determine memory resource usage + by the amount of available physical memory. Such + tunables can unnecessarily over-allocate due to the + large memory nature of a PAE system. + One such example is the + sysctl, which controls the maximum number of vnodes allowed + in the kernel. It is advised to adjust this and other + such tunables to a reasonable value. + + + + It might be necessary to increase the kernel virtual + address (KVA) space or to reduce the + amount of specific kernel resource that is heavily used + (see above) in order to avoid KVA + exhaustion. The kernel option + can be used for increasing the + KVA space. + + + + For performance and stability concerns, it is advised to + consult the &man.tuning.7; manual page. The &man.pae.4; + manual page contains up-to-date information on &os;'s + PAE support. + + + + + If Something Goes Wrong + + There are five categories of trouble that can occur when + building a custom kernel. They are: + + + + config fails: + + + If the &man.config.8; command fails when you + give it your kernel description, you have probably made a + simple error somewhere. Fortunately, + &man.config.8; will print the line number that it + had trouble with, so that you can quickly locate the line + containing the error. For example, if you see: + + config: line 17: syntax error + + Make sure the + keyword is typed correctly by comparing it to the + GENERIC kernel or another + reference. + + + + + make fails: + + + If the make command fails, it usually + signals an error in your kernel description which is not severe + enough for &man.config.8; to catch. Again, look + over your configuration, and if you still cannot resolve the + problem, send mail to the &a.questions; with your kernel + configuration, and it should be diagnosed quickly. + + + + + The kernel does not boot: + + + If your new kernel does not boot, or fails to + recognize your devices, do not panic! Fortunately, &os; has + an excellent mechanism for recovering from incompatible + kernels. Simply choose the kernel you want to boot from at + the &os; boot loader. You can access this when the system + boot menu appears. Select the Escape to a loader + prompt option, number six. At the prompt, type + unload kernel + and then type + boot /boot/kernel.old/kernel, + or the filename of any other kernel that will boot properly. + When reconfiguring a kernel, it is always a good idea to keep + a kernel that is known to work on hand. + + After booting with a good kernel you can check over your + configuration file and try to build it again. One helpful + resource is the /var/log/messages file + which records, among other things, all of the kernel messages + from every successful boot. Also, the &man.dmesg.8; command + will print the kernel messages from the current boot. + + + If you are having trouble building a kernel, make sure + to keep a GENERIC, or some other kernel + that is known to work on hand as a different name that will + not get erased on the next build. You cannot rely on + kernel.old because when installing a + new kernel, kernel.old is overwritten + with the last installed kernel which may be non-functional. + Also, as soon as possible, move the working kernel to the + proper /boot/kernel + location or commands such + as &man.ps.1; may not work properly. To do this, simply + rename the directory containing the good kernel: + + &prompt.root; mv /boot/kernel /boot/kernel.bad +&prompt.root; mv /boot/kernel.good /boot/kernel + + + + + + + The kernel works, but &man.ps.1; does not work + any more: + + + If you have installed a different version of the kernel + from the one that the system utilities have been built with, + for example, a -CURRENT kernel on a -RELEASE, many system-status + commands like &man.ps.1; and &man.vmstat.8; will not work any + more. You should recompile and install + a world built with the same version of the source tree as + your kernel. This is one reason it is + not normally a good idea to use a different version of the + kernel from the rest of the operating system. + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/l10n/Makefile b/pl_PL.ISO8859-2/books/handbook/l10n/Makefile new file mode 100644 index 0000000000..c6741a2341 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/l10n/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= l10n/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/l10n/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/l10n/chapter.sgml new file mode 100644 index 0000000000..8acb937c50 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/l10n/chapter.sgml @@ -0,0 +1,940 @@ + + + + + + + Andrey + Chernov + Contributed by + + + + + Michael C. + Wu + Rewritten by + + + + + + Localization - I18N/L10N Usage and Setup + + + Synopsis + + FreeBSD is a very distributed project with users and + contributors located all over the world. This chapter discusses + the internationalization and localization features of FreeBSD + that allow non-English speaking users to get real work done. + There are many aspects of the i18n implementation in both the system + and application levels, so where applicable we refer the reader + to more specific sources of documentation. + + After reading this chapter, you will know: + + How different languages and locales are encoded + on modern operating systems. + How to set the locale for your login + shell. + How to configure your console for non-English + languages. + How to use X Window System effectively with different + languages. + Where to find more information about writing + i18n-compliant applications. + + + Before reading this chapter, you should: + + + Know how to install additional third-party + applications (). + + + + + The Basics + + + What Is I18N/L10N? + + internationalization + localization + + localization + + Developers shortened internationalization into the term I18N, + counting the number of letters between the first and the last + letters of internationalization. L10N uses the same naming + scheme, coming from localization. Combined + together, I18N/L10N methods, protocols, and applications allow + users to use languages of their choice. + + I18N applications are programmed using I18N kits under + libraries. It allows for developers to write a simple file and + translate displayed menus and texts to each language. We strongly + encourage programmers to follow this convention. + + + + Why Should I Use I18N/L10N? + + I18N/L10N is used whenever you wish to either view, input, or + process data in non-English languages. + + + + What Languages Are Supported in the I18N Effort? + + I18N and L10N are not FreeBSD specific. Currently, one can + choose from most of the major languages of the World, including + but not limited to: Chinese, German, Japanese, Korean, French, + Russian, Vietnamese and others. + + + + + Using Localization + + In all its splendor, I18N is not FreeBSD-specific and is a + convention. We encourage you to help FreeBSD in following this + convention. + locale + + Localization settings are based on three main terms: + Language Code, Country Code, and Encoding. Locale names are + constructed from these parts as follows: + + LanguageCode_CountryCode.Encoding + + + Language and Country Codes + language codes + country codes + + In order to localize a FreeBSD system to a specific language + (or any other I18N-supporting &unix; like systems), the user needs to find out + the codes for the specify country and language (country + codes tell applications what variation of given + language to use). In addition, web + browsers, SMTP/POP servers, web servers, etc. make decisions based on + them. The following are examples of language/country codes: + + + + + + Language/Country Code + Description + + + + + + en_US + English - United States + + + + ru_RU + Russian for Russia + + + + zh_TW + Traditional Chinese for Taiwan + + + + + + + + + Encodings + encodings + ASCII + + Some languages use non-ASCII encodings that are 8-bit, wide + or multibyte characters, see &man.multibyte.3; for more + details. Older applications do not recognize them + and mistake them for control characters. Newer applications + usually do recognize 8-bit characters. Depending on the + implementation, users may be required to compile an application + with wide or multibyte characters support, or configure it correctly. + To be able to input and process wide or multibyte characters, the FreeBSD Ports Collection has provided + each language with different programs. Refer to the I18N + documentation in the respective FreeBSD Port. + + Specifically, the user needs to look at the application + documentation to decide on how to configure it correctly or to + pass correct values into the configure/Makefile/compiler. + + Some things to keep in mind are: + + + + Language specific single C chars character sets + (see &man.multibyte.3;), e.g. + ISO8859-1, ISO8859-15, KOI8-R, CP437. + + + + Wide or multibyte encodings, e.g. EUC, Big5. + + + + You can check the active list of character sets at the + IANA Registry. + + + &os; use X11-compatible locale encodings instead. + + + + + + I18N Applications + + In the FreeBSD Ports and Package system, I18N applications + have been named with I18N in their names for + easy identification. However, they do not always support the + language needed. + + + + Setting Locale + + Usually it is sufficient to export the value of the locale name + as LANG in the login shell. This could be done in + the user's ~/.login_conf file or in the + startup file of the user's shell (~/.profile, + ~/.bashrc, ~/.cshrc). + There is no need to set the locale subsets such as + LC_CTYPE, LC_CTIME. Please + refer to language-specific FreeBSD documentation for more + information. + + You should set the following two environment variables in your configuration + files: + + + POSIX + + LANG for &posix; &man.setlocale.3; family + functions + + + MIME + + MM_CHARSET for applications' MIME character + set + + + + This includes the user shell configuration, the specific application + configuration, and the X11 configuration. + + + Setting Locale Methods + locale + login class + + There are two methods for setting locale, and both are + described below. The first (recommended one) is by assigning + the environment variables in login + class, and the second is by adding the environment + variable assignments to the system's shell startup file. + + + Login Classes Method + + This method allows environment variables needed for locale + name and MIME character sets to be assigned once for every + possible shell instead of adding specific shell assignments to + each shell's startup file. User + Level Setup can be done by an user himself and Administrator Level Setup require + superuser privileges. + + + User Level Setup + + Here is a minimal example of a + .login_conf file in user's home + directory which has both variables set for Latin-1 + encoding: + + me:\ + :charset=ISO-8859-1:\ + :lang=de_DE.ISO8859-1: + + Traditional ChineseBIG-5 encoding + Here is an example of a + .login_conf that sets the variables + for Traditional Chinese in BIG-5 encoding. Notice the many + more variables set because some software does not respect + locale variables correctly for Chinese, Japanese, and Korean. + + #Users who do not wish to use monetary units or time formats +#of Taiwan can manually change each variable +me:\ + :lang=zh_TW.Big5:\ + :lc_all=zh_TW.Big:\ + :lc_collate=zh_TW.Big5:\ + :lc_ctype=zh_TW.Big5:\ + :lc_messages=zh_TW.Big5:\ + :lc_monetary=zh_TW.Big5:\ + :lc_numeric=zh_TW.Big5:\ + :lc_time=zh_TW.Big5:\ + :charset=big5:\ + :xmodifiers="@im=xcin": #Setting the XIM Input Server + + See Administrator Level + Setup and &man.login.conf.5; for more details. + + + + Administrator Level Setup + + Verify that the user's login class in + /etc/login.conf sets the correct + language. Make sure these settings + appear in /etc/login.conf: + + language_name:accounts_title:\ + :charset=MIME_charset:\ + :lang=locale_name:\ + :tc=default: + + So sticking with our previous example using Latin-1, it + would look like this: + + german:German Users Accounts:\ + :charset=ISO-8859-1:\ + :lang=de_DE.ISO8859-1:\ + :tc=default: + + Before changing users Login Classes execute + the following command + + &prompt.root; cap_mkdb /etc/login.conf + + to make new configuration in + /etc/login.conf visible to the system. + + Changing Login Classes with &man.vipw.8; + + + vipw + + Use vipw to add new users, and make + the entry look like this: + + user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh + + Changing Login Classes with &man.adduser.8; + + + adduser + + login class + Use adduser to add new users, and do + the following: + + + + Set defaultclass = + language in + /etc/adduser.conf. Keep in mind + you must enter a default class for + all users of other languages in this case. + + + + An alternative variant is answering the specified + language each time that +Enter login class: default []: + appears from &man.adduser.8;. + + + + Another alternative is to use the following for each + user of a different language that you wish to + add: + + &prompt.root; adduser -class language + + + + Changing Login Classes with &man.pw.8; + + pw + + If you use &man.pw.8; for adding new users, call it in + this form: + + &prompt.root; pw useradd user_name -L language + + + + + Shell Startup File Method + + + This method is not recommended because it requires a + different setup for each possible shell program chosen. Use + the Login Class Method + instead. + + + MIME + locale + To add the locale name and MIME character set, just set + the two environment variables shown below in the + /etc/profile and/or + /etc/csh.login shell startup files. We + will use the German language as an example below: + + In /etc/profile: + + LANG=de_DE.ISO8859-1; export LANG +MM_CHARSET=ISO-8859-1; export MM_CHARSET + + Or in /etc/csh.login: + + setenv LANG de_DE.ISO8859-1 +setenv MM_CHARSET ISO-8859-1 + + Alternatively, you can add the above instructions to + /usr/share/skel/dot.profile (similar to + what was used in /etc/profile above), or + /usr/share/skel/dot.login (similar to + what was used in /etc/csh.login + above). + + For X11: + + In $HOME/.xinitrc: + + LANG=de_DE.ISO8859-1; export LANG + + Or: + + setenv LANG de_DE.ISO8859-1 + + Depending on your shell (see above). + + + + + + + Console Setup + + For all single C chars character sets, set the correct + console fonts in /etc/rc.conf for the + language in question with: + + font8x16=font_name +font8x14=font_name +font8x8=font_name + + The font_name here is taken from + the /usr/share/syscons/fonts directory, + without the .fnt suffix. + + + sysinstall + + keymap + screenmap + Also be sure to set the correct keymap and screenmap for your + single C chars character set through + sysinstall (/stand/sysinstall + in &os; versions older than 5.2). + Once inside sysinstall, choose Configure, then + Console. Alternatively, you can add the + following to /etc/rc.conf: + + scrnmap=screenmap_name +keymap=keymap_name +keychange="fkey_number sequence" + + The screenmap_name here is taken + from the /usr/share/syscons/scrnmaps + directory, without the .scm suffix. A + screenmap with a corresponding mapped font is usually needed as a + workaround for expanding bit 8 to bit 9 on a VGA adapter's font + character matrix in pseudographics area, i.e., to move letters out + of that area if screen font uses a bit 8 column. + + If you have the moused daemon + enabled by setting the following + in your /etc/rc.conf: + +moused_enable="YES" + + then examine the mouse cursor information in the next + paragraph. + + + moused + + By default the mouse cursor of the &man.syscons.4; driver occupies the + 0xd0-0xd3 range in the character set. If your language uses this + range, you need to move the cursor's range outside of it. To enable + the workaround for &os;, add the following line to + /etc/rc.conf: + + mousechar_start=3 + + The keymap_name here is taken from + the /usr/share/syscons/keymaps directory, + without the .kbd suffix. If you are + uncertain which keymap to use, you use can &man.kbdmap.1; to test + keymaps without rebooting. + + The keychange is usually needed to program + function keys to match the selected terminal type because + function key sequences cannot be defined in the key map. + + Also be sure to set the correct console terminal type in + /etc/ttys for all ttyv* + entries. Current pre-defined correspondences are: + + + + + + Character Set + Terminal Type + + + + + + ISO8859-1 or ISO8859-15 + cons25l1 + + + + ISO8859-2 + cons25l2 + + + + ISO8859-7 + cons25l7 + + + + KOI8-R + cons25r + + + + KOI8-U + cons25u + + + + CP437 (VGA default) + cons25 + + + + US-ASCII + cons25w + + + + + + For wide or multibyte characters languages, use the correct + FreeBSD port in your + /usr/ports/language + directory. Some ports appear as console while the system sees it + as serial vtty's, hence you must reserve enough vtty's for both + X11 and the pseudo-serial console. Here is a partial list of + applications for using other languages in console: + + + + + + Language + Location + + + + + + Traditional Chinese (BIG-5) + chinese/big5con + + + + Japanese + japanese/kon2-16dot or + japanese/mule-freewnn + + + + Korean + korean/han + + + + + + + + X11 Setup + + Although X11 is not part of the FreeBSD Project, we have + included some information here for FreeBSD users. For more + details, refer to the &xorg; + web site or whichever X11 Server you use. + + In ~/.Xresources, you can additionally + tune application specific I18N settings (e.g., fonts, menus, + etc.). + + + Displaying Fonts + X11 True Type font server + Install &xorg; server + (x11-servers/xorg-server) + or &xfree86; server + (x11-servers/XFree86-4-Server), + then install the language &truetype; fonts. Setting the correct + locale should allow you to view your selected language in menus + and such. + + + + Inputting Non-English Characters + X11 Input Method (XIM) + The X11 Input Method (XIM) Protocol is a new standard for + all X11 clients. All X11 applications should be written as XIM + clients that take input from XIM Input servers. There are + several XIM servers available for different languages. + + + + + Printer Setup + + Some single C chars character sets are usually hardware + coded into printers. Wide or multibyte + character sets require special setup and we recommend using + apsfilter. You may also convert the + document to &postscript; or PDF formats using language specific + converters. + + + + Kernel and File Systems + + The FreeBSD fast filesystem (FFS) is 8-bit clean, so it can be used + with any single C chars character set (see &man.multibyte.3;), + but there is no character set + name stored in the filesystem; i.e., it is raw 8-bit and does not + know anything about encoding order. Officially, FFS does not + support any form of wide or multibyte character sets yet. However, some + wide or multibyte character sets have independent patches for FFS + enabling such support. They are only temporary unportable + solutions or hacks and we have decided to not include them in the + source tree. Refer to respective languages' web sites for more + information and the patch files. + + DOS + Unicode + The FreeBSD &ms-dos; filesystem has the configurable ability to + convert between &ms-dos;, Unicode character sets and chosen + FreeBSD filesystem character sets. See &man.mount.msdos.8; for + details. + + + + + Compiling I18N Programs + + Many FreeBSD Ports have been ported with I18N support. Some + of them are marked with -I18N in the port name. These and many + other programs have built in support for I18N and need no special + consideration. + + + MySQL + + However, some applications such as + MySQL need to be have the + Makefile configured with the specific + charset. This is usually done in the + Makefile or done by passing a value to + configure in the source. + + + + Localizing FreeBSD to Specific Languages + + + + + + Andrey + Chernov + Originally contributed by + + + + Russian Language (KOI8-R Encoding) + + localization + Russian + + + For more information about KOI8-R encoding, see the KOI8-R References + (Russian Net Character Set). + + + Locale Setup + + Put the following lines into your + ~/.login_conf file: + + me:My Account:\ + :charset=KOI8-R:\ + :lang=ru_RU.KOI8-R: + + See earlier in this chapter for examples of setting up the + locale. + + + + Console Setup + + + + Add the following line + to your /etc/rc.conf file: + + mousechar_start=3 + + + + Also, use following settings in + /etc/rc.conf: + + keymap="ru.koi8-r" +scrnmap="koi8-r2cp866" +font8x16="cp866b-8x16" +font8x14="cp866-8x14" +font8x8="cp866-8x8" + + + + + For each ttyv* entry in + /etc/ttys, use + cons25r as the terminal type. + + + + See earlier in this chapter for examples of setting up the + console. + + + + Printer Setup + printers + Since most printers with Russian characters come with + hardware code page CP866, a special output filter is needed + to convert from KOI8-R to CP866. Such a filter is installed by + default as /usr/libexec/lpr/ru/koi2alt. + A Russian printer /etc/printcap entry + should look like: + + lp|Russian local line printer:\ + :sh:of=/usr/libexec/lpr/ru/koi2alt:\ + :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: + + See &man.printcap.5; for a detailed description. + + + + &ms-dos; FS and Russian Filenames + + The following example &man.fstab.5; entry enables support + for Russian filenames in mounted &ms-dos; filesystems: + + /dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0 + + The option selects the locale name + used, and sets the character conversion + table. To use the option, be sure to + mount /usr before the &ms-dos; partition + because the conversion tables are located in + /usr/libdata/msdosfs. For more + information, see the &man.mount.msdos.8; manual + page. + + + + X11 Setup + + + + Do non-X locale + setup first as described. + + + + If you use &xorg;, + install + x11-fonts/xorg-fonts-cyrillic + package. + + Check the "Files" section + in your /etc/X11/xorg.conf file. + The following + lines must be added before any other + FontPath entries: + + FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" +FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi" + + If you use a high resolution video mode, swap the 75 dpi + and 100 dpi lines. + + + + To activate a Russian keyboard, add the following to the + "Keyboard" section of your + xorg.conf file. + + Option "XkbLayout" "us,ru" +Option "XkbOptions" "grp:toggle" + + Also make sure that XkbDisable is + turned off (commented out) there. + + For grp:caps_toggle + the RUS/LAT switch will be CapsLock. + The old CapsLock function is still + available via ShiftCapsLock (in LAT mode + only). For grp:toggle + the RUS/LAT switch will be Right Alt. + grp:caps_toggle does not work in + &xorg; for unknown reason. + + If you have &windows; keys on your keyboard, + and notice that some non-alphabetical keys are mapped + incorrectly in RUS mode, add the following line in your + xorg.conf file. + + Option "XkbVariant" ",winkeys" + + + The Russian XKB keyboard may not work with non-localized + applications. + + + + + Minimally localized applications + should call a XtSetLanguageProc (NULL, NULL, + NULL); function early in the program. + See + KOI8-R for X Window for more instructions on + localizing X11 applications. + + + + + + Traditional Chinese Localization for Taiwan + + localization + Traditional Chinese + + The FreeBSD-Taiwan Project has an Chinese HOWTO for + FreeBSD at + using many Chinese ports. + Current editor for the FreeBSD Chinese HOWTO is + Shen Chuan-Hsing statue@freebsd.sinica.edu.tw. + + + Chuan-Hsing Shen statue@freebsd.sinica.edu.tw has + created the + Chinese FreeBSD Collection (CFC) using FreeBSD-Taiwan's + zh-L10N-tut. The packages and the script files + are available at . + + + + German Language Localization (for All ISO 8859-1 + Languages) + + localization + German + + + Slaven Rezic eserte@cs.tu-berlin.de wrote a + tutorial how to use umlauts on a FreeBSD machine. The tutorial + is written in German and available at + . + + + + Japanese and Korean Language Localization + + localization + Japanese + + + localization + Korean + + For Japanese, refer to + , + and for Korean, refer to + . + + + + Non-English FreeBSD Documentation + + Some FreeBSD contributors have translated parts of FreeBSD to + other languages. They are available through links on the main site or in + /usr/share/doc. + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/linuxemu/Makefile b/pl_PL.ISO8859-2/books/handbook/linuxemu/Makefile new file mode 100644 index 0000000000..37adfa9af6 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/linuxemu/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= linuxemu/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/linuxemu/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/linuxemu/chapter.sgml new file mode 100644 index 0000000000..60624c3e77 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/linuxemu/chapter.sgml @@ -0,0 +1,3357 @@ + + + + + + + Jim + Mock + Restructured and parts updated by + + + + + + Brian N. + Handy + Originally contributed by + + + Rich + Murphey + + + + + Linux Binary Compatibility + + + Synopsis + Linux binary compatibility + + binary compatibility + Linux + + + FreeBSD provides binary compatibility with several other + &unix; like operating systems, including Linux. At this point, + you may be asking yourself why exactly, does + FreeBSD need to be able to run Linux binaries? The answer to that + question is quite simple. Many companies and developers develop + only for Linux, since it is the latest hot thing in + the computing world. That leaves the rest of us FreeBSD users + bugging these same companies and developers to put out native + FreeBSD versions of their applications. The problem is, that most + of these companies do not really realize how many people would use + their product if there were FreeBSD versions too, and most continue + to only develop for Linux. So what is a FreeBSD user to do? This + is where the Linux binary compatibility of FreeBSD comes into + play. + + In a nutshell, the compatibility allows FreeBSD users to run + about 90% of all Linux applications without modification. This + includes applications such as &staroffice;, + the Linux version of &netscape;, + &adobe; &acrobat;, + RealPlayer, + VMware, + &oracle;, + WordPerfect, Doom, + Quake, and more. It is also reported + that in some situations, Linux binaries perform better on FreeBSD + than they do under Linux. + + There are, however, some Linux-specific operating system + features that are not supported under FreeBSD. Linux binaries will + not work on FreeBSD if they overly use &i386; specific + calls, such as enabling virtual 8086 mode. + + After reading this chapter, you will know: + + + How to enable Linux binary compatibility on your system. + + + + How to install additional Linux shared + libraries. + + + + How to install Linux applications on your FreeBSD system. + + + + The implementation details of Linux compatibility in FreeBSD. + + + + Before reading this chapter, you should: + + + + Know how to install additional third-party + software (). + + + + + + + Installation + + KLD (kernel loadable object) + + Linux binary compatibility is not turned on by default. The + easiest way to enable this functionality is to load the + linux KLD object (Kernel LoaDable + object). You can load this module by typing the + following as root: + + &prompt.root; kldload linux + + If you would like Linux compatibility to always be enabled, + then you should add the following line to + /etc/rc.conf: + + linux_enable="YES" + + The &man.kldstat.8; command can be used to verify that the + KLD is loaded: + + &prompt.user; kldstat +Id Refs Address Size Name + 1 2 0xc0100000 16bdb8 kernel + 7 1 0xc24db000 d000 linux.ko + + kernel options + COMPAT_LINUX + + + If for some reason you do not want to or cannot load the KLD, + then you may statically link Linux binary compatibility into the kernel + by adding options COMPAT_LINUX to your kernel + configuration file. Then install your new kernel as described in + . + + + Installing Linux Runtime Libraries + + Linux + installing Linux libraries + + + This can be done one of two ways, either by using the + linux_base port, or + by installing them manually. + + + Installing Using the linux_base Port + Ports Collection + + This is by far the easiest method to use when installing the + runtime libraries. It is just like installing any other port + from the Ports Collection. + Simply do the following: + + &prompt.root; cd /usr/ports/emulators/linux_base-fc4 +&prompt.root; make install distclean + + You should now have working Linux binary compatibility. + Some programs may complain about incorrect minor versions of the + system libraries. In general, however, this does not seem to be + a problem. + + There may be multiple versions of the emulators/linux_base port available, + corresponding to different versions of various Linux distributions. + You should install the port most closely resembling the + requirements of the Linux applications you would like to + install. + + + + + Installing Libraries Manually + + If you do not have the ports collection + installed, you can install the libraries by hand instead. You + will need the Linux shared libraries that the program depends on + and the runtime linker. Also, you will need to create a + shadow root directory, + /compat/linux, for Linux libraries on your + FreeBSD system. Any shared libraries opened by Linux programs + run under FreeBSD will look in this tree first. So, if a Linux + program loads, for example, /lib/libc.so, + FreeBSD will first try to open + /compat/linux/lib/libc.so, and if that does + not exist, it will then try /lib/libc.so. + Shared libraries should be installed in the shadow tree + /compat/linux/lib rather than the paths + that the Linux ld.so reports. + + Generally, you will need to look for the shared libraries + that Linux binaries depend on only the first few times that you + install a Linux program on your FreeBSD system. After a while, + you will have a sufficient set of Linux shared libraries on your + system to be able to run newly imported Linux binaries without + any extra work. + + + + How to Install Additional Shared Libraries + shared libraries + + What if you install the linux_base port + and your application still complains about missing shared + libraries? How do you know which shared libraries Linux + binaries need, and where to get them? Basically, there are 2 + possibilities (when following these instructions you will need + to be root on your FreeBSD system). + + If you have access to a Linux system, see what shared + libraries the application needs, and copy them to your FreeBSD + system. Look at the following example: + + + Let us assume you used FTP to get the Linux binary of + Doom, and put it on a Linux system you have access to. You + then can check which shared libraries it needs by running + ldd linuxdoom, like so: + + &prompt.user; ldd linuxdoom +libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 +libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 +libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 + + symbolic links + You would need to get all the files from the last column, + and put them under /compat/linux, with + the names in the first column as symbolic links pointing to + them. This means you eventually have these files on your + FreeBSD system: + + /compat/linux/usr/X11/lib/libXt.so.3.1.0 +/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 +/compat/linux/usr/X11/lib/libX11.so.3.1.0 +/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 +/compat/linux/lib/libc.so.4.6.29 +/compat/linux/lib/libc.so.4 -> libc.so.4.6.29 + +
+ + Note that if you already have a Linux shared library + with a matching major revision number to the first column + of the ldd output, you will not need to + copy the file named in the last column to your system, the + one you already have should work. It is advisable to copy + the shared library anyway if it is a newer version, + though. You can remove the old one, as long as you make + the symbolic link point to the new one. So, if you have + these libraries on your system: + + /compat/linux/lib/libc.so.4.6.27 +/compat/linux/lib/libc.so.4 -> libc.so.4.6.27 + + and you find a new binary that claims to require a + later version according to the output of + ldd: + + libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 + + If it is only one or two versions out of date in the + in the trailing digit then do not worry about copying + /lib/libc.so.4.6.29 too, because the + program should work fine with the slightly older version. + However, if you like, you can decide to replace the + libc.so anyway, and that should leave + you with: + + /compat/linux/lib/libc.so.4.6.29 +/compat/linux/lib/libc.so.4 -> libc.so.4.6.29 + +
+ +
+ + The symbolic link mechanism is + only needed for Linux binaries. The + FreeBSD runtime linker takes care of looking for matching + major revision numbers itself and you do not need to worry + about it. + +
+ + + + + + Installing Linux ELF Binaries + + Linux + ELF binaries + + + ELF binaries sometimes require an extra step of + branding. If you attempt to run an unbranded ELF + binary, you will get an error message like the following: + + &prompt.user; ./my-linux-elf-binary +ELF binary type not known +Abort + + To help the FreeBSD kernel distinguish between a FreeBSD ELF + binary from a Linux binary, use the &man.brandelf.1; + utility. + + &prompt.user; brandelf -t Linux my-linux-elf-binary + + GNU toolchain + The GNU toolchain now places the appropriate branding + information into ELF binaries automatically, so this step + should become increasingly unnecessary in the future. + + + + Configuring the Hostname Resolver + + If DNS does not work or you get this message: + + resolv+: "bind" is an invalid keyword resolv+: +"hosts" is an invalid keyword + + You will need to configure a + /compat/linux/etc/host.conf file + containing: + + order hosts, bind +multi on + + The order here specifies that /etc/hosts + is searched first and DNS is searched second. When + /compat/linux/etc/host.conf is not + installed, Linux applications find FreeBSD's + /etc/host.conf and complain about the + incompatible FreeBSD syntax. You should remove + bind if you have not configured a name server + using the /etc/resolv.conf file. + + + + + + + + Boris + Hollas + Updated for Mathematica 5.X by + + + + Installing &mathematica; + + + applications + Mathematica + + + This document describes the process of installing the Linux + version of &mathematica; 5.X onto + a FreeBSD system. + + The Linux version of &mathematica; + or &mathematica; for Students can + be ordered directly from Wolfram at + . + + + Running the &mathematica; Installer + + First, you have to tell &os; that + &mathematica;'s Linux + binaries use the Linux ABI. The easiest way to do so is to + set the default ELF brand + to Linux for all unbranded binaries with the command: + + &prompt.root; sysctl kern.fallback_elf_brand=3 + + This will make &os; assume that unbranded ELF binaries + use the Linux ABI and so you should be able to run the + installer straight from the CDROM. + + Now, copy the file MathInstaller to + your hard drive: + + &prompt.root; mount /cdrom +&prompt.root; cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/ + + and in this file, replace /bin/sh in + the first line by /compat/linux/bin/sh. + This makes sure that the installer is executed by the Linux + version of &man.sh.1;. Next, replace all occurrences of + Linux) by FreeBSD) with + a text editor or the script below in the next section. This + tells the &mathematica; installer, + who calls uname -s to determine the + operating system, to treat &os; as a Linux-like operating + system. Invoking MathInstaller will now + install &mathematica;. + + + + Modifying the &mathematica; Executables + + The shell scripts that + &mathematica; created during + installation have to be modified before you can use them. If + you chose /usr/local/bin + as the directory to place the + &mathematica; executables in, you + will find symlinks in this directory to files called + math, mathematica, + Mathematica, and + MathKernel. In each of these, replace + Linux) by FreeBSD) with + a text editor or the following shell script: + + #!/bin/sh +cd /usr/local/bin +for i in math mathematica Mathematica MathKernel + do sed 's/Linux)/FreeBSD)/g' $i > $i.tmp + sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp > $i + rm $i.tmp + chmod a+x $i +done + + + + Obtaining Your &mathematica; Password + + + Ethernet + MAC address + + + When you start &mathematica; + for the first time, you will be asked for a password. If you + have not yet obtained a password from Wolfram, run the program + mathinfo in the installation directory to + obtain your machine ID. This machine ID is + based solely on the MAC address of your first Ethernet card, + so you cannot run your copy of + &mathematica; on different + machines. + + When you register with Wolfram, either by email, phone or fax, + you will give them the machine ID and they will + respond with a corresponding password consisting of groups of + numbers. + + + + Running the &mathematica; Frontend over a Network + + &mathematica; uses some special + fonts to display characters not + present in any of the standard font sets (integrals, sums, Greek + letters, etc.). The X protocol requires these fonts to be install + locally. This means you will have to copy + these fonts from the CDROM or from a host with + &mathematica; + installed to your local machine. These fonts are normally stored + in /cdrom/Unix/Files/SystemFiles/Fonts on the + CDROM, or + /usr/local/mathematica/SystemFiles/Fonts on + your hard drive. The actual fonts are in the subdirectories + Type1 and X. There are + several ways to use them, as described below. + + The first way is to copy them into one of the existing font + directories in /usr/X11R6/lib/X11/fonts. + This will require editing the fonts.dir file, + adding the font names to it, and changing the number of fonts on + the first line. Alternatively, you should also just be able to + run &man.mkfontdir.1; in the directory you have copied + them to. + + The second way to do this is to copy the directories to + /usr/X11R6/lib/X11/fonts: + + &prompt.root; cd /usr/X11R6/lib/X11/fonts +&prompt.root; mkdir X +&prompt.root; mkdir MathType1 +&prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts +&prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X +&prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1 +&prompt.root; cd /usr/X11R6/lib/X11/fonts/X +&prompt.root; mkfontdir +&prompt.root; cd ../MathType1 +&prompt.root; mkfontdir + + Now add the new font directories to your font path: + + &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X +&prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1 +&prompt.root; xset fp rehash + + If you are using the &xorg; server, you can have these font + directories loaded automatically by adding them to your + xorg.conf file. + + For &xfree86; servers, + the configuration file is XF86Config. + fonts + + If you do not already have a directory + called /usr/X11R6/lib/X11/fonts/Type1, you + can change the name of the MathType1 + directory in the example above to + Type1. + + + + + + + + Aaron + Kaplan + + Contributed by + + + + + Robert + Getschmann + + Thanks to + + + + Installing &maple; + + + applications + Maple + + + &maple; is a commercial mathematics program similar to + &mathematica;. You must purchase this software from and then register there + for a license file. To install this software on FreeBSD, please + follow these simple steps. + + + Execute the INSTALL shell + script from the product distribution. Choose the + RedHat option when prompted by the + installation program. A typical installation directory + might be /usr/local/maple. + + If you have not done so, order a license for &maple; + from Maple Waterloo Software () + and copy it to + /usr/local/maple/license/license.dat. + + Install the FLEXlm + license manager by running the + INSTALL_LIC install shell script that + comes with &maple;. Specify the + primary hostname for your machine for the license + server. + + Patch the + /usr/local/maple/bin/maple.system.type + file with the following: + ----- snip ------------------ +*** maple.system.type.orig Sun Jul 8 16:35:33 2001 +--- maple.system.type Sun Jul 8 16:35:51 2001 +*************** +*** 72,77 **** +--- 72,78 ---- + # the IBM RS/6000 AIX case + MAPLE_BIN="bin.IBM_RISC_UNIX" + ;; ++ "FreeBSD"|\ + "Linux") + # the Linux/x86 case + # We have two Linux implementations, one for Red Hat and + ----- snip end of patch ----- + + Please note that after the "FreeBSD"|\ no other + whitespace should be present. + + This patch instructs &maple; to + recognize FreeBSD as a type of Linux system. + The bin/maple shell script calls the + bin/maple.system.type shell script + which in turn calls uname -a to find out the operating + system name. Depending on the OS name it will find out which + binaries to use. + + Start the license server. + + The following script, installed as + /usr/local/etc/rc.d/lmgrd.sh is a + convenient way to start up lmgrd: + + ----- snip ------------ + +#! /bin/sh +PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin +PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX +export PATH + +LICENSE_FILE=/usr/local/maple/license/license.dat +LOG=/var/log/lmgrd.log + +case "$1" in +start) + lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2 + echo -n " lmgrd" + ;; +stop) + lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2 + ;; +*) + echo "Usage: `basename $0` {start|stop}" 1>&2 + exit 64 + ;; +esac + +exit 0 + ----- snip ------------ + + + Test-start &maple;: + &prompt.user; cd /usr/local/maple/bin +&prompt.user; ./xmaple + + You should be up and running. Make sure to write + Maplesoft to let them know you would like a native FreeBSD + version! + + + + Common Pitfalls + + + The FLEXlm license manager can be a difficult + tool to work with. Additional documentation on the subject + can be found at . + + lmgrd is known to be very picky + about the license file and to core dump if there are any + problems. A correct license file should look like this: + +# ======================================================= +# License File for UNIX Installations ("Pointer File") +# ======================================================= +SERVER chillig ANY +#USE_SERVER +VENDOR maplelmg + +FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ + PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \ + ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \ + SN=XXXXXXXXX + + Serial number and key 'X''ed out. chillig is a + hostname. + + Editing the license file works as long as you do not + touch the FEATURE line (which is protected by the + license key). + + + + + + + + + Dan + Pelleg + Contributed by + + + + + Installing &matlab; + + + applications + MATLAB + + + This document describes the process of installing the Linux + version of &matlab; version 6.5 onto + a &os; system. It works quite well, with the exception of the + &java.virtual.machine; (see + ). + + The Linux version of &matlab; can be + ordered directly from The MathWorks at . Make sure you also get + the license file or instructions how to create it. While you + are there, let them know you would like a native &os; + version of their software. + + + Installing &matlab; + + To install &matlab;, do the + following: + + + + Insert the installation CD and mount it. + Become root, as recommended by the + installation script. To start the installation script + type: + + &prompt.root; /compat/linux/bin/sh /cdrom/install + + + The installer is graphical. If you get errors about + not being able to open a display, type + setenv HOME ~USER, + where USER is the user you did a + &man.su.1; as. + + + + + + When asked for the &matlab; root + directory, type: + /compat/linux/usr/local/matlab. + + + For easier typing on the rest of the installation + process, type this at your shell prompt: + set MATLAB=/compat/linux/usr/local/matlab + + + + + Edit the license file as instructed when + obtaining the &matlab; license. + + + You can prepare this file in advance using your + favorite editor, and copy it to + $MATLAB/license.dat before the + installer asks you to edit it. + + + + + Complete the installation process. + + + + At this point your &matlab; + installation is complete. The following steps apply + glue to connect it to your &os; system. + + + + License Manager Startup + + + Create symlinks for the license manager scripts: + + &prompt.root; ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW +&prompt.root; ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW + + + + Create a startup file at + /usr/local/etc/rc.d/flexlm.sh. The + example below is a modified version of the distributed + $MATLAB/etc/rc.lm.glnx86. The changes + are file locations, and startup of the license manager + under Linux emulation. + + #!/bin/sh +case "$1" in + start) + if [ -f /usr/local/etc/lmboot_TMW ]; then + /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u username && echo 'MATLAB_lmgrd' + fi + ;; + stop) + if [ -f /usr/local/etc/lmdown_TMW ]; then + /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1 + fi + ;; + *) + echo "Usage: $0 {start|stop}" + exit 1 + ;; +esac + +exit 0 + + + The file must be made executable: + + &prompt.root; chmod +x /usr/local/etc/rc.d/flexlm.sh + + You must also replace + username above with the name + of a valid user on your system (and not + root). + + + + + Start the license manager with the command: + + &prompt.root; /usr/local/etc/rc.d/flexlm.sh start + + + + + + Linking the &java; Runtime Environment + + Change the &java; Runtime + Environment (JRE) link to one working under &os;: + + &prompt.root; cd $MATLAB/sys/java/jre/glnx86/ +&prompt.root; unlink jre; ln -s ./jre1.1.8 ./jre + + + + Creating a &matlab; Startup Script + + + + Place the following startup script in + /usr/local/bin/matlab: + + + #!/bin/sh +/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@" + + + + Then type the command + chmod +x /usr/local/bin/matlab. + + + + + Depending on your version of + emulators/linux_base, you + may run into errors when running this script. To avoid that, + edit the file + /compat/linux/usr/local/matlab/bin/matlab, + and change the line that says: + + if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then + + (in version 13.0.1 it is on line 410) to this + line: + + if test -L $newbase; then + + + + + Creating a &matlab; Shutdown Script + + The following is needed to solve a problem with &matlab; + not exiting correctly. + + + + Create a file + $MATLAB/toolbox/local/finish.m, and + in it put the single line: + + ! $MATLAB/bin/finish.sh + + The $MATLAB is + literal. + + + In the same directory, you will find the files + finishsav.m and + finishdlg.m, which let you save + your workspace before quitting. If you use either of + them, insert the line above immediately after the + save command. + + + + Create a file + $MATLAB/bin/finish.sh, which will + contain the following: + + #!/usr/compat/linux/bin/sh +(sleep 5; killall -1 matlab_helper) & +exit 0 + + + + Make the file executable: + + &prompt.root; chmod +x $MATLAB/bin/finish.sh + + + + + + Using &matlab; + + At this point you are ready to type + matlab and start using it. + + + + + + + + Marcel + Moolenaar + Contributed by + + + + + Installing &oracle; + + + applications + Oracle + + + + Preface + This document describes the process of installing &oracle; 8.0.5 and + &oracle; 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD + machine. + + + + Installing the Linux Environment + + Make sure you have both emulators/linux_base and + devel/linux_devtools from the Ports Collection + installed. If you run into difficulties with these ports, + you may have to use + the packages or older versions available in the Ports Collection. + + If you want to run the intelligent agent, you will + also need to install the Red Hat Tcl package: + tcl-8.0.3-20.i386.rpm. The general command + for installing packages with the official RPM port (archivers/rpm) is: + + &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package + + Installation of the package should not generate any errors. + + + + Creating the &oracle; Environment + + Before you can install &oracle;, you need to set up a proper + environment. This document only describes what to do + specially to run &oracle; for Linux on FreeBSD, not + what has been described in the &oracle; installation guide. + + + Kernel Tuning + kernel tuning + + As described in the &oracle; installation guide, you need to set + the maximum size of shared memory. Do not use + SHMMAX under FreeBSD. SHMMAX + is merely calculated out of SHMMAXPGS and + PGSIZE. Therefore define + SHMMAXPGS. All other options can be used as + described in the guide. For example: + + options SHMMAXPGS=10000 +options SHMMNI=100 +options SHMSEG=10 +options SEMMNS=200 +options SEMMNI=70 +options SEMMSL=61 + + Set these options to suit your intended use of &oracle;. + + Also, make sure you have the following options in your kernel + configuration file: + +options SYSVSHM #SysV shared memory +options SYSVSEM #SysV semaphores +options SYSVMSG #SysV interprocess communication + + + + + &oracle; Account + + Create an oracle account just as you would create any other + account. The oracle account is special only that you need to give + it a Linux shell. Add /compat/linux/bin/bash to + /etc/shells and set the shell for the oracle + account to /compat/linux/bin/bash. + + + + Environment + + Besides the normal &oracle; variables, such as + ORACLE_HOME and ORACLE_SID you must + set the following environment variables: + + + + + + + + Variable + + Value + + + + + LD_LIBRARY_PATH + + $ORACLE_HOME/lib + + + + CLASSPATH + + $ORACLE_HOME/jdbc/lib/classes111.zip + + + + PATH + + /compat/linux/bin +/compat/linux/sbin +/compat/linux/usr/bin +/compat/linux/usr/sbin +/bin +/sbin +/usr/bin +/usr/sbin +/usr/local/bin +$ORACLE_HOME/bin + + + + + + It is advised to set all the environment variables in + .profile. A complete example is: + +ORACLE_BASE=/oracle; export ORACLE_BASE +ORACLE_HOME=/oracle; export ORACLE_HOME +LD_LIBRARY_PATH=$ORACLE_HOME/lib +export LD_LIBRARY_PATH +ORACLE_SID=ORCL; export ORACLE_SID +ORACLE_TERM=386x; export ORACLE_TERM +CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip +export CLASSPATH +PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin +PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin +PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin +export PATH + + + + + Installing &oracle; + + Due to a slight inconsistency in the Linux emulator, you need to + create a directory named .oracle in + /var/tmp before you start the installer. + Let it be owned by the oracle user. You + should be able to install &oracle; without any problems. If you have + problems, check your &oracle; distribution and/or configuration first! + After you have installed &oracle;, apply the patches described in the + next two subsections. + + A frequent problem is that the TCP protocol adapter is not + installed right. As a consequence, you cannot start any TCP listeners. + The following actions help solve this problem: + + &prompt.root; cd $ORACLE_HOME/network/lib +&prompt.root; make -f ins_network.mk ntcontab.o +&prompt.root; cd $ORACLE_HOME/lib +&prompt.root; ar r libnetwork.a ntcontab.o +&prompt.root; cd $ORACLE_HOME/network/lib +&prompt.root; make -f ins_network.mk install + + Do not forget to run root.sh again! + + + Patching root.sh + + When installing &oracle;, some actions, which need to be performed + as root, are recorded in a shell script called + root.sh. This script is + written in the orainst directory. Apply the + following patch to root.sh, to have it use to proper location of + chown or alternatively run the script under a + Linux native shell. + + *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 +--- orainst/root.sh Mon Dec 28 15:58:53 1998 +*************** +*** 31,37 **** +# This is the default value for CHOWN +# It will redefined later in this script for those ports +# which have it conditionally defined in ss_install.h +! CHOWN=/bin/chown +# +# Define variables to be used in this script +--- 31,37 ---- +# This is the default value for CHOWN +# It will redefined later in this script for those ports +# which have it conditionally defined in ss_install.h +! CHOWN=/usr/sbin/chown +# +# Define variables to be used in this script + + When you do not install &oracle; from CD, you can patch the source + for root.sh. It is called + rthd.sh and is located in the + orainst directory in the source tree. + + + + Patching genclntsh + + The script genclntsh is used to create + a single shared client + library. It is used when building the demos. Apply the following + patch to comment out the definition of PATH: + + *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 +--- bin/genclntsh Tue Dec 22 15:36:49 1998 +*************** +*** 32,38 **** +# +# Explicit path to ensure that we're using the correct commands +#PATH=/usr/bin:/usr/ccs/bin export PATH +! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH +# +# each product MUST provide a $PRODUCT/admin/shrept.lst +--- 32,38 ---- +# +# Explicit path to ensure that we're using the correct commands +#PATH=/usr/bin:/usr/ccs/bin export PATH +! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH +# +# each product MUST provide a $PRODUCT/admin/shrept.lst + + + + + Running &oracle; + + When you have followed the instructions, you should be able to run + &oracle; as if it was run on Linux + itself. + + + + + + + + Holger + Kipp + Contributed by + + + + + + Valentino + Vaschetto + Original version converted to SGML by + + + + + Installing &sap.r3; + + + applications + SAP R/3 + + + Installations of &sap; Systems using FreeBSD will not be + supported by the &sap; support team — they only offer support + for certified platforms. + + + Preface + + This document describes a possible way of installing a + &sap.r3; System + with &oracle; Database + for Linux onto a FreeBSD machine, including the installation + of FreeBSD and &oracle;. Two different + configurations will be described: + + + + &sap.r3; 4.6B (IDES) with + &oracle; 8.0.5 on FreeBSD 4.3-STABLE + + + + &sap.r3; 4.6C with + &oracle; 8.1.7 on FreeBSD 4.5-STABLE + + + + Even though this document tries to describe all important + steps in a greater detail, it is not intended as a replacement + for the &oracle; and + &sap.r3; installation guides. + + Please see the documentation that comes with the + &sap.r3; + Linux edition for &sap; and + &oracle; specific questions, as well + as resources from &oracle; and + &sap; OSS. + + + + Software + + The following CD-ROMs have been used for &sap; installations: + + + &sap.r3; 4.6B, &oracle; 8.0.5 + + + + + + Name Number Description + + + + + KERNEL 51009113 SAP Kernel Oracle / + Installation / AIX, Linux, Solaris + + + + RDBMS 51007558 Oracle / RDBMS 8.0.5.X / + Linux + + + + EXPORT1 51010208 IDES / DB-Export / + Disc 1 of 6 + + + + EXPORT2 51010209 IDES / DB-Export / + Disc 2 of 6 + + + + EXPORT3 51010210 IDES / DB-Export / + Disc 3 of 6 + + + + EXPORT4 51010211 IDES / DB-Export / + Disc 4 of 6 + + + + EXPORT5 51010212 IDES / DB-Export / + Disc 5 of 6 + + + + EXPORT6 51010213 IDES / DB-Export / + Disc 6 of 6 + + + + + + Additionally, we used the &oracle; 8 + Server (Pre-production version 8.0.5 for Linux, + Kernel Version 2.0.33) CD which is not really necessary, and + FreeBSD 4.3-STABLE (it was only a few days past 4.3 + RELEASE). + + + + &sap.r3; 4.6C SR2, &oracle; 8.1.7 + + + + + + Name Number Description + + + + + + KERNEL 51014004 SAP Kernel Oracle / + SAP Kernel Version 4.6D / DEC, Linux + + + + RDBMS 51012930 Oracle 8.1.7/ RDBMS / + Linux + + + + EXPORT1 51013953 Release 4.6C SR2 / Export + / Disc 1 of 4 + + + + EXPORT1 51013953 Release 4.6C SR2 / Export + / Disc 2 of 4 + + + + EXPORT1 51013953 Release 4.6C SR2 / Export + / Disc 3 of 4 + + + + EXPORT1 51013953 Release 4.6C SR2 / Export + / Disc 4 of 4 + + + + LANG1 51013954 Release 4.6C SR2 / + Language / DE, EN, FR / Disc 1 of 3 + + + + + + Depending on the languages you would like to install, additional + language CDs might be necessary. Here we are just using DE and EN, so + the first language CD is the only one needed. As a little note, the + numbers for all four EXPORT CDs are identical. All three language CDs + also have the same number (this is different from the 4.6B IDES + release CD numbering). At the time of writing this installation is + running on FreeBSD 4.5-STABLE (20.03.2002). + + + + + &sap; Notes + + The following notes should be read before installing + &sap.r3; and proved to be useful + during installation: + + + &sap.r3; 4.6B, &oracle; 8.0.5 + + + + + + Number + Title + + + + + + 0171356 SAP Software on Linux: Essential + Comments + + + + 0201147 INST: 4.6C R/3 Inst. on UNIX - + Oracle + + + + 0373203 Update / Migration Oracle 8.0.5 --> + 8.0.6/8.1.6 LINUX + + + + 0072984 Release of Digital UNIX 4.0B for + Oracle + + + + 0130581 R3SETUP step DIPGNTAB terminates + + + + 0144978 Your system has not been installed + correctly + + + + 0162266 Questions and tips for R3SETUP on Windows + NT / W2K + + + + + + + + &sap.r3; 4.6C, &oracle; 8.1.7 + + + + + + Number + Title + + + + + 0015023 Initializing table TCPDB (RSXP0004) + (EBCDIC) + + + + 0045619 R/3 with several languages or + typefaces + + + + 0171356 SAP Software on Linux: Essential + Comments + + + + 0195603 RedHat 6.1 Enterprise version: + Known problems + + + + 0212876 The new archiving tool SAPCAR + + + + 0300900 Linux: Released DELL Hardware + + + + 0377187 RedHat 6.2: important remarks + + + + 0387074 INST: R/3 4.6C SR2 Installation on + UNIX + + + + 0387077 INST: R/3 4.6C SR2 Inst. on UNIX - + Oracle + + + + 0387078 SAP Software on UNIX: OS Dependencies + 4.6C SR2 + + + + + + + + + Hardware Requirements + + The following equipment is sufficient for the installation + of a &sap.r3; System. For production + use, a more exact sizing is of course needed: + + + + + + Component + 4.6B + 4.6C + + + + + Processor + 2 x 800MHz &pentium; III + 2 x 800MHz &pentium; III + + + + Memory + 1GB ECC + 2GB ECC + + + + Hard Disk Space + 50-60GB (IDES) + 50-60GB (IDES) + + + + + + For use in production, &xeon; Processors with large cache, + high-speed disk access (SCSI, RAID hardware controller), USV + and ECC-RAM is recommended. The large amount of hard disk + space is due to the preconfigured IDES System, which creates + 27 GB of database files during installation. This space is + also sufficient for initial production systems and application + data. + + + &sap.r3; 4.6B, &oracle; 8.0.5 + + The following off-the-shelf hardware was used: a dual processor + board with 2 800 MHz &pentium; III processors, &adaptec; 29160 Ultra160 + SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM), + &mylex; &acceleraid; (2 channels, firmware 6.00-1-00 with 32 MB RAM). + To the &mylex; RAID controller are attached two 17 GB hard disks + (mirrored) and four 36 GB hard disks (RAID level 5). + + + + &sap.r3; 4.6C, &oracle; 8.1.7 + + For this installation a &dell; &poweredge; 2500 was used: a + dual processor board with two 1000 MHz &pentium; III processors + (256 kB Cache), 2 GB PC133 ECC SDRAM, PERC/3 DC PCI RAID Controller + with 128 MB, and an EIDE DVD-ROM drive. To the RAID controller are + attached two 18 GB hard disks (mirrored) and four 36 GB hard disks + (RAID level 5). + + + + + Installation of FreeBSD + + First you have to install FreeBSD. There are several ways to do + this, for more information read the . + + + Disk Layout + + To keep it simple, the same disk layout both for the + &sap.r3; 46B and &sap.r3; 46C + SR2 installation was used. Only the device names + changed, as the installations were on different hardware (/dev/da + and /dev/amr respectively, so if using an AMI &megaraid;, one will see + /dev/amr0s1a instead of /dev/da0s1a): + + + + + + File system + Size (1k-blocks) + Size (GB) + Mounted on + + + + + /dev/da0s1a + 1.016.303 + 1 + / + + + + /dev/da0s1b + + 6 + swap + + + + /dev/da0s1e + 2.032.623 + 2 + /var + + + + /dev/da0s1f + 8.205.339 + 8 + /usr + + + + /dev/da1s1e + 45.734.361 + 45 + /compat/linux/oracle + + + + /dev/da1s1f + 2.032.623 + 2 + /compat/linux/sapmnt + + + + /dev/da1s1g + 2.032.623 + 2 + /compat/linux/usr/sap + + + + + + Configure and initialize the two logical drives + with the &mylex; or PERC/3 RAID software beforehand. + The software can be started during the + BIOS boot phase. + + Please note that this disk layout differs slightly from + the &sap; recommendations, as &sap; suggests mounting the + &oracle; subdirectories (and some others) separately — we + decided to just create them as real subdirectories for + simplicity. + + + + <command>make world</command> and a New Kernel + + Download the latest -STABLE sources. Rebuild world and your + custom kernel after configuring your kernel configuration file. + Here you should also include the + kernel parameters + which are required for both &sap.r3; + and &oracle;. + + + + + Installing the Linux Environment + + + Installing the Linux Base System + + First the linux_base + port needs to be installed (as root): + + &prompt.root; cd /usr/ports/emulators/linux_base +&prompt.root; make install distclean + + + + + + Installing Linux Development Environment + + The Linux development environment is needed, if you want to install + &oracle; on FreeBSD according to the + : + + &prompt.root; cd /usr/ports/devel/linux_devtools +&prompt.root; make install distclean + + The Linux development environment has only been installed for the &sap.r3; + 46B IDES installation. It is not needed, if + the &oracle; DB is not relinked on the + FreeBSD system. This is the case if you are using the + &oracle; tarball from a Linux system. + + + + + + Installing the Necessary RPMs + RPMs + + To start the R3SETUP program, PAM support is needed. + During the first &sap; Installation on FreeBSD 4.3-STABLE we + tried to install PAM with all the required packages and + finally forced the installation of the PAM package, which + worked. For &sap.r3; 4.6C SR2 we + directly forced the installation of the PAM RPM, which also + works, so it seems the dependent packages are not needed: + + +&prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \ +pam-0.68-7.i386.rpm + + For &oracle; 8.0.5 to run the + intelligent agent, we also had to install the RedHat Tcl package + tcl-8.0.5-30.i386.rpm (otherwise the + relinking during &oracle; installation + will not work). There are some other issues regarding + relinking of &oracle;, but that is + a &oracle; Linux issue, not FreeBSD specific. + + + + + Some Additional Hints + + It might also be a good idea to add linprocfs + to /etc/fstab, for more information, see the &man.linprocfs.5; manual page. + Another parameter to set is kern.fallback_elf_brand=3 + which is done in the file /etc/sysctl.conf. + + + + + Creating the &sap.r3; Environment + + + Creating the Necessary File Systems and Mountpoints + + For a simple installation, it is sufficient to create the + following file systems: + + + + + + mount point + size in GB + + + + + /compat/linux/oracle + 45 GB + + + + /compat/linux/sapmnt + 2 GB + + + + /compat/linux/usr/sap + 2 GB + + + + + + It is also necessary to created some links. Otherwise + the &sap; Installer will complain, as it is checking the + created links: + + &prompt.root; ln -s /compat/linux/oracle /oracle +&prompt.root; ln -s /compat/linux/sapmnt /sapmnt +&prompt.root; ln -s /compat/linux/usr/sap /usr/sap + + Possible error message during installation (here with + System PRD and the + &sap.r3; 4.6C SR2 + installation): + + INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200 + Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to + /sapmnt/PRD/exe. Creating if it does not exist... + +WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400 + Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file + /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The + program cannot go on as long as this link exists at this + location. Move the link to another location. + +ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0 + can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content + '/sapmnt/PRD/exe' + + + + Creating Users and Directories + + &sap.r3; needs two users and + three groups. The user names depend on the + &sap; system ID (SID) which consists + of three letters. Some of these SIDs are reserved + by &sap; (for example + SAP and NIX. For a + complete list please see the &sap; documentation). For the IDES + installation we used IDS, for the + 4.6C SR2 installation PRD, as that system + is intended for production use. We have + therefore the following groups (group IDs might differ, these + are just the values we used with our installation): + + + + + + group ID + group name + description + + + + + 100 + dba + Data Base Administrator + + + 101 + sapsys + &sap; System + + + 102 + oper + Data Base Operator + + + + + + For a default &oracle; installation, only group + dba is used. As + oper group, one also uses group + dba (see &oracle; and + &sap; documentation for further information). + + We also need the following users: + + + + + + user ID + user name + generic name + group + additional groups + description + + + + + 1000 + idsadm/prdadm + sidadm + sapsys + oper + &sap; Administrator + + + 1002 + oraids/oraprd + orasid + dba + oper + &oracle; Administrator + + + + + + Adding the users with &man.adduser.8; + requires the following (please note shell and home + directory) entries for &sap; Administrator: + + Name: sidadm +Password: ****** +Fullname: SAP Administrator SID +Uid: 1000 +Gid: 101 (sapsys) +Class: +Groups: sapsys dba +HOME: /home/sidadm +Shell: bash (/compat/linux/bin/bash) + + and for &oracle; Administrator: + + Name: orasid +Password: ****** +Fullname: Oracle Administrator SID +Uid: 1002 +Gid: 100 (dba) +Class: +Groups: dba +HOME: /oracle/sid +Shell: bash (/compat/linux/bin/bash) + + This should also include group + oper in case you are using both + groups dba and + oper. + + + + + Creating Directories + + These directories are usually created as separate + file systems. This depends entirely on your requirements. We + choose to create them as simple directories, as they are all + located on the same RAID 5 anyway: + + First we will set owners and rights of some directories (as + user root): + + &prompt.root; chmod 775 /oracle +&prompt.root; chmod 777 /sapmnt +&prompt.root; chown root:dba /oracle +&prompt.root; chown sidadm:sapsys /compat/linux/usr/sap +&prompt.root; chmod 775 /compat/linux/usr/sap + + Second we will create directories as user + orasid. These + will all be subdirectories of + /oracle/SID: + + &prompt.root; su - orasid +&prompt.root; cd /oracle/SID +&prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB +&prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6 +&prompt.root; mkdir saparch sapreorg +&prompt.root; exit + + For the &oracle; 8.1.7 installation + some additional directories are needed: + + &prompt.root; su - orasid +&prompt.root; cd /oracle +&prompt.root; mkdir 805_32 +&prompt.root; mkdir client stage +&prompt.root; mkdir client/80x_32 +&prompt.root; mkdir stage/817_32 +&prompt.root; cd /oracle/SID +&prompt.root; mkdir 817_32 + + The directory client/80x_32 is used + with exactly this name. Do not replace the x + with some number or anything. + + In the third step we create directories as user + sidadm: + + &prompt.root; su - sidadm +&prompt.root; cd /usr/sap +&prompt.root; mkdir SID +&prompt.root; mkdir trans +&prompt.root; exit + + + + Entries in <filename>/etc/services</filename> + + &sap.r3; requires some entries in file + /etc/services, which will not be set + correctly during installation under FreeBSD. Please add the + following entries (you need at least those entries + corresponding to the instance number — in this case, + 00. It will do no harm adding all + entries from 00 to + 99 for dp, + gw, sp and + ms). If you are going to use a SAProuter + or need to access &sap; OSS, you also need 99, + as port 3299 is usually used for the SAProuter process on the + target system: + + +sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number +sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number +sapsp00 3400/tcp # 3400 + Instance-Number +sapms00 3500/tcp # 3500 + Instance-Number +sapmsSID 3600/tcp # SAP Message Server. 3600 + Instance-Number +sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-Number + + + + Necessary Locales + locale + + &sap; requires at least two locales that are not part of + the default RedHat installation. &sap; offers the required + RPMs as download from their FTP server (which is only + accessible if you are a customer with OSS access). See note + 0171356 for a list of RPMs you need. + + It is also possible to just create appropriate links + (for example from de_DE and + en_US ), but we would not recommend this + for a production system (so far it worked with the IDES + system without any problems, though). The following locales + are needed: + + de_DE.ISO-8859-1 +en_US.ISO-8859-1 + + Create the links like this: + + &prompt.root; cd /compat/linux/usr/share/locale +&prompt.root; ln -s de_DE de_DE.ISO-8859-1 +&prompt.root; ln -s en_US en_US.ISO-8859-1 + + If they are not present, there will be some problems + during the installation. If these are then subsequently + ignored (by setting the STATUS of the offending steps to + OK in file CENTRDB.R3S), it will be impossible to log onto + the &sap; system without some additional effort. + + + + Kernel Tuning + kernel tuning + + &sap.r3; systems need a lot of resources. We therefore + added the following parameters to the kernel configuration file: + + # Set these for memory pigs (SAP and Oracle): +options MAXDSIZ="(1024*1024*1024)" +options DFLDSIZ="(1024*1024*1024)" +# System V options needed. +options SYSVSHM #SYSV-style shared memory +options SHMMAXPGS=262144 #max amount of shared mem. pages +#options SHMMAXPGS=393216 #use this for the 46C inst.parameters +options SHMMNI=256 #max number of shared memory ident if. +options SHMSEG=100 #max shared mem.segs per process +options SYSVMSG #SYSV-style message queues +options MSGSEG=32767 #max num. of mes.segments in system +options MSGSSZ=32 #size of msg-seg. MUST be power of 2 +options MSGMNB=65535 #max char. per message queue +options MSGTQL=2046 #max amount of msgs in system +options SYSVSEM #SYSV-style semaphores +options SEMMNU=256 #number of semaphore UNDO structures +options SEMMNS=1024 #number of semaphores in system +options SEMMNI=520 #number of semaphore identifiers +options SEMUME=100 #number of UNDO keys + + The minimum values are specified in the documentation that + comes from &sap;. As there is no description for Linux, see the + HP-UX section (32-bit) for further information. As the system + for the 4.6C SR2 installation has more main memory, the shared + segments can be larger both for &sap; + and &oracle;, therefore choose a larger + number of shared memory pages. + + With the default installation of FreeBSD on &i386;, + leave MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange + errors like ORA-27102: out of memory and + Linux Error: 12: Cannot allocate memory + might happen. + + + + + Installing &sap.r3; + + + Preparing &sap; CDROMs + + There are many CDROMs to mount and unmount during the + installation. Assuming you have enough CDROM drives, you + can just mount them all. We decided to copy the CDROMs + contents to corresponding directories: + + /oracle/SID/sapreorg/cd-name + + where cd-name was one of KERNEL, + RDBMS, EXPORT1, + EXPORT2, EXPORT3, + EXPORT4, EXPORT5 and + EXPORT6 for the 4.6B/IDES installation, and + KERNEL, RDBMS, + DISK1, DISK2, + DISK3, DISK4 and + LANG for the 4.6C SR2 installation. All the + filenames on the mounted CDs should be in capital letters, + otherwise use the option for mounting. So use the following + commands: + + &prompt.root; mount_cd9660 -g /dev/cd0a /mnt +&prompt.root; cp -R /mnt/* /oracle/SID/sapreorg/cd-name +&prompt.root; umount /mnt + + + + Running the Installation Script + + First you have to prepare an install directory: + + &prompt.root; cd /oracle/SID/sapreorg +&prompt.root; mkdir install +&prompt.root; cd install + + Then the installation script is started, which will copy nearly + all the relevant files into the install directory: + + &prompt.root; /oracle/SID/sapreorg/KERNEL/UNIX/INSTTOOL.SH + + The IDES installation (4.6B) comes with a fully customized + &sap.r3; demonstration system, so there are six instead of just three + EXPORT CDs. At this point the installation template + CENTRDB.R3S is for installing a standard + central instance (&r3; and database), not the IDES central + instance, so one needs to copy the corresponding CENTRDB.R3S + from the EXPORT1 directory, otherwise R3SETUP will only ask + for three EXPORT CDs. + + The newer &sap; 4.6C SR2 release + comes with four EXPORT CDs. The parameter file that controls + the installation steps is CENTRAL.R3S. + Contrary to earlier releases there are no separate installation + templates for a central instance with or without database. + &sap; is using a separate template for database installation. To restart + the installation later it is however sufficient to restart with + the original file. + + During and after installation, &sap; requires + hostname to return the computer name + only, not the fully qualified domain name. So either + set the hostname accordingly, or set an alias with + alias hostname='hostname -s' for + both orasid and + sidadm (and for + root at least during installation + steps performed as root). It is also + possible to adjust the installed .profile and .login files of + both users that are installed during + &sap; installation. + + + + Start <command>R3SETUP</command> 4.6B + + Make sure LD_LIBRARY_PATH is set correctly: + + &prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib + + Start R3SETUP as root from + installation directory: + + &prompt.root; cd /oracle/IDS/sapreorg/install +&prompt.root; ./R3SETUP -f CENTRDB.R3S + + The script then asks some questions (defaults in brackets, + followed by actual input): + + + + + + Question + Default + Input + + + + + Enter SAP System ID + [C11] + IDSEnter + + + Enter SAP Instance Number + [00] + Enter + + + Enter SAPMOUNT Directory + [/sapmnt] + Enter + + + Enter name of SAP central host + [troubadix.domain.de] + Enter + + + Enter name of SAP db host + [troubadix] + Enter + + + Select character set + [1] (WE8DEC) + Enter + + + Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6 + + 1Enter + + + Extract Oracle Client archive + [1] (Yes, extract) + Enter + + + Enter path to KERNEL CD + [/sapcd] + /oracle/IDS/sapreorg/KERNEL + + + Enter path to RDBMS CD + [/sapcd] + /oracle/IDS/sapreorg/RDBMS + + + Enter path to EXPORT1 CD + [/sapcd] + /oracle/IDS/sapreorg/EXPORT1 + + + Directory to copy EXPORT1 CD + [/oracle/IDS/sapreorg/CD4_DIR] + Enter + + + Enter path to EXPORT2 CD + [/sapcd] + /oracle/IDS/sapreorg/EXPORT2 + + + Directory to copy EXPORT2 CD + [/oracle/IDS/sapreorg/CD5_DIR] + Enter + + + Enter path to EXPORT3 CD + [/sapcd] + /oracle/IDS/sapreorg/EXPORT3 + + + Directory to copy EXPORT3 CD + [/oracle/IDS/sapreorg/CD6_DIR] + Enter + + + Enter path to EXPORT4 CD + [/sapcd] + /oracle/IDS/sapreorg/EXPORT4 + + + Directory to copy EXPORT4 CD + [/oracle/IDS/sapreorg/CD7_DIR] + Enter + + + Enter path to EXPORT5 CD + [/sapcd] + /oracle/IDS/sapreorg/EXPORT5 + + + Directory to copy EXPORT5 CD + [/oracle/IDS/sapreorg/CD8_DIR] + Enter + + + Enter path to EXPORT6 CD + [/sapcd] + /oracle/IDS/sapreorg/EXPORT6 + + + Directory to copy EXPORT6 CD + [/oracle/IDS/sapreorg/CD9_DIR] + Enter + + + Enter amount of RAM for SAP + DB + + 850Enter (in Megabytes) + + + Service Entry Message Server + [3600] + Enter + + + Enter Group-ID of sapsys + [101] + Enter + + + Enter Group-ID of oper + [102] + Enter + + + Enter Group-ID of dba + [100] + Enter + + + Enter User-ID of sidadm + [1000] + Enter + + + Enter User-ID of orasid + [1002] + Enter + + + Number of parallel procs + [2] + Enter + + + + + + If you had not copied the CDs to the different locations, + then the &sap; installer cannot find the CD needed (identified + by the LABEL.ASC file on the CD) and would + then ask you to insert and mount the CD and confirm or enter + the mount path. + + The CENTRDB.R3S might not be + error free. In our case, it requested EXPORT4 CD again but + indicated the correct key (6_LOCATION, then 7_LOCATION + etc.), so one can just continue with entering the correct + values. + + Apart from some problems mentioned below, everything + should go straight through up to the point where the &oracle; + database software needs to be installed. + + + + Start <command>R3SETUP</command> 4.6C SR2 + + Make sure LD_LIBRARY_PATH is set correctly. This is a + different value from the 4.6B installation with + &oracle; 8.0.5: + + &prompt.root; export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib + + Start R3SETUP as user root from installation directory: + + &prompt.root; cd /oracle/PRD/sapreorg/install +&prompt.root; ./R3SETUP -f CENTRAL.R3S + + The script then asks some questions (defaults in brackets, + followed by actual input): + + + + + + Question + Default + Input + + + + + Enter SAP System ID + [C11] + PRDEnter + + + Enter SAP Instance Number + [00] + Enter + + + Enter SAPMOUNT Directory + [/sapmnt] + Enter + + + Enter name of SAP central host + [majestix] + Enter + + + Enter Database System ID + [PRD] + PRDEnter + + + Enter name of SAP db host + [majestix] + Enter + + + Select character set + [1] (WE8DEC) + Enter + + + Enter Oracle server version (2) Oracle 8.1.7 + + 2Enter + + + Extract Oracle Client archive + [1] (Yes, extract) + Enter + + + Enter path to KERNEL CD + [/sapcd] + /oracle/PRD/sapreorg/KERNEL + + + Enter amount of RAM for SAP + DB + 2044 + 1800Enter (in Megabytes) + + + Service Entry Message Server + [3600] + Enter + + + Enter Group-ID of sapsys + [100] + Enter + + + Enter Group-ID of oper + [101] + Enter + + + Enter Group-ID of dba + [102] + Enter + + + Enter User-ID of oraprd + [1002] + Enter + + + Enter User-ID of prdadm + [1000] + Enter + + + LDAP support + + 3Enter (no support) + + + Installation step completed + [1] (continue) + Enter + + + Choose installation service + [1] (DB inst,file) + Enter + + + + + + So far, creation of users gives an error during + installation in phases OSUSERDBSID_IND_ORA (for creating + user orasid) and + OSUSERSIDADM_IND_ORA (creating user + sidadm). + + Apart from some problems mentioned below, everything + should go straight through up to the point where the &oracle; + database software needs to be installed. + + + + + Installing &oracle; 8.0.5 + + Please see the corresponding &sap; Notes and &oracle; Readmes + regarding Linux and &oracle; DB for possible problems. Most if + not all problems stem from incompatible libraries. + + For more information on installing &oracle;, refer to the Installing &oracle; + chapter. + + + + Installing the &oracle; 8.0.5 with <command>orainst</command> + + If &oracle; 8.0.5 is to be + used, some additional libraries are needed for successfully + relinking, as &oracle; 8.0.5 was linked with an old glibc + (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So + you have to install the following additional packages to + ensure that linking will work: + + compat-libs-5.2-2.i386.rpm + compat-glibc-5.2-2.0.7.2.i386.rpm + compat-egcs-5.2-1.0.3a.1.i386.rpm + compat-egcs-c++-5.2-1.0.3a.1.i386.rpm + compat-binutils-5.2-2.9.1.0.23.1.i386.rpm + + See the corresponding &sap; Notes or &oracle; Readmes for + further information. If this is no option (at the time of + installation we did not have enough time to check this), one + could use the original binaries, or use the relinked + binaries from an original RedHat system. + + For compiling the intelligent agent, the RedHat Tcl + package must be installed. If you cannot get + tcl-8.0.3-20.i386.rpm, a newer one like + tcl-8.0.5-30.i386.rpm for RedHat 6.1 + should also do. + + Apart from relinking, the installation is + straightforward: + + &prompt.root; su - oraids +&prompt.root; export TERM=xterm +&prompt.root; export ORACLE_TERM=xterm +&prompt.root; export ORACLE_HOME=/oracle/IDS +&prompt.root; cd $ORACLE_HOME/orainst_sap +&prompt.root; ./orainst + + Confirm all screens with Enter until the software is + installed, except that one has to deselect the + &oracle; On-Line Text Viewer, as this is + not currently available for Linux. &oracle; then wants to + relink with i386-glibc20-linux-gcc + instead of the available gcc, + egcs or i386-redhat-linux-gcc + . + + Due to time constrains we decided to use the binaries + from an &oracle; 8.0.5 PreProduction + release, after the first + attempt at getting the version from the RDBMS CD working, + failed, and finding and accessing the correct RPMs was a + nightmare at that time. + + + + + Installing the &oracle; 8.0.5 Pre-production Release for + Linux (Kernel 2.0.33) + + This installation is quite easy. Mount the CD, start the + installer. It will then ask for the location of the &oracle; + home directory, and copy all binaries there. We did not + delete the remains of our previous RDBMS installation tries, + though. + + Afterwards, &oracle; Database could be started with no + problems. + + + + + Installing the &oracle; 8.1.7 Linux Tarball + Take the tarball oracle81732.tgz you + produced from the installation directory on a Linux system + and untar it to /oracle/SID/817_32/. + + + + Continue with &sap.r3; Installation + + First check the environment settings of users + idsamd + (sidadm) and + oraids (orasid). They should now + both have the files .profile, + .login and .cshrc + which are all using hostname. In case the + system's hostname is the fully qualified name, you need to + change hostname to hostname + -s within all three files. + + + Database Load + + Afterwards, R3SETUP can either be restarted or continued + (depending on whether exit was chosen or not). R3SETUP then + creates the tablespaces and loads the data (for 46B IDES, from + EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with R3load + into the database. + + When the database load is finished (might take a few + hours), some passwords are requested. For test + installations, one can use the well known default passwords + (use different ones if security is an issue!): + + + + + + Question + Input + + + + + Enter Password for sapr3 + sapEnter + + + Confirum Password for sapr3 + sapEnter + + + Enter Password for sys + change_on_installEnter + + + Confirm Password for sys + change_on_installEnter + + + Enter Password for system + managerEnter + + + Confirm Password for system + managerEnter + + + + + + At this point We had a few problems with + dipgntab during the 4.6B + installation. + + + + Listener + + Start the &oracle; Listener as user + orasid as follows: + + &prompt.user; umask 0; lsnrctl start + + Otherwise you might get the error ORA-12546 as the sockets will not + have the correct permissions. See &sap; Note 072984. + + + + Updating MNLS Tables + If you plan to import non-Latin-1 languages into the &sap; system, + you have to update the Multi National Language Support tables. + This is described in the &sap; OSS Notes 15023 and 45619. Otherwise, + you can skip this question during &sap; installation. + If you do not need MNLS, it is still necessary to check + the table TCPDB and initializing it if this has not been done. See + &sap; note 0015023 and 0045619 for further information. + + + + + Post-installation Steps + + + Request &sap.r3; License Key + + You have to request your &sap.r3; License Key. This is needed, + as the temporary license that was installed during installation + is only valid for four weeks. First get the hardware key. Log + on as user idsadm and call + saplicense: + + &prompt.root; /sapmnt/IDS/exe/saplicense -get + + Calling saplicense without parameters gives + a list of options. Upon receiving the license key, it can be + installed using: + + &prompt.root; /sapmnt/IDS/exe/saplicense -install + + You are then required to enter the following values: + + SAP SYSTEM ID = SID, 3 chars +CUSTOMER KEY = hardware key, 11 chars +INSTALLATION NO = installation, 10 digits +EXPIRATION DATE = yyyymmdd, usually "99991231" +LICENSE KEY = license key, 24 chars + + + + Creating Users + + Create a user within client 000 (for some tasks required + to be done within client 000, but with a user different from + users sap* and + ddic). As a user name, We usually choose + wartung (or + service in English). Profiles + required are sap_new and + sap_all. For additional safety the + passwords of default users within all clients should be + changed (this includes users sap* and + ddic). + + + + Configure Transport System, Profile, Operation Modes, Etc. + + Within client 000, user different from ddic + and sap*, do at least the following: + + + + + + Task + Transaction + + + + + Configure Transport System, e.g. as Stand-Alone + Transport Domain Entity + STMS + + + Create / Edit Profile for System + RZ10 + + + Maintain Operation Modes and Instances + RZ04 + + + + + + These and all the other post-installation steps are + thoroughly described in &sap; installation guides. + + + + Edit <filename>init<replaceable>sid</replaceable>.sap</filename> (<filename>initIDS.sap</filename>) + + The file /oracle/IDS/dbs/initIDS.sap + contains the &sap; backup profile. Here the size of the tape to + be used, type of compression and so on need to be defined. To + get this running with sapdba / + brbackup, we changed the following values: + + compress = hardware +archive_function = copy_delete_save +cpio_flags = "-ov --format=newc --block-size=128 --quiet" +cpio_in_flags = "-iuv --block-size=128 --quiet" +tape_size = 38000M +tape_address = /dev/nsa0 +tape_address_rew = /dev/sa0 + + Explanations: + + compress: The tape we use is a HP DLT1 + which does hardware compression. + + archive_function: This defines the + default behavior for saving &oracle; archive logs: new logfiles + are saved to tape, already saved logfiles are saved again and + are then deleted. This prevents lots of trouble if you need to + recover the database, and one of the archive-tapes has gone + bad. + + cpio_flags: Default is to use which + sets block size to 5120 Bytes. For DLT Tapes, HP recommends at + least 32 K block size, so we used for + 64 K. is needed because we have inode numbers greater than + 65535. The last option is needed as otherwise + brbackup + complains as soon as cpio outputs the + numbers of blocks saved. + + cpio_in_flags: Flags needed for + loading data back from tape. Format is recognized + automatically. + + tape_size: This usually gives the raw + storage capability of the tape. For security reason (we use + hardware compression), the value is slightly lower than the + actual value. + + tape_address: The non-rewindable + device to be used with cpio. + + tape_address_rew: The rewindable device to be + used with cpio. + + + + Configuration Issues after Installation + + The following &sap; parameters should be tuned after + installation (examples for IDES 46B, 1 GB memory): + + + + + + Name + Value + + + + + ztta/roll_extension + 250000000 + + + abap/heap_area_dia + 300000000 + + + abap/heap_area_nondia + 400000000 + + + em/initial_size_MB + 256 + + + em/blocksize_kB + 1024 + + + ipc/shm_psize_40 + 70000000 + + + + + + &sap; Note 0013026: + + + + + + Name + Value + + + + + ztta/dynpro_area + 2500000 + + + + + + &sap; Note 0157246: + + + + + + Name + Value + + + + + rdisp/ROLL_MAXFS + 16000 + + + rdisp/PG_MAXFS + 30000 + + + + + + + With the above parameters, on a system with 1 gigabyte + of memory, one may find memory consumption similar to: + + Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free + + + + + + Problems during Installation + + + Restart <command>R3SETUP</command> after Fixing a Problem + + R3SETUP stops if it encounters an error. If you have + looked at the corresponding logfiles and fixed the error, + you have to start R3SETUP again, usually selecting REPEAT + as option for the last step R3SETUP complained about. + + To restart R3SETUP, just start it with the corresponding + R3S file: + + &prompt.root; ./R3SETUP -f CENTRDB.R3S + + for 4.6B, or with + + &prompt.root; ./R3SETUP -f CENTRAL.R3S + + for 4.6C, no matter whether the error occurred + with CENTRAL.R3S or + DATABASE.R3S. + + At some stages, R3SETUP assumes that both database + and &sap; processes are up and running (as those were steps it + already completed). Should errors occur and for example the + database could not be started, you have to start both database + and &sap; by hand after you fixed the errors and before starting + R3SETUP again. + Do not forget to also start the &oracle; listener again (as + orasid with + umask 0; lsnrctl start) if it was also + stopped (for example due to a necessary reboot of the + system). + + + + + OSUSERSIDADM_IND_ORA during <command>R3SETUP</command> + + If R3SETUP complains at this stage, edit the + template file R3SETUP used at that time + (CENTRDB.R3S (4.6B) or either + CENTRAL.R3S or + DATABASE.R3S (4.6C)). + Locate [OSUSERSIDADM_IND_ORA] or search for the + only STATUS=ERROR entry + and edit the following values: + + HOME=/home/sidadm (was empty) +STATUS=OK (had status ERROR) + + + Then you can restart R3SETUP again. + + + + OSUSERDBSID_IND_ORA during <command>R3SETUP</command> + + Possibly R3SETUP also complains at this stage. The error + here is similar to the one in phase OSUSERSIDADM_IND_ORA. + Just edit + the template file R3SETUP used at that time + (CENTRDB.R3S (4.6B) or either + CENTRAL.R3S or + DATABASE.R3S (4.6C)). + Locate [OSUSERDBSID_IND_ORA] or search for the + only STATUS=ERROR entry + and edit the following value in that section: + + STATUS=OK + + Then restart R3SETUP. + + + + <errorname>oraview.vrf FILE NOT FOUND</errorname> during &oracle; Installation + + You have not deselected &oracle; On-Line Text Viewer + before starting the installation. This is marked for installation even + though this option is currently not available for Linux. Deselect this + product inside the &oracle; installation menu and restart installation. + + + + <errorname>TEXTENV_INVALID</errorname> during <command>R3SETUP</command>, RFC or SAPgui Start + + If this error is encountered, the correct locale is + missing. &sap; Note 0171356 lists the necessary RPMs that need + be installed (e.g. saplocales-1.0-3, + saposcheck-1.0-1 for RedHat 6.1). In case + you ignored all the related errors and set the corresponding + STATUS from ERROR to OK (in CENTRDB.R3S) every time R3SETUP + complained and just restarted R3SETUP, the &sap; system will not + be properly configured and you will then not be able to + connect to the system with a + SAPgui, even though the system + can be started. Trying to connect with the old Linux + SAPgui gave the following + messages: + + Sat May 5 14:23:14 2001 +*** ERROR => no valid userarea given [trgmsgo. 0401] +Sat May 5 14:23:22 2001 +*** ERROR => ERROR NR 24 occured [trgmsgi. 0410] +*** ERROR => Error when generating text environment. [trgmsgi. 0435] +*** ERROR => function failed [trgmsgi. 0447] +*** ERROR => no socket operation allowed [trxio.c 3363] +Speicherzugriffsfehler + + This behavior is due to &sap.r3; being unable to correctly + assign a locale and also not being properly configured itself + (missing entries in some database tables). To be able to connect + to &sap;, add the following entries to file + DEFAULT.PFL (see Note 0043288): + + abap/set_etct_env_at_new_mode = 0 +install/collate/active = 0 +rscp/TCP0B = TCP0B + + Restart the &sap; system. Now you can connect to the + system, even though country-specific language settings might + not work as expected. After correcting country settings + (and providing the correct locales), these entries can be + removed from DEFAULT.PFL and the &sap; + system can be restarted. + + + + + <errorcode>ORA-00001</errorcode> + This error only happened with + &oracle; 8.1.7 on FreeBSD. + The reason was that the &oracle; database could not initialize itself + properly and crashed, leaving semaphores and shared memory on the + system. The next try to start the database then returned + ORA-00001. + + Find them with ipcs -a and remove them + with ipcrm. + + + + <errorcode>ORA-00445</errorcode> (Background Process PMON Did Not Start) + This error happened with &oracle; 8.1.7. + This error is reported if the database is started with + the usual startsap script (for example + startsap_majestix_00) as user + prdadm. + + A possible workaround is to start the database as user + oraprd instead + with svrmgrl: + + &prompt.user; svrmgrl +SVRMGR> connect internal; +SVRMGR> startup; +SVRMGR> exit + + + + + <errorcode>ORA-12546</errorcode> (Start Listener with Correct Permissions) + + Start the &oracle; listener as user + oraids with the following commands: + + &prompt.root; umask 0; lsnrctl start + + Otherwise you might get ORA-12546 as the sockets will not + have the correct permissions. See &sap; Note 0072984. + + + + <errorcode>ORA-27102</errorcode> (Out of Memory) + + This error happened whilst trying to use values for + MAXDSIZ and DFLDSIZ + greater than 1 GB (1024x1024x1024). Additionally, we got + Linux Error 12: Cannot allocate memory. + + + + [DIPGNTAB_IND_IND] during <command>R3SETUP</command> + + In general, see &sap; Note 0130581 (R3SETUP step + DIPGNTAB terminates). During the + IDES-specific installation, for some reason the installation + process was not using the proper &sap; system name IDS, but + the empty string "" instead. This leads to some minor problems + with accessing directories, as the paths are generated + dynamically using SID (in this case IDS). So instead + of accessing: + + /usr/sap/IDS/SYS/... +/usr/sap/IDS/DVMGS00 + + the following paths were used: + + /usr/sap//SYS/... +/usr/sap/D00 + + To continue with the installation, we created a link and an + additional directory: + + &prompt.root; pwd +/compat/linux/usr/sap +&prompt.root; ls -l +total 4 +drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00 +drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS +lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS +drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp +drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans + + We also found &sap; Notes (0029227 and 0008401) describing + this behavior. We did not encounter any of these problems with + the &sap; 4.6C installation. + + + + [RFCRSWBOINI_IND_IND] during <command>R3SETUP</command> + + During installation of &sap; 4.6C, + this error was just the result of another error happening + earlier during installation. In this case, you have to look + through the corresponding logfiles and correct the real + problem. + + If after looking through the logfiles this error is + indeed the correct one (check the &sap; Notes), you can set + STATUS of the offending step from ERROR to OK (file + CENTRDB.R3S) and restart R3SETUP. After + installation, you have to execute the report + RSWBOINS from transaction SE38. See &sap; + Note 0162266 for additional information about phase + RFCRSWBOINI and + RFCRADDBDIF. + + + + [RFCRADDBDIF_IND_IND] during <command>R3SETUP</command> + Here the same restrictions apply: make sure by looking + through the logfiles, that this error is not caused by some + previous problems. + + If you can confirm that &sap; Note 0162266 applies, just + set STATUS of the offending step from ERROR to OK (file + CENTRDB.R3S) and restart R3SETUP. After + installation, you have to execute the report + RADDBDIF from transaction SE38. + + + + <errorcode>sigaction sig31: File size limit exceeded</errorcode> + + This error occurred during start of &sap; processes + disp+work. If starting &sap; with the + startsap script, subprocesses are then started which + detach and do the dirty work of starting all other &sap; + processes. As a result, the script itself will not notice + if something goes wrong. + + To check whether the &sap; processes did start properly, + have a look at the process status with + ps ax | grep SID, which will give + you a list of all &oracle; and &sap; processes. If it looks like + some processes are missing or if you cannot connect to the &sap; system, + look at the corresponding logfiles which can be found + at /usr/sap/SID/DVEBMGSnr/work/. + The files to look at are dev_ms and + dev_disp. + + Signal 31 happens here if the amount of shared memory used by + &oracle; and &sap; exceed the one defined within the kernel configuration + file and could be resolved by using a larger value: + + # larger value for 46C production systems: +options SHMMAXPGS=393216 +# smaller value sufficient for 46B: +#options SHMMAXPGS=262144 + + + + + Start of <command>saposcol</command> Failed + There are some problems with the program saposcol (version 4.6D). + The &sap; system is using saposcol to collect data about the + system performance. This program is not needed to use the &sap; system, + so this problem can be considered a minor one. The older versions + (4.6B) does work, but does not collect all the data (many calls will + just return 0, for example for CPU usage). + + + + + + Advanced Topics + + If you are curious as to how the Linux binary compatibility + works, this is the section you want to read. Most of what follows + is based heavily on an email written to &a.chat; by Terry Lambert + tlambert@primenet.com (Message ID: + <199906020108.SAA07001@usr09.primenet.com>). + + + How Does It Work? + execution class loader + + FreeBSD has an abstraction called an execution class + loader. This is a wedge into the &man.execve.2; system + call. + + What happens is that FreeBSD has a list of loaders, instead of + a single loader with a fallback to the #! + loader for running any shell interpreters or shell scripts. + + Historically, the only loader on the &unix; platform examined + the magic number (generally the first 4 or 8 bytes of the file) to + see if it was a binary known to the system, and if so, invoked the + binary loader. + + If it was not the binary type for the system, the + &man.execve.2; call returned a failure, and the shell attempted to + start executing it as shell commands. + + The assumption was a default of whatever the current + shell is. + + Later, a hack was made for &man.sh.1; to examine the first two + characters, and if they were :\n, then it + invoked the &man.csh.1; shell instead (we believe SCO first made + this hack). + + What FreeBSD does now is go through a list of loaders, with a + generic #! loader that knows about interpreters + as the characters which follow to the next whitespace next to + last, followed by a fallback to + /bin/sh. + ELF + + For the Linux ABI support, FreeBSD sees the magic number as an + ELF binary (it makes no distinction between FreeBSD, &solaris;, + Linux, or any other OS which has an ELF image type, at this + point). + Solaris + + The ELF loader looks for a specialized + brand, which is a comment section in the ELF + image, and which is not present on SVR4/&solaris; ELF + binaries. + + For Linux binaries to function, they must be + branded as type Linux + from &man.brandelf.1;: + + &prompt.root; brandelf -t Linux file + + When this is done, the ELF loader will see the + Linux brand on the file. + + ELF + branding + + + When the ELF loader sees the Linux brand, + the loader replaces a pointer in the proc + structure. All system calls are indexed through this pointer (in + a traditional &unix; system, this would be the + sysent[] structure array, containing the system + calls). In addition, the process is flagged for special handling of + the trap vector for the signal trampoline code, and several other + (minor) fix-ups that are handled by the Linux kernel + module. + + The Linux system call vector contains, among other things, a + list of sysent[] entries whose addresses reside + in the kernel module. + + When a system call is called by the Linux binary, the trap + code dereferences the system call function pointer off the + proc structure, and gets the Linux, not the + FreeBSD, system call entry points. + + In addition, the Linux mode dynamically + reroots lookups; this is, in effect, what the + option to file system mounts + (not the unionfs file system type!) does. First, an attempt + is made to lookup the file in the + /compat/linux/original-path + directory, then only if that fails, the + lookup is done in the + /original-path + directory. This makes sure that binaries that require other + binaries can run (e.g., the Linux toolchain can all run under + Linux ABI support). It also means that the Linux binaries can + load and execute FreeBSD binaries, if there are no corresponding + Linux binaries present, and that you could place a &man.uname.1; + command in the /compat/linux directory tree + to ensure that the Linux binaries could not tell they were not + running on Linux. + + In effect, there is a Linux kernel in the FreeBSD kernel; the + various underlying functions that implement all of the services + provided by the kernel are identical to both the FreeBSD system + call table entries, and the Linux system call table entries: file + system operations, virtual memory operations, signal delivery, + System V IPC, etc… The only difference is that FreeBSD + binaries get the FreeBSD glue functions, and + Linux binaries get the Linux glue functions + (most older OS's only had their own glue + functions: addresses of functions in a static global + sysent[] structure array, instead of addresses + of functions dereferenced off a dynamically initialized pointer in + the proc structure of the process making the + call). + + Which one is the native FreeBSD ABI? It does not matter. + Basically the only difference is that (currently; this could + easily be changed in a future release, and probably will be after + this) the FreeBSD glue functions are + statically linked into the kernel, and the Linux glue functions + can be statically linked, or they can be accessed via a kernel + module. + + Yeah, but is this really emulation? No. It is an ABI + implementation, not an emulation. There is no emulator (or + simulator, to cut off the next question) involved. + + So why is it sometimes called Linux emulation? + To make it hard to sell FreeBSD! Really, it + is because the historical implementation was done at a time when + there was really no word other than that to describe what was + going on; saying that FreeBSD ran Linux binaries was not true, if + you did not compile the code in or load a module, and there needed + to be a word to describe what was being loaded—hence + the Linux emulator. + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/mac/Makefile b/pl_PL.ISO8859-2/books/handbook/mac/Makefile new file mode 100644 index 0000000000..74aca4172f --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/mac/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= mac/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/mac/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/mac/chapter.sgml new file mode 100644 index 0000000000..1a8bd9f165 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/mac/chapter.sgml @@ -0,0 +1,2182 @@ + + + + + + + Tom + Rhodes + Written by + + + + + Mandatory Access Control + + + Synopsis + + MAC + + Mandatory Access Control + MAC + + + &os; 5.X introduced new security extensions from the + TrustedBSD project based on the &posix;.1e draft. Two of the most + significant new security mechanisms are file system Access Control + Lists (ACLs) and Mandatory Access Control + (MAC) facilities. Mandatory Access Control allows + new access control modules to be loaded, implementing new security + policies. Some provide protections of a narrow subset of the + system, hardening a particular service. Others provide + comprehensive labeled security across all subjects and objects. + The mandatory part + of the definition comes from the fact that the enforcement of + the controls is done by administrators and the system, and is + not left up to the discretion of users as is done with + discretionary access control (DAC, the standard + file and System V IPC permissions on &os;). + + This chapter will focus on the + Mandatory Access Control Framework (MAC Framework), and a set + of pluggable security policy modules enabling various security + mechanisms. + + After reading this chapter, you will know: + + + + What MAC security policy modules are currently + included in &os; and their associated mechanisms. + + + + What MAC security policy modules implement as + well as the difference between a labeled and non-labeled + policy. + + + + How to efficiently configure a system to use + the MAC framework. + + + + How to configure the different security policy modules included with the + MAC framework. + + + + How to implement a more secure environment using the + MAC framework and the examples + shown. + + + + How to test the MAC configuration + to ensure the framework has been properly implemented. + + + + Before reading this chapter, you should: + + + + Understand &unix; and &os; basics + (). + + + + Be familiar with + the basics of kernel configuration/compilation + (). + + + + Have some familiarity with security and how it + pertains to &os; (). + + + + + The improper use of the + information contained herein may cause loss of system access, + aggravation of users, or inability to access the features + provided by X11. More importantly, MAC should not + be relied upon to completely secure a system. The + MAC framework only augments + existing security policy; without sound security practices and + regular security checks, the system will never be completely + secure. + + It should also be noted that the examples contained + within this chapter are just that, examples. It is not + recommended that these particular settings be rolled out + on a production system. Implementing the various security policy modules takes + a good deal of thought and testing. One who does not fully understand + exactly how everything works may find him or herself going + back through the entire system and reconfiguring many files + or directories. + + + + What Will Not Be Covered + + This chapter covers a broad range of security issues relating + to the MAC framework. The + development of new MAC security policy modules + will not be covered. A number of security policy modules included with the + MAC framework have specific characteristics + which are provided for both testing and new module + development. These include the &man.mac.test.4;, + &man.mac.stub.4; and &man.mac.none.4;. + For more information on these security policy modules and the various + mechanisms they provide, please review the manual pages. + + + + + Key Terms in this Chapter + + Before reading this chapter, a few key terms must be + explained. This will hopefully clear up any confusion that + may occur and avoid the abrupt introduction of new terms + and information. + + + + compartment: A compartment is a + set of programs and data to be partitioned or separated, + where users are given explicit access to specific components + of a system. Also, a compartment represents a grouping, + such as a work group, department, project, or topic. Using + compartments, it is possible to implement a need-to-know + security policy. + + + + high water mark: A high water mark + policy is one which permits the raising of security levels + for the purpose of accessing higher level information. In + most cases, the original level is restored after the process + is complete. Currently, the &os; MAC + framework does not have a policy for this, but the definition + is included for completeness. + + + + integrity: Integrity, as a key + concept, is the level of trust which can be placed on data. + As the integrity of the data is elevated, so does the ability + to trust that data. + + + + label: A label is a security + attribute which can be applied to files, directories, or + other items in the system. It could be considered + a confidentiality stamp; when a label is placed on + a file it describes the security properties for that specific + file and will only permit access by files, users, resources, + etc. with a similar security setting. The meaning and + interpretation of label values depends on the policy configuration: while + some policies might treat a label as representing the + integrity or secrecy of an object, other policies might use + labels to hold rules for access. + + + + level: The increased or decreased + setting of a security attribute. As the level increases, + its security is considered to elevate as well. + + + + low water mark: A low water mark + policy is one which permits lowering of the security levels + for the purpose of accessing information which is less + secure. In most cases, the original security level of the + user is restored after the process is complete. The only + security policy module in &os; to use this is + &man.mac.lomac.4;. + + + + multilabel: The + property is a file system option + which can be set in single user mode using the + &man.tunefs.8; utility, during the boot operation + using the &man.fstab.5; file, or during the creation of + a new file system. This option will permit an administrator + to apply different MAC labels on different + objects. This option + only applies to security policy modules which support labeling. + + + + object: An object or system + object is an entity through which information flows + under the direction of a subject. + This includes directories, files, fields, screens, keyboards, + memory, magnetic storage, printers or any other data + storage/moving device. Basically, an object is a data container or + a system resource; access to an object + effectively means access to the data. + + + + policy: A collection of rules + which defines how objectives are to be achieved. A + policy usually documents how certain + items are to be handled. This chapter will + consider the term policy in this + context as a security policy; i.e. + a collection of rules which will control the flow of data + and information and define whom will have access to that + data and information. + + + + sensitivity: Usually used when + discussing MLS. A sensitivity level is + a term used to describe how important or secret the data + should be. As the sensitivity level increases, so does the + importance of the secrecy, or confidentiality of the data. + + + + single label: A single label is + when the entire file system uses one label to + enforce access control over the flow of data. When a file + system has this set, which is any time when the + option is not set, all + files will conform to the same label setting. + + + + subject: a subject is any + active entity that causes information to flow between + objects; e.g. a user, user processor, + system process, etc. On &os;, this is almost always a thread + acting in a process on behalf of a user. + + + + + + Explanation of MAC + + With all of these new terms in mind, consider how the + MAC framework augments the security of + the system as a whole. The various security policy modules provided by + the MAC framework could be used to + protect the network and file systems, block users from + accessing certain ports and sockets, and more. Perhaps + the best use of the policy modules is to blend them together, by loading + several security policy modules at a time for a multi-layered + security environment. In a multi-layered security environment, + multiple policy modules are in effect to keep security in check. This + is different to a hardening policy, which typically hardens + elements of a system that is used only for specific purposes. + The only downside is administrative overhead in cases of + multiple file system labels, setting network access control + user by user, etc. + + These downsides are minimal when compared to the lasting + effect of the framework; for instance, the ability to pick and choose + which policies are required for a specific configuration keeps + performance overhead down. The reduction of support for unneeded + policies can increase the overall performance of the system as well as + offer flexibility of choice. A good implementation would + consider the overall security requirements and effectively implement + the various security policy modules offered by the framework. + + Thus a system utilizing MAC features + should at least guarantee that a user will not be permitted + to change security attributes at will; all user utilities, + programs and scripts must work within the constraints of + the access rules provided by the selected security policy modules; and + that total control of the MAC access + rules are in the hands of the system administrator. + + It is the sole duty of the system administrator to + carefully select the correct security policy modules. Some environments + may need to limit access control over the network; in these + cases, the &man.mac.portacl.4;, &man.mac.ifoff.4; and even + &man.mac.biba.4; policy modules might make good starting points. In other + cases, strict confidentiality of file system objects might + be required. Policy modules such as &man.mac.bsdextended.4; + and &man.mac.mls.4; exist for this purpose. + + Policy decisions could be made based on network + configuration. Perhaps only certain users should be permitted + access to facilities provided by &man.ssh.1; to access the + network or the Internet. The &man.mac.portacl.4; would be + the policy module of choice for these situations. But what should be + done in the case of file systems? Should all access to certain + directories be severed from other groups or specific + users? Or should we limit user or utility access to specific + files by setting certain objects as classified? + + In the file system case, access to objects might be + considered confidential to some users, but not to others. + For an example, a large development team might be broken + off into smaller groups of individuals. Developers in + project A might not be permitted to access objects written + by developers in project B. Yet they might need to access + objects created by developers in project C; that is quite a + situation indeed. Using the different security policy modules provided by + the MAC framework; users could + be divided into these groups and then given access to the + appropriate areas without fear of information + leakage. + + Thus, each security policy module has a unique way of dealing with + the overall security of a system. Module selection should be based + on a well thought out security policy. In many cases, the + overall policy may need to be revised and reimplemented on + the system. Understanding the different security policy modules offered by + the MAC framework will help administrators + choose the best policies for their situations. + + The default &os; kernel does not include the option for + the MAC framework; thus the following + kernel option must be added before trying any of the examples or + information in this chapter: + + options MAC + + And the kernel will require a rebuild and a reinstall. + + + While the various manual pages for MAC + policy modules state that they may be built into the kernel, + it is possible to lock the system out of + the network and more. Implementing MAC + is much like implementing a firewall, care must be taken + to prevent being completely locked out of the system. The + ability to revert back to a previous configuration should be + considered while the implementation of MAC + remotely should be done with extreme caution. + + + + + Understanding MAC Labels + + A MAC label is a security attribute + which may be applied to subjects and objects throughout + the system. + + When setting a label, the user must be able to comprehend + what it is, exactly, that is being done. The attributes + available on an object depend on the policy module loaded, and that + policy modules interpret their attributes in different + ways. If improperly configured due to lack of comprehension, or + the inability to understand the implications, the result will + be the unexpected and perhaps, undesired, behavior of the + system. + + The security label on an object is used as a part of a + security access control decision by a policy. With some + policies, the label by itself contains all information necessary + to make a decision; in other models, the labels may be processed + as part of a larger rule set, etc. + + For instance, setting the label of biba/low + on a file will represent a label maintained by the Biba security policy module, + with a value of low. + + A few policy modules which support the labeling feature in + &os; offer three specific predefined labels. These + are the low, high, and equal labels. Although they enforce + access control in a different manner with each policy module, you + can be sure that the low label will be the lowest setting, + the equal label will set the subject or object to be disabled + or unaffected, and the high label will enforce the highest + setting available in the Biba and MLS + policy modules. + + Within single label file system environments, only one label may be + used on objects. This will enforce one set of + access permissions across the entire system and in many + environments may be all that is required. There are a few + cases where multiple labels may be set on objects + or subjects in the file system. For those cases, the + option may be passed to + &man.tunefs.8;. + + In the case of Biba and MLS, a numeric + label may be set to indicate the precise level of hierarchical + control. This numeric level is used to partition or sort + information into different groups of say, classification only + permitting access to that group or a higher group level. + + In most cases the administrator will only be setting up a + single label to use throughout the file system. + + Hey wait, this is similar to DAC! + I thought MAC gave control strictly to the + administrator. That statement still holds true, to some + extent as root is the one in control and who + configures the policies so that users are placed in the + appropriate categories/access levels. Alas, many policy modules can + restrict the root user as well. Basic + control over objects will then be released to the group, but + root may revoke or modify the settings + at any time. This is the hierarchal/clearance model covered + by policies such as Biba and MLS. + + + Label Configuration + + Virtually all aspects of label policy module configuration + will be performed using the base system utilities. These + commands provide a simple interface for object or subject + configuration or the manipulation and verification of + the configuration. + + All configuration may be done by use of the + &man.setfmac.8; and &man.setpmac.8; utilities. + The setfmac command is used to set + MAC labels on system objects while the + setpmac command is used to set the labels + on system subjects. Observe: + + &prompt.root; setfmac biba/high test + + If no errors occurred with the command above, a prompt + will be returned. The only time these commands are not + quiescent is when an error occurred; similarly to the + &man.chmod.1; and &man.chown.8; commands. In some cases this + error may be a Permission denied and + is usually obtained when the label is being set or modified + on an object which is restricted.Other conditions + may produce different failures. For instance, the file may not + be owned by the user attempting to relabel the object, the + object may not exist or may be read only. A mandatory policy + will not allow the process to relabel the file, maybe because + of a property of the file, a property of the process, or a + property of the proposed new label value. For example: a user + running at low integrity tries to change the label of a high + integrity file. Or perhaps a user running at low integrity + tries to change the label of a low integrity file to a high + integrity label. The system administrator + may use the following commands to overcome this: + + &prompt.root; setfmac biba/high test +Permission denied +&prompt.root; setpmac biba/low setfmac biba/high test +&prompt.root; getfmac test +test: biba/high + + As we see above, setpmac + can be used to override the policy module's settings by assigning + a different label to the invoked process. The + getpmac utility is usually used with currently + running processes, such as sendmail: + although it takes a process ID in place of + a command the logic is extremely similar. If users + attempt to manipulate a file not in their access, subject to the + rules of the loaded policy modules, the + Operation not permitted error + will be displayed by the mac_set_link + function. + + + Common Label Types + + For the &man.mac.biba.4;, &man.mac.mls.4; and + &man.mac.lomac.4; policy modules, the ability to assign + simple labels is provided. These take the form of high, + equal and low, what follows is a brief description of + what these labels provide: + + + + The low label is considered the + lowest label setting an object or subject may have. + Setting this on objects or subjects will block their + access to objects or subjects marked high. + + + + The equal label should only be + placed on objects considered to be exempt from the + policy. + + + + The high label grants an object or + subject the highest possible setting. + + + + With respect to each policy module, each of those settings + will instate a different information flow directive. Reading + the proper manual pages will further explain the traits of + these generic label configurations. + + + Advanced Label Configuration + + Numeric grade labels are used for + comparison:compartment+compartment; thus + the following: + + biba/10:2+3+6(5:2+3-20:2+3+4+5+6) + + May be interpreted as: + + Biba Policy Label/Grade 10 + :Compartments 2, 3 and 6: + (grade 5 ...) + + In this example, the first grade would be considered + the effective grade with + effective compartments, the second grade + is the low grade and the last one is the high grade. + In most configurations these settings will not be used; + indeed, they offered for more advanced + configurations. + + When applied to system objects, they will only have a + current grade/compartments as opposed to system subjects + as they reflect the range of available rights in the system, + and network interfaces, where they are used for access + control. + + The grade and compartments in a subject and object pair + are used to construct a relationship referred to as + dominance, in which a subject dominates an + object, the object dominates the subject, neither dominates + the other, or both dominate each other. The + both dominate case occurs when the two labels + are equal. Due to the information flow nature of Biba, you + have rights to a set of compartments, + need to know, that might correspond to + projects, but objects also have a set of compartments. + Users may have to subset their rights using + su or setpmac in order + to access objects in a compartment from which they are not + restricted. + + + + + Users and Label Settings + + Users themselves are required to have labels so that + their files and processes may properly interact with the + security policy defined on the system. This is + configured through the login.conf file + by use of login classes. Every policy module that uses labels + will implement the user class setting. + + An example entry containing every policy module setting is displayed + below: + + default:\ + :copyright=/etc/COPYRIGHT:\ + :welcome=/etc/motd:\ + :setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ + :path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:\ + :manpath=/usr/share/man /usr/local/man:\ + :nologin=/usr/sbin/nologin:\ + :cputime=1h30m:\ + :datasize=8M:\ + :vmemoryuse=100M:\ + :stacksize=2M:\ + :memorylocked=4M:\ + :memoryuse=8M:\ + :filesize=8M:\ + :coredumpsize=8M:\ + :openfiles=24:\ + :maxproc=32:\ + :priority=0:\ + :requirehome:\ + :passwordtime=91d:\ + :umask=022:\ + :ignoretime@:\ + :label=partition/13,mls/5,biba/10(5-15),lomac/10[2]: + + The label option is used to set the + user class default label which will be enforced by + MAC. Users will never be permitted to + modify this value, thus it can be considered not optional + in the user case. In a real configuration, however, the + administrator will never wish to enable every policy module. + It is recommended that the rest of this chapter be reviewed + before any of this configuration is implemented. + + + Users may change their label after the initial login; + however, this change is subject constraints of the policy. + The example above tells the Biba policy that a process's + minimum integrity is 5, its maximum is 15, but the default + effective label is 10. The process will run at 10 until + it chooses to change label, perhaps due to the user using + the setpmac command, which will be constrained by Biba to + the range set at login. + + + In all cases, after a change to + login.conf, the login class capability + database must be rebuilt using cap_mkdb + and this will be reflected throughout every forthcoming + example or discussion. + + It is useful to note that many sites may have a + particularly large number of users requiring several + different user classes. In depth planning is required + as this may get extremely difficult to manage. + + Future versions of &os; will include a new way to + deal with mapping users to labels; however, this will + not be available until some time after &os; 5.3. + + + + Network Interfaces and Label Settings + + Labels may also be set on network interfaces to help + control the flow of data across the network. In all cases + they function in the same way the policies function with + respect to objects. Users at high settings in + biba, for example, will not be permitted + to access network interfaces with a label of low. + + The may be passed to + ifconfig when setting the + MAC label on network interfaces. For + example: + + &prompt.root; ifconfig bge0 maclabel biba/equal + + will set the MAC label of + biba/equal on the &man.bge.4; interface. + When using a setting similar to + biba/high(low-high) the entire label should + be quoted; otherwise an error will be returned. + + Each policy module which supports labeling has a tunable + which may be used to disable the MAC + label on network interfaces. Setting the label to + will have a similar effect. Review + the output from sysctl, the policy manual + pages, or even the information found later in this chapter + for those tunables. + + + + + Singlelabel or Multilabel? + + By default the system will use the + option. But what does this + mean to the administrator? There are several differences + which, in their own right, offer pros and cons to the + flexibility in the systems security model. + + The only permits for one + label, for instance biba/high to be used + for each subject or object. It provides for lower + administration overhead but decreases the flexibility of + policies which support labeling. Many administrators may + want to use the option in + their security policy. + + The option will permit each + subject or object to have its own independent + MAC label in + place of the standard option + which will allow only one label throughout the partition. + The and + label options are only required for the policies which + implement the labeling feature, including the Biba, Lomac, + MLS and SEBSD + policies. + + In many cases, the may not need + to be set at all. Consider the following situation and + security model: + + + + &os; web-server using the MAC + framework and a mix of the various policies. + + + + This machine only requires one label, + biba/high, for everything in the system. + Here the file system would not require the + option as a single label + will always be in effect. + + + + But, this machine will be a web server and should have + the web server run at biba/low to prevent + write up capabilities. The Biba policy and how it works + will be discussed later, so if the previous comment was + difficult to interpret just continue reading and return. + The server could use a separate partition set at + biba/low for most if not all of its + runtime state. Much is lacking from this example, for + instance the restrictions on data, configuration and user + settings; however, this is just a quick example to prove the + aforementioned point. + + + + If any of the non-labeling policies are to be used, + then the option would never + be required. These include the seeotheruids, + portacl and partition + policies. + + It should also be noted that using + with a partition and establishing + a security model based on + functionality could open the doors for higher administrative + overhead as everything in the file system would have a label. + This includes directories, files, and even device + nodes. + + The following command will set + on the file systems to have multiple labels. This may only be + done in single user mode: + + &prompt.root; tunefs -l enable / + + This is not a requirement for the swap file + system. + + + Some users have experienced problems with setting the + flag on the root partition. + If this is the case, please review the + of this chapter. + + + + + Controlling MAC with Tunables + + Without any modules loaded, there are still some parts + of MAC which may be configured using + the sysctl interface. These tunables + are described below and in all cases the number one (1) + means enabled while the number zero (0) means + disabled: + + + + security.mac.enforce_fs defaults to + one (1) and enforces MAC file system + policies on the file systems. + + + + security.mac.enforce_kld defaults to + one (1) and enforces MAC kernel linking + policies on the dynamic kernel linker (see + &man.kld.4;). + + + + security.mac.enforce_network defaults + to one (1) and enforces MAC network + policies. + + + + security.mac.enforce_pipe defaults + to one (1) and enforces MAC policies + on pipes. + + + + security.mac.enforce_process defaults + to one (1) and enforces MAC policies + on processes which utilize inter-process + communication. + + + + security.mac.enforce_socket defaults + to one (1) and enforces MAC policies + on sockets (see the &man.socket.2; manual page). + + + + security.mac.enforce_system defaults + to one (1) and enforces MAC policies + on system activities such as accounting and + rebooting. + + + + security.mac.enforce_vm defaults + to one (1) and enforces MAC policies + on the virtual memory system. + + + + + Every policy or MAC option supports + tunables. These usually hang off of the + security.mac.<policyname> tree. + To view all of the tunables from MAC + use the following command: + + &prompt.root; sysctl -da | grep mac + + + This should be interpreted as all of the basic + MAC policies are enforced by default. + If the modules were built into the kernel the system + would be extremely locked down and most likely unable to + communicate with the local network or connect to the Internet, + etc. This is why building the modules into the kernel is not + completely recommended. Not because it limits the ability to + disable features on the fly with sysctl, + but it permits the administrator to instantly switch the + policies of a system without the requirement of rebuilding + and reinstalling a new system. + + + + + Planning the Security Configuration + + Whenever a new technology is implemented, a planning phase is + always a good idea. During the planning stages, an administrator + should in general look at the big picture, trying + to keep in view at least the following: + + + + The implementation requirements; + + + + The implementation goals; + + + + For MAC installations, these include: + + + + How to classify information and resources available on + the target systems. + + + + What sorts of information or resources to restrict + access to along with the type of restrictions that should be + applied. + + + + Which MAC module or modules will be + required to achieve this goal. + + + + It is always possible to reconfigure and change the + system resources and security settings, it is quite often very inconvenient to + search through the system and fix existing files and user + accounts. Planning helps to ensure a trouble-free and efficient + trusted system implementation. A trial run of the trusted system, + including the configuration, is often vital and definitely + beneficial before a MAC + implementation is used on production systems. The idea of just + letting loose on a system + with MAC is like setting up for failure. + + Different environments may have explicit needs and + requirements. Establishing an in depth and complete security + profile will decrease the need of changes once the system + goes live. As such, the future sections will cover the + different modules available to administrators; describe their + use and configuration; and in some cases provide insight on + what situations they would be most suitable for. For instance, + a web server might roll out the &man.mac.biba.4; and + &man.mac.bsdextended.4; policies. In other cases, a machine + with very few local users, the &man.mac.partition.4; might + be a good choice. + + + + Module Configuration + + Every module included with the MAC + framework may be either compiled into the kernel as noted above + or loaded as a run-time kernel module. + The recommended method is to add the module name to the + /boot/loader.conf file so that it will load + during the initial boot operation. + + The following sections will discuss the various + MAC modules and cover their features. + Implementing them into a specific environment will also + be a consideration of this chapter. Some modules support + the use of labeling, which is controlling access by enforcing + a label such as this is allowed and this is not. + A label configuration file may control how files may be accessed, + network communication can be exchanged, and more. The previous + section showed how the flag could + be set on file systems to enable per-file or per-partition + access control. + + A single label configuration would enforce only one label + across the system, that is why the tunefs + option is called . + + + The MAC seeotheruids Module + + + MAC See Other UIDs Policy + + Module name: mac_seeotheruids.ko + + Kernel configuration line: + options MAC_SEEOTHERUIDS + + Boot option: + mac_seeotheruids_load="YES" + + The &man.mac.seeotheruids.4; module mimics and extends + the security.bsd.see_other_uids and + security.bsd.see_other_gids + sysctl tunables. This option does + not require any labels to be set before configuration and + can operate transparently with the other modules. + + After loading the module, the following + sysctl tunables may be used to control + the features: + + + + security.mac.seeotheruids.enabled + will enable the module's features and use the default + settings. These default settings will deny users the + ability to view processes and sockets owned by other + users. + + + + + security.mac.seeotheruids.specificgid_enabled + will allow a certain group to be exempt from this policy. + To exempt specific groups from this policy, use the + security.mac.seeotheruids.specificgid=XXX + sysctl tunable. In the above example, + the XXX should be replaced with the + numeric group ID to be exempted. + + + + + security.mac.seeotheruids.primarygroup_enabled + is used to exempt specific primary groups from this policy. + When using this tunable, the + security.mac.seeotheruids.specificgid_enabled + may not be set. + + + + + + + The MAC bsdextended Module + + + MAC + File System Firewall Policy + + Module name: mac_bsdextended.ko + + Kernel configuration line: + options MAC_BSDEXTENDED + + Boot option: + mac_bsdextended_load="YES" + + The &man.mac.bsdextended.4; module enforces the file system + firewall. This module's policy provides an extension to the + standard file system permissions model, permitting an + administrator to create a firewall-like ruleset to protect files, + utilities, and directories in the file system hierarchy. When + access to a file system object is attempted, the list of rules + is iterated until either a matching rule is located or the end + is reached. This behavior may be changed by the use of a + &man.sysctl.8; parameter, + security.mac.bsdextended.firstmatch_enabled. Similar to + other firewall modules in &os;, a file containing access control + rules can be created and read by the system at boot time using + an &man.rc.conf.5; variable. + + The rule list may be entered using a utility, &man.ugidfw.8;, + that has a syntax similar to that of &man.ipfw.8;. More tools + can be written by using the functions in the + &man.libugidfw.3; library. + + Extreme caution should be taken when working with this + module; incorrect use could block access to certain parts of + the file system. + + + Examples + + After the &man.mac.bsdextended.4; module has + been loaded, the following command may be used to list the + current rule configuration: + + &prompt.root; ugidfw list +0 slots, 0 rules + + As expected, there are no rules defined. This means that + everything is still completely accessible. To create a rule + which will block all access by users but leave + root unaffected, simply run the + following command: + + &prompt.root; ugidfw add subject not uid root new object not uid root mode n + + + In releases prior to &os; 5.3, the + add parameter did not exist. In those + cases the set should be used + instead. See below for a command example. + + This is a very bad idea as it will block all users from + issuing even the most simple commands, such as + ls. A more patriotic list of rules + might be: + + &prompt.root; ugidfw set 2 subject uid user1 object uid user2 mode n +&prompt.root; ugidfw set 3 subject uid user1 object gid user2 mode n + + This will block any and all access, including directory + listings, to user2's home + directory from the username user1. + + In place of user1, the + could + be passed. This will enforce the same access restrictions + above for all users in place of just one user. + + + The root user will be unaffected + by these changes. + + + This should provide a general idea of how the + &man.mac.bsdextended.4; module may be used to help fortify + a file system. For more information, see the + &man.mac.bsdextended.4; and the &man.ugidfw.8; manual + pages. + + + + + The MAC ifoff Module + + + MAC Interface Silencing Policy + + Module name: mac_ifoff.ko + + Kernel configuration line: + options MAC_IFOFF + + Boot option: mac_ifoff_load="YES" + + The &man.mac.ifoff.4; module exists solely to disable network + interfaces on the fly and keep network interfaces from being + brought up during the initial system boot. It does not require + any labels to be set up on the system, nor does it have a + dependency on other MAC modules. + + Most of the control is done through the + sysctl tunables listed below. + + + + security.mac.ifoff.lo_enabled will + enable/disable all traffic on the loopback (&man.lo.4;) + interface. + + + + security.mac.ifoff.bpfrecv_enabled will + enable/disable all traffic on the Berkeley Packet Filter + interface (&man.bpf.4;) + + + + security.mac.ifoff.other_enabled will + enable/disable traffic on all other interfaces. + + + + One of the most common uses of &man.mac.ifoff.4; is network + monitoring in an environment where network traffic should not + be permitted during the boot sequence. Another suggested use + would be to write a script which uses + security/aide to automatically + block network traffic if it finds new or altered files in + protected directories. + + + + The MAC portacl Module + + + MAC Port Access Control List Policy + + Module name: mac_portacl.ko + + Kernel configuration line: + MAC_PORTACL + + Boot option: mac_portacl_load="YES" + + The &man.mac.portacl.4; module is used to limit binding to + local TCP and UDP ports + using a variety of sysctl variables. In + essence &man.mac.portacl.4; makes it possible to allow + non-root users to bind to specified + privileged ports, i.e. ports fewer than 1024. + + Once loaded, this module will enable the + MAC policy on all sockets. The following + tunables are available: + + + + security.mac.portacl.enabled will + enable/disable the policy completely.Due to + a bug the security.mac.portacl.enabled + sysctl variable will not work on + &os; 5.2.1 or previous releases. + + + + security.mac.portacl.port_high will set + the highest port number that &man.mac.portacl.4; + will enable protection for. + + + + security.mac.portacl.suser_exempt will, + when set to a non-zero value, exempt the + root user from this policy. + + + + security.mac.portacl.rules will + specify the actual mac_portacl policy; see below. + + + + The actual mac_portacl policy, as + specified in the security.mac.portacl.rules + sysctl, is a text string of the form: + rule[,rule,...] with as many rules as + needed. Each rule is of the form: + idtype:id:protocol:port. The + idtype parameter can be + uid or gid and used to + interpret the id parameter as either a + user id or group id, respectively. The + protocol parameter is used to determine if + the rule should apply to TCP or + UDP by setting the parameter to + tcp or udp. The final + port parameter is the port number to allow + the specified user or group to bind to. + + + Since the ruleset is interpreted directly by the kernel + only numeric values can be used for the user ID, group ID, and + port parameters. I.e. user, group, and port service names + cannot be used. + + + By default, on &unix;-like systems, ports fewer than 1024 + can only be used by/bound to privileged processes, + i.e. those run as root. For + &man.mac.portacl.4; to allow non-privileged processes to bind + to ports below 1024 this standard &unix; restriction has to be + disabled. This can be accomplished by setting the &man.sysctl.8; + variables net.inet.ip.portrange.reservedlow and + net.inet.ip.portrange.reservedhigh + to zero. + + See the examples below or review the &man.mac.portacl.4; + manual page for further information. + + + Examples + + The following examples should illuminate the above + discussion a little better: + + &prompt.root; sysctl security.mac.portacl.port_high=1023 +&prompt.root; sysctl net.inet.ip.portrange.reservedlow=0 net.inet.ip.portrange.reservedhigh=0 + + First we set &man.mac.portacl.4; to cover the standard + privileged ports and disable the normal &unix; bind + restrictions. + + &prompt.root; sysctl security.mac.portacl.suser_exempt=1 + + The root user should not be crippled + by this policy, thus set the + security.mac.portacl.suser_exempt to a + non-zero value. The &man.mac.portacl.4; module + has now been set up to behave the same way &unix;-like systems + behave by default. + + &prompt.root; sysctl security.mac.portacl.rules=uid:80:tcp:80 + + Allow the user with UID 80 (normally + the www user) to bind to port 80. + This can be used to allow the www + user to run a web server without ever having + root privilege. + + &prompt.root; sysctl security.mac.portacl.rules=uid:1001:tcp:110,uid:1001:tcp:995 + + Permit the user with the UID of + 1001 to bind to the TCP ports 110 + (pop3) and 995 (pop3s). + This will permit this user to start a server that accepts + connections on ports 110 and 995. + + + + + The MAC partition Module + + + MAC Process Partition Policy + + Module name: mac_partition.ko + + Kernel configuration line: + options MAC_PARTITION + + Boot option: + mac_partition_load="YES" + + The &man.mac.partition.4; policy will drop processes into + specific partitions based on their + MAC label. Think of it as a special + type of &man.jail.8;, though that is hardly a worthy + comparison. + + This is one module that should be added to the + &man.loader.conf.5; file so that it loads + and enables the policy during the boot process. + + Most configuration for this policy is done using + the &man.setpmac.8; utility which will be explained below. + The following sysctl tunable is + available for this policy: + + + + security.mac.partition.enabled will + enable the enforcement of MAC process + partitions. + + + + When this policy is enabled, users will only be permitted + to see their processes, and any others within their partition, + but will not be permitted to work with + utilities outside the scope of this partition. For instance, a user in the + insecure class above will not be permitted + to access the top command as well as many + other commands that must spawn a process. + + To set or drop utilities into a partition label, use the + setpmac utility: + + &prompt.root; setpmac partition/13 top + + This will add the top command to the + label set on users in the insecure class. + Note that all processes spawned by users + in the insecure class will stay in the + partition/13 label. + + + Examples + + The following command will show you the partition label + and the process list: + + &prompt.root; ps Zax + + This next command will allow the viewing of another + user's process partition label and that user's currently + running processes: + + &prompt.root; ps -ZU trhodes + + + Users can see processes in root's + label unless the &man.mac.seeotheruids.4; policy is + loaded. + + + A really crafty implementation could have all of the + services disabled in /etc/rc.conf and + started by a script that starts them with the proper + labeling set. + + + The following policies support integer settings + in place of the three default labels offered. These options, + including their limitations, are further explained in + the module manual pages. + + + + + + The MAC Multi-Level Security Module + + + MAC Multi-Level Security Policy + + Module name: mac_mls.ko + + Kernel configuration line: + options MAC_MLS + + Boot option: mac_mls_load="YES" + + The &man.mac.mls.4; policy controls access between subjects + and objects in the system by enforcing a strict information + flow policy. + + In MLS environments, a + clearance level is set in each subject or objects + label, along with compartments. Since these clearance or + sensibility levels can reach numbers greater than six thousand; + it would be a daunting task for any system administrator to + thoroughly configure each subject or object. Thankfully, three + instant labels are already included in this + policy. + + These labels are mls/low, + mls/equal and mls/high. + Since these labels are described in depth in the manual page, + they will only get a brief description here: + + + + The mls/low label contains a low + configuration which permits it to be dominated by all other + objects. Anything labeled with mls/low + will have a low clearance level and not be permitted to access + information of a higher level. In addition, this label will + prevent objects of a higher clearance level from writing or + passing information on to them. + + + + The mls/equal label should be + placed on objects considered to be exempt from the + policy. + + + + The mls/high label is the highest level + of clearance possible. Objects assigned this label will + hold dominance over all other objects in the system; however, + they will not permit the leaking of information to objects + of a lower class. + + + + MLS provides for: + + + + A hierarchical security level with a set of non + hierarchical categories; + + + + Fixed rules: no read up, no write down (a subject can + have read access to objects on its own level or below, but + not above. Similarly, a subject can have write access to + objects on its own level or above but not beneath.); + + + + Secrecy (preventing inappropriate disclosure + of data); + + + + Basis for the design of systems that concurrently handle + data at multiple sensitivity levels (without leaking + information between secret and confidential). + + + + The following sysctl tunables are + available for the configuration of special services and + interfaces: + + + + security.mac.mls.enabled is used to + enable/disable the MLS policy. + + + + security.mac.mls.ptys_equal will label + all &man.pty.4; devices as mls/equal during + creation. + + + + security.mac.mls.revocation_enabled is + used to revoke access to objects after their label changes + to a label of a lower grade. + + + + security.mac.mls.max_compartments is + used to set the maximum number of compartment levels with + objects; basically the maximum compartment number allowed + on a system. + + + + To manipulate the MLS labels, the + &man.setfmac.8; command has been provided. To assign a label + to an object, issue the following command: + + &prompt.root; setfmac mls/5 test + + To get the MLS label for the file + test issue the following command: + + &prompt.root; getfmac test + + This is a summary of the MLS + policy's features. Another approach is to create a master policy + file in /etc which + specifies the MLS policy information and to + feed that file into the setfmac command. This + method will be explained after all policies are covered. + + + Planning Mandatory Sensitivity + + With the Multi-Level Security Policy Module, an + administrator plans for controlling the flow of sensitive + information. By default, with its block read up block write + down nature, the system defaults everything to a low state. + Everything is accessible and an administrator + slowly changes this during the configuration stage; augmenting + the confidentiality of the information. + + Beyond the three basic label options above, an administrator + may group users and groups as required to block the information + flow between them. It might be easier to look at the + information in clearance levels familiarized with words, for + instance classifications such as + Confidential, Secret, + and Top Secret. Some administrators might + just create different groups based on project levels. + Regardless of classification method, a well thought out plan + must exist before implementing such a restrictive policy. + + Some example situations for this security policy module + could be an e-commerce web server, a file server holding critical + company information, and financial institution environments. + The most unlikely place would be a personal workstation with + only two or three users. + + + + The MAC Biba Module + + + MAC Biba Integrity Policy + + Module name: mac_biba.ko + + Kernel configuration line: options MAC_BIBA + + Boot option: mac_biba_load="YES" + + The &man.mac.biba.4; module loads the MAC + Biba policy. This policy works much like that of the + MLS policy with the exception that the rules + for information flow + are slightly reversed. This is said to prevent the downward + flow of sensitive information whereas the MLS + policy prevents the upward flow of sensitive information; thus, + much of this section can apply to both policies. + + In Biba environments, an integrity label is + set on each subject or object. These labels are made up of + hierarchal grades, and non-hierarchal components. As an object's + or subject's grade ascends, so does its integrity. + + Supported labels are biba/low, + biba/equal, and biba/high; + as explained below: + + + + The biba/low label is considered the + lowest integrity an object or subject may have. Setting + this on objects or subjects will block their write access + to objects or subjects marked high. They still have read + access though. + + + + The biba/equal label should only be + placed on objects considered to be exempt from the + policy. + + + + The biba/high label will permit + writing to objects set at a lower label, but not + permit reading that object. It is recommended that this + label be placed on objects that affect the integrity of + the entire system. + + + + Biba provides for: + + + + Hierarchical integrity level with a set of non + hierarchical integrity categories; + + + + Fixed rules: no write up, no read down (opposite of + MLS). A subject can have write access + to objects on its own level or below, but not above. Similarly, a + subject can have read access to objects on its own level + or above, but not below; + + + + Integrity (preventing inappropriate modification of + data); + + + + Integrity levels (instead of MLS sensitivity + levels). + + + + The following sysctl tunables can + be used to manipulate the Biba policy. + + + + security.mac.biba.enabled may be used + to enable/disable enforcement of the Biba policy on the + target machine. + + + + security.mac.biba.ptys_equal may be + used to disable the Biba policy on &man.pty.4; + devices. + + + + security.mac.biba.revocation_enabled + will force the revocation of access to objects if the label + is changed to dominate the subject. + + + + To access the Biba policy setting on system objects, use + the setfmac and getfmac + commands: + + &prompt.root; setfmac biba/low test +&prompt.root; getfmac test +test: biba/low + + + Planning Mandatory Integrity + + Integrity, different from sensitivity, guarantees that the + information will never be manipulated by untrusted parties. + This includes information passed between subjects, objects, + and both. It ensures that users will only be able to modify + and in some cases even access information they explicitly need + to. + + The &man.mac.biba.4; security policy module permits an + administrator to address which files and programs a user or + users may see and invoke while assuring that the programs and + files are free from threats and trusted by the system for that + user, or group of users. + + During the initial planning phase, an administrator must be + prepared to partition users into grades, levels, and areas. + Users will be blocked access not only to data but programs + and utilities both before and after they start. The system will + default to a high label once this policy module is enabled, and + it is up to the administrator to configure the different grades + and levels for users. Instead of using clearance levels as + described above, a good planning method could include topics. + For instance, only allow developers modification access to the source code + repository, source code compiler, and other development + utilities. While other users would be grouped into other + categories such as testers, designers, or just ordinary + users and would only be permitted read access. + + With its natural security control, a lower integrity subject + is unable to write to a higher integrity subject; a higher + integrity subject cannot observe or read a lower integrity + object. Setting a label at the lowest possible grade could make + it inaccessible to subjects. Some prospective environments for + this security policy module would include a constrained web + server, development and test machine, and source code + repository. A less useful implementation would be a personal + workstation, a machine used as a router, or a network + firewall. + + + + + The MAC LOMAC Module + + + MAC LOMAC + + Module name: mac_lomac.ko + + Kernel configuration line: options MAC_LOMAC + Boot option: mac_lomac_load="YES" + + Unlike the MAC Biba policy, the + &man.mac.lomac.4; policy permits access to lower integrity + objects only after decreasing the integrity level to not disrupt + any integrity rules. + + The MAC version of the Low-watermark + integrity policy, not to be confused with the older &man.lomac.4; + implementation, works almost identically to Biba, but with the + exception of using floating labels to support subject + demotion via an auxiliary grade compartment. This secondary + compartment takes the form of [auxgrade]. + When assigning a lomac policy with an auxiliary grade, it + should look a little bit like: lomac/10[2] + where the number two (2) is the auxiliary grade. + + The MAC LOMAC policy relies on the + ubiquitous labeling of all system objects with integrity labels, + permitting subjects to read from low integrity objects and then + downgrading the label on the subject to prevent future writes to + high integrity objects. This is the + [auxgrade] option discussed above, thus the + policy may provide for greater compatibility and require less + initial configuration than Biba. + + + Examples + + Like the Biba and MLS policies; + the setfmac and setpmac + utilities may be used to place labels on system objects: + + &prompt.root; setfmac /usr/home/trhodes lomac/high[low] +&prompt.root; getfmac /usr/home/trhodes lomac/high[low] + + Notice the auxiliary grade here is low, + this is a feature provided only by the MAC + LOMAC policy. + + + + + Nagios in a MAC Jail + + + Nagios in a MAC Jail + + + The following demonstration will implement a secure + environment using various MAC modules + with properly configured policies. This is only a test and + should not be considered the complete answer to everyone's + security woes. Just implementing a policy and ignoring it + never works and could be disastrous in a production + environment. + + Before beginning this process, the + multilabel option must be set on each file + system as stated at the beginning of this chapter. Not doing + so will result in errors. While at it, ensure that the + net-mngt/nagios-plugins, + net-mngt/nagios, and + www/apache13 ports are all + installed, configured, and working correctly. + + + Create an insecure User Class + + Begin the procedure by adding the following user class + to the /etc/login.conf file: + + insecure:\ +:copyright=/etc/COPYRIGHT:\ +:welcome=/etc/motd:\ +:setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ +:path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin +:manpath=/usr/share/man /usr/local/man:\ +:nologin=/usr/sbin/nologin:\ +:cputime=1h30m:\ +:datasize=8M:\ +:vmemoryuse=100M:\ +:stacksize=2M:\ +:memorylocked=4M:\ +:memoryuse=8M:\ +:filesize=8M:\ +:coredumpsize=8M:\ +:openfiles=24:\ +:maxproc=32:\ +:priority=0:\ +:requirehome:\ +:passwordtime=91d:\ +:umask=022:\ +:ignoretime@:\ +:label=biba/10(10-10): + + And adding the following line to the default user + class: + + :label=biba/high: + + Once this is completed, the following command must be + issued to rebuild the database: + + &prompt.root; cap_mkdb /etc/login.conf + + + + Boot Configuration + + Do not reboot yet, just add the following lines to + /boot/loader.conf so the required + modules will load during system initialization: + + mac_biba_load="YES" +mac_seeotheruids_load="YES" + + + + Configure Users + + Set the root user to the default + class using: + + &prompt.root; pw usermod root -L default + + All user accounts that are not root + or system users will now require a login class. The login + class is required otherwise users will be refused access + to common commands such as &man.vi.1;. + The following sh script should do the + trick: + + &prompt.root; for x in `awk -F: '($3 >= 1001) && ($3 != 65534) { print $1 }' \ + /etc/passwd`; do pw usermod $x -L default; done; + + Drop the nagios and + www users into the insecure class: + + &prompt.root; pw usermod nagios -L insecure + &prompt.root; pw usermod www -L insecure + + + + Create the Contexts File + + A contexts file should now be created; the following example + file should be placed in + /etc/policy.contexts. + + # This is the default BIBA policy for this system. + +# System: +/var/run biba/equal +/var/run/* biba/equal + +/dev biba/equal +/dev/* biba/equal + +/var biba/equal +/var/spool biba/equal +/var/spool/* biba/equal + +/var/log biba/equal +/var/log/* biba/equal + +/tmp biba/equal +/tmp/* biba/equal +/var/tmp biba/equal +/var/tmp/* biba/equal + +/var/spool/mqueue biba/equal +/var/spool/clientmqueue biba/equal + +# For Nagios: +/usr/local/etc/nagios +/usr/local/etc/nagios/* biba/10 + +/var/spool/nagios biba/10 +/var/spool/nagios/* biba/10 + +# For apache +/usr/local/etc/apache biba/10 +/usr/local/etc/apache/* biba/10 + + This policy will enforce security by setting restrictions + on the flow of information. In this specific configuration, + users, root and others, should never be + allowed to access Nagios. + Configuration files and processes that are a part of + Nagios will be completely self + contained or jailed. + + This file may now be read into our system by issuing the + following command: + + &prompt.root; setfsmac -ef /etc/policy.contexts / +&prompt.root; setfsmac -ef /etc/policy.contexts / + + + The above file system layout may be different depending + on environment; however, it must be run on every single file + system. + + + The /etc/mac.conf file requires + the following modifications in the main section: + + default_labels file ?biba +default_labels ifnet ?biba +default_labels process ?biba +default_labels socket ?biba + + + + Enable Networking + + Add the following line to + /boot/loader.conf: + + security.mac.biba.trust_all_interfaces=1 + + And the following to the network card configuration stored + in rc.conf. If the primary Internet + configuration is done via DHCP, this may + need to be configured manually after every system boot: + + maclabel biba/equal + + + + Testing the Configuration + + + MAC Configuration Testing + + + Ensure that the web server and + Nagios will not be started + on system initialization, and reboot. Ensure the + root user cannot access any of the files + in the Nagios configuration + directory. If root can issue an &man.ls.1; + command on /var/spool/nagios, then something + is wrong. Otherwise a permission denied error + should be returned. + + If all seems well, Nagios, + Apache, and + Sendmail can now be started in a way + fitting of the security policy. The following commands will + make this happen: + + &prompt.root; cd /etc/mail && make stop && \ +setpmac biba/equal make start && setpmac biba/10\(10-10\) apachectl start && \ +setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart + + Double check to ensure that everything is working + properly. If not, check the log files or error messages. Use + the &man.sysctl.8; utility to disable the &man.mac.biba.4; + security policy module enforcement and try starting everything + again, like normal. + + + The root user can change the security + enforcement and edit the configuration files without fear. + The following command will permit the degradation of the + security policy to a lower grade for a newly spawned + shell: + + &prompt.root; setpmac biba/10 csh + + To block this from happening, force the user into a range + via &man.login.conf.5;. If &man.setpmac.8; attempts to run + a command outside of the compartment's range, an error will + be returned and the command will not be executed. In this + case, setting root to + biba/high(high-high). + + + + + + User Lock Down + + This example considers a relatively small, fewer than fifty + users, storage system. Users would have login capabilities, and + be permitted to not only store data but access resources as + well. + + For this scenario, the &man.mac.bsdextended.4; mixed with + &man.mac.seeotheruids.4; could co-exist and block access not + only to system objects but to hide user processes as well. + + Begin by adding the following lines to + /boot/loader.conf: + + mac_seeotheruids_enabled="YES" + + The &man.mac.bsdextended.4; security policy module may be + activated through the use of the following rc.conf + variable: + + ugidfw_enable="YES" + + Default rules stored in + /etc/rc.bsdextended will be loaded at system + initialization; however, the default entries may need + modification. Since this machine is expected only to service + users, everything may be left commented out except the last + two. These will force the loading of user owned system objects + by default. + + Add the required users to this machine and reboot. For + testing purposes, try logging in as a different user across two + consoles. Run the ps aux command to see if + processes of other users are visible. Try to run &man.ls.1; on + another users home directory, it should fail. + + Do not try to test with the root user + unless the specific sysctls have been modified + to block super user access. + + + When a new user is added, their &man.mac.bsdextended.4; + rule will not be in the ruleset list. To update the ruleset + quickly, simply unload the security policy module and reload + it again using the &man.kldunload.8; and &man.kldload.8; + utilities. + + + + + Troubleshooting the MAC Framework + + + MAC Troubleshooting + + + During the development stage, a few users reported problems + with normal configuration. Some of these problems + are listed below: + + + The <option>multilabel</option> option cannot be enabled on + <filename>/</filename> + + The flag does not stay + enabled on my root (/) partition! + + + It seems that one out of every fifty users has this + problem, indeed, we had this problem during our initial + configuration. Further observation of this so called + bug has lead me to believe that it is a + result of either incorrect documentation or misinterpretation + of the documentation. Regardless of why it happened, the + following steps may be taken to resolve it: + + + + Edit /etc/fstab and set the root + partition at for read-only. + + + + Reboot into single user mode. + + + + Run tunefs + on /. + + + + Reboot the system into normal mode. + + + + Run mount + / and change the + back to in /etc/fstab + and reboot the system again. + + + + Double-check the output from the + mount to ensure that + has been properly set on the + root file system. + + + + + + Cannot start a X11 server after <acronym>MAC</acronym> + + After establishing a secure environment with + MAC, I am no longer able to start + X! + + This could be caused by the MAC + partition policy or by a mislabeling in + one of the MAC labeling policies. To + debug, try the following: + + + + Check the error message; if the user is in the + insecure class, the + partition policy may be the culprit. + Try setting the user's class back to the + default class and rebuild the database + with the cap_mkdb command. If this + does not alleviate the problem, go to step two. + + + + Double-check the label policies. Ensure that the + policies are set correctly for the user in question, the + X11 application, and + the /dev + entries. + + + + If neither of these resolve the problem, send the + error message and a description of your environment to + the TrustedBSD discussion lists located at the + TrustedBSD + website or to the &a.questions; + mailing list. + + + + + + Error: &man..secure.path.3; cannot stat <filename>.login_conf</filename> + + When I attempt to switch from the root + to another user in the system, the error message + _secure_path: unable to state .login_conf. + + This message is usually shown when the user has a higher + label setting then that of the user whom they are attempting to + become. For instance a user on the system, + joe, has a default label of + . The root user, + who has a label of , cannot view + joe's home directory. This will happen + regardless if root has used the + su command to become joe, + or not. In this scenario, the Biba integrity model will not + permit root to view objects set at a lower + integrity level. + + + + The <username>root</username> username is broken! + + In normal or even single user mode, the + root is not recognized. The + whoami command returns 0 (zero) and + su returns who are you?. + What could be going on? + + This can happen if a labeling policy has been disabled, + either by a &man.sysctl.8; or the policy module was unloaded. + If the policy is being disabled or has been temporarily + disabled, then the login capabilities database needs to be + reconfigured with the option being + removed. Double check the login.conf + file to ensure that all options have + been removed and rebuild the database with the + cap_mkdb command. + + This may also happen if a policy restricts access to the + master.passwd file or database. Usually + caused by an administrator altering the file under a label + which conflicts with the general policy being used by the + system. In these cases, the user information would be read + by the system and access would be blocked as the file has + inherited the new label. Disable the policy via a + &man.sysctl.8; and everything should return to normal. + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/mail/Makefile b/pl_PL.ISO8859-2/books/handbook/mail/Makefile new file mode 100644 index 0000000000..538dff091f --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/mail/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= mail/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/mail/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/mail/chapter.sgml new file mode 100644 index 0000000000..b6a04bf11d --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/mail/chapter.sgml @@ -0,0 +1,2323 @@ + + + + + + + Bill + Lloyd + Original work by + + + + + Jim + Mock + Rewritten by + + + + + + Electronic Mail + + + Synopsis + email + + Electronic Mail, better known as email, is one of the + most widely used forms of communication today. This chapter provides + a basic introduction to running a mail server on &os;, as well as an + introduction to sending and receiving email using &os;; however, + it is not a complete reference and in fact many important + considerations are omitted. For more complete coverage of the + subject, the reader is referred to the many excellent books listed + in . + + After reading this chapter, you will know: + + + + What software components are involved in sending and receiving + electronic mail. + + + + Where basic sendmail configuration + files are located in FreeBSD. + + + + The difference between remote and + local mailboxes. + + + + How to block spammers from illegally using your mail server as a + relay. + + + + How to install and configure an alternate Mail Transfer Agent on + your system, replacing sendmail. + + + + How to troubleshoot common mail server problems. + + + + How to use SMTP with UUCP. + + + + How to set up the system to send mail only. + + + + How to use mail with a dialup connection. + + + + How to configure SMTP Authentication for added security. + + + + How to install and use a Mail User Agent, such as + mutt to send and receive email. + + + + + How to download your mail from a remote POP + or IMAP server. + + + + How to automatically apply filters and rules to incoming + email. + + + + Before reading this chapter, you should: + + + + Properly set up your network connection + (). + + + + Properly set up the DNS information for your mail host + (). + + + + Know how to install additional third-party software + (). + + + + + Using Electronic Mail + POP + IMAP + DNS + + There are five major parts involved in an email exchange. They + are: the user program, the server daemon, DNS, a + remote or local mailbox, and of course, the + mailhost itself. + + + The User Program + + This includes command line programs such as + mutt, + pine, elm, + and mail, and GUI programs such as + balsa, + xfmail to name a few, and something + more sophisticated like a WWW browser. These + programs simply pass off the email transactions to the local + mailhost, either + by calling one of the server + daemons available, or delivering it over TCP. + + + + Mailhost Server Daemon + + mail server daemons + sendmail + + + mail server daemons + postfix + + + mail server daemons + qmail + + + mail server daemons + exim + + + &os; ships with sendmail by + default, but also support numerous other mail server daemons, + just some of which include: + + + + exim; + + + + postfix; + + + + qmail. + + + + The server daemon usually has two functions—it is responsible + for receiving incoming mail as well as delivering outgoing mail. It is + not responsible for the collection of mail using protocols + such as POP or IMAP to + read your email, nor does it allow connecting to local + mbox or Maildir mailboxes. You may require + an additional daemon for + that. + + + Older versions of sendmail + have some serious security issues which may result in an + attacker gaining local and/or remote access to your machine. + Make sure that you are running a current version to avoid + these problems. Optionally, install an alternative + MTA from the &os; + Ports Collection. + + + + + Email and DNS + + The Domain Name System (DNS) and its daemon + named play a large role in the delivery of + email. In order to deliver mail from your site to another, the + server daemon will look up the remote site in the DNS to determine the + host that will receive mail for the destination. This process + also occurs when mail is sent from a remote host to your mail + server. + + + MX record + + + DNS is responsible for mapping + hostnames to IP addresses, as well as for storing information + specific to mail delivery, known as MX records. The MX (Mail + eXchanger) record specifies which host, or hosts, will receive + mail for a particular domain. If you do not have an MX record + for your hostname or domain, the mail will be delivered + directly to your host provided you have an A record pointing + your hostname to your IP address. + + You may view the MX records for any domain by using the + &man.host.1; command, as seen in the example below: + + &prompt.user; host -t mx FreeBSD.org +FreeBSD.org mail is handled (pri=10) by mx1.FreeBSD.org + + + + Receiving Mail + + email + receiving + + + Receiving mail for your domain is done by the mail host. It + will collect all mail sent to your domain and store it + either in mbox (the default method for storing mail) or Maildir format, depending + on your configuration. + Once mail has been stored, it may either be read locally using + applications such as &man.mail.1; or + mutt, or remotely accessed and + collected using protocols such as + POP or IMAP. + This means that should you only + wish to read mail locally, you are not required to install a + POP or IMAP server. + + + Accessing remote mailboxes using <acronym>POP</acronym> and <acronym>IMAP</acronym> + + POP + IMAP + In order to access mailboxes remotely, you are required to + have access to a POP or IMAP + server. These protocols allow users to connect to their mailboxes from + remote locations with ease. Though both + POP and IMAP allow users + to remotely access mailboxes, IMAP offers + many advantages, some of which are: + + + + IMAP can store messages on a remote + server as well as fetch them. + + + + IMAP supports concurrent updates. + + + + IMAP can be extremely useful over + low-speed links as it allows users to fetch the structure + of messages without downloading them; it can also + perform tasks such as searching on the server in + order to minimize data transfer between clients and + servers. + + + + + In order to install a POP or + IMAP server, the following steps should be + performed: + + + + Choose an IMAP or + POP server that best suits your needs. + The following POP and + IMAP servers are well known and serve + as some good examples: + + + + qpopper; + + + + teapop; + + + + imap-uw; + + + + courier-imap; + + + + + + + Install the POP or + IMAP daemon of your choosing from the + ports + collection. + + + + Where required, modify /etc/inetd.conf + to load the POP or + IMAP server. + + + + + It should be noted that both POP and + IMAP transmit information, including + username and password credentials in clear-text. This means + that if you wish to secure the transmission of information + across these protocols, you should consider tunneling + sessions over &man.ssh.1;. Tunneling sessions is + described in . + + + + + Accessing local mailboxes + + Mailboxes may be accessed locally by directly utilizing + MUAs on the server on which the mailbox + resides. This can be done using applications such as + mutt or &man.mail.1;. + + + + + + The Mail Host + mail host + + The mail host is the name given to a server that is + responsible for delivering and receiving mail for your host, and + possibly your network. + + + + + + + + Christopher + Shumway + Contributed by + + + + <application>sendmail</application> Configuration + + + sendmail + + + &man.sendmail.8; is the default Mail Transfer Agent (MTA) in + FreeBSD. sendmail's job is to accept + mail from Mail User Agents (MUA) and deliver it + to the appropriate mailer as defined by its configuration file. + sendmail can also accept network + connections and deliver mail to local mailboxes or deliver it to + another program. + + sendmail uses the following + configuration files: + + + /etc/mail/access + + + /etc/mail/aliases + + + /etc/mail/local-host-names + + + /etc/mail/mailer.conf + + + /etc/mail/mailertable + + + /etc/mail/sendmail.cf + + + /etc/mail/virtusertable + + + + + + Filename + Function + + + + + + /etc/mail/access + + sendmail access database + file + + + + /etc/mail/aliases + + Mailbox aliases + + + + /etc/mail/local-host-names + + Lists of hosts sendmail + accepts mail for + + + + /etc/mail/mailer.conf + + Mailer program configuration + + + + /etc/mail/mailertable + + Mailer delivery table + + + + /etc/mail/sendmail.cf + + sendmail master + configuration file + + + + /etc/mail/virtusertable + + Virtual users and domain tables + + + + + + + <filename>/etc/mail/access</filename> + + The access database defines what host(s) or IP addresses + have access to the local mail server and what kind of access + they have. Hosts can be listed as , + , or simply passed + to sendmail's error handling routine with a given mailer error. + Hosts that are listed as , which is the + default, are allowed to send mail to this host as long as the + mail's final destination is the local machine. Hosts that are + listed as are rejected for all mail + connections. Hosts that have the option + for their hostname are allowed to send mail for any destination + through this mail server. + + + Configuring the <application>sendmail</application> + Access Database + + cyberspammer.com 550 We do not accept mail from spammers +FREE.STEALTH.MAILER@ 550 We do not accept mail from spammers +another.source.of.spam REJECT +okay.cyberspammer.com OK +128.32 RELAY + + + In this example we have five entries. Mail senders that + match the left hand side of the table are affected by the action + on the right side of the table. The first two examples give an + error code to sendmail's error + handling routine. The message is printed to the remote host when + a mail matches the left hand side of the table. The next entry + rejects mail from a specific host on the Internet, + another.source.of.spam. The next entry accepts + mail connections from a host + okay.cyberspammer.com, which is more exact than + the cyberspammer.com line above. More specific + matches override less exact matches. The last entry allows + relaying of electronic mail from hosts with an IP address that + begins with 128.32. These hosts would be able + to send mail through this mail server that are destined for other + mail servers. + + When this file is updated, you need to run + make in /etc/mail/ to + update the database. + + + + <filename>/etc/mail/aliases</filename> + + The aliases database contains a list of virtual mailboxes + that are expanded to other user(s), files, programs or other + aliases. Here are a few examples that can be used in + /etc/mail/aliases: + + + Mail Aliases + root: localuser +ftp-bugs: joe,eric,paul +bit.bucket: /dev/null +procmail: "|/usr/local/bin/procmail" + + + The file format is simple; the mailbox name on the left + side of the colon is expanded to the target(s) on the right. + The + first example simply expands the mailbox root + to the mailbox localuser, which is then + looked up again in the aliases database. If no match is found, + then the message is delivered to the local user + localuser. The next example shows a mail + list. Mail to the mailbox ftp-bugs is + expanded to the three local mailboxes joe, + eric, and paul. Note + that a remote mailbox could be specified as user@example.com. The + next example shows writing mail to a file, in this case + /dev/null. The last example shows sending + mail to a program, in this case the mail message is written to the + standard input of /usr/local/bin/procmail + through a &unix; pipe. + + When this file is updated, you need to run + make in /etc/mail/ to + update the database. + + + <filename>/etc/mail/local-host-names</filename> + + This is a list of hostnames &man.sendmail.8; is to accept as + the local host name. Place any domains or hosts that + sendmail is to be receiving mail for. + For example, if this mail server was to accept mail for the + domain example.com and the host + mail.example.com, its + local-host-names might look something like + this: + + example.com +mail.example.com + + When this file is updated, &man.sendmail.8; needs to be + restarted to read the changes. + + + + + <filename>/etc/mail/sendmail.cf</filename> + + sendmail's master configuration + file, sendmail.cf controls the overall + behavior of sendmail, including everything + from rewriting e-mail addresses to printing rejection messages to + remote mail servers. Naturally, with such a diverse role, this + configuration file is quite complex and its details are a bit + out of the scope of this section. Fortunately, this file rarely + needs to be changed for standard mail servers. + + The master sendmail configuration + file can be built from &man.m4.1; macros that define the features + and behavior of sendmail. Please see + /usr/src/contrib/sendmail/cf/README for + some of the details. + + When changes to this file are made, + sendmail needs to be restarted for + the changes to take effect. + + + + <filename>/etc/mail/virtusertable</filename> + + The virtusertable maps mail addresses for + virtual domains and + mailboxes to real mailboxes. These mailboxes can be local, + remote, aliases defined in + /etc/mail/aliases or files. + + + Example Virtual Domain Mail Map + + root@example.com root +postmaster@example.com postmaster@noc.example.net +@example.com joe + + + In the above example, we have a mapping for a domain + example.com. This file is processed in a + first match order down the file. The first item maps + root@example.com to the local mailbox root. The next entry maps + postmaster@example.com to the mailbox postmaster on the host + noc.example.net. Finally, if nothing from example.com has + matched so far, it will match the last mapping, which matches + every other mail message addressed to someone at + example.com. + This will be mapped to the local mailbox joe. + + + + + + + + + Andrew + Boothman + Written by + + + + + Gregory + Neil Shapiro + Information taken from e-mails written by + + + + Changing Your Mail Transfer Agent + + email + change mta + + + As already mentioned, FreeBSD comes with + sendmail already installed as your + MTA (Mail Transfer Agent). Therefore by default it is + in charge of your outgoing and incoming mail. + + However, for a variety of reasons, some system + administrators want to change their system's MTA. These + reasons range from simply wanting to try out another MTA to + needing a specific feature or package which relies on another + mailer. Fortunately, whatever the reason, FreeBSD makes it + easy to make the change. + + + Install a New MTA + + You have a wide choice of MTAs available. A good + starting point is the + FreeBSD Ports Collection where + you will be able to find many. Of course you are free to use + any MTA you want from any location, as long as you can make + it run under FreeBSD. + + Start by installing your new MTA. Once it is installed + it gives you a chance to decide if it really fulfills your + needs, and also gives you the opportunity to configure your + new software before getting it to take over from + sendmail. When doing this, you + should be sure that installing the new software will not attempt + to overwrite system binaries such as + /usr/bin/sendmail. Otherwise, your new + mail software has essentially been put into service before + you have configured it. + + Please refer to your chosen MTA's documentation for + information on how to configure the software you have + chosen. + + + + Disable <application>sendmail</application> + + The procedure used to start + sendmail changed significantly + between 4.5-RELEASE, 4.6-RELEASE, and later releases. + Therefore, the procedure used to disable it is subtly + different. + + + If you disable sendmail's + outgoing mail service, it is important that you replace it + with an alternative mail delivery system. If + you choose not to, system functions such as &man.periodic.8; + will be unable to deliver their results by e-mail as they + would normally expect to. Many parts of your system may + expect to have a functional + sendmail-compatible system. If + applications continue to use + sendmail's binaries to try to send + e-mail after you have disabled them, mail could go into an + inactive sendmail queue, and + never be delivered. + + + + FreeBSD 4.5-STABLE before 2002/4/4 and Earlier + (Including 4.5-RELEASE and Earlier) + + Enter: + + sendmail_enable="NO" + + into /etc/rc.conf. This will disable + sendmail's incoming mail service, + but if /etc/mail/mailer.conf (see below) + is not changed, sendmail will + still be used to send e-mail. + + + + FreeBSD 4.5-STABLE after 2002/4/4 + (Including 4.6-RELEASE and Later) + + In order to completely disable + sendmail, including the outgoing + mail service, you must use + + sendmail_enable="NONE" + + in /etc/rc.conf. + + If you only want to disable + sendmail's incoming mail service, + you should set + + sendmail_enable="NO" + + in /etc/rc.conf. However, if + incoming mail is disabled, local delivery will still + function. More information on + sendmail's startup options is + available from the &man.rc.sendmail.8; manual page. + + + + FreeBSD 5.0-STABLE and Later + + In order to completely disable + sendmail, including the outgoing + mail service, you must use + + sendmail_enable="NO" +sendmail_submit_enable="NO" +sendmail_outbound_enable="NO" +sendmail_msp_queue_enable="NO" + + in /etc/rc.conf. + + If you only want to disable + sendmail's incoming mail service, + you should set + + sendmail_enable="NO" + + in /etc/rc.conf. More information on + sendmail's startup options is + available from the &man.rc.sendmail.8; manual page. + + + + + Running Your New MTA on Boot + + You may have a choice of two methods for running your + new MTA on boot, again depending on what version of FreeBSD + you are running. + + + FreeBSD 4.5-STABLE before 2002/4/11 + (Including 4.5-RELEASE and Earlier) + + Add a script to + /usr/local/etc/rc.d/ that + ends in .sh and is executable by + root. The script should accept start and + stop parameters. At startup time the + system scripts will execute the command + + /usr/local/etc/rc.d/supermailer.sh start + + which you can also use to manually start the server. At + shutdown time, the system scripts will use the + stop option, running the command + + /usr/local/etc/rc.d/supermailer.sh stop + + which you can also use to manually stop the server + while the system is running. + + + + + FreeBSD 4.5-STABLE after 2002/4/11 + (Including 4.6-RELEASE and Later) + + With later versions of FreeBSD, you can use the + above method or you can set + + mta_start_script="filename" + + in /etc/rc.conf, where + filename is the name of some + script that you want executed at boot to start your + MTA. + + + + + + Replacing <application>sendmail</application> as + the System's Default Mailer + + The program sendmail is so ubiquitous + as standard software on &unix; systems that some software + just assumes it is already installed and configured. + For this reason, many alternative MTA's provide their own compatible + implementations of the sendmail + command-line interface; this facilitates using them as + drop-in replacements for sendmail. + + Therefore, if you are using an alternative mailer, + you will need to make sure that software trying to execute + standard sendmail binaries such as + /usr/bin/sendmail actually executes + your chosen mailer instead. Fortunately, FreeBSD provides + a system called &man.mailwrapper.8; that does this job for + you. + + When sendmail is operating as installed, you will + find something like the following + in /etc/mail/mailer.conf: + +sendmail /usr/libexec/sendmail/sendmail +send-mail /usr/libexec/sendmail/sendmail +mailq /usr/libexec/sendmail/sendmail +newaliases /usr/libexec/sendmail/sendmail +hoststat /usr/libexec/sendmail/sendmail +purgestat /usr/libexec/sendmail/sendmail + + This means that when any of these common commands + (such as sendmail itself) are run, + the system actually invokes a copy of mailwrapper named sendmail, which + checks mailer.conf and + executes /usr/libexec/sendmail/sendmail + instead. This system makes it easy to change what binaries + are actually executed when these default sendmail functions + are invoked. + + Therefore if you wanted + /usr/local/supermailer/bin/sendmail-compat + to be run instead of sendmail, you could change + /etc/mail/mailer.conf to read: + +sendmail /usr/local/supermailer/bin/sendmail-compat +send-mail /usr/local/supermailer/bin/sendmail-compat +mailq /usr/local/supermailer/bin/mailq-compat +newaliases /usr/local/supermailer/bin/newaliases-compat +hoststat /usr/local/supermailer/bin/hoststat-compat +purgestat /usr/local/supermailer/bin/purgestat-compat + + + + + Finishing + + Once you have everything configured the way you want it, you should + either kill the sendmail processes that + you no longer need and start the processes belonging to your new + software, or simply reboot. Rebooting will also + give you the opportunity to ensure that you have correctly + configured your system to start your new MTA automatically on boot. + + + + + + Troubleshooting + + email + troubleshooting + + + + + + Why do I have to use the FQDN for hosts on my site? + + + + You will probably find that the host is actually in a + different domain; for example, if you are in + foo.bar.edu and you wish to reach + a host called mumble in the bar.edu domain, you will have to + refer to it by the fully-qualified domain name, mumble.bar.edu, instead of just + mumble. + + BIND + Traditionally, this was allowed by BSD BIND resolvers. + However the current version of BIND + that ships with FreeBSD no longer provides default abbreviations + for non-fully qualified domain names other than the domain you + are in. So an unqualified host mumble must + either be found as mumble.foo.bar.edu, or it will be searched + for in the root domain. + + This is different from the previous behavior, where the + search continued across mumble.bar.edu, and mumble.edu. Have a look at RFC 1535 + for why this was considered bad practice, or even a security + hole. + + As a good workaround, you can place the line: + + search foo.bar.edu bar.edu + + instead of the previous: + + domain foo.bar.edu + + into your /etc/resolv.conf. However, make + sure that the search order does not go beyond the + boundary between local and public administration, + as RFC 1535 calls it. + + + + + MX record + + + + + sendmail says mail + loops back to myself + + + + This is answered in the + sendmail FAQ as follows: + + I'm getting these error messages: + +553 MX list for domain.net points back to relay.domain.net +554 <user@domain.net>... Local configuration error + +How can I solve this problem? + +You have asked mail to the domain (e.g., domain.net) to be +forwarded to a specific host (in this case, relay.domain.net) +by using an MX record, but the relay machine does not recognize +itself as domain.net. Add domain.net to /etc/mail/local-host-names +[known as /etc/sendmail.cw prior to version 8.10] +(if you are using FEATURE(use_cw_file)) or add Cw domain.net +to /etc/mail/sendmail.cf. + + The sendmail FAQ can be found at + and is + recommended reading if you want to do any + tweaking of your mail setup. + + + + PPP + + + How can I run a mail server on a dial-up PPP host? + + + + You want to connect a FreeBSD box on a LAN to the + Internet. The FreeBSD box will be a mail gateway for the LAN. + The PPP connection is non-dedicated. + + UUCP + + MX record + + + There are at least two ways to do this. One way is to use + UUCP. + + Another way is to get a full-time Internet server to provide secondary MX + services for your domain. For example, if your company's domain is + example.com and your Internet service provider has + set example.net up to provide secondary MX services + to your domain: + + example.com. MX 10 example.com. + MX 20 example.net. + + Only one host should be specified as the final recipient + (add Cw example.com in + /etc/mail/sendmail.cf on example.com). + + When the sending sendmail is trying to + deliver the mail it will try to connect to you (example.com) over the modem + link. It will most likely time out because you are not online. + The program sendmail will automatically deliver it to the + secondary MX site, i.e. your Internet provider (example.net). The secondary MX + site will then periodically try to connect to + your host and deliver the mail to the primary MX host (example.com). + + You might want to use something like this as a login + script: + + #!/bin/sh +# Put me in /usr/local/bin/pppmyisp +( sleep 60 ; /usr/sbin/sendmail -q ) & +/usr/sbin/ppp -direct pppmyisp + + If you are going to create a separate login script for a + user you could use sendmail -qRexample.com + instead in the script above. This will force all mail in your + queue for example.com to be processed immediately. + + A further refinement of the situation is as follows: + + Message stolen from the &a.isp;. + + > we provide the secondary MX for a customer. The customer connects to +> our services several times a day automatically to get the mails to +> his primary MX (We do not call his site when a mail for his domains +> arrived). Our sendmail sends the mailqueue every 30 minutes. At the +> moment he has to stay 30 minutes online to be sure that all mail is +> gone to the primary MX. +> +> Is there a command that would initiate sendmail to send all the mails +> now? The user has not root-privileges on our machine of course. + +In the privacy flags section of sendmail.cf, there is a +definition Opgoaway,restrictqrun + +Remove restrictqrun to allow non-root users to start the queue processing. +You might also like to rearrange the MXs. We are the 1st MX for our +customers like this, and we have defined: + +# If we are the best MX for a host, try directly instead of generating +# local config error. +OwTrue + +That way a remote site will deliver straight to you, without trying +the customer connection. You then send to your customer. Only works for +hosts, so you need to get your customer to name their mail +machine customer.com as well as +hostname.customer.com in the DNS. Just put an A record in +the DNS for customer.com. + + + + + + Why do I keep getting Relaying + Denied errors when sending mail from other + hosts? + + + + In default FreeBSD installations, + sendmail is configured to only + send mail from the host it is running on. For example, if + a POP server is available, then users + will be able to check mail from school, work, or other + remote locations but they still will not be able to send + outgoing emails from outside locations. Typically, a few + moments after the attempt, an email will be sent from + MAILER-DAEMON with a + 5.7 Relaying Denied error + message. + + There are several ways to get around this. The most + straightforward solution is to put your ISP's address in + a relay-domains file at + /etc/mail/relay-domains. A quick way + to do this would be: + + &prompt.root; echo "your.isp.example.com" > /etc/mail/relay-domains + + After creating or editing this file you must restart + sendmail. This works great if + you are a server administrator and do not wish to send mail + locally, or would like to use a point and click + client/system on another machine or even another ISP. It + is also very useful if you only have one or two email + accounts set up. If there is a large number of addresses + to add, you can simply open this file in your favorite + text editor and then add the domains, one per line: + + your.isp.example.com +other.isp.example.net +users-isp.example.org +www.example.org + + Now any mail sent through your system, by any host in + this list (provided the user has an account on your + system), will succeed. This is a very nice way to allow + users to send mail from your system remotely without + allowing people to send SPAM through your system. + + + + + + + + Advanced Topics + + The following section covers more involved topics such as mail + configuration and setting up mail for your entire domain. + + + Basic Configuration + + email + configuration + + + Out of the box, you should be able to send email to external + hosts as long as you have set up + /etc/resolv.conf or are running your own + name server. If you would like to have mail for your host + delivered to the MTA (e.g., sendmail) on your own FreeBSD host, there are two methods: + + + + Run your own name server and have your own domain. For + example, FreeBSD.org + + + + Get mail delivered directly to your host. This is done by + delivering mail directly to the current DNS name for your + machine. For example, example.FreeBSD.org. + + + + SMTP + Regardless of which of the above you choose, in order to have + mail delivered directly to your host, it must have a permanent + static IP address (not a dynamic address, as with most PPP dial-up configurations). If you are behind a + firewall, it must pass SMTP traffic on to you. If you want to + receive mail directly at your host, you need to be sure of either of two + things: + + + MX record + + Make sure that the (lowest-numbered) MX record in your DNS points to your + host's IP address. + + + + Make sure there is no MX entry in your DNS for your + host. + + + + Either of the above will allow you to receive mail directly at + your host. + + Try this: + + &prompt.root; hostname +example.FreeBSD.org +&prompt.root; host example.FreeBSD.org +example.FreeBSD.org has address 204.216.27.XX + + If that is what you see, mail directly to + yourlogin@example.FreeBSD.org should work without + problems (assuming sendmail is + running correctly on example.FreeBSD.org). + + If instead you see something like this: + + &prompt.root; host example.FreeBSD.org +example.FreeBSD.org has address 204.216.27.XX +example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org + + All mail sent to your host (example.FreeBSD.org) will end up being + collected on hub under the same username instead + of being sent directly to your host. + + The above information is handled by your DNS server. The DNS + record that carries mail routing information is the + Mail eXchange entry. If + no MX record exists, mail will be delivered directly to the host by + way of its IP address. + + The MX entry for freefall.FreeBSD.org at one time looked like + this: + + freefall MX 30 mail.crl.net +freefall MX 40 agora.rdrop.com +freefall MX 10 freefall.FreeBSD.org +freefall MX 20 who.cdrom.com + + As you can see, freefall had many MX entries. + The lowest MX number is the host that receives mail directly if + available; if it is not accessible for some reason, the others + (sometimes called backup MXes) accept messages + temporarily, and pass it along when a lower-numbered host becomes + available, eventually to the lowest-numbered host. + + Alternate MX sites should have separate Internet connections + from your own in order to be most useful. Your ISP or another + friendly site should have no problem providing this service for + you. + + + + Mail for Your Domain + + In order to set up a mailhost (a.k.a. mail + server) you need to have any mail sent to various workstations + directed to it. Basically, you want to claim any + mail for any hostname in your domain (in this case *.FreeBSD.org) and divert it to your mail + server so your users can receive their mail on + the master mail server. + + DNS + To make life easiest, a user account with the same + username should exist on both machines. Use + &man.adduser.8; to do this. + + The mailhost you will be using must be the designated mail + exchanger for each workstation on the network. This is done in + your DNS configuration like so: + + example.FreeBSD.org A 204.216.27.XX ; Workstation + MX 10 hub.FreeBSD.org ; Mailhost + + This will redirect mail for the workstation to the mailhost no + matter where the A record points. The mail is sent to the MX + host. + + You cannot do this yourself unless you are running a DNS + server. If you are not, or cannot run your own DNS server, talk + to your ISP or whoever provides your DNS. + + If you are doing virtual email hosting, the following + information will come in handy. For this example, we + will assume you have a customer with his own domain, in this + case customer1.org, and you want + all the mail for customer1.org + sent to your mailhost, mail.myhost.com. The entry in your DNS + should look like this: + + customer1.org MX 10 mail.myhost.com + + You do not need an A record for customer1.org if you only + want to handle email for that domain. + + + Be aware that pinging customer1.org will not work unless + an A record exists for it. + + + The last thing that you must do is tell + sendmail on your mailhost what domains + and/or hostnames it should be accepting mail for. There are a few + different ways this can be done. Either of the following will + work: + + + + Add the hosts to your + /etc/mail/local-host-names file if you are using the + FEATURE(use_cw_file). If you are using + a version of sendmail earlier than 8.10, the file is + /etc/sendmail.cw. + + + + Add a Cwyour.host.com line to your + /etc/sendmail.cf or + /etc/mail/sendmail.cf if you are using + sendmail 8.10 or higher. + + + + + + + SMTP with UUCP + + The sendmail configuration that ships with FreeBSD is + designed 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/mail/sendmail.cf manually + is an advanced topic. sendmail version 8 generates config files + via &man.m4.1; preprocessing, where the actual configuration + occurs on a higher abstraction level. The &man.m4.1; + configuration files can be found under + /usr/src/usr.sbin/sendmail/cf. + + If you did not install your system with full sources, the + sendmail configuration set has been broken out into a separate source + distribution tarball. Assuming you have your FreeBSD source code + CDROM mounted, do: + + &prompt.root; cd /cdrom/src +&prompt.root; cat scontrib.?? | tar xzf - -C /usr/src/contrib/sendmail + + This extracts to only a few hundred kilobytes. The file + README in the cf + directory can serve as a basic introduction to &man.m4.1; + configuration. + + The best way to support UUCP delivery is to use the + mailertable feature. This creates a database + that sendmail can use to make routing decisions. + + First, you have to create your .mc + file. The directory + /usr/src/usr.sbin/sendmail/cf/cf contains 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/mail/sendmail.cf + + A typical .mc file might look + like: + + VERSIONID(`Your version number') OSTYPE(bsd4.4) + +FEATURE(accept_unresolvable_domains) +FEATURE(nocanonify) +FEATURE(mailertable, `hash -o /etc/mail/mailertable') + +define(`UUCP_RELAY', your.uucp.relay) +define(`UUCP_MAX_SIZE', 200000) +define(`confDONT_PROBE_INTERFACES') + +MAILER(local) +MAILER(smtp) +MAILER(uucp) + +Cw your.alias.host.name +Cw youruucpnodename.UUCP + + The lines containing + accept_unresolvable_domains, + nocanonify, and + confDONT_PROBE_INTERFACES features will + prevent any usage of the DNS during mail delivery. The + UUCP_RELAY clause is needed to support UUCP + delivery. Simply put an Internet hostname there that is able to + handle .UUCP pseudo-domain addresses; most likely, you will + enter the mail relay of your ISP there. + + Once you have this, you need an + /etc/mail/mailertable file. If you have + only one link to the outside that is used for all your mails, + the following file will suffice: + + # +# makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable +. uucp-dom:your.uucp.relay + + A more complex example might look like this: + + # +# makemap hash /etc/mail/mailertable.db < /etc/mail/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: + + + 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 use. The command line to accomplish + this is best placed as a comment at the top of the mailertable file. + You always have to execute this command each time you change + your mailertable file. + + 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 3,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 CtrlD. + + &prompt.user; sendmail -bt +ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) +Enter <ruleset> <address> +> 3,0 foo@example.com +canonify input: foo @ example . com +... +parse returns: $# uucp-dom $@ your.uucp.relay $: foo < @ example . com . > +> ^D + + + + + + + Bill + Moran + Contributed by + + + + + Setting Up to Send Only + + There are many instances where you may only want to send + mail through a relay. Some examples are: + + + + Your computer is a desktop machine, but you want + to use programs such as &man.send-pr.1;. To do so, you should use + your ISP's mail relay. + + + + The computer is a server that does not handle mail + locally, but needs to pass off all mail to a relay for + processing. + + + + Just about any MTA is capable of filling + this particular niche. Unfortunately, it can be very difficult + to properly configure a full-featured MTA + just to handle offloading mail. Programs such as + sendmail and + postfix are largely overkill for + this use. + + Additionally, if you are using a typical Internet access + service, your agreement may forbid you from running a + mail server. + + The easiest way to fulfill those needs is to install the + mail/ssmtp port. Execute + the following commands as root: + + &prompt.root; cd /usr/ports/mail/ssmtp +&prompt.root; make install replace clean + + Once installed, + mail/ssmtp can be configured + with a four-line file located at + /usr/local/etc/ssmtp/ssmtp.conf: + + root=yourrealemail@example.com +mailhub=mail.example.com +rewriteDomain=example.com +hostname=_HOSTNAME_ + + Make sure you use your real email address for + root. Enter your ISP's outgoing mail relay + in place of mail.example.com (some ISPs call + this the outgoing mail server or + SMTP server). + + Make sure you disable sendmail, + including the outgoing mail service. See + for details. + + mail/ssmtp has some + other options available. See the example configuration file in + /usr/local/etc/ssmtp or the manual page of + ssmtp for some examples and more + information. + + Setting up ssmtp in this manner + will allow any software on your computer that needs to send + mail to function properly, while not violating your ISP's usage + policy or allowing your computer to be hijacked for spamming. + + + + Using Mail with a Dialup Connection + + If you have a static IP address, you should not need to + adjust anything from the defaults. Set your host name to your + assigned Internet name and sendmail will do the rest. + + If you have a dynamically assigned IP number and use a + dialup PPP connection to the Internet, you will probably have a + mailbox on your ISPs mail server. Let's assume your ISP's domain + is example.net, and that your + user name is user, you have called your + machine bsd.home, and your ISP has + told you that you may use relay.example.net as a mail relay. + + In order to retrieve mail from your mailbox, you must + install a retrieval agent. The + fetchmail utility is a good choice as + it supports many different protocols. This program is available + as a package or from the Ports Collection (mail/fetchmail). Usually, your ISP will + provide POP. If you are using user PPP, you can + automatically fetch your mail when an Internet connection is + established with the following entry in + /etc/ppp/ppp.linkup: + + MYADDR: +!bg su user -c fetchmail + + If you are using sendmail (as + shown below) to deliver mail to non-local accounts, you probably + want to have sendmail process your + mailqueue as soon as your Internet connection is established. + To do this, put this command after the + fetchmail command in + /etc/ppp/ppp.linkup: + + !bg su user -c "sendmail -q" + + Assume that you have an account for + user on bsd.home. In the home directory of + user on bsd.home, create a + .fetchmailrc file: + + poll example.net protocol pop3 fetchall pass MySecret + + 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@example.net rather than + user@bsd.home. You may also wish to tell + sendmail to send all mail via relay.example.net, 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(`example.net')dnl +FEATURE(allmasquerade)dnl +FEATURE(masquerade_envelope)dnl +FEATURE(nocanonify)dnl +FEATURE(nodns)dnl +define(`SMART_HOST', `relay.example.net') +Dmbsd.home +define(`confDOMAIN_NAME',`bsd.home')dnl +define(`confDELIVERY_MODE',`deferred')dnl + + Refer to the previous section for details of how to turn + this .mc file into a + sendmail.cf file. Also, do not forget to + restart sendmail after updating + sendmail.cf. + + + + + + + James + Gorham + Written by + + + + + SMTP Authentication + + Having SMTP Authentication in place on + your mail server has a number of benefits. + SMTP Authentication can add another layer + of security to sendmail, and has the benefit of giving mobile + users who switch hosts the ability to use the same mail server + without the need to reconfigure their mail client settings + each time. + + + + Install security/cyrus-sasl + from the ports. You can find this port in + security/cyrus-sasl. + security/cyrus-sasl has + a number of compile time options to choose from and, for + the method we will be using here, make sure to select the + option. + + + + + After installing security/cyrus-sasl, + edit /usr/local/lib/sasl/Sendmail.conf + (or create it if it does not exist) and add the following + line: + + pwcheck_method: passwd + + This method will enable sendmail + to authenticate against your FreeBSD passwd + database. This saves the trouble of creating a new set of usernames + and passwords for each user that needs to use + SMTP authentication, and keeps the login + and mail password the same. + + + + Now edit /etc/make.conf and add the + following lines: + + SENDMAIL_CFLAGS=-I/usr/local/include/sasl1 -DSASL +SENDMAIL_LDFLAGS=-L/usr/local/lib +SENDMAIL_LDADD=-lsasl + + These lines will give sendmail + the proper configuration options for linking + to cyrus-sasl at compile time. + Make sure that cyrus-sasl + has been installed before recompiling + sendmail. + + + + Recompile sendmail by executing the following commands: + + &prompt.root; cd /usr/src/usr.sbin/sendmail +&prompt.root; make cleandir +&prompt.root; make obj +&prompt.root; make +&prompt.root; make install + + The compile of sendmail should not have any problems + if /usr/src has not been changed extensively + and the shared libraries it needs are available. + + + + After sendmail has been compiled + and reinstalled, edit your /etc/mail/freebsd.mc + file (or whichever file you use as your .mc file. Many administrators + choose to use the output from &man.hostname.1; as the .mc file for + uniqueness). Add these lines to it: + + dnl set SASL options +TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl +define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl +define(`confDEF_AUTH_INFO', `/etc/mail/auth-info')dnl + + These options configure the different methods available to + sendmail for authenticating users. + If you would like to use a method other than + pwcheck, please see the + included documentation. + + + + Finally, run &man.make.1; while in /etc/mail. + That will run your new .mc file and create a .cf file named + freebsd.cf (or whatever name you have used + for your .mc file). Then use the + command make install restart, which will + copy the file to sendmail.cf, and will + properly restart sendmail. + For more information about this process, you should refer + to /etc/mail/Makefile. + + + + If all has gone correctly, you should be able to enter your login + information into the mail client and send a test message. + For further investigation, set the of + sendmail to 13 and watch + /var/log/maillog for any errors. + + You may wish to add the following line to /etc/rc.conf + so this service will be available after every system boot: + + cyrus_pwcheck_enable="YES" + + This will ensure the initialization of SMTP_AUTH upon system + boot. + + For more information, please see the sendmail + page regarding + + SMTP authentication. + + + + + + + + Marc + Silver + Contributed by + + + + Mail User Agents + + + Mail User Agents + + + A Mail User Agent (MUA) is an application + that is used to send and receive email. Furthermore, as email + evolves and becomes more complex, + MUA's are becoming increasingly powerful in the + way they interact with email; this gives users increased + functionality and flexibility. &os; contains support for + numerous mail user agents, all of which can be easily installed + using the FreeBSD Ports Collection. + Users may choose between graphical email clients such as + evolution or + balsa, console based clients such as + mutt, pine + or mail, or the web interfaces used by some + large organizations. + + + mail + + &man.mail.1; is the default Mail User Agent + (MUA) in &os;. It is a + console based MUA that offers all the basic + functionality required to send and receive text-based email, + though it is limited in interaction abilities with attachments + and can only support local mailboxes. + + Although mail does not natively support + interaction with POP or + IMAP servers, these mailboxes may be + downloaded to a local mbox file using an + application such as fetchmail, which + will be discussed later in this chapter (). + + In order to send and receive email, simply invoke the + mail command as per the following + example: + + &prompt.user; mail + + The contents of the user mailbox in + /var/mail are + automatically read by the mail utility. + Should the mailbox be empty, the utility exits with a + message indicating that no mails could be found. Once the + mailbox has been read, the application interface is started, and + a list of messages will be displayed. Messages are automatically + numbered, as can be seen in the following example: + + Mail version 8.1 6/6/93. Type ? for help. +"/var/mail/marcs": 3 messages 3 new +>N 1 root@localhost Mon Mar 8 14:05 14/510 "test" + N 2 root@localhost Mon Mar 8 14:05 14/509 "user account" + N 3 root@localhost Mon Mar 8 14:05 14/509 "sample" + + Messages can now be read by using the t + mail command, suffixed by the message number + that should be displayed. In this example, we will read the + first email: + + & t 1 +Message 1: +From root@localhost Mon Mar 8 14:05:52 2004 +X-Original-To: marcs@localhost +Delivered-To: marcs@localhost +To: marcs@localhost +Subject: test +Date: Mon, 8 Mar 2004 14:05:52 +0200 (SAST) +From: root@localhost (Charlie Root) + +This is a test message, please reply if you receive it. + + As can be seen in the example above, the t + key will cause the message to be displayed with full headers. + To display the list of messages again, the h + key should be used. + + If the email requires a response, you may use + mail to reply, by using either the + R or r mail + keys. The R key instructs + mail to reply only to the sender of the + email, while r replies not only to the sender, + but also to other recipients of the message. You may also + suffix these commands with the mail number which you would like + make a reply to. Once this has been done, the response should + be entered, and the end of the message should be marked by a + single . on a new line. An example can be seen + below: + + & R 1 +To: root@localhost +Subject: Re: test + +Thank you, I did get your email. +. +EOT + + In order to send new email, the m + key should be used, followed by the + recipient email address. Multiple recipients may also be + specified by separating each address with the , + delimiter. The subject of the message may then be entered, + followed by the message contents. The end of the message should + be specified by putting a single . on a new + line. + + & mail root@localhost +Subject: I mastered mail + +Now I can send and receive email using mail ... :) +. +EOT + + While inside the mail utility, the + ? command may be used to display help at any + time, the &man.mail.1; manual page should also be consulted for + more help with mail. + + + As previously mentioned, the &man.mail.1; command was not + originally designed to handle attachments, and thus deals with + them very poorly. Newer MUAs such as + mutt handle attachments in a much + more intelligent way. But should you still wish to use the + mail command, the converters/mpack port may be of + considerable use. + + + + + mutt + + mutt is a small yet very + powerful Mail User Agent, with excellent features, + just some of which include: + + + + The ability to thread messages; + + + + PGP support for digital signing and encryption of + email; + + + + MIME Support; + + + + Maildir Support; + + + + Highly customizable. + + + + All of these features help to make + mutt one of the most advanced mail + user agents available. See for more + information on mutt. + + The stable version of mutt may be + installed using the mail/mutt port, while the current + development version may be installed via the mail/mutt-devel port. After the port + has been installed, mutt can be + started by issuing the following command: + + &prompt.user; mutt + + mutt will automatically read the + contents of the user mailbox in /var/mail and display the contents + if applicable. If no mails are found in the user mailbox, then + mutt will wait for commands from the + user. The example below shows mutt + displaying a list of messages: + + + + + + + + In order to read an email, simply select it using the cursor + keys, and press the Enter key. An example of + mutt displaying email can be seen + below: + + + + + + + + As with the &man.mail.1; command, + mutt allows users to reply only to + the sender of the message as well as to all recipients. To + reply only to the sender of the email, use the + r keyboard shortcut. To send a group reply, + which will be sent to the original sender as well as all the + message recipients, use the g shortcut. + + + mutt makes use of the + &man.vi.1; command as an editor for creating and replying to + emails. This may be customized by the user by creating or + editing their own .muttrc file in their home directory and setting the + editor variable. + + + In order to compose a new mail message, press + m. After a valid subject has been given, + mutt will start &man.vi.1; and the + mail can be written. Once the contents of the mail are + complete, save and quit from vi and + mutt will resume, displaying a + summary screen of the mail that is to be delivered. In order to + send the mail, press y. An example of the + summary screen can be seen below: + + + + + + + + mutt also contains extensive + help, which can be accessed from most of the menus by pressing + the ? key. The top line also displays the + keyboard shortcuts where appropriate. + + + + pine + + pine is aimed at a beginner + user, but also includes some advanced features. + + + The pine software has had several remote vulnerabilities + discovered in the past, which allowed remote attackers to + execute arbitrary code as users on the local system, by the + action of sending a specially-prepared email. All such + known problems have been fixed, but the + pine code is written in a very insecure style and the &os; + Security Officer believes there are likely to be other + undiscovered vulnerabilities. You install + pine at your own risk. + + + The current version of pine may + be installed using the mail/pine4 port. Once the port has + installed, pine can be started by + issuing the following command: + + &prompt.user; pine + + The first time that pine is run + it displays a greeting page with a brief introduction, as well + as a request from the pine + development team to send an anonymous email message allowing + them to judge how many users are using their client. To send + this anonymous message, press Enter, or + alternatively press E to exit the greeting + without sending an anonymous message. An example of the + greeting page can be seen below: + + + + + + + + Users are then presented with the main menu, which can be + easily navigated using the cursor keys. This main menu provides + shortcuts for the composing new mails, browsing of mail directories, + and even the administration of address book entries. Below the + main menu, relevant keyboard shortcuts to perform functions + specific to the task at hand are shown. + + The default directory opened by pine + is the inbox. To view the message index, press + I, or select the MESSAGE INDEX + option as seen below: + + + + + + + + The message index shows messages in the current directory, + and can be navigated by using the cursor keys. Highlighted + messages can be read by pressing the + Enter key. + + + + + + + + In the screenshot below, a sample message is displayed by + pine. Keyboard shortcuts are + displayed as a reference at the bottom of the screen. An + example of one of these shortcuts is the r key, + which tells the MUA to reply to the current + message being displayed. + + + + + + + + Replying to an email in pine is + done using the pico editor, which is + installed by default with pine. + The pico utility makes it easy to + navigate around the message and is slightly more forgiving on + novice users than &man.vi.1; or &man.mail.1;. Once the reply + is complete, the message can be sent by pressing + CtrlX + . The pine application + will ask for confirmation. + + + + + + + + The pine application can be + customized using the SETUP option from the main + menu. Consult + for more information. + + + + + + + + + Marc + Silver + Contributed by + + + + Using fetchmail + + + fetchmail + + + fetchmail is a full-featured + IMAP and POP client which + allows users to automatically download mail from remote + IMAP and POP servers and + save it into local mailboxes; there it can be accessed more easily. + fetchmail can be installed using the + mail/fetchmail port, and + offers various features, some of which include: + + + + Support of POP3, + APOP, KPOP, + IMAP, ETRN and + ODMR protocols. + + + + Ability to forward mail using SMTP, which + allows filtering, forwarding, and aliasing to function + normally. + + + + May be run in daemon mode to check periodically for new + messages. + + + + Can retrieve multiple mailboxes and forward them based + on configuration, to different local users. + + + + While it is outside the scope of this document to explain + all of fetchmail's features, some + basic features will be explained. The + fetchmail utility requires a + configuration file known as .fetchmailrc, + in order to run correctly. This file includes server information + as well as login credentials. Due to the sensitive nature of the + contents of this file, it is advisable to make it readable only by the owner, + with the following command: + + &prompt.user; chmod 600 .fetchmailrc + + The following .fetchmailrc serves as an + example for downloading a single user mailbox using + POP. It tells + fetchmail to connect to example.com using a username of + joesoap and a password of + XXX. This example assumes that the user + joesoap is also a user on the local + system. + + poll example.com protocol pop3 username "joesoap" password "XXX" + + The next example connects to multiple POP + and IMAP servers and redirects to different + local usernames where applicable: + + poll example.com proto pop3: +user "joesoap", with password "XXX", is "jsoap" here; +user "andrea", with password "XXXX"; +poll example2.net proto imap: +user "john", with password "XXXXX", is "myth" here; + + The fetchmail utility can be run in daemon + mode by running it with the flag, followed + by the interval (in seconds) that + fetchmail should poll servers listed + in the .fetchmailrc file. The following + example would cause fetchmail to poll + every 600 seconds: + + &prompt.user; fetchmail -d 600 + + More information on fetchmail can + be found at . + + + + + + + Marc + Silver + Contributed by + + + + Using procmail + + + procmail + + + The procmail utility is an + incredibly powerful application used to filter incoming mail. + It allows users to define rules which can be + matched to incoming mails to perform specific functions or to + reroute mail to alternative mailboxes and/or email addresses. + procmail can be installed using the + mail/procmail port. Once + installed, it can be directly integrated into most + MTAs; consult your MTA + documentation for more information. Alternatively, + procmail can be integrated by adding + the following line to a .forward in the home + directory of the user utilizing + procmail features: + + "|exec /usr/local/bin/procmail || exit 75" + + The following section will display some basic + procmail rules, as well as brief + descriptions on what they do. These rules, and others must be + inserted into a .procmailrc file, which + must reside in the user's home directory. + + The majority of these rules can also be found in the + &man.procmailex.5; manual page. + + Forward all mail from user@example.com to an + external address of goodmail@example2.com: + + :0 +* ^From.*user@example.com +! goodmail@example2.com + + Forward all mails shorter than 1000 bytes to an external + address of goodmail@example2.com: + + :0 +* < 1000 +! goodmail@example2.com + + Send all mail sent to alternate@example.com + into a mailbox called alternate: + + :0 +* ^TOalternate@example.com +alternate + + Send all mail with a subject of Spam to + /dev/null: + + :0 +^Subject:.*Spam +/dev/null + + A useful recipe that parses incoming &os;.org mailing lists + and places each list in its own mailbox: + + :0 +* ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG +{ + LISTNAME=${MATCH} + :0 + * LISTNAME??^\/[^@]+ + FreeBSD-${MATCH} +} + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/mirrors/Makefile b/pl_PL.ISO8859-2/books/handbook/mirrors/Makefile new file mode 100644 index 0000000000..ad5c0e2abe --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/mirrors/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= mirrors/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/mirrors/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/mirrors/chapter.sgml new file mode 100644 index 0000000000..51a8e71664 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/mirrors/chapter.sgml @@ -0,0 +1,3207 @@ + + + + Obtaining FreeBSD + + + CDROM and DVD Publishers + + + Retail Boxed Products + + FreeBSD is available as a boxed product (FreeBSD CDs, + additional software, and printed documentation) from several + retailers: + + + +
+ CompUSA + WWW: +
+ + + +
+ Frys Electronics + WWW: +
+ + + + + + CD and DVD Sets + + FreeBSD CD and DVD sets are available from many online + retailers: + + + +
+ BSD Mall by Daemon News + PO Box 161 + Nauvoo, IL 62354 + USA + Phone: +1 866 273-6255 + Fax: +1 217 453-9956 + Email: sales@bsdmall.com + WWW: +
+ + + +
+ BSD-Systems + Email: info@bsd-systems.co.uk + WWW: +
+ + + +
+ FreeBSD Mall, Inc. + 3623 Sanford Street + Concord, CA 94520-1405 + USA + Phone: +1 925 674-0783 + Fax: +1 925 674-0821 + Email: info@freebsdmall.com + WWW: +
+ + + +
+ Hinner EDV + St. Augustinus-Str. 10 + D-81825 München + Germany + Phone: (089) 428 419 + WWW: +
+ + + +
+ Ikarios + 22-24 rue Voltaire + 92000 Nanterre + France + WWW: +
+ + + +
+ JMC Software + Ireland + Phone: 353 1 6291282 + WWW: +
+ + + +
+ Linux CD Mall + Private Bag MBE N348 + Auckland 1030 + New Zealand + Phone: +64 21 866529 + WWW: +
+ + + +
+ The Linux Emporium + Hilliard House, Lester Way + Wallingford + OX10 9TA + United Kingdom + Phone: +44 1491 837010 + Fax: +44 1491 837016 + WWW: +
+ + + +
+ Linux+ DVD Magazine + Lewartowskiego 6 + Warsaw + 00-190 + Poland + Phone: +48 22 860 18 18 + Email: editors@lpmagazine.org + WWW: +
+ + + +
+ Linux System Labs Australia + 21 Ray Drive + Balwyn North + VIC - 3104 + Australia + Phone: +61 3 9857 5918 + Fax: +61 3 9857 8974 + WWW: +
+ + + +
+ LinuxCenter.Ru + Galernaya Street, 55 + Saint-Petersburg + 190000 + Russia + Phone: +7-812-3125208 + Email: info@linuxcenter.ru + WWW: +
+ + + + + + + Distributors + + If you are a reseller and want to carry FreeBSD CDROM products, + please contact a distributor: + + + +
+ Cylogistics + 809B Cuesta Dr., #2149 + Mountain View, CA 94040 + USA + Phone: +1 650 694-4949 + Fax: +1 650 694-4953 + Email: sales@cylogistics.com + WWW: +
+ + + +
+ Ingram Micro + 1600 E. St. Andrew Place + Santa Ana, CA 92705-4926 + USA + Phone: 1 (800) 456-8000 + WWW: +
+ + + +
+ Kudzu, LLC + 7375 Washington Ave. S. + Edina, MN 55439 + USA + Phone: +1 952 947-0822 + Fax: +1 952 947-0876 + Email: sales@kudzuenterprises.com +
+ + + +
+ LinuxCenter.Ru + Galernaya Street, 55 + Saint-Petersburg + 190000 + Russia + Phone: +7-812-3125208 + Email: info@linuxcenter.ru + WWW: +
+ + + +
+ Navarre Corp + 7400 49th Ave South + New Hope, MN 55428 + USA + Phone: +1 763 535-8333 + Fax: +1 763 535-0341 + WWW: +
+ + + + + + + FTP Sites + + The official sources for FreeBSD are available via anonymous FTP + from a worldwide set of mirror sites. The site + is well + connected and allows a large number of connections to it, but + you are probably better off finding a closer + mirror site (especially if you decide to set up some sort of + mirror site). + + The FreeBSD mirror + sites database is more accurate than the mirror listing in the + Handbook, as it gets its information from the DNS rather than relying on + static lists of hosts. + + Additionally, FreeBSD is available via anonymous FTP from the + following mirror sites. If you choose to obtain FreeBSD via anonymous + FTP, please try to use a site near you. The mirror sites listed as + Primary Mirror Sites typically have the entire FreeBSD archive (all + the currently available versions for each of the architectures) but + you will probably have faster download times from a site that is + in your country or region. The regional sites carry the most recent + versions for the most popular architecture(s) but might not carry + the entire FreeBSD archive. All sites provide access via anonymous + FTP but some sites also provide access via other methods. The access + methods available for each site are provided in parentheses + after the hostname. + + &chap.mirrors.ftp.inc; + + + + Anonymous CVS + + + <anchor id="anoncvs-intro">Introduction + + + CVS + anonymous + + + Anonymous CVS (or, as it is otherwise known, + anoncvs) is a feature provided by the CVS + utilities bundled with FreeBSD for synchronizing with a remote + CVS repository. Among other things, it allows users of FreeBSD + to perform, with no special privileges, read-only CVS operations + against one of the FreeBSD project's official anoncvs servers. + To use it, one simply sets the CVSROOT + environment variable to point at the appropriate anoncvs server, + provides the well-known password anoncvs with the + cvs login command, and then uses the + &man.cvs.1; command to access it like any local + repository. + + + The cvs login command, stores the passwords + that are used for authenticating to the CVS server in a file + called .cvspass in your + HOME directory. If this file does not exist, + you might get an error when trying to use cvs + login for the first time. Just make an empty + .cvspass file, and retry to login. + + + While it can also be said that the CVSup and anoncvs + services both perform essentially the same function, there are + various trade-offs which can influence the user's choice of + synchronization methods. In a nutshell, + CVSup is much more efficient in its + usage of network resources and is by far the most technically + sophisticated of the two, but at a price. To use + CVSup, a special client must first be + installed and configured before any bits can be grabbed, and + then only in the fairly large chunks which + CVSup calls + collections. + + Anoncvs, by contrast, can be used + to examine anything from an individual file to a specific + program (like ls or grep) + by referencing the CVS module name. Of course, + anoncvs is also only good for + read-only operations on the CVS repository, so if it is your + intention to support local development in one repository shared + with the FreeBSD project bits then + CVSup is really your only + option. + + + + <anchor id="anoncvs-usage">Using Anonymous CVS + + Configuring &man.cvs.1; to use an Anonymous CVS repository + is a simple matter of setting the CVSROOT + environment variable to point to one of the FreeBSD project's + anoncvs servers. At the time of this + writing, the following servers are available: + + + + Austria: + :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs + (Use cvs login and enter any + password when prompted.) + + + France: + :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs + (pserver (password anoncvs), ssh (no password)) + + + + Germany: + :pserver:anoncvs@anoncvs.de.FreeBSD.org:/home/ncvs + (Use cvs login and enter the password + anoncvs when prompted.) + + + Germany: + :pserver:anoncvs@anoncvs2.de.FreeBSD.org:/home/ncvs + (rsh, pserver, ssh, ssh/2022) + + + + Japan: + :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs + (Use cvs login and enter the password + anoncvs when prompted.) + + + USA: + freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs + (ssh only - no password) + + SSH HostKey: 1024 a1:e7:46:de:fb:56:ef:05:bc:73:aa:91:09:da:f7:f4 root@sanmateo.ecn.purdue.edu +SSH2 HostKey: 1024 52:02:38:1a:2f:a8:71:d3:f5:83:93:8d:aa:00:6f:65 ssh_host_dsa_key.pub + + + + USA: + anoncvs@anoncvs1.FreeBSD.org:/home/ncvs (ssh only - no + password) + + SSH HostKey: 1024 8b:c4:6f:9a:7e:65:8a:eb:50:50:29:7c:a1:47:03:bc root@ender.liquidneon.com +SSH2 HostKey: 2048 4d:59:19:7b:ea:9b:76:0b:ca:ee:da:26:e2:3a:83:b8 ssh_host_dsa_key.pub + + + + + Since CVS allows one to check out virtually + any version of the FreeBSD sources that ever existed (or, in + some cases, will exist), you need to be + familiar with the revision () flag to + &man.cvs.1; and what some of the permissible values for it in + the FreeBSD Project repository are. + + There are two kinds of tags, revision tags and branch tags. + A revision tag refers to a specific revision. Its meaning stays + the same from day to day. A branch tag, on the other hand, + refers to the latest revision on a given line of development, at + any given time. Because a branch tag does not refer to a + specific revision, it may mean something different tomorrow than + it means today. + + contains revision tags that users + might be interested + in. Again, none of these are valid for the Ports Collection + since the Ports Collection does not have multiple + revisions. + + When you specify a branch tag, you normally receive the + latest versions of the files on that line of development. If + you wish to receive some past version, you can do so by + specifying a date with the flag. + See the &man.cvs.1; manual page for more details. + + + + Examples + + While it really is recommended that you read the manual page + for &man.cvs.1; thoroughly before doing anything, here are some + quick examples which essentially show how to use Anonymous + CVS: + + + Checking Out Something from -CURRENT (&man.ls.1;): + + &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs +&prompt.user; cvs login +At the prompt, enter the password anoncvs. +&prompt.user; cvs co ls + + + + + Using SSH to check out the <filename>src/</filename> + tree: + &prompt.user; cvs -d freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs co src +The authenticity of host 'anoncvs.freebsd.org (128.46.156.46)' can't be established. +DSA key fingerprint is 52:02:38:1a:2f:a8:71:d3:f5:83:93:8d:aa:00:6f:65. +Are you sure you want to continue connecting (yes/no)? yes +Warning: Permanently added 'anoncvs.freebsd.org' (DSA) to the list of known hosts. + + + + Checking Out the Version of &man.ls.1; in the 6-STABLE + Branch: + + &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs +&prompt.user; cvs login +At the prompt, enter the password anoncvs. +&prompt.user; cvs co -rRELENG_6 ls + + + + + Creating a List of Changes (as Unified Diffs) to &man.ls.1; + + &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs +&prompt.user; cvs login +At the prompt, enter the password anoncvs. +&prompt.user; cvs rdiff -u -rRELENG_5_3_0_RELEASE -rRELENG_5_4_0_RELEASE ls + + + + + Finding Out What Other Module Names Can Be Used: + + &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs +&prompt.user; cvs login +At the prompt, enter the password anoncvs. +&prompt.user; cvs co modules +&prompt.user; more modules/modules + + + + + + Other Resources + + The following additional resources may be helpful in learning + CVS: + + + + CVS Tutorial from Cal Poly. + + + + CVS Home, + the CVS development and support community. + + + + CVSweb is + the FreeBSD Project web interface for CVS. + + + + + + + + Using CTM + + + CTM + + + CTM is a method for keeping a + remote directory tree in sync with a central one. It has been + developed for usage with FreeBSD's source trees, though other + people may find it useful for other purposes as time goes by. + Little, if any, documentation currently exists at this time on the + process of creating deltas, so contact the &a.ctm-users.name; mailing list for more + information and if you wish to use CTM + for other things. + + + Why Should I Use <application>CTM</application>? + + CTM will give you a local copy of + the FreeBSD source trees. There are a number of + flavors of the tree available. Whether you wish + to track the entire CVS tree or just one of the branches, + CTM can provide you the information. + If you are an active developer on FreeBSD, but have lousy or + non-existent TCP/IP connectivity, or simply wish to have the + changes automatically sent to you, + CTM was made for you. You will need + to obtain up to three deltas per day for the most active + branches. However, you should consider having them sent by + automatic email. The sizes of the updates are always kept as + small as possible. This is typically less than 5K, with an + occasional (one in ten) being 10-50K and every now and then a + large 100K+ or more coming around. + + You will also need to make yourself aware of the various + caveats related to working directly from the development sources + rather than a pre-packaged release. This is particularly true + if you choose the current sources. It is + recommended that you read Staying + current with FreeBSD. + + + + What Do I Need to Use + <application>CTM</application>? + + You will need two things: The CTM + program, and the initial deltas to feed it (to get up to + current levels). + + The CTM program has been part of + FreeBSD ever since version 2.0 was released, and lives in + /usr/src/usr.sbin/ctm if you have a copy + of the source available. + + The deltas you feed + CTM can be had two ways, FTP or + email. If you have general FTP access to the Internet then the + following FTP sites support access to + CTM: + + + + or see section mirrors. + + FTP the relevant directory and fetch the + README file, starting from there. + + If you wish to get your deltas via email: + + Subscribe to one of the + CTM distribution lists. + &a.ctm-cvs-cur.name; supports the entire CVS tree. + &a.ctm-src-cur.name; supports the head of the development + branch. &a.ctm-src-4.name; supports the 4.X release + branch, etc.. (If you do not know how to subscribe yourself + to a list, click on the list name above or go to + &a.mailman.lists.link; and click on the list that you + wish to subscribe to. The list page should contain all of + the necessary subscription instructions.) + + When you begin receiving your CTM + updates in the mail, you may use the + ctm_rmail program to unpack and apply them. + You can actually use the ctm_rmail program + directly from a entry in /etc/aliases if + you want to have the process run in a fully automated fashion. + Check the ctm_rmail manual page for more + details. + + + No matter what method you use to get the + CTM deltas, you should subscribe to + the &a.ctm-announce.name; mailing list. In + the future, this will be the only place where announcements + concerning the operations of the + CTM system will be posted. Click + on the list name above and follow the instructions + to subscribe to the + list. + + + + + Using <application>CTM</application> for the First + Time + + Before you can start using CTM + deltas, you will need to get to a starting point for the deltas + produced subsequently to it. + + First you should determine what you already have. Everyone + can start from an empty directory. You must use + an initial Empty delta to start off your + CTM supported tree. At some point it + is intended that one of these started deltas be + distributed on the CD for your convenience, however, this does + not currently happen. + + Since the trees are many tens of megabytes, you should + prefer to start from something already at hand. If you have a + -RELEASE CD, you can copy or extract an initial source from it. + This will save a significant transfer of data. + + You can recognize these starter deltas by the + X appended to the number + (src-cur.3210XEmpty.gz for instance). The + designation following the X corresponds to + the origin of your initial seed. + Empty is an empty directory. As a rule a + base transition from Empty is produced + every 100 deltas. By the way, they are large! 70 to 80 + Megabytes of gzip'd data is common for the + XEmpty deltas. + + Once you have picked a base delta to start from, you will also + need all deltas with higher numbers following it. + + + + Using <application>CTM</application> in Your Daily + Life + + To apply the deltas, simply say: + + &prompt.root; cd /where/ever/you/want/the/stuff +&prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.* + + CTM understands deltas which have + been put through gzip, so you do not need to + gunzip them first, this saves disk space. + + Unless it feels very secure about the entire process, + CTM will not touch your tree. To + verify a delta you can also use the flag and + CTM will not actually touch your + tree; it will merely verify the integrity of the delta and see + if it would apply cleanly to your current tree. + + There are other options to CTM + as well, see the manual pages or look in the sources for more + information. + + That is really all there is to it. Every time you get a new + delta, just run it through CTM to + keep your sources up to date. + + Do not remove the deltas if they are hard to download again. + You just might want to keep them around in case something bad + happens. Even if you only have floppy disks, consider using + fdwrite to make a copy. + + + + Keeping Your Local Changes + + As a developer one would like to experiment with and change + files in the source tree. CTM + supports local modifications in a limited way: before checking + for the presence of a file foo, it first + looks for foo.ctm. If this file exists, + CTM will operate on it instead of + foo. + + This behavior gives us a simple way to maintain local + changes: simply copy the files you plan to modify to the + corresponding file names with a .ctm + suffix. Then you can freely hack the code, while CTM keeps the + .ctm file up-to-date. + + + + Other Interesting <application>CTM</application> Options + + + Finding Out Exactly What Would Be Touched by an + Update + + You can determine the list of changes that + CTM will make on your source + repository using the option to + CTM. + + This is useful if you would like to keep logs of the + changes, pre- or post- process the modified files in any + manner, or just are feeling a tad paranoid. + + + + Making Backups Before Updating + + Sometimes you may want to backup all the files that would + be changed by a CTM update. + + Specifying the option + causes CTM to backup all files that + would be touched by a given CTM + delta to backup-file. + + + + Restricting the Files Touched by an Update + + Sometimes you would be interested in restricting the scope + of a given CTM update, or may be + interested in extracting just a few files from a sequence of + deltas. + + You can control the list of files that + CTM would operate on by specifying + filtering regular expressions using the + and options. + + For example, to extract an up-to-date copy of + lib/libc/Makefile from your collection of + saved CTM deltas, run the commands: + + &prompt.root; cd /where/ever/you/want/to/extract/it/ +&prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* + + For every file specified in a + CTM delta, the + and options are applied in the order given + on the command line. The file is processed by + CTM only if it is marked as + eligible after all the and + options are applied to it. + + + + + Future Plans for <application>CTM</application> + + Tons of them: + + + + Use some kind of authentication into the CTM system, so + as to allow detection of spoofed CTM updates. + + + + Clean up the options to CTM, + they became confusing and counter intuitive. + + + + + + Miscellaneous Stuff + + There is a sequence of deltas for the + ports collection too, but interest has not + been all that high yet. + + + + CTM Mirrors + + CTM/FreeBSD is available via anonymous + FTP from the following mirror sites. If you choose to obtain CTM via + anonymous FTP, please try to use a site near you. + + In case of problems, please contact the &a.ctm-users.name; + mailing list. + + + + California, Bay Area, official source + + + + + + + + + + + + South Africa, backup server for old deltas + + + + + + + + + + + + Taiwan/R.O.C. + + + + + + + + + + + + + + + + + + + + If you did not find a mirror near to you or the mirror is + incomplete, try to use a search engine such as + alltheweb. + + + + Using CVSup + + + Introduction + + CVSup is a software package for + distributing and updating source trees from a master CVS + repository on a remote server host. The FreeBSD sources are + maintained in a CVS repository on a central development machine + in California. With CVSup, FreeBSD + users can easily keep their own source trees up to date. + + CVSup uses the so-called + pull model of updating. Under the pull + model, each client asks the server for updates, if and when they + are wanted. The server waits passively for update requests from + its clients. Thus all updates are instigated by the client. + The server never sends unsolicited updates. Users must either + run the CVSup client manually to get + an update, or they must set up a cron job to + run it automatically on a regular basis. + + The term CVSup, capitalized just + so, refers to the entire software package. Its main components + are the client cvsup which runs on each + user's machine, and the server cvsupd which + runs at each of the FreeBSD mirror sites. + + As you read the FreeBSD documentation and mailing lists, you + may see references to sup. + Sup was the predecessor of + CVSup, and it served a similar + purpose. CVSup is used much in the + same way as sup and, in fact, uses configuration files which are + backward-compatible with sup's. + Sup is no longer used in the FreeBSD + project, because CVSup is both faster + and more flexible. + + + + Installation + + The easiest way to install CVSup + is to use the precompiled net/cvsup package + from the FreeBSD packages collection. + If you prefer to build CVSup from + source, you can use the net/cvsup + port instead. But be forewarned: the + net/cvsup port depends on the Modula-3 + system, which takes a substantial amount of time and + disk space to download and build. + + + If you are going to be using + CVSup on a machine which will not have + &xfree86; or &xorg; installed, such as a server, be + sure to use the port which does not include the + CVSup GUI, + net/cvsup-without-gui. + + + + + CVSup Configuration + + CVSup's operation is controlled + by a configuration file called the supfile. + There are some sample supfiles in the + directory /usr/share/examples/cvsup/. + + The information in a supfile answers + the following questions for CVSup: + + + + Which files do you + want to receive? + + + + Which versions of them + do you want? + + + + Where do you want to + get them from? + + + + Where do you want to + put them on your own machine? + + + + Where do you want to + put your status files? + + + + In the following sections, we will construct a typical + supfile by answering each of these + questions in turn. First, we describe the overall structure of + a supfile. + + A supfile is a text file. Comments + begin with # and extend to the end of the + line. Lines that are blank and lines that contain only + comments are ignored. + + Each remaining line describes a set of files that the user + wishes to receive. The line begins with the name of a + collection, a logical grouping of files defined by + the server. The name of the collection tells the server which + files you want. After the collection name come zero or more + fields, separated by white space. These fields answer the + questions listed above. There are two types of fields: flag + fields and value fields. A flag field consists of a keyword + standing alone, e.g., delete or + compress. A value field also begins with a + keyword, but the keyword is followed without intervening white + space by = and a second word. For example, + release=cvs is a value field. + + A supfile typically specifies more than + one collection to receive. One way to structure a + supfile is to specify all of the relevant + fields explicitly for each collection. However, that tends to + make the supfile lines quite long, and it + is inconvenient because most fields are the same for all of the + collections in a supfile. + CVSup provides a defaulting mechanism + to avoid these problems. Lines beginning with the special + pseudo-collection name *default can be used + to set flags and values which will be used as defaults for the + subsequent collections in the supfile. A + default value can be overridden for an individual collection, by + specifying a different value with the collection itself. + Defaults can also be changed or augmented in mid-supfile by + additional *default lines. + + With this background, we will now proceed to construct a + supfile for receiving and updating the main + source tree of FreeBSD-CURRENT. + + + + Which files do you want + to receive? + + The files available via CVSup + are organized into named groups called + collections. The collections that are + available are described in the following section. In this + example, we + wish to receive the entire main source tree for the FreeBSD + system. There is a single large collection + src-all which will give us all of that. + As a first step toward constructing our + supfile, we + simply list the collections, one per line (in this case, + only one line): + + src-all + + + + Which version(s) of them + do you want? + + With CVSup, you can receive + virtually any version of the sources that ever existed. + That is possible because the + cvsupd server works directly from + the CVS repository, which contains all of the versions. You + specify which one of them you want using the + tag= and value + fields. + + + Be very careful to specify any tag= + fields correctly. Some tags are valid only for certain + collections of files. If you specify an incorrect or + misspelled tag, CVSup + will delete files which you probably + do not want deleted. In particular, use only + tag=. for the + ports-* collections. + + + The tag= field names a symbolic tag + in the repository. There are two kinds of tags, revision + tags and branch tags. A revision tag refers to a specific + revision. Its meaning stays the same from day to day. A + branch tag, on the other hand, refers to the latest revision + on a given line of development, at any given time. Because + a branch tag does not refer to a specific revision, it may + mean something different tomorrow than it means + today. + + contains branch tags that + users might be interested in. When specifying a tag in + CVSup's configuration file, it + must be preceded with tag= + (RELENG_4 will become + tag=RELENG_4). + Keep in mind that only the tag=. is + relevant for the Ports Collection. + + + Be very careful to type the tag name exactly as shown. + CVSup cannot distinguish + between valid and invalid tags. If you misspell the tag, + CVSup will behave as though you + had specified a valid tag which happens to refer to no + files at all. It will delete your existing sources in + that case. + + + When you specify a branch tag, you normally receive the + latest versions of the files on that line of development. + If you wish to receive some past version, you can do so by + specifying a date with the value + field. The &man.cvsup.1; manual page explains how to do + that. + + For our example, we wish to receive FreeBSD-CURRENT. We + add this line at the beginning of our + supfile: + + *default tag=. + + There is an important special case that comes into play + if you specify neither a tag= field nor a + date= field. In that case, you receive + the actual RCS files directly from the server's CVS + repository, rather than receiving a particular version. + Developers generally prefer this mode of operation. By + maintaining a copy of the repository itself on their + systems, they gain the ability to browse the revision + histories and examine past versions of files. This gain is + achieved at a large cost in terms of disk space, + however. + + + + Where do you want to get + them from? + + We use the host= field to tell + cvsup where to obtain its updates. Any + of the CVSup mirror + sites will do, though you should try to select one + that is close to you in cyberspace. In this example we will + use a fictional FreeBSD distribution site, + cvsup99.FreeBSD.org: + + *default host=cvsup99.FreeBSD.org + + You will need to change the host to one that actually + exists before running CVSup. + On any particular run of + cvsup, you can override the host setting + on the command line, with . + + + + Where do you want to put + them on your own machine? + + The prefix= field tells + cvsup where to put the files it receives. + In this example, we will put the source files directly into + our main source tree, /usr/src. The + src directory is already implicit in + the collections we have chosen to receive, so this is the + correct specification: + + *default prefix=/usr + + + + Where should + cvsup maintain its status files? + + The CVSup client maintains + certain status files in what + is called the base directory. These files + help CVSup to work more + efficiently, by keeping track of which updates you have + already received. We will use the standard base directory, + /var/db: + + *default base=/var/db + + If your base directory does not already exist, now would + be a good time to create it. The cvsup + client will refuse to run if the base directory does not + exist. + + + + Miscellaneous supfile + settings: + + There is one more line of boiler plate that normally + needs to be present in the + supfile: + + *default release=cvs delete use-rel-suffix compress + + release=cvs indicates that the server + should get its information out of the main FreeBSD CVS + repository. This is virtually always the case, but there + are other possibilities which are beyond the scope of this + discussion. + + delete gives + CVSup permission to delete files. + You should always specify this, so that + CVSup can keep your source tree + fully up-to-date. CVSup is + careful to delete only those files for which it is + responsible. Any extra files you happen to have will be + left strictly alone. + + use-rel-suffix is ... arcane. If you + really want to know about it, see the &man.cvsup.1; manual + page. Otherwise, just specify it and do not worry about + it. + + compress enables the use of + gzip-style compression on the communication channel. If + your network link is T1 speed or faster, you probably should + not use compression. Otherwise, it helps + substantially. + + + + Putting it all together: + + Here is the entire supfile for our + example: + + *default tag=. +*default host=cvsup99.FreeBSD.org +*default prefix=/usr +*default base=/var/db +*default release=cvs delete use-rel-suffix compress + +src-all + + + + The <filename>refuse</filename> File + + As mentioned above, CVSup uses + a pull method. Basically, this means that + you connect to the CVSup server, and + it says, Here is what you can download from + me..., and your client responds OK, I will take + this, this, this, and this. In the default + configuration, the CVSup client will + take every file associated with the collection and tag you + chose in the configuration file. However, this is not always + what you want, especially if you are synching the doc, ports, or + www trees — most people cannot read four or five + languages, and therefore they do not need to download the + language-specific files. If you are + CVSuping the Ports Collection, you + can get around this by specifying each collection individually + (e.g., ports-astrology, + ports-biology, etc instead of simply + saying ports-all). However, since the doc + and www trees do not have language-specific collections, you + must use one of CVSup's many nifty + features: the refuse file. + + The refuse file essentially tells + CVSup that it should not take every + single file from a collection; in other words, it tells the + client to refuse certain files from the + server. The refuse file can be found (or, if you do not yet + have one, should be placed) in + base/sup/. + base is defined in your supfile; + our defined base is + /var/db, + which means that by default the refuse file is + /var/db/sup/refuse. + + The refuse file has a very simple format; it simply + contains the names of files or directories that you do not wish + to download. For example, if you cannot speak any languages other + than English and some German, and you do not feel the need to read + the German translation of documentation, you can put the following in your + refuse file: + + doc/bn_* +doc/da_* +doc/de_* +doc/el_* +doc/es_* +doc/fr_* +doc/it_* +doc/ja_* +doc/nl_* +doc/no_* +doc/pl_* +doc/pt_* +doc/ru_* +doc/sr_* +doc/tr_* +doc/zh_* + + and so forth for the other languages (you can find the + full list by browsing the FreeBSD + CVS repository). + + With this very useful feature, those users who are on + slow links or pay by the minute for their Internet connection + will be able to save valuable time as they will no longer need + to download files that they will never use. For more + information on refuse files and other neat + features of CVSup, please view its + manual page. + + + + + Running <application>CVSup</application> + + You are now ready to try an update. The command line for + doing this is quite simple: + + &prompt.root; cvsup supfile + + where supfile + is of course the name of the supfile you have just created. + Assuming you are running under X11, cvsup + will display a GUI window with some buttons to do the usual + things. Press the go button, and watch it + run. + + Since you are updating your actual + /usr/src tree in this example, you will + need to run the program as root so that + cvsup has the permissions it needs to update + your files. Having just created your configuration file, and + having never used this program before, that might + understandably make you nervous. There is an easy way to do a + trial run without touching your precious files. Just create an + empty directory somewhere convenient, and name it as an extra + argument on the command line: + + &prompt.root; mkdir /var/tmp/dest +&prompt.root; cvsup supfile /var/tmp/dest + + The directory you specify will be used as the destination + directory for all file updates. + CVSup will examine your usual files + in /usr/src, but it will not modify or + delete any of them. Any file updates will instead land in + /var/tmp/dest/usr/src. + CVSup will also leave its base + directory status files untouched when run this way. The new + versions of those files will be written into the specified + directory. As long as you have read access to + /usr/src, you do not even need to be + root to perform this kind of trial run. + + If you are not running X11 or if you just do not like GUIs, + you should add a couple of options to the command line when you + run cvsup: + + &prompt.root; cvsup -g -L 2 supfile + + The tells + CVSup not to use its GUI. This is + automatic if you are not running X11, but otherwise you have to + specify it. + + The tells + CVSup to print out the + details of all the file updates it is doing. There are three + levels of verbosity, from to + . The default is 0, which means total + silence except for error messages. + + There are plenty of other options available. For a brief + list of them, type cvsup -H. For more + detailed descriptions, see the manual page. + + Once you are satisfied with the way updates are working, you + can arrange for regular runs of CVSup + using &man.cron.8;. + Obviously, you should not let CVSup + use its GUI when running it from &man.cron.8;. + + + + <application>CVSup</application> File Collections + + The file collections available via + CVSup are organized hierarchically. + There are a few large collections, and they are divided into + smaller sub-collections. Receiving a large collection is + equivalent to receiving each of its sub-collections. The + hierarchical relationships among collections are reflected by + the use of indentation in the list below. + + The most commonly used collections are + src-all, and + ports-all. The other collections are used + only by small groups of people for specialized purposes, and + some mirror sites may not carry all of them. + + + + cvs-all release=cvs + + + The main FreeBSD CVS repository, including the + cryptography code. + + + + distrib release=cvs + + + Files related to the distribution and mirroring + of FreeBSD. + + + + + doc-all release=cvs + + Sources for the FreeBSD Handbook and other + documentation. This does not include files for + the FreeBSD web site. + + + + + ports-all release=cvs + + + The FreeBSD Ports Collection. + + + If you do not want to update the whole of + ports-all (the whole ports tree), + but use one of the subcollections listed below, + make sure that you always update + the ports-base subcollection! + Whenever something changes in the ports build + infrastructure represented by + ports-base, it is virtually certain + that those changes will be used by real + ports real soon. Thus, if you only update the + real ports and they use some of the new + features, there is a very high chance that their build + will fail with some mysterious error message. The + very first thing to do in this + case is to make sure that your + ports-base subcollection is up to + date. + + + + If you are going to be building your own local + copy of ports/INDEX, you + must accept + ports-all (the whole ports tree). + Building ports/INDEX with + a partial tree is not supported. See the + + FAQ. + + + + + ports-accessibility + release=cvs + + + Software to help disabled users. + + + + + ports-arabic + release=cvs + + + Arabic language support. + + + + + ports-archivers + release=cvs + + + Archiving tools. + + + + + ports-astro + release=cvs + + + Astronomical ports. + + + + + ports-audio + release=cvs + + + Sound support. + + + + + ports-base + release=cvs + + + The Ports Collection build infrastructure - + various files located in the + Mk/ and + Tools/ subdirectories of + /usr/ports. + + + Please see the important + warning above: you should + always update this + subcollection, whenever you update any part of + the FreeBSD Ports Collection! + + + + + + ports-benchmarks + release=cvs + + + Benchmarks. + + + + + ports-biology + release=cvs + + + Biology. + + + + + ports-cad + release=cvs + + + Computer aided design tools. + + + + + ports-chinese + release=cvs + + + Chinese language support. + + + + + ports-comms + release=cvs + + + Communication software. + + + + + ports-converters + release=cvs + + + character code converters. + + + + + ports-databases + release=cvs + + + Databases. + + + + + ports-deskutils + release=cvs + + + Things that used to be on the desktop + before computers were invented. + + + + + ports-devel + release=cvs + + + Development utilities. + + + + + ports-dns + release=cvs + + + DNS related software. + + + + + ports-editors + release=cvs + + + Editors. + + + + + ports-emulators + release=cvs + + + Emulators for other operating + systems. + + + + + ports-finance + release=cvs + + + Monetary, financial and related applications. + + + + + ports-ftp + release=cvs + + + FTP client and server utilities. + + + + + ports-games + release=cvs + + + Games. + + + + + ports-german + release=cvs + + + German language support. + + + + + ports-graphics + release=cvs + + + Graphics utilities. + + + + + ports-hebrew + release=cvs + + + Hebrew language support. + + + + + ports-hungarian + release=cvs + + + Hungarian language support. + + + + + ports-irc + release=cvs + + + Internet Relay Chat utilities. + + + + + ports-japanese + release=cvs + + + Japanese language support. + + + + + ports-java + release=cvs + + + &java; utilities. + + + + + ports-korean + release=cvs + + + Korean language support. + + + + + ports-lang + release=cvs + + + Programming languages. + + + + + ports-mail + release=cvs + + + Mail software. + + + + + ports-math + release=cvs + + + Numerical computation software. + + + + + ports-mbone + release=cvs + + + MBone applications. + + + + + ports-misc + release=cvs + + + Miscellaneous utilities. + + + + + ports-multimedia + release=cvs + + + Multimedia software. + + + + + ports-net + release=cvs + + + Networking software. + + + + + ports-net-im + release=cvs + + + Instant messaging software. + + + + + ports-net-mgmt + release=cvs + + + Network management software. + + + + + ports-net-p2p + release=cvs + + + Peer to peer networking. + + + + + ports-news + release=cvs + + + USENET news software. + + + + + ports-palm + release=cvs + + + Software support for Palm + series. + + + + + ports-polish + release=cvs + + + Polish language support. + + + + + ports-portuguese + release=cvs + + + Portuguese language support. + + + + + ports-print + release=cvs + + + Printing software. + + + + + ports-russian + release=cvs + + + Russian language support. + + + + + ports-science + release=cvs + + + Science. + + + + + ports-security + release=cvs + + + Security utilities. + + + + + ports-shells + release=cvs + + + Command line shells. + + + + + ports-sysutils + release=cvs + + + System utilities. + + + + + ports-textproc + release=cvs + + + text processing utilities (does not + include desktop publishing). + + + + + ports-ukrainian + release=cvs + + + Ukrainian language support. + + + + + ports-vietnamese + release=cvs + + + Vietnamese language support. + + + + + ports-www + release=cvs + + + Software related to the World Wide + Web. + + + + + ports-x11 + release=cvs + + + Ports to support the X window + system. + + + + + ports-x11-clocks + release=cvs + + + X11 clocks. + + + + + ports-x11-fm + release=cvs + + + X11 file managers. + + + + + ports-x11-fonts + release=cvs + + + X11 fonts and font utilities. + + + + + ports-x11-toolkits + release=cvs + + + X11 toolkits. + + + + + ports-x11-servers + release=cvs + + + X11 servers. + + + + + ports-x11-themes + release=cvs + + + X11 themes. + + + + + ports-x11-wm + release=cvs + + + X11 window managers. + + + + + + + + projects-all release=cvs + + Sources for the FreeBSD projects repository. + + + + + src-all release=cvs + + + The main FreeBSD sources, including the + cryptography code. + + + + src-base + release=cvs + + + Miscellaneous files at the top of + /usr/src. + + + + + src-bin + release=cvs + + + User utilities that may be needed in + single-user mode + (/usr/src/bin). + + + + + src-contrib + release=cvs + + + Utilities and libraries from outside the + FreeBSD project, used relatively unmodified + (/usr/src/contrib). + + + + + src-crypto release=cvs + + + Cryptography utilities and libraries from + outside the FreeBSD project, used relatively + unmodified + (/usr/src/crypto). + + + + + src-eBones release=cvs + + + Kerberos and DES + (/usr/src/eBones). Not + used in current releases of FreeBSD. + + + + + src-etc + release=cvs + + + System configuration files + (/usr/src/etc). + + + + + src-games + release=cvs + + + Games + (/usr/src/games). + + + + + src-gnu + release=cvs + + + Utilities covered by the GNU Public + License (/usr/src/gnu). + + + + + src-include + release=cvs + + + Header files + (/usr/src/include). + + + + + src-kerberos5 + release=cvs + + + Kerberos5 security package + (/usr/src/kerberos5). + + + + + src-kerberosIV + release=cvs + + + KerberosIV security package + (/usr/src/kerberosIV). + + + + + src-lib + release=cvs + + + Libraries + (/usr/src/lib). + + + + + src-libexec + release=cvs + + + System programs normally executed by other + programs + (/usr/src/libexec). + + + + + src-release + release=cvs + + + Files required to produce a FreeBSD + release + (/usr/src/release). + + + + + src-sbin release=cvs + + + System utilities for single-user mode + (/usr/src/sbin). + + + + + src-secure + release=cvs + + + Cryptographic libraries and commands + (/usr/src/secure). + + + + + src-share + release=cvs + + + Files that can be shared across multiple + systems + (/usr/src/share). + + + + + src-sys + release=cvs + + + The kernel + (/usr/src/sys). + + + + + src-sys-crypto + release=cvs + + + Kernel cryptography code + (/usr/src/sys/crypto). + + + + + src-tools + release=cvs + + + Various tools for the maintenance of + FreeBSD + (/usr/src/tools). + + + + + src-usrbin + release=cvs + + + User utilities + (/usr/src/usr.bin). + + + + + src-usrsbin + release=cvs + + + System utilities + (/usr/src/usr.sbin). + + + + + + + + www release=cvs + + + The sources for the FreeBSD WWW site. + + + + + + + + distrib release=self + + + The CVSup server's own + configuration files. Used by CVSup + mirror sites. + + + + + gnats release=current + + + The GNATS bug-tracking database. + + + + + mail-archive release=current + + + FreeBSD mailing list archive. + + + + + www release=current + + + The pre-processed FreeBSD WWW site files (not the + source files). Used by WWW mirror sites. + + + + + + + For More Information + + For the CVSup FAQ and other + information about CVSup, see + The + CVSup Home Page. + + Most FreeBSD-related discussion of + CVSup takes place on the + &a.hackers;. New versions of the software are announced there, + as well as on the &a.announce;. + + Questions and bug reports should be addressed to the author + of the program at cvsup-bugs@polstra.com. + + + + CVSup Sites + + CVSup servers for FreeBSD are running + at the following sites: + + &chap.mirrors.cvsup.inc; + + + + + Using Portsnap + + + Introduction + + Portsnap is a system for securely + distributing the &os; ports tree. Approximately once an hour, + a snapshot of the ports tree is generated, + repackaged, and cryptographically signed. The resulting files + are then distributed via HTTP. + + Like CVSup, + Portsnap uses a + pull model of updating: The packaged and + signed ports trees are placed on a web server which waits + passively for clients to request files. Users must either run + &man.portsnap.8; manually to download updates + or set up a &man.cron.8; job to download updates + automatically on a regular basis. + + For technical reasons, Portsnap + does not update the live ports tree in + /usr/ports/ directly; instead, it works + via a compressed copy of the ports tree stored in + /var/db/portsnap/ by default. This + compressed copy is then used to update the live ports tree. + + + If Portsnap is installed from + the &os; Ports Collection, then the default location for its + compressed snapshot will be /usr/local/portsnap/ + instead of /var/db/portsnap/. + + + + + Installation + + On &os; 6.0 and more recent versions, + Portsnap is contained in the &os; + base system. On older versions of &os;, it can be installed + using the sysutils/portsnap + port. + + + + Portsnap Configuration + + Portsnap's operation is controlled + by the /etc/portsnap.conf configuration + file. For most users, the default configuration file will + suffice; for more details, consult the &man.portsnap.conf.5; + manual page. + + + If Portsnap is installed from + the &os; Ports Collection, it will use the configuration file + /usr/local/etc/portsnap.conf instead of + /etc/portsnap.conf. This configuration + file is not created when the port is installed, but a sample + configuration file is distributed; to copy it into place, run + the following command: + + &prompt.root; cd /usr/local/etc && cp portsnap.conf.sample portsnap.conf + + + + + Running <application>Portsnap</application> for the First + Time + + The first time &man.portsnap.8; is run, + it will need to download a compressed snapshot of the entire + ports tree into /var/db/portsnap/ (or + /usr/local/portsnap/ if + Portsnap was installed from the + Ports Collection). For the beginning of 2006 this is approximately a 41 MB + download. + + &prompt.root; portsnap fetch + + Once the compressed snapshot has been downloaded, a + live copy of the ports tree can be extracted into + /usr/ports/. This is necessary even if a + ports tree has already been created in that directory (e.g., by + using CVSup), since it establishes a + baseline from which portsnap can + determine which parts of the ports tree need to be updated + later. + + &prompt.root; portsnap extract + + + In the default installation + /usr/ports is not + created. If you run &os; 6.0-RELEASE, it should be created before + portsnap is used. On more recent + versions of &os; or Portsnap, + this operation will be done automatically at first use + of the portsnap command. + + + + + Updating the Ports Tree + + After an initial compressed snapshot of the ports tree has + been downloaded and extracted into /usr/ports/, + updating the ports tree consists of two steps: + fetching updates to the compressed + snapshot, and using them to update the + live ports tree. These two steps can be specified to + portsnap as a single command: + + &prompt.root; portsnap fetch update + + + Some older versions of portsnap + do not support this syntax; if it fails, try instead the + following: + + &prompt.root; portsnap fetch +&prompt.root; portsnap update + + + + + Running Portsnap from cron + + In order to avoid problems with flash crowds + accessing the Portsnap servers, + portsnap fetch will not run from + a &man.cron.8; job. Instead, a special + portsnap cron command exists, which + waits for a random duration up to 3600 seconds before fetching + updates. + + In addition, it is strongly recommended that + portsnap update not be run from a + cron job, since it is liable to cause + major problems if it happens to run at the same time as a port + is being built or installed. However, it is safe to update + the ports' INDEX files, and this can be done by passing the + flag to + portsnap. (Obviously, if + portsnap -I update is run from + cron, then it will be necessary to run + portsnap update without the + flag at a later time in order to update the rest of the tree.) + + Adding the following line to /etc/crontab + will cause portsnap to update its + compressed snapshot and the INDEX files in + /usr/ports/, and will send an email if any + installed ports are out of date: + + 0 3 * * * root portsnap -I cron update && pkg_version -vIL= + + + If the system clock is not set to the local time zone, + please replace 3 with a random + value between 0 and 23, in order to spread the load on the + Portsnap servers more evenly. + + + Some older versions of portsnap + do not support listing multiple commands (e.g., cron update) + in the same invocation of portsnap. If + the line above fails, try replacing + portsnap -I cron update with + portsnap cron && portsnap -I update. + + + + + + CVS Tags + + When obtaining or updating sources using + cvs or + CVSup, a revision tag must be specified. + A revision tag refers to either a particular line of &os; + development, or a specific point in time. The first type are called + branch tags, and the second type are called + release tags. + + + Branch Tags + + All of these, with the exception of HEAD (which + is always a valid tag), only apply to the src/ + tree. The ports/, doc/, and + www/ trees are not branched. + + + + HEAD + + + Symbolic name for the main line, or FreeBSD-CURRENT. + Also the default when no revision is specified. + + In CVSup, this tag is represented + by a . (not punctuation, but a literal + . character). + + + In CVS, this is the default when no revision tag is + specified. It is usually not + a good idea to checkout or update to CURRENT sources + on a STABLE machine, unless that is your intent. + + + + + + RELENG_6 + + + The line of development for FreeBSD-6.X, also known + as FreeBSD 6-STABLE + + + + + RELENG_6_1 + + + The release branch for FreeBSD-6.1, used only for + security advisories and other critical fixes. + + + + + RELENG_6_0 + + + The release branch for FreeBSD-6.0, used only for + security advisories and other critical fixes. + + + + + RELENG_5 + + + The line of development for FreeBSD-5.X, also known + as FreeBSD 5-STABLE. + + + + + RELENG_5_5 + + + The release branch for FreeBSD-5.5, used only + for security advisories and other critical fixes. + + + + + RELENG_5_4 + + + The release branch for FreeBSD-5.4, used only + for security advisories and other critical fixes. + + + + + RELENG_5_3 + + + The release branch for FreeBSD-5.3, used only + for security advisories and other critical fixes. + + + + + RELENG_5_2 + + + The release branch for FreeBSD-5.2 and FreeBSD-5.2.1, used only + for security advisories and other critical fixes. + + + + + RELENG_5_1 + + + The release branch for FreeBSD-5.1, used only + for security advisories and other critical fixes. + + + + + RELENG_5_0 + + + The release branch for FreeBSD-5.0, used only + for security advisories and other critical fixes. + + + + + RELENG_4 + + + The line of development for FreeBSD-4.X, also known + as FreeBSD 4-STABLE. + + + + + RELENG_4_11 + + + The release branch for FreeBSD-4.11, used only + for security advisories and other critical fixes. + + + + + RELENG_4_10 + + + The release branch for FreeBSD-4.10, used only + for security advisories and other critical fixes. + + + + + RELENG_4_9 + + + The release branch for FreeBSD-4.9, used only + for security advisories and other critical fixes. + + + + + RELENG_4_8 + + + The release branch for FreeBSD-4.8, used only + for security advisories and other critical fixes. + + + + + RELENG_4_7 + + + The release branch for FreeBSD-4.7, used only + for security advisories and other critical fixes. + + + + + RELENG_4_6 + + + The release branch for FreeBSD-4.6 and FreeBSD-4.6.2, + used only for security advisories and other + critical fixes. + + + + + RELENG_4_5 + + + The release branch for FreeBSD-4.5, used only + for security advisories and other critical fixes. + + + + + RELENG_4_4 + + + The release branch for FreeBSD-4.4, used only + for security advisories and other critical fixes. + + + + + RELENG_4_3 + + + The release branch for FreeBSD-4.3, used only + for security advisories and other critical fixes. + + + + + RELENG_3 + + + The line of development for FreeBSD-3.X, also known + as 3.X-STABLE. + + + + + RELENG_2_2 + + + The line of development for FreeBSD-2.2.X, also known + as 2.2-STABLE. This branch is mostly obsolete. + + + + + + + Release Tags + + These tags refer to a specific point in time when a particular + version of &os; was released. The release engineering process is + documented in more detail by the + Release Engineering + Information and + Release + Process documents. + The src tree uses tag names that + start with RELENG_ tags. + The ports and + doc trees use tags whose names + begin with RELEASE tags. + Finally, the www tree is not + tagged with any special name for releases. + + + + RELENG_6_1_0_RELEASE + + + FreeBSD 6.1 + + + + + RELENG_6_0_0_RELEASE + + + FreeBSD 6.0 + + + + + RELENG_5_5_0_RELEASE + + + FreeBSD 5.5 + + + + + RELENG_5_4_0_RELEASE + + + FreeBSD 5.4 + + + + + RELENG_4_11_0_RELEASE + + + FreeBSD 4.11 + + + + + RELENG_5_3_0_RELEASE + + + FreeBSD 5.3 + + + + + RELENG_4_10_0_RELEASE + + + FreeBSD 4.10 + + + + + RELENG_5_2_1_RELEASE + + + FreeBSD 5.2.1 + + + + + RELENG_5_2_0_RELEASE + + + FreeBSD 5.2 + + + + + RELENG_4_9_0_RELEASE + + + FreeBSD 4.9 + + + + + RELENG_5_1_0_RELEASE + + + FreeBSD 5.1 + + + + + RELENG_4_8_0_RELEASE + + + FreeBSD 4.8 + + + + + RELENG_5_0_0_RELEASE + + + FreeBSD 5.0 + + + + + RELENG_4_7_0_RELEASE + + + FreeBSD 4.7 + + + + + RELENG_4_6_2_RELEASE + + + FreeBSD 4.6.2 + + + + + RELENG_4_6_1_RELEASE + + + FreeBSD 4.6.1 + + + + + RELENG_4_6_0_RELEASE + + + FreeBSD 4.6 + + + + + RELENG_4_5_0_RELEASE + + + FreeBSD 4.5 + + + + + RELENG_4_4_0_RELEASE + + + FreeBSD 4.4 + + + + + RELENG_4_3_0_RELEASE + + + FreeBSD 4.3 + + + + + RELENG_4_2_0_RELEASE + + + FreeBSD 4.2 + + + + + RELENG_4_1_1_RELEASE + + + FreeBSD 4.1.1 + + + + + RELENG_4_1_0_RELEASE + + + FreeBSD 4.1 + + + + + RELENG_4_0_0_RELEASE + + + FreeBSD 4.0 + + + + + RELENG_3_5_0_RELEASE + + + FreeBSD-3.5 + + + + + RELENG_3_4_0_RELEASE + + + FreeBSD-3.4 + + + + + RELENG_3_3_0_RELEASE + + + FreeBSD-3.3 + + + + + RELENG_3_2_0_RELEASE + + + FreeBSD-3.2 + + + + + RELENG_3_1_0_RELEASE + + + FreeBSD-3.1 + + + + + RELENG_3_0_0_RELEASE + + + FreeBSD-3.0 + + + + + RELENG_2_2_8_RELEASE + + + FreeBSD-2.2.8 + + + + + RELENG_2_2_7_RELEASE + + + FreeBSD-2.2.7 + + + + + RELENG_2_2_6_RELEASE + + + FreeBSD-2.2.6 + + + + + RELENG_2_2_5_RELEASE + + + FreeBSD-2.2.5 + + + + + RELENG_2_2_2_RELEASE + + + FreeBSD-2.2.2 + + + + + RELENG_2_2_1_RELEASE + + + FreeBSD-2.2.1 + + + + + RELENG_2_2_0_RELEASE + + + FreeBSD-2.2.0 + + + + + + + + AFS Sites + + AFS servers for FreeBSD are running at the following sites: + + + + Sweden + + + The path to the files are: + /afs/stacken.kth.se/ftp/pub/FreeBSD/ + + stacken.kth.se # Stacken Computer Club, KTH, Sweden +130.237.234.43 #hot.stacken.kth.se +130.237.237.230 #fishburger.stacken.kth.se +130.237.234.3 #milko.stacken.kth.se + + Maintainer ftp@stacken.kth.se + + + + + + + rsync Sites + + The following sites make FreeBSD available through the rsync + protocol. The rsync utility works in + much the same way as the &man.rcp.1; command, + but has more options and uses the rsync remote-update protocol + which transfers only the differences between two sets of files, + thus greatly speeding up the synchronization over the network. + This is most useful if you are a mirror site for the + FreeBSD FTP server, or the CVS repository. The + rsync suite is available for many + operating systems, on FreeBSD, see the + net/rsync + port or use the package. + + + + Czech Republic + + + rsync://ftp.cz.FreeBSD.org/ + + Available collections: + + ftp: A partial mirror of the FreeBSD FTP + server. + FreeBSD: A full mirror of the FreeBSD FTP + server. + + + + + + Germany + + + rsync://grappa.unix-ag.uni-kl.de/ + + Available collections: + + freebsd-cvs: The full FreeBSD CVS + repository. + + This machine also mirrors the CVS repositories of the + NetBSD and the OpenBSD projects, among others. + + + + + Netherlands + + + rsync://ftp.nl.FreeBSD.org/ + + Available collections: + + vol/4/freebsd-core: A full mirror of the + FreeBSD FTP server. + + + + + + United Kingdom + + + rsync://rsync.mirror.ac.uk/ + + Available collections: + + ftp.FreeBSD.org: A full mirror of the + FreeBSD FTP server. + + + + + + United States of America + + + rsync://ftp-master.FreeBSD.org/ + + This server may only be used by FreeBSD primary mirror + sites. + Available collections: + + FreeBSD: The master archive of the FreeBSD + FTP server. + acl: The FreeBSD master ACL + list. + + + rsync://ftp13.FreeBSD.org/ + + Available collections: + + FreeBSD: A full mirror of the FreeBSD FTP + server. + + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/multimedia/Makefile b/pl_PL.ISO8859-2/books/handbook/multimedia/Makefile new file mode 100644 index 0000000000..f90e1cd2b0 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/multimedia/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= multimedia/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/multimedia/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/multimedia/chapter.sgml new file mode 100644 index 0000000000..3b22f16cb9 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/multimedia/chapter.sgml @@ -0,0 +1,1798 @@ + + + + + + + Ross + Lippert + Edited by + + + + + Multimedia + + Synopsis + + FreeBSD supports a wide variety of sound cards, allowing you + to enjoy high fidelity output from your computer. This includes + the ability to record and playback audio in the MPEG Audio Layer + 3 (MP3), WAV, and Ogg Vorbis formats as well as many other + formats. The FreeBSD Ports Collection also contains + applications allowing you to edit your recorded audio, add sound + effects, and control attached MIDI devices. + + With some willingness to experiment, FreeBSD can support + playback of video files and DVD's. The number of applications + to encode, convert, and playback various video media is more + limited than the number of sound applications. For example as + of this writing, there is no good re-encoding application in the + FreeBSD Ports Collection, which could be use to convert + between formats, as there is with audio/sox. However, the software + landscape in this area is changing rapidly. + + This chapter will describe the necessary steps to configure + your sound card. The configuration and installation of X11 + () has already taken care of the + hardware issues for your video card, though there may be some + tweaks to apply for better playback. + + After reading this chapter, you will know: + + + + How to configure your system so that your sound card is + recognized. + + + + Methods to test that your card is working using + sample applications. + + + + How to troubleshoot your sound setup. + + + + How to playback and encode MP3s and other audio. + + + + How video is supported by the X server. + + + + Some video player/encoder ports which give good results. + + + + How to playback DVD's, .mpg and + .avi files. + + + + How to rip CD and DVD information into files. + + + + How to configure a TV card. + + + + How to configure an image scanner. + + + + Before reading this chapter, you should: + + + Know how to configure and install a new kernel (). + + + + Trying to mount audio CDs + with the &man.mount.8; command will + result in an error, at least, and a kernel + panic, at worst. These media have specialized + encodings which differ from the usual ISO-filesystem. + + + + + + + + + Moses + Moore + Contributed by + + + + + + Marc + Fonvieille + Enhanced for &os; 5.X by + + + + + + Setting Up the Sound Card + + + Configuring the System + + PCI + ISA + sound cards + Before you begin, you should know the model of the card you + have, the chip it uses, and whether it is a PCI or ISA card. + FreeBSD supports a wide variety of both PCI and ISA cards. + Check the supported audio devices list of the Hardware Notes to see if + your card is supported. This document will also mention which + driver supports your card. + + + kernel + configuration + + + To use your sound device, you will need to load the proper + device driver. This may be accomplished in one of two ways. + The easiest way is to simply load a kernel module for your sound + card with &man.kldload.8; which can either be done from the + command line: + + &prompt.root; kldload snd_emu10k1 + + or by adding the appropriate line to the file + /boot/loader.conf like this: + + snd_emu10k1_load="YES" + + These examples are for a Creative &soundblaster; Live! sound + card. Other available loadable sound modules are listed in + /boot/defaults/loader.conf. + If you are not sure which driver to use, you may try to load + the snd_driver module: + + &prompt.root; kldload snd_driver + + This is a metadriver loading the most common device drivers + at once. This speeds up the search for the correct driver. It + is also possible to load all sound drivers via the + /boot/loader.conf facility. + + If you wish to find out the driver selected for your + soundcard after loading the snd_driver + metadriver, you may check the /dev/sndstat + file with the cat /dev/sndstat + command. + + A second method is to statically + compile in support for your sound card in your kernel. The + section below provides the information you need to add support + for your hardware in this manner. For more information about + recompiling your kernel, please see . + + + Configuring a Custom Kernel with Sound Support + + The first thing to do is adding the generic audio driver + &man.sound.4; to the kernel, for that you will need to + add the following line to the kernel configuration file: + + device sound + + Then we have to add the support for our sound card. + Therefore, we need to know which driver supports the card. + Check the supported audio devices list of the Hardware Notes, to + determine the correct driver for your sound card. For + example, a Creative &soundblaster; Live! sound card is + supported by the &man.snd.emu10k1.4; driver. To add the support + for this card, use the following: + + device snd_emu10k1 + + Be sure to read the manual page of the driver for the + syntax to use. Information regarding the syntax of sound + drivers in the kernel configuration can also be found in the + /usr/src/sys/conf/NOTES file. + + Non-PnP ISA cards may require you to provide the kernel + with information on the sound card settings (IRQ, I/O port, + etc). This is done via the + /boot/device.hints file. At system boot, + the &man.loader.8; will read this file and pass the settings + to the kernel. For example, an old + Creative &soundblaster; 16 ISA non-PnP card will use the + &man.snd.sbc.4; driver in conjunction with snd_sb16(4). For this card the following lines have to be added to + the kernel configuration file: + + device snd_sbc +device snd_sb16 + + as well as the following in + /boot/device.hints: + + hint.sbc.0.at="isa" +hint.sbc.0.port="0x220" +hint.sbc.0.irq="5" +hint.sbc.0.drq="1" +hint.sbc.0.flags="0x15" + + In this case, the card uses the 0x220 + I/O port and the IRQ 5. + + The syntax used in the + /boot/device.hints file is covered in the + sound driver manual page. On &os; 4.X, these settings + are directly written in the kernel configuration file. + + The settings shown above are the defaults. In some + cases, you may need to change the IRQ or the other settings to + match your card. See the &man.snd.sbc.4; manual page for more + information. + + + + + Testing the Sound Card + + After rebooting with the modified kernel, or after loading + the required module, the sound card should appear in your system + message buffer (&man.dmesg.8;) as something like: + + pcm0: <Intel ICH3 (82801CA)> port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0 +pcm0: [GIANT-LOCKED] +pcm0: <Cirrus Logic CS4205 AC97 Codec> + + The status of the sound card may be checked via the + /dev/sndstat file: + + &prompt.root; cat /dev/sndstat +FreeBSD Audio Driver (newpcm) +Installed devices: +pcm0: <Intel ICH3 (82801CA)> at io 0xd800, 0xdc80 irq 5 bufsz 16384 +kld snd_ich (1p/2r/0v channels duplex default) + + The output from your system may vary. If no + pcm devices show up, go back and review + what was done earlier. Go through your kernel + configuration file again and make sure the correct + device is chosen. Common problems are listed in . + + If all goes well, you should now have a functioning sound + card. If your CD-ROM or DVD-ROM drive is properly coupled to + your sound card, you can put a CD in the drive and play it + with &man.cdcontrol.1;: + + &prompt.user; cdcontrol -f /dev/acd0 play 1 + + Various applications, such as audio/workman can provide a friendlier + interface. You may want to install an application such as + audio/mpg123 to listen to + MP3 audio files. A quick way to test the card is sending data + to the /dev/dsp, like this: + + &prompt.user; cat filename > /dev/dsp + + where filename can be any file. + This command line should produce some noise, confirming the + sound card is actually working. + + Sound card mixer levels can be changed via the &man.mixer.8; + command. More details can be found in the &man.mixer.8; manual + page. + + + Common Problems + + device nodes + I/O port + IRQ + DSP + + + + + + Error + Solution + + + + + + unsupported subdevice XX + One or more of the device nodes was not created + correctly. Repeat the steps above. + + + + sb_dspwr(XX) timed out + The I/O port is not set correctly. + + + + bad irq XX + The IRQ is set incorrectly. Make sure that + the set IRQ and the sound IRQ are the same. + + + + xxx: gus pcm not attached, out of memory + There is not enough available memory to use + the device. + + + + xxx: can't open /dev/dsp! + Check with fstat | grep dsp + if another application is holding the device open. + Noteworthy troublemakers are esound and KDE's sound + support. + + + + + + + + + + + + Munish + Chopra + Contributed by + + + + Utilizing Multiple Sound Sources + + It is often desirable to have multiple sources of sound that + are able to play simultaneously, such as when + esound or + artsd do not support sharing of the + sound device with a certain application. + + FreeBSD lets you do this through Virtual Sound + Channels, which can be set with the &man.sysctl.8; + facility. Virtual channels allow you to multiplex your sound + card's playback channels by mixing sound in the kernel. + + To set the number of virtual channels, there are two sysctl + knobs which, if you are the root user, can + be set like this: + &prompt.root; sysctl hw.snd.pcm0.vchans=4 +&prompt.root; sysctl hw.snd.maxautovchans=4 + + The above example allocates four virtual channels, which is a + practical number for everyday use. hw.snd.pcm0.vchans + is the number of virtual channels pcm0 has, and is configurable + once a device has been attached. + hw.snd.maxautovchans is the number of virtual channels + a new audio device is given when it is attached using + &man.kldload.8;. Since the pcm module + can be loaded independently of the hardware drivers, + hw.snd.maxautovchans can store how many + virtual channels any devices which are attached later will be + given. + + + You cannot change the number of virtual channels for a + device while it is in use. First close any programs using the + device, such as music players or sound daemons. + + + If you are not using &man.devfs.5;, you will have to point + your applications at + /dev/dsp0.x, + where x is 0 to 3 if + hw.snd.pcm.0.vchans is set to 4 as in the + above example. On a system using &man.devfs.5;, the above will + automatically be allocated transparently to the user. + + + + + + + Josef + El-Rayes + Contributed by + + + + + Setting Default Values for Mixer Channels + + + This is only supported in &os; 5.3-RELEASE and later. + + + The default values for the different mixer channels are + hardcoded in the sourcecode of the &man.pcm.4; driver. There are + a lot of different applications and daemons that allow + you to set values for the mixer they remember and set + each time they are started, but this is not a clean + solution, we want to have default values at the driver + level. This is accomplished by defining the appropriate + values in /boot/device.hints. E.g.: +hint.pcm.0.vol="100" + + This will set the volume channel to a default value of + 100, when the &man.pcm.4; module is loaded. + + + + + + + + Chern + Lee + Contributed by + + + + + + MP3 Audio + + MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound, + leaving no reason to let your FreeBSD workstation fall short of + its offerings. + + + MP3 Players + + By far, the most popular X11 MP3 player is + XMMS (X Multimedia System). + Winamp + skins can be used with XMMS since the + GUI is almost identical to that of Nullsoft's + Winamp. + XMMS also has native plug-in + support. + + XMMS can be installed from the + multimedia/xmms port or package. + + XMMS' interface is intuitive, + with a playlist, graphic equalizer, and more. Those familiar + with Winamp will find + XMMS simple to use. + + The audio/mpg123 port is an alternative, + command-line MP3 player. + + mpg123 can be run by specifying + the sound device and the MP3 file on the command line, as + shown below: + + &prompt.root; mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3 +High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3. +Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp. +Uses code from various people. See 'README' for more! +THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK! + + + + + +Playing MPEG stream from Foobar-GreatestHits.mp3 ... +MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo + + + /dev/dsp1.0 should be replaced with the + dsp device entry on your system. + + + + + Ripping CD Audio Tracks + + Before encoding a CD or CD track to MP3, the audio data on + the CD must be ripped onto the hard drive. This is done by + copying the raw CDDA (CD Digital Audio) data to WAV + files. + + The cdda2wav tool, which is a part of + the sysutils/cdrtools + suite, is used for ripping audio information from CDs and the + information associated with them. + + With the audio CD in the drive, the following command can + be issued (as root) to rip an entire CD + into individual (per track) WAV files: + + &prompt.root; cdda2wav -D 0,1,0 -B + + cdda2wav will support + ATAPI (IDE) CDROM drives. To rip from an IDE drive, specify + the device name in place of the SCSI unit numbers. For + example, to rip track 7 from an IDE drive: + + &prompt.root; cdda2wav -D /dev/acd0a -t 7 + + The + indicates the SCSI device 0,1,0, + which corresponds to the output of cdrecord + -scanbus. + + To rip individual tracks, make use of the + option as shown: + + &prompt.root; cdda2wav -D 0,1,0 -t 7 + + This example rips track seven of the audio CDROM. To rip + a range of tracks, for example, track one to seven, specify a + range: + + &prompt.root; cdda2wav -D 0,1,0 -t 1+7 + + The utility &man.dd.1; can also be used to extract audio tracks + on ATAPI drives, read + for more information on that possibility. + + + + + Encoding MP3s + + Nowadays, the mp3 encoder of choice is + lame. + Lame can be found at + audio/lame in the ports tree. + + Using the ripped WAV files, the following command will + convert audio01.wav to + audio01.mp3: + + &prompt.root; lame -h -b 128 \ +--tt "Foo Song Title" \ +--ta "FooBar Artist" \ +--tl "FooBar Album" \ +--ty "2001" \ +--tc "Ripped and encoded by Foo" \ +--tg "Genre" \ +audio01.wav audio01.mp3 + + 128 kbits seems to be the standard MP3 bitrate in use. + Many enjoy the higher quality 160, or 192. The higher the + bitrate, the more disk space the resulting MP3 will + consume--but the quality will be higher. The + option turns on the higher quality + but a little slower mode. The options beginning with + indicate ID3 tags, which usually contain + song information, to be embedded within the MP3 file. + Additional encoding options can be found by consulting the + lame man page. + + + + Decoding MP3s + + In order to burn an audio CD from MP3s, they must be + converted to a non-compressed WAV format. Both + XMMS and + mpg123 support the output of MP3 to + an uncompressed file format. + + Writing to Disk in XMMS: + + + + Launch XMMS. + + + + Right-click on the window to bring up the + XMMS menu. + + + + Select Preference under + Options. + + + + Change the Output Plugin to Disk Writer + Plugin. + + + + Press Configure. + + + + Enter (or choose browse) a directory to write the + uncompressed files to. + + + + Load the MP3 file into XMMS + as usual, with volume at 100% and EQ settings turned + off. + + + + Press Play — + XMMS will appear as if it is + playing the MP3, but no music will be heard. It is + actually playing the MP3 to a file. + + + + Be sure to set the default Output Plugin back to what + it was before in order to listen to MP3s again. + + + + Writing to stdout in mpg123: + + + + Run mpg123 -s audio01.mp3 + > audio01.pcm + + + + XMMS writes a file in the WAV + format, while mpg123 converts the + MP3 into raw PCM audio data. Both of these formats can be + used with cdrecord to create audio CDs. + You have to use raw PCM with &man.burncd.8;. + If you use WAV files, you will notice a small tick sound at the + beginning of each track, this sound is the header of the WAV + file. You can simply remove the header of a WAV file with the + utility SoX (it can be installed from + the audio/sox port or + package): + + &prompt.user; sox -t wav -r 44100 -s -w -c 2 track.wav track.raw + + Read for more information on using a + CD burner in FreeBSD. + + + + + + + + Ross + Lippert + Contributed by + + + + + + Video Playback + + Video playback is a very new and rapidly developing application + area. Be patient. Not everything is going to work as smoothly as + it did with sound. + + Before you begin, you should know the model of the video + card you have and the chip it uses. While &xorg; and &xfree86; support a + wide variety of video cards, fewer give good playback + performance. To obtain a list of extensions supported by the + X server using your card use the command &man.xdpyinfo.1; while + X11 is running. + + It is a good idea to have a short MPEG file which can be + treated as a test file for evaluating various players and + options. Since some DVD players will look for DVD media in + /dev/dvd by default, or have this device + name hardcoded in them, you might find it useful to make + symbolic links to the proper devices: + + &prompt.root; ln -sf /dev/acd0c /dev/dvd +&prompt.root; ln -sf /dev/racd0c /dev/rdvd + + On FreeBSD 5.X, which uses &man.devfs.5; there + is a slightly different set of recommended links: + + &prompt.root; ln -sf /dev/acd0 /dev/dvd +&prompt.root; ln -sf /dev/acd0 /dev/rdvd + + Note that due to the nature of &man.devfs.5;, + manually created links like these will not persist if you reboot + your system. In order to create the symbolic links + automatically whenever you boot your system, add the following + lines to /etc/devfs.conf: + + link acd0 dvd +link acd0 rdvd + + Additionally, DVD decryption, which requires invoking + special DVD-ROM functions, requires write permission on the DVD + devices. + + + kernel options + CPU_ENABLE_SSE + + + Some of the ports discussed rely on the following kernel + options to build correctly. Before attempting to build, add + this option to the kernel configuration file, build a new kernel, and reboot: + + options CPU_ENABLE_SSE + + To enhance the shared memory X11 interface, it is + recommended that the values of some &man.sysctl.8; variables + should be increased: + + kern.ipc.shmmax=67108864 +kern.ipc.shmall=32768 + + + Determining Video Capabilities + + XVideo + SDL + DGA + + There are several possible ways to display video under X11. + What will really work is largely hardware dependent. Each + method described below will have varying quality across + different hardware. Secondly, the rendering of video in X11 is + a topic receiving a lot of attention lately, and with each + version of &xorg;, or of &xfree86;, there may be significant improvement. + + A list of common video interfaces: + + + + X11: normal X11 output using shared memory. + + + XVideo: an extension to the X11 + interface which supports video in any X11 drawable. + + + SDL: the Simple Directmedia Layer. + + + DGA: the Direct Graphics Access. + + + SVGAlib: low level console graphics layer. + + + + + XVideo + + &xorg; and &xfree86; 4.X have an extension called + XVideo (aka Xvideo, aka Xv, aka xv) which + allows video to be directly displayed in drawable objects + through a special acceleration. This extension provides very + good quality playback even on low-end machines. + + To check whether the extension is running, + use xvinfo: + + &prompt.user; xvinfo + + XVideo is supported for your card if the result looks like: +X-Video Extension version 2.2 +screen #0 + Adaptor #0: "Savage Streams Engine" + number of ports: 1 + port base: 43 + operations supported: PutImage + supported visuals: + depth 16, visualID 0x22 + depth 16, visualID 0x23 + number of attributes: 5 + "XV_COLORKEY" (range 0 to 16777215) + client settable attribute + client gettable attribute (current value is 2110) + "XV_BRIGHTNESS" (range -128 to 127) + client settable attribute + client gettable attribute (current value is 0) + "XV_CONTRAST" (range 0 to 255) + client settable attribute + client gettable attribute (current value is 128) + "XV_SATURATION" (range 0 to 255) + client settable attribute + client gettable attribute (current value is 128) + "XV_HUE" (range -180 to 180) + client settable attribute + client gettable attribute (current value is 0) + maximum XvImage size: 1024 x 1024 + Number of image formats: 7 + id: 0x32595559 (YUY2) + guid: 59555932-0000-0010-8000-00aa00389b71 + bits per pixel: 16 + number of planes: 1 + type: YUV (packed) + id: 0x32315659 (YV12) + guid: 59563132-0000-0010-8000-00aa00389b71 + bits per pixel: 12 + number of planes: 3 + type: YUV (planar) + id: 0x30323449 (I420) + guid: 49343230-0000-0010-8000-00aa00389b71 + bits per pixel: 12 + number of planes: 3 + type: YUV (planar) + id: 0x36315652 (RV16) + guid: 52563135-0000-0000-0000-000000000000 + bits per pixel: 16 + number of planes: 1 + type: RGB (packed) + depth: 0 + red, green, blue masks: 0x1f, 0x3e0, 0x7c00 + id: 0x35315652 (RV15) + guid: 52563136-0000-0000-0000-000000000000 + bits per pixel: 16 + number of planes: 1 + type: RGB (packed) + depth: 0 + red, green, blue masks: 0x1f, 0x7e0, 0xf800 + id: 0x31313259 (Y211) + guid: 59323131-0000-0010-8000-00aa00389b71 + bits per pixel: 6 + number of planes: 3 + type: YUV (packed) + id: 0x0 + guid: 00000000-0000-0000-0000-000000000000 + bits per pixel: 0 + number of planes: 0 + type: RGB (packed) + depth: 1 + red, green, blue masks: 0x0, 0x0, 0x0 + + Also note that the formats listed (YUV2, YUV12, etc) are not + present with every implementation of XVideo and their absence may + hinder some players. + + If the result looks like: +X-Video Extension version 2.2 +screen #0 +no adaptors present + + Then XVideo is probably not supported for your card. + + If XVideo is not supported for your card, this only means + that it will be more difficult for your display to meet the + computational demands of rendering video. Depending on your + video card and processor, though, you might still be able to + have a satisfying experience. You should probably read about + ways of improving performance in the advanced reading . + + + + + Simple Directmedia Layer + + The Simple Directmedia Layer, SDL, was intended to be a + porting layer between µsoft.windows;, BeOS, and &unix;, + allowing cross-platform applications to be developed which made + efficient use of sound and graphics. The SDL layer provides a + low-level abstraction to the hardware which can sometimes be + more efficient than the X11 interface. + + The SDL can be found at devel/sdl12. + + + + + Direct Graphics Access + + Direct Graphics Access is an X11 extension which allows + a program to bypass the X server and directly alter the + framebuffer. Because it relies on a low level memory mapping to + effect this sharing, programs using it must be run as + root. + + The DGA extension can be tested and benchmarked by + &man.dga.1;. When dga is running, it + changes the colors of the display whenever a key is pressed. To + quit, use q. + + + + + + + Ports and Packages Dealing with Video + + video ports + video packages + + This section discusses the software available from the + FreeBSD Ports Collection which can be used for video playback. + Video playback is a very active area of software development, + and the capabilities of various applications are bound to + diverge somewhat from the descriptions given here. + + Firstly, it is important to know that many of the video + applications which run on FreeBSD were developed as Linux + applications. Many of these applications are still + beta-quality. Some of the problems that you may encounter with + video packages on FreeBSD include: + + + + + An application cannot playback a file which another + application produced. + + + + An application cannot playback a file which the + application itself produced. + + + + The same application on two different machines, + rebuilt on each machine for that machine, plays back the same + file differently. + + + + A seemingly trivial filter like rescaling of the image + size results in very bad artifacts from a buggy rescaling + routine. + + + + An application frequently dumps core. + + + + Documentation is not installed with the port and can be + found either on the web or under the port's work + directory. + + + + + Many of these applications may also exhibit + Linux-isms. That is, there may be + issues resulting from the way some standard libraries are + implemented in the Linux distributions, or some features of the + Linux kernel which have been assumed by the authors of the + applications. These issues are not always noticed and worked around + by the port maintainers, which can lead to problems like + these: + + + + + The use of /proc/cpuinfo to detect + processor characteristics. + + + + A misuse of threads which causes a program to hang upon + completion instead of truly terminating. + + + + Software not yet in the FreeBSD Ports Collection + which is commonly used in conjunction with the application. + + + + + So far, these application developers have been cooperative with + port maintainers to minimize the work-arounds needed for + port-ing. + + + MPlayer + + MPlayer is a recently developed and rapidly developing + video player. The goals of the MPlayer team are speed and + flexibility on Linux and other Unices. The project was + started when the team founder got fed up with bad playback + performance on then available players. Some would say that + the graphical interface has been sacrificed for a streamlined + design. However, once + you get used to the command line options and the key-stroke + controls, it works very well. + + + Building MPlayer + MPlayer + making + + MPlayer resides in multimedia/mplayer. + MPlayer performs a variety of + hardware checks during the build process, resulting in a + binary which will not be portable from one system to + another. Therefore, it is important to build it from + ports and not to use a binary package. Additionally, a + number of options can be specified in the make + command line, as described in the Makefile and at the start of the build: + + &prompt.root; cd /usr/ports/multimedia/mplayer +&prompt.root; make +N - O - T - E + +Take a careful look into the Makefile in order +to learn how to tune mplayer towards you personal preferences! +For example, +make WITH_GTK1 +builds MPlayer with GTK1-GUI support. +If you want to use the GUI, you can either install +/usr/ports/multimedia/mplayer-skins +or download official skin collections from +http://www.mplayerhq.hu/homepage/dload.html + + + The default port options should be sufficient for most + users. However, if you need the XviD codec, you have to + specify the WITH_XVID option in the + command line. The default DVD device can also be defined + with the WITH_DVD_DEVICE option, by + default /dev/acd0 will be used. + + As of this writing, the MPlayer port will build its HTML + documentation and two executables, + mplayer, and + mencoder, which is a tool for + re-encoding video. + + The HTML documentation for MPlayer is very informative. + If the reader finds the information on video hardware and + interfaces in this chapter lacking, the MPlayer documentation + is a very thorough supplement. You should definitely take + the time to read the MPlayer + documentation if you are looking for information about video + support in &unix;. + + + + + Using MPlayer + MPlayer + use + + Any user of MPlayer must set up a + .mplayer subdirectory of her + home directory. To create this necessary subdirectory, + you can type the following: + +&prompt.user; cd /usr/ports/multimedia/mplayer +&prompt.user; make install-user + + The command options for mplayer are + listed in the manual page. For even more detail there is HTML + documentation. In this section, we will describe only a few + common uses. + + To play a file, such as + testfile.avi, + through one of the various video interfaces set the + option: + + &prompt.user; mplayer -vo xv testfile.avi + &prompt.user; mplayer -vo sdl testfile.avi + &prompt.user; mplayer -vo x11 testfile.avi + &prompt.root; mplayer -vo dga testfile.avi + &prompt.root; mplayer -vo 'sdl:dga' testfile.avi + + It is worth trying all of these options, as their relative + performance depends on many factors and will vary significantly + with hardware. + + To play from a DVD, replace the + testfile.avi with where N is + the title number to play and + DEVICE is the + device node for the DVD-ROM. For example, to play title 3 + from /dev/dvd: + + &prompt.root; mplayer -vo xv dvd://3 -dvd-device /dev/dvd + + + The default DVD device can be defined during the build + of the MPlayer port via the + WITH_DVD_DEVICE option. By default, + this device is /dev/acd0. More + details can be found in the port + Makefile. + + + To stop, pause, advance and so on, consult the + keybindings, which are output by running mplayer + -h or read the manual page. + + Additional important options for playback are: + which engages the fullscreen mode + and which helps performance. + + In order for the mplayer command line to not become too + large, the user can create a file + .mplayer/config and set default options + there: +vo=xv +fs=yes +zoom=yes + + Finally, mplayer can be used to rip a + DVD title into a .vob file. To dump + out the second title from a DVD, type this: + + &prompt.root; mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd + + The output file, out.vob, will be + MPEG and can be manipulated by the other packages described + in this section. + + + + mencoder + + mencoder + + + Before using + mencoder it is a good idea to + familiarize yourself with the options from the HTML + documentation. There is a manual page, but it is not very + useful without the HTML documentation. There are innumerable ways to + improve quality, lower bitrate, and change formats, and some + of these tricks may make the difference between good + or bad performance. Here are a couple of examples to get + you going. First a simple copy: + + &prompt.user; mencoder input.avi -oac copy -ovc copy -o output.avi + + Improper combinations of command line options can yield + output files that are + unplayable even by mplayer. Thus, if you + just want to rip to a file, stick to the + in mplayer. + + To convert input.avi to the MPEG4 + codec with MPEG3 audio encoding (audio/lame is required): + + &prompt.user; mencoder input.avi -oac mp3lame -lameopts br=192 \ + -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi + + This has produced output playable by mplayer + and xine. + + input.avi can be replaced with + and run as + root to re-encode a DVD title + directly. Since you are likely to be dissatisfied with + your results the first time around, it is recommended you + dump the title to a file and work on the file. + + + + + + The xine Video Player + + The xine video player is a project of wide scope aiming not only at being an + all in one video solution, but also in producing a reusable base + library and a modular executable which can be extended with + plugins. It comes both as a package and as a port, multimedia/xine. + + The xine player + is still very rough around the edges, but it is clearly off to a + good start. In practice, xine requires either a fast CPU with a + fast video card, or support for the XVideo extension. The GUI is + usable, but a bit clumsy. + + As of this writing, there is no input module shipped with + xine which will play CSS encoded DVD's. There are third party + builds which do have modules for this built in them, but none + of these are in the FreeBSD Ports Collection. + + Compared to MPlayer, xine does more for the user, but at the + same time, takes some of the more fine-grained control away from + the user. The xine video player + performs best on XVideo interfaces. + + By default, xine player will + start up in a graphical user interface. The menus can then be + used to open a specific file: + + &prompt.user; xine + + Alternatively, it may be invoked to play a file immediately + without the GUI with the command: + + &prompt.user; xine -g -p mymovie.avi + + + + + The transcode Utilities + + The software transcode is not a player, but a suite of tools for + re-encoding video and audio files. With transcode, one has the + ability to merge video files, repair broken files, using command + line tools with stdin/stdout stream + interfaces. + + A great number of options can be specified during + the build from the multimedia/transcode port, we recommend the + following command line to build + transcode: + + &prompt.root; make WITH_OPTIMIZED_CFLAGS=yes WITH_LIBA52=yes WITH_LAME=yes WITH_OGG=yes \ +WITH_MJPEG=yes -DWITH_XVID=yes + + The proposed settings should be sufficient for most users. + + To illustrate transcode capacities, one + example to show how to convert a DivX file into a PAL MPEG-1 + file (PAL VCD): + + &prompt.user; transcode -i input.avi -V --export_prof vcd-pal -o output_vcd +&prompt.user; mplex -f 1 -o output_vcd.mpg output_vcd.m1v output_vcd.mpa + + The resulting MPEG file, + output_vcd.mpg, is ready to be played with + MPlayer. You could even burn the + file on a CD-R media to create a Video CD, in this case you will + need to install and use both multimedia/vcdimager and sysutils/cdrdao programs. + + There is a manual page for transcode, but + you should also consult the transcode + wiki for further information and examples. + + + + + + Further Reading + + The various video software packages for FreeBSD are + developing rapidly. It is quite possible that in the near + future many of the problems discussed here will have been + resolved. In the mean time, those who + want to get the very most out of FreeBSD's A/V capabilities will + have to cobble together knowledge from several FAQs and tutorials + and use a few different applications. This section exists to + give the reader pointers to such additional information. + + The + MPlayer documentation + is very technically informative. + These documents should probably be consulted by anyone wishing + to obtain a high level of expertise with &unix; video. The + MPlayer mailing list is hostile to anyone who has not bothered + to read the documentation, so if you plan on making bug reports + to them, RTFM. + + The + xine HOWTO + contains a chapter on performance improvement + which is general to all players. + + Finally, there are some other promising applications which + the reader may try: + + + + + Avifile which + is also a port multimedia/avifile. + + + + Ogle + which is also a port multimedia/ogle. + + + + Xtheater + + + + multimedia/dvdauthor, an open + source package for authoring DVD content. + + + + + + + + + + + + Josef + El-Rayes + Original contribution by + + + + + Marc + Fonvieille + Enhanced and adapted by + + + + + + Setting Up TV Cards + + TV cards + + + + Introduction + + TV cards allow you to watch broadcast or cable TV on your + computer. Most of them accept composite video via an RCA or + S-video input and some of these cards come with a FM + radio tuner. + + &os; provides support for PCI-based TV cards using a + Brooktree Bt848/849/878/879 or a Conexant CN-878/Fusion 878a + Video Capture Chip with the &man.bktr.4; driver. You must + also ensure the board comes with a supported tuner, consult + the &man.bktr.4; manual page for a list of supported + tuners. + + + + Adding the Driver + + To use your card, you will need to load the &man.bktr.4; + driver, this can be done by adding the following line to the + /boot/loader.conf file like this: + + bktr_load="YES" + + Alternatively, you may statically compile the support for + the TV card in your kernel, in that case add the following + lines to your kernel configuration: + + device bktr +device iicbus +device iicbb +device smbus + + These additional device drivers are necessary because of the + card components being interconnected via an I2C bus. Then build + and install a new kernel. + + Once the support was added to your system, you have to + reboot your machine. During the boot process, your TV card + should show up, like this: + + bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0 +iicbb0: <I2C bit-banging driver> on bti2c0 +iicbus0: <Philips I2C bus> on iicbb0 master-only +iicbus1: <Philips I2C bus> on iicbb0 master-only +smbus0: <System Management Bus> on bti2c0 +bktr0: Pinnacle/Miro TV, Philips SECAM tuner. + + Of course these messages can differ according to your + hardware. However you should check if the tuner is correctly + detected; it is still possible to override some of the + detected parameters with &man.sysctl.8; MIBs and kernel + configuration file options. For example, if you want to force + the tuner to a Philips SECAM tuner, you should add the + following line to your kernel configuration file: + + options OVERRIDE_TUNER=6 + + or you can directly use &man.sysctl.8;: + + &prompt.root; sysctl hw.bt848.tuner=6 + + See the &man.bktr.4; manual page and the + /usr/src/sys/conf/NOTES file for more + details on the available options. + + + + Useful Applications + + To use your TV card you need to install one of the + following applications: + + + + multimedia/fxtv + provides TV-in-a-window and image/audio/video capture + capabilities. + + + multimedia/xawtv + is also a TV application, with the same features as + fxtv. + + + misc/alevt decodes + and displays Videotext/Teletext. + + + audio/xmradio, an + application to use the FM radio tuner coming with some + TV cards. + + + audio/wmtune, a handy + desktop application for radio tuners. + + + + More applications are available in the &os; Ports + Collection. + + + + Troubleshooting + + If you encounter any problem with your TV card, you should + check at first if the video capture chip and the tuner are + really supported by the &man.bktr.4; driver and if you used the right + configuration options. For more support and various questions + about your TV card you may want to contact and use the + archives of the &a.multimedia.name; mailing list. + + + + + + + + Marc + Fonvieille + Written by + + + + + + Image Scanners + + image scanners + + + + Introduction + + &os;, like any modern operating system, allows the use of + image scanners. Standardized access to scanners is provided + by the SANE (Scanner Access Now + Easy) API available through the &os; Ports + Collection. SANE will also use + some &os; devices drivers to access to the scanner + hardware. + + &os; supports both SCSI and USB scanners. Be sure your + scanner is supported by SANE prior + to performing any configuration. + SANE has a supported + devices list that can provide you with information + about the support for a scanner and its status. The + &man.uscanner.4; manual page also provides a list of supported + USB scanners. + + + + Kernel Configuration + + As mentioned above both SCSI and USB interfaces are + supported. According to your scanner interface, different + device drivers are required. + + + USB Interface + + The GENERIC kernel by default + includes the device drivers needed to support USB scanners. + Should you decide to use a custom kernel, be sure that the + following lines are present in your kernel configuration + file: + + device usb +device uhci +device ohci +device uscanner + + Depending upon the USB chipset on your motherboard, you + will only need either device uhci or + device ohci, however having both in the + kernel configuration file is harmless. + + If you do not want to rebuild your kernel and your + kernel is not the GENERIC one, you can + directly load the &man.uscanner.4; device driver module with + the &man.kldload.8; command: + + &prompt.root; kldload uscanner + + To load this module at each system startup, add the + following line to + /boot/loader.conf: + + uscanner_load="YES" + + After rebooting with the correct kernel, or after + loading the required module, plug in your USB scanner. The + scanner should appear in your system message buffer + (&man.dmesg.8;) as something like: + + uscanner0: EPSON EPSON Scanner, rev 1.10/3.02, addr 2 + + This shows that our scanner is using the + /dev/uscanner0 device node. + + + + SCSI Interface + + If your scanner comes with a SCSI interface, it is + important to know which SCSI controller board you will use. + According to the SCSI chipset used, you will have to tune + your kernel configuration file. The + GENERIC kernel supports the most common + SCSI controllers. Be sure to read the + NOTES file + and add the correct line to your kernel + configuration file. In addition to the SCSI adapter driver, + you need to have the following lines in your kernel + configuration file: + + device scbus +device pass + + Once your kernel has been properly compiled, you should + be able to see the devices in your system message buffer, + when booting: + + pass2 at aic0 bus 0 target 2 lun 0 +pass2: <AGFA SNAPSCAN 600 1.10> Fixed Scanner SCSI-2 device +pass2: 3.300MB/s transfers + + If your scanner was not powered-on at system boot, it is + still possible to manually force the detection by performing + a SCSI bus scan with the &man.camcontrol.8; command: + + &prompt.root; camcontrol rescan all +Re-scan of bus 0 was successful +Re-scan of bus 1 was successful +Re-scan of bus 2 was successful +Re-scan of bus 3 was successful + + Then the scanner will appear in the SCSI devices + list: + + &prompt.root; camcontrol devlist +<IBM DDRS-34560 S97B> at scbus0 target 5 lun 0 (pass0,da0) +<IBM DDRS-34560 S97B> at scbus0 target 6 lun 0 (pass1,da1) +<AGFA SNAPSCAN 600 1.10> at scbus1 target 2 lun 0 (pass3) +<PHILIPS CDD3610 CD-R/RW 1.00> at scbus2 target 0 lun 0 (pass2,cd0) + + More details about SCSI devices, are available in the + &man.scsi.4; and &man.camcontrol.8; manual pages. + + + + + SANE Configuration + + The SANE system has been + splitted in two parts: the backends (graphics/sane-backends) and the + frontends (graphics/sane-frontends). The + backends part provides access to the scanner itself. The + SANE's supported + devices list specifies which backend will support your + image scanner. It is mandatory to determine the correct + backend for your scanner if you want to be able to use your + device. The frontends part provides the graphical scanning + interface (xscanimage). + + The first thing to do is install the graphics/sane-backends port or + package. Then, use the sane-find-scanner + command to check the scanner detection by the + SANE system: + + &prompt.root; sane-find-scanner -q +found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3 + + The output will show the interface type of the scanner and + the device node used to attach the scanner to the system. The + vendor and the product model may not appear, it is not + important. + + + Some USB scanners require you to load a firmware, this + is explained in the backend manual page. You should also read + &man.sane-find-scanner.1; and &man.sane.7; manual + pages. + + + Now we have to check if the scanner will be identified by + a scanning frontend. By default, the + SANE backends comes with a command + line tool called &man.scanimage.1;. This command allows you + to list the devices and to perform an image acquisition from + the command line. The option is used to + list the scanner device: + + &prompt.root; scanimage -L +device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner + + No output or a message saying that no scanners were + identified indicates that &man.scanimage.1; is unable to + identify the scanner. If this happens, you will need to edit + the backend configuration file and define the scanner device + used. The /usr/local/etc/sane.d/ directory + contains all backends configuration files. This + identification problem does appear with certain USB + scanners. + + For example, with the USB scanner used in the , + sane-find-scanner gives us the following + information: + + &prompt.root; sane-find-scanner -q +found USB scanner (UNKNOWN vendor and product) at device /dev/uscanner0 + The scanner is correctly detected, it uses the USB + interface and is attached to the + /dev/uscanner0 device node. We can now + check if the scanner is correctly identified: + + &prompt.root; scanimage -L + +No scanners were identified. If you were expecting something different, +check that the scanner is plugged in, turned on and detected by the +sane-find-scanner tool (if appropriate). Please read the documentation +which came with this software (README, FAQ, manpages). + + Since the scanner is not identified, we will need to edit + the /usr/local/etc/sane.d/epson.conf + file. The scanner model used was the &epson.perfection; 1650, + so we know the scanner will use the epson + backend. Be sure to read the help comments in the backends + configuration files. Line changes are quite simple: comment + out all lines that have the wrong interface for your scanner + (in our case, we will comment out all lines starting with the + word scsi as our scanner uses the USB + interface), then add at the end of the file a line specifying + the interface and the device node used. In this case, we add + the following line: + + usb /dev/uscanner0 + + Please be sure to read the comments provided in the + backend configuration file as well as the backend manual page + for more details and correct syntax to use. We can now verify + if the scanner is identified: + + &prompt.root; scanimage -L +device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner + + Our USB scanner has been identified. It is not important + if the brand and the model do not match. The key item to be + concerned with is the + `epson:/dev/uscanner0' field, which give us + the right backend name and the right device node. + + Once the scanimage -L command is able + to see the scanner, the configuration is complete. The device + is now ready to scan. + + While &man.scanimage.1; does allow us to perform an + image acquisition from the command line, it is preferable to + use a graphical user interface to perform image scanning. + SANE offers a simple but efficient + graphical interface: xscanimage + (graphics/sane-frontends). + + Xsane (graphics/xsane) is another popular + graphical scanning frontend. This frontend offers advanced + features such as various scanning mode (photocopy, fax, etc.), + color correction, batch scans, etc. Both of these applications + are useable as a GIMP + plugin. + + + + Allowing Scanner Access to Other Users + + All previous operations have been done with + root privileges. You may however, need + other users to have access + to the scanner. The user will need read and write + permissions to the device node used by the scanner. As an + example, our USB scanner uses the device node + /dev/uscanner0 which is owned by the + operator group. Adding the user + joe to the + operator group will allow him to use + the scanner: + + &prompt.root; pw groupmod operator -m joe + + For more details read the &man.pw.8; manual page. You + also have to set the correct write permissions (0660 or 0664) + on the /dev/uscanner0 device node, by + default the operator group can only + read the device node. This is done by adding the following + lines to the /etc/devfs.rules file: + + [system=5] +add path uscanner0 mode 660 + + Then add the following to + /etc/rc.conf and reboot the + machine: + + devfs_system_ruleset="system" + + More information regarding these lines can be found in the + &man.devfs.8; manual page. + + + Of course, for security reasons, you should think twice + before adding a user to any group, especially the + operator group. + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/network-servers/Makefile b/pl_PL.ISO8859-2/books/handbook/network-servers/Makefile new file mode 100644 index 0000000000..150dbe3121 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/network-servers/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= network-servers/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/network-servers/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/network-servers/chapter.sgml new file mode 100644 index 0000000000..2013b83364 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/network-servers/chapter.sgml @@ -0,0 +1,4764 @@ + + + + + + + Murray + Stokely + Reorganized by + + + + + + Network Servers + + + Synopsis + + This chapter will cover some of the more frequently used + network services on &unix; systems. We will cover how to + install, configure, test, and maintain many different types of + network services. Example configuration files are included + throughout this chapter for you to benefit from. + + After reading this chapter, you will know: + + + + + How to manage the inetd + daemon. + + + + How to set up a network file system. + + + + How to set up a network information server for sharing + user accounts. + + + + How to set up automatic network settings using DHCP. + + + + How to set up a domain name server. + + + + How to set up the Apache HTTP Server. + + + + How to set up a File Transfer Protocol (FTP) Server. + + + + How to set up a file and print server for &windows; + clients using Samba. + + + + How to synchronize the time and date, and set up a + time server, with the NTP protocol. + + + + + Before reading this chapter, you should: + + + + Understand the basics of the + /etc/rc scripts. + + + + Be familiar with basic network terminology. + + + + Know how to install additional third-party + software (). + + + + + + + + + + Chern + Lee + Contributed by + + + + + Updated for &os; 6.1-RELEASE by + The &os; Documentation Project + + + + + The <application>inetd</application> <quote>Super-Server</quote> + + + Overview + + &man.inetd.8; is sometimes referred to as the Internet + Super-Server because it manages connections for + several services. When a + connection is received by inetd, it + determines which program the connection is destined for, spawns + the particular process and delegates the socket to it (the program + is invoked with the service socket as its standard input, output + and error descriptors). Running + inetd for servers that are not heavily used can reduce the + overall system load, when compared to running each daemon + individually in stand-alone mode. + + Primarily, inetd is used to + spawn other daemons, but several trivial protocols are handled + directly, such as chargen, + auth, and + daytime. + + This section will cover the basics in configuring + inetd through its command-line + options and its configuration file, + /etc/inetd.conf. + + + + Settings + + inetd is initialized through + the &man.rc.8; system. The + inetd_enable option is set to + NO by default, but may be turned on + by sysinstall during installation, + depending on the configuration chosen by the user. + Placing: + inetd_enable="YES" or + inetd_enable="NO" into + /etc/rc.conf will enable or disable + inetd starting at boot time. + The command: + /etc/rc.d/inetd rcvar + can be run to display the current effective setting. + + Additionally, different command-line options can be passed + to inetd via the + inetd_flags option. + + + + Command-Line Options + + Like most server daemons, inetd + has a number of options that it can be passed in order to + modify its behaviour. The full list of options reads: + + inetd + + Options can be passed to inetd using the + inetd_flags option in + /etc/rc.conf. By default, + inetd_flags is set to + -wW -C 60, which turns on TCP wrapping for + inetd's services, and prevents any + single IP address from requesting any service more than 60 times + in any given minute. + + Novice users may be pleased to note that + these parameters usually do not need to be modified, + although we mention the rate-limiting options below as + they be useful should you find that you are receiving an + excessive amount of connections. A full list of options + can be found in the &man.inetd.8; manual. + + + + -c maximum + + + Specify the default maximum number of simultaneous + invocations of each service; the default is unlimited. + May be overridden on a per-service basis with the + parameter. + + + + + -C rate + + + Specify the default maximum number of times a + service can be invoked from a single IP address in one + minute; the default is unlimited. May be overridden on a + per-service basis with the + + parameter. + + + + + -R rate + + + Specify the maximum number of times a service can be + invoked in one minute; the default is 256. A rate of 0 + allows an unlimited number of invocations. + + + + + -s maximum + + + Specify the maximum number of times a service can be + invoked from a single IP address at any one time; the + default is unlimited. May be overridden on a per-service + basis with the + parameter. + + + + + + + + <filename>inetd.conf</filename> + + Configuration of inetd is + done via the file /etc/inetd.conf. + + When a modification is made to + /etc/inetd.conf, + inetd can be forced to re-read its + configuration file by running the command: + + + Reloading the <application>inetd</application> + configuration file + + &prompt.root; /etc/rc.d/inetd reload + + + Each line of the configuration file specifies an + individual daemon. Comments in the file are preceded by a + #. The format of each entry in + /etc/inetd.conf is as follows: + + service-name +socket-type +protocol +{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] +user[:group][/login-class] +server-program +server-program-arguments + + An example entry for the &man.ftpd.8; daemon + using IPv4 might read: + + ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l + + + + service-name + + + This is the service name of the particular daemon. + It must correspond to a service listed in + /etc/services. This determines + which port inetd must listen + to. If a new service is being created, it must be + placed in /etc/services + first. + + + + + socket-type + + + Either stream, + dgram, raw, or + seqpacket. stream + must be used for connection-based, TCP daemons, while + dgram is used for daemons utilizing + the UDP transport protocol. + + + + + protocol + + + One of the following: + + + + + + Protocol + Explanation + + + + + tcp, tcp4 + TCP IPv4 + + + udp, udp4 + UDP IPv4 + + + tcp6 + TCP IPv6 + + + udp6 + UDP IPv6 + + + tcp46 + Both TCP IPv4 and v6 + + + udp46 + Both UDP IPv4 and v6 + + + + + + + + + {wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] + + + indicates whether the + daemon invoked from inetd is + able to handle its own socket or not. + socket types must use the + option, while stream socket + daemons, which are usually multi-threaded, should use + . usually + hands off multiple sockets to a single daemon, while + spawns a child daemon for each + new socket. + + The maximum number of child daemons + inetd may spawn can be set + using the option. If a limit + of ten instances of a particular daemon is needed, a + /10 would be placed after + . Specifying /0 + allows an unlimited number of children + + In addition to , two other + options which limit the maximum connections from a single + place to a particular daemon can be enabled. + limits + the number of connections from any particular IP address + per minutes, e.g. a value of ten would limit any particular + IP address connecting to a particular service to ten + attempts per minute. + limits the number of children that can be started on + behalf on any single IP address at any moment. These + options are useful to prevent intentional or unintentional + excessive resource consumption and Denial of Service (DoS) + attacks to a machine. + + In this field, either of or + is mandatory. + , + and + are + optional. + + A stream-type multi-threaded daemon without any + , + or + limits + would simply be: nowait. + + The same daemon with a maximum limit of ten daemons + would read: nowait/10. + + The same setup with a limit of twenty + connections per IP address per minute and a maximum + total limit of ten child daemons would read: + nowait/10/20. + + These options are utilized by the default + settings of the &man.fingerd.8; daemon, + as seen here: + + finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s + + Finally, an example of this field with a maximum of + 100 children in total, with a maximum of 5 for any one + IP address would read: + nowait/100/0/5. + + + + + user + + + This is the username that the particular daemon + should run as. Most commonly, daemons run as the + root user. For security purposes, it is + common to find some servers running as the + daemon user, or the least privileged + nobody user. + + + + + server-program + + + The full path of the daemon to be executed when a + connection is received. If the daemon is a service + provided by inetd internally, + then should be + used. + + + + + server-program-arguments + + + This works in conjunction with + by specifying the + arguments, starting with argv[0], + passed to the daemon on invocation. If + mydaemon -d is the command line, + mydaemon -d would be the value of + . Again, if + the daemon is an internal service, use + here. + + + + + + + Security + + Depending on the choices made at install time, many + of inetd's services may be enabled + by default. If there is no apparent need for a particular + daemon, consider disabling it. Place a # in front of the + daemon in question in /etc/inetd.conf, + and then reload the + inetd configuration. Some daemons, such as + fingerd, may not be desired at all + because they provide + information that may be useful to an attacker. + + Some daemons are not security-conscious and have long, or + non-existent, timeouts for connection attempts. This allows an + attacker to slowly send connections to a particular daemon, + thus saturating available resources. It may be a good idea to + place , + or limitations on certain + daemons if you find that you have too many connections. + + By default, TCP wrapping is turned on. Consult the + &man.hosts.access.5; manual page for more information on placing + TCP restrictions on various inetd + invoked daemons. + + + + Miscellaneous + + daytime, + time, + echo, + discard, + chargen, and + auth are all internally provided + services of inetd. + + The auth service provides + identity + network services, and is + configurable to a certain degree, whilst the others are simply on or off. + + Consult the &man.inetd.8; manual page for more in-depth + information. + + + + + + + + Tom + Rhodes + Reorganized and enhanced by + + + + + Bill + Swingle + Written by + + + + Network File System (NFS) + + NFS + Among the many different file systems that FreeBSD supports + is the Network File System, also known as NFS. NFS allows a system to share directories and + files with others over a network. By using NFS, users and programs can + access files on remote systems almost as if they were local + files. + + Some of the most notable benefits that + NFS can provide are: + + + + Local workstations use less disk space because commonly + used data can be stored on a single machine and still remain + accessible to others over the network. + + + + There is no need for users to have separate home + directories on every network machine. Home directories + could be set up on the NFS server and + made available throughout the network. + + + + Storage devices such as floppy disks, CDROM drives, and + &iomegazip; drives can be used by other machines on the network. + This may reduce the number of removable media drives + throughout the network. + + + + + How <acronym>NFS</acronym> Works + + NFS consists of at least two main + parts: a server and one or more clients. The client remotely + accesses the data that is stored on the server machine. In + order for this to function properly a few processes have to be + configured and running. + + The server has to be running the following daemons: + + NFS + server + + + file server + UNIX clients + + + + rpcbind + + + mountd + + + nfsd + + + + + + + + + + Daemon + Description + + + + + nfsd + The NFS daemon which services + requests from the NFS + clients. + + + mountd + The NFS mount daemon which carries out + the requests that &man.nfsd.8; passes on to it. + + + rpcbind + This daemon allows + NFS clients to discover which port + the NFS server is using. + + + + + + The client can also run a daemon, known as + nfsiod. The + nfsiod daemon services the requests + from the NFS server. This is optional, and + improves performance, but is not required for normal and + correct operation. See the &man.nfsiod.8; manual page for + more information. + + + + + Configuring <acronym>NFS</acronym> + + NFS + configuration + + + NFS configuration is a relatively + straightforward process. The processes that need to be + running can all start at boot time with a few modifications to + your /etc/rc.conf file. + + On the NFS server, make sure that the + following options are configured in the + /etc/rc.conf file: + + rpcbind_enable="YES" +nfs_server_enable="YES" +mountd_flags="-r" + + mountd runs automatically + whenever the NFS server is enabled. + + On the client, make sure this option is present in + /etc/rc.conf: + + nfs_client_enable="YES" + + The /etc/exports file specifies which + file systems NFS should export (sometimes + referred to as share). Each line in + /etc/exports specifies a file system to be + exported and which machines have access to that file system. + Along with what machines have access to that file system, + access options may also be specified. There are many such + options that can be used in this file but only a few will be + mentioned here. You can easily discover other options by + reading over the &man.exports.5; manual page. + + Here are a few example /etc/exports + entries: + + + NFS + export examples + + + The following examples give an idea of how to export + file systems, although the settings may be different depending + on your environment and network configuration. For instance, + to export the /cdrom directory to three + example machines that have the same domain name as the server + (hence the lack of a domain name for each) or have entries in + your /etc/hosts file. The + flag makes the exported file system + read-only. With this flag, the remote system will not be able + to write any changes to the exported file system. + + /cdrom -ro host1 host2 host3 + + The following line exports /home to + three hosts by IP address. This is a useful setup if you have + a private network without a DNS server + configured. Optionally the /etc/hosts + file could be configured for internal hostnames; please review + &man.hosts.5; for more information. The + flag allows the subdirectories to be + mount points. In other words, it will not mount the + subdirectories but permit the client to mount only the + directories that are required or needed. + + /home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4 + + The following line exports /a so that + two clients from different domains may access the file system. + The flag allows the + root user on the remote system to write + data on the exported file system as root. + If the -maproot=root flag is not specified, + then even if a user has root access on + the remote system, he will not be able to modify files on + the exported file system. + + /a -maproot=root host.example.com box.example.org + + In order for a client to access an exported file system, + the client must have permission to do so. Make sure the + client is listed in your /etc/exports + file. + + In /etc/exports, each line represents + the export information for one file system to one host. A + remote host can only be specified once per file system, and may + only have one default entry. For example, assume that + /usr is a single file system. The + following /etc/exports would be + invalid: + + # Invalid when /usr is one file system +/usr/src client +/usr/ports client + + One file system, /usr, has two lines + specifying exports to the same host, client. + The correct format for this situation is: + + /usr/src /usr/ports client + + The properties of one file system exported to a given host + must all occur on one line. Lines without a client specified + are treated as a single host. This limits how you can export + file systems, 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 file systems: + + # Export src and ports to client01 and client02, but only +# client01 has root privileges on it +/usr/src /usr/ports -maproot=root client01 +/usr/src /usr/ports client02 +# The client machines have root and can mount anywhere +# on /exports. Anyone in the world can mount /exports/obj read-only +/exports -alldirs -maproot=root client01 client02 +/exports/obj -ro + + The mountd daemon must be forced to + recheck the /etc/exports file whenever it has + been modified, so the changes can take effect. This can be + accomplished either by sending a HUP signal to the running daemon: + + &prompt.root; kill -HUP `cat /var/run/mountd.pid` + + or by invoking the mountd &man.rc.8; script + with the appropriate parameter: + + &prompt.root; /etc/rc.d/mountd reload + + Please refer to for more + information about using rc scripts. + + Alternatively, a reboot will make FreeBSD set everything + up properly. A reboot is not necessary though. + Executing the following commands as root + should start everything up. + + On the NFS server: + + &prompt.root; rpcbind +&prompt.root; nfsd -u -t -n 4 +&prompt.root; mountd -r + + On the NFS client: + + &prompt.root; nfsiod -n 4 + + Now everything should be ready to actually mount a remote file + system. In these examples the + server's name will be server and the client's + name will be client. If you only want to + temporarily mount a remote file system or would rather test the + configuration, just execute a command like this as root on the + client: + + NFS + mounting + + &prompt.root; mount server:/home /mnt + + This will mount the /home directory + on the server at /mnt on the client. If + everything is set up correctly you should be able to enter + /mnt on the client and see all the files + that are on the server. + + If you want to automatically mount a remote file system + each time the computer boots, add the file system to the + /etc/fstab file. Here is an example: + + server:/home /mnt nfs rw 0 0 + + The &man.fstab.5; manual page lists all the available + options. + + + + Practical Uses + + NFS has many practical uses. Some of + the more common ones are listed below: + + + NFS + uses + + + + Set several machines to share a CDROM or other media + among them. This is cheaper and often a more convenient + method to install software on multiple machines. + + + + On large networks, it might be more convenient to + configure a central NFS server in which + to store all the user home directories. These home + directories can then be exported to the network so that + users would always have the same home directory, + regardless of which workstation they log in to. + + + + Several machines could have a common + /usr/ports/distfiles directory. That + way, when you need to install a port on several machines, + you can quickly access the source without downloading it + on each machine. + + + + + + + + + Wylie + Stilwell + Contributed by + + + + + Chern + Lee + Rewritten by + + + + Automatic Mounts with <application>amd</application> + + amd + automatic mounter daemon + + &man.amd.8; (the automatic mounter daemon) + automatically mounts a + remote file system whenever a file or directory within that + file system is accessed. Filesystems that are inactive for a + period of time will also be automatically unmounted by + amd. Using + amd provides a simple alternative + to permanent mounts, as permanent mounts are usually listed in + /etc/fstab. + + amd operates by attaching + itself as an NFS server to the /host and + /net directories. When a file is accessed + within one of these directories, amd + looks up the corresponding remote mount and automatically mounts + it. /net is used to mount an exported + file system from an IP address, while /host + is used to mount an export from a remote hostname. + + An access to a file within + /host/foobar/usr would tell + amd to attempt to mount the + /usr export on the host + foobar. + + + Mounting an Export with <application>amd</application> + + You can view the available mounts of a remote host with + the showmount command. For example, to + view the mounts of a host named foobar, you + can use: + + &prompt.user; showmount -e foobar +Exports list on foobar: +/usr 10.10.10.0 +/a 10.10.10.0 +&prompt.user; cd /host/foobar/usr + + + As seen in the example, the showmount shows + /usr as an export. When changing directories to + /host/foobar/usr, amd + attempts to resolve the hostname foobar and + automatically mount the desired export. + + amd can be started by the + startup scripts by placing the following lines in + /etc/rc.conf: + + amd_enable="YES" + + Additionally, custom flags can be passed to + amd from the + amd_flags option. By default, + amd_flags is set to: + + amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map" + + The /etc/amd.map file defines the + default options that exports are mounted with. The + /etc/amd.conf file defines some of the more + advanced features of amd. + + Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more + information. + + + + + + + John + Lind + Contributed by + + + + Problems Integrating with Other Systems + + Certain Ethernet adapters for ISA PC systems have limitations + which can lead to serious network problems, particularly with NFS. + This difficulty is not specific to FreeBSD, but FreeBSD systems + are affected by it. + + The problem nearly always occurs when (FreeBSD) PC systems are + networked with high-performance workstations, such as those made + by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS + mount will work fine, and some operations may succeed, but + suddenly the server will seem to become unresponsive to the + client, even though requests to and from other systems continue to + be processed. This happens to the client system, whether the + client is the FreeBSD system or the workstation. On many systems, + there is no way to shut down the client gracefully once this + problem has manifested itself. The only solution is often to + reset the client, because the NFS situation cannot be + resolved. + + Though the correct solution is to get a + higher performance and capacity Ethernet adapter for the + FreeBSD system, there is a simple workaround that will allow + satisfactory operation. If the FreeBSD system is the + server, include the option + on the mount from the client. If the + FreeBSD system is the client, then mount + the NFS file system with the option . + These options may be specified using the fourth field of the + fstab entry on the client for automatic + mounts, or by using the parameter of the + &man.mount.8; command for manual mounts. + + It should be noted that there is a different problem, + sometimes mistaken for this one, when the NFS servers and + clients are on different networks. If that is the case, make + certain that your routers are routing the + necessary UDP information, or you will not get anywhere, no + matter what else you are doing. + + In the following examples, fastws is the host + (interface) name of a high-performance workstation, and + freebox is the host (interface) name of a FreeBSD + system with a lower-performance Ethernet adapter. Also, + /sharedfs will be the exported NFS + file system (see &man.exports.5;), and + /project will be the mount point on the + client for the exported file system. In all cases, note that + additional options, such as or + and may be desirable in + your application. + + Examples for the FreeBSD system (freebox) + as the client in /etc/fstab on + freebox: + + fastws:/sharedfs /project nfs rw,-r=1024 0 0 + + As a manual mount command on freebox: + + &prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /project + + Examples for the FreeBSD system as the server in + /etc/fstab on + fastws: + + freebox:/sharedfs /project nfs rw,-w=1024 0 0 + + As a manual mount command on fastws: + + &prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /project + + Nearly any 16-bit Ethernet adapter will allow operation + without the above restrictions on the read or write size. + + For anyone who cares, here is what happens when the + failure occurs, which also explains why it is unrecoverable. + NFS typically works with a block size of + 8 K (though it may do fragments of smaller sizes). Since + the maximum Ethernet packet is around 1500 bytes, the NFS + block gets split into multiple Ethernet + packets, even though it is still a single unit to the + upper-level code, and must be received, assembled, and + acknowledged as a unit. The + high-performance workstations can pump out the packets which + comprise the NFS unit one right after the other, just as close + together as the standard allows. On the smaller, lower + capacity cards, the later packets overrun the earlier packets + of the same unit before they can be transferred to the host + and the unit as a whole cannot be reconstructed or + acknowledged. As a result, the workstation will time out and + try again, but it will try again with the entire 8 K + unit, and the process will be repeated, ad infinitum. + + By keeping the unit size below the Ethernet packet size + limitation, we ensure that any complete Ethernet packet + received can be acknowledged individually, avoiding the + deadlock situation. + + Overruns may still occur when a high-performance + workstations is slamming data out to a PC system, but with the + better cards, such overruns are not guaranteed on NFS + units. When an overrun occurs, the units + affected will be retransmitted, and there will be a fair + chance that they will be received, assembled, and + acknowledged. + + + + + + + + Bill + Swingle + Written by + + + + + Eric + Ogren + Enhanced by + + + Udo + Erdelhoff + + + + Network Information System (NIS/YP) + + + What Is It? + NIS + Solaris + HP-UX + AIX + Linux + NetBSD + OpenBSD + + NIS, + which stands for Network Information Services, was developed + by Sun Microsystems to centralize administration of &unix; + (originally &sunos;) systems. It has now essentially become + an industry standard; all major &unix; like systems + (&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD, + etc) support NIS. + + yellow pagesNIS + + NIS + was formerly known as Yellow Pages, but because of trademark + issues, Sun changed the name. The old term (and yp) is still + often seen and used. + + + NIS + domains + + + It is a RPC-based client/server system that allows a group + of machines within an NIS domain to share a common set of + configuration files. This permits a system administrator to + set up NIS client systems with only minimal configuration data + and add, remove or modify configuration data from a single + location. + + Windows NT + + It is similar to the &windowsnt; domain system; although + the internal implementation of the two are not at all similar, + the basic functionality can be compared. + + + + Terms/Processes You Should Know + + There are several terms and several important user + processes that you will come across when attempting to + implement NIS on FreeBSD, whether you are trying to create an + NIS server or act as an NIS client: + + + rpcbind + + + portmap + + + + + + + + + + Term + Description + + + + + NIS domainname + + An NIS master server and all of its clients + (including its slave servers) have a NIS domainname. + Similar to an &windowsnt; domain name, the NIS + domainname does not have anything to do with + DNS. + + + rpcbind + + Must be running in order to enable + RPC (Remote Procedure Call, a + network protocol used by NIS). If + rpcbind is not running, it + will be impossible to run an NIS server, or to act as + an NIS client. + + + ypbind + + Binds an NIS client to its NIS + server. It will take the NIS domainname from the + system, and using RPC, connect to + the server. ypbind is the + core of client-server communication in an NIS + environment; if ypbind dies + on a client machine, it will not be able to access the + NIS server. + + + ypserv + Should only be running on NIS servers; this is + the NIS server process itself. If &man.ypserv.8; + dies, then the server will no longer be able to + respond to NIS requests (hopefully, there is a slave + server to take over for it). There are some + implementations of NIS (but not the FreeBSD one), that + do not try to reconnect to another server if the + server it used before dies. Often, the only thing + that helps in this case is to restart the server + process (or even the whole server) or the + ypbind process on the + client. + + + + rpc.yppasswdd + Another process that should only be running on + NIS master servers; this is a daemon that will allow NIS + clients to change their NIS passwords. If this daemon + is not running, users will have to login to the NIS + master server and change their passwords there. + + + + + + + + + + How Does It Work? + + There are three types of hosts in an NIS environment: + master servers, slave servers, and clients. Servers act as a + central repository for host configuration information. Master + servers hold the authoritative copy of this information, while + slave servers mirror this information for redundancy. Clients + rely on the servers to provide this information to + them. + + Information in many files can be shared in this manner. + The master.passwd, + group, and hosts + files are commonly shared via NIS. Whenever a process on a + client needs information that would normally be found in these + files locally, it makes a query to the NIS server that it is + bound to instead. + + + Machine Types + + + + NIS + master server + + + A NIS master server. This + server, analogous to a &windowsnt; primary domain + controller, maintains the files used by all of the NIS + clients. The passwd, + group, and other various files used + by the NIS clients live on the master server. + + It is possible for one machine to be an NIS + master server for more than one NIS domain. However, + this will not be covered in this introduction, which + assumes a relatively small-scale NIS + environment. + + + NIS + slave server + + + NIS slave servers. Similar to + the &windowsnt; backup domain controllers, NIS slave + servers maintain copies of the NIS master's data files. + NIS slave servers provide the redundancy, which is + needed in important environments. They also help to + balance the load of the master server: NIS Clients + always attach to the NIS server whose response they get + first, and this includes slave-server-replies. + + + NIS + client + + + NIS clients. NIS clients, like + most &windowsnt; workstations, authenticate against the + NIS server (or the &windowsnt; domain controller in the + &windowsnt; workstations case) to log on. + + + + + + + Using NIS/YP + + This section will deal with setting up a sample NIS + environment. + + This section assumes that you are running + FreeBSD 3.3 or later. The instructions given here will + probably work for any version of FreeBSD + greater than 3.0, but there are no guarantees that this is + true. + + + + Planning + + Let us assume that you are the administrator of a small + university lab. This lab, which consists of 15 FreeBSD + machines, currently has no centralized point of + administration; each machine has its own + /etc/passwd and + /etc/master.passwd. These files are + kept in sync with each other only through manual + intervention; currently, when you add a user to the lab, you + must run adduser on all 15 machines. + Clearly, this has to change, so you have decided to convert + the lab to use NIS, using two of the machines as + servers. + + Therefore, the configuration of the lab now looks something + like: + + + + + + Machine name + IP address + Machine role + + + + + ellington + 10.0.0.2 + NIS master + + + coltrane + 10.0.0.3 + NIS slave + + + basie + 10.0.0.4 + Faculty workstation + + + bird + 10.0.0.5 + Client machine + + + cli[1-11] + 10.0.0.[6-17] + Other client machines + + + + + + If you are setting up a NIS scheme for the first time, it + is a good idea to think through how you want to go about it. No + matter what the size of your network, there are a few decisions + that need to be made. + + + Choosing a NIS Domain Name + + + NIS + domainname + + This might not be the domainname that + you are used to. It is more accurately called the + NIS domainname. When a client broadcasts + its requests for info, it includes the name of the NIS + domain that it is part of. This is how multiple servers + on one network can tell which server should answer which + request. Think of the NIS domainname as the name for a + group of hosts that are related in some way. + + Some organizations choose to use their Internet + domainname for their NIS domainname. This is not + recommended as it can cause confusion when trying to debug + network problems. The NIS domainname should be unique + within your network and it is helpful if it describes the + group of machines it represents. For example, the Art + department at Acme Inc. might be in the + acme-art NIS domain. For this example, + assume you have chosen the name + test-domain. + + SunOS + However, some operating systems (notably &sunos;) use + their NIS domain name as their Internet domain name. If one + or more machines on your network have this restriction, you + must use the Internet domain name as + your NIS domain name. + + + + Physical Server Requirements + + There are several things to keep in mind when choosing + a machine to use as a NIS server. One of the unfortunate + things about NIS is the level of dependency the clients + have on the server. If a client cannot contact the server + for its NIS domain, very often the machine becomes + unusable. The lack of user and group information causes + most systems to temporarily freeze up. With this in mind + you should make sure to choose a machine that will not be + prone to being rebooted regularly, or one that might be + used for development. The NIS server should ideally be a + stand alone machine whose sole purpose in life is to be an + NIS server. If you have a network that is not very + heavily used, it is acceptable to put the NIS server on a + machine running other services, just keep in mind that if + the NIS server becomes unavailable, it will affect + all of your NIS clients + adversely. + + + + + NIS Servers + + The canonical copies of all NIS information are stored + on a single machine called the NIS master server. The + databases used to store the information are called NIS maps. + In FreeBSD, these maps are stored in + /var/yp/[domainname] where + [domainname] is the name of the NIS + domain being served. A single NIS server can support + several domains at once, therefore it is possible to have + several such directories, one for each supported domain. + Each domain will have its own independent set of + maps. + + NIS master and slave servers handle all NIS requests + with the ypserv daemon. + ypserv is responsible for receiving + incoming requests from NIS clients, translating the + requested domain and map name to a path to the corresponding + database file and transmitting data from the database back + to the client. + + + Setting Up a NIS Master Server + + NIS + server configuration + + Setting up a master NIS server can be relatively + straight forward, depending on your needs. FreeBSD comes + with support for NIS out-of-the-box. All you need is to + add the following lines to + /etc/rc.conf, and FreeBSD will do the + rest for you. + + + + nisdomainname="test-domain" + This line will set the NIS domainname to + test-domain + upon network setup (e.g. after reboot). + + + nis_server_enable="YES" + This will tell FreeBSD to start up the NIS server processes + when the networking is next brought up. + + + nis_yppasswdd_enable="YES" + This will enable the rpc.yppasswdd + daemon which, as mentioned above, will allow users to + change their NIS password from a client machine. + + + + + Depending on your NIS setup, you may need to add + further entries. See the section about NIS + servers that are also NIS clients, below, for + details. + + + Now, all you have to do is to run the command + /etc/netstart as superuser. It will + set up everything for you, using the values you defined in + /etc/rc.conf. + + + + Initializing the NIS Maps + + NIS + maps + + The NIS maps are database files, + that are kept in the /var/yp + directory. They are generated from configuration files in + the /etc directory of the NIS master, + with one exception: the + /etc/master.passwd file. This is for + a good reason, you do not want to propagate passwords to + your root and other administrative + accounts to all the servers in the NIS domain. Therefore, + before we initialize the NIS maps, you should: + + &prompt.root; cp /etc/master.passwd /var/yp/master.passwd +&prompt.root; cd /var/yp +&prompt.root; vi master.passwd + + You should remove all entries regarding system + accounts (bin, + tty, kmem, + games, etc), as well as any accounts + that you do not want to be propagated to the NIS clients + (for example root and any other UID 0 + (superuser) accounts). + + Make sure the + /var/yp/master.passwd is neither group + nor world readable (mode 600)! Use the + chmod command, if appropriate. + + Tru64 UNIX + + When you have finished, it is time to initialize the + NIS maps! FreeBSD includes a script named + ypinit to do this for you (see its + manual page for more information). Note that this script + is available on most &unix; Operating Systems, but not on + all. On Digital UNIX/Compaq Tru64 UNIX it is called + ypsetup. Because we are generating + maps for an NIS master, we are going to pass the + option to ypinit. + To generate the NIS maps, assuming you already performed + the steps above, run: + + ellington&prompt.root; ypinit -m test-domain +Server Type: MASTER Domain: test-domain +Creating an YP server will require that you answer a few questions. +Questions will all be asked at the beginning of the procedure. +Do you want this procedure to quit on non-fatal errors? [y/n: n] n +Ok, please remember to go back and redo manually whatever fails. +If you don't, something might not work. +At this point, we have to construct a list of this domains YP servers. +rod.darktech.org is already known as master server. +Please continue to add any slave servers, one per line. When you are +done with the list, type a <control D>. +master server : ellington +next host to add: coltrane +next host to add: ^D +The current list of NIS servers looks like this: +ellington +coltrane +Is this correct? [y/n: y] y + +[..output from map generation..] + +NIS Map update completed. +ellington has been setup as an YP master server without any errors. + + ypinit should have created + /var/yp/Makefile from + /var/yp/Makefile.dist. + When created, this file assumes that you are operating + in a single server NIS environment with only FreeBSD + machines. Since test-domain has + a slave server as well, you must edit + /var/yp/Makefile: + + ellington&prompt.root; vi /var/yp/Makefile + + You should comment out the line that says + + NOPUSH = "True" + + (if it is not commented out already). + + + + Setting up a NIS Slave Server + + NIS + slave server + + Setting up an NIS slave server is even more simple than + setting up the master. Log on to the slave server and edit the + file /etc/rc.conf as you did before. + The only difference is that we now must use the + option when running ypinit. + The option requires the name of the NIS + master be passed to it as well, so our command line looks + like: + + coltrane&prompt.root; ypinit -s ellington test-domain + +Server Type: SLAVE Domain: test-domain Master: ellington + +Creating an YP server will require that you answer a few questions. +Questions will all be asked at the beginning of the procedure. + +Do you want this procedure to quit on non-fatal errors? [y/n: n] n + +Ok, please remember to go back and redo manually whatever fails. +If you don't, something might not work. +There will be no further questions. The remainder of the procedure +should take a few minutes, to copy the databases from ellington. +Transferring netgroup... +ypxfr: Exiting: Map successfully transferred +Transferring netgroup.byuser... +ypxfr: Exiting: Map successfully transferred +Transferring netgroup.byhost... +ypxfr: Exiting: Map successfully transferred +Transferring master.passwd.byuid... +ypxfr: Exiting: Map successfully transferred +Transferring passwd.byuid... +ypxfr: Exiting: Map successfully transferred +Transferring passwd.byname... +ypxfr: Exiting: Map successfully transferred +Transferring group.bygid... +ypxfr: Exiting: Map successfully transferred +Transferring group.byname... +ypxfr: Exiting: Map successfully transferred +Transferring services.byname... +ypxfr: Exiting: Map successfully transferred +Transferring rpc.bynumber... +ypxfr: Exiting: Map successfully transferred +Transferring rpc.byname... +ypxfr: Exiting: Map successfully transferred +Transferring protocols.byname... +ypxfr: Exiting: Map successfully transferred +Transferring master.passwd.byname... +ypxfr: Exiting: Map successfully transferred +Transferring networks.byname... +ypxfr: Exiting: Map successfully transferred +Transferring networks.byaddr... +ypxfr: Exiting: Map successfully transferred +Transferring netid.byname... +ypxfr: Exiting: Map successfully transferred +Transferring hosts.byaddr... +ypxfr: Exiting: Map successfully transferred +Transferring protocols.bynumber... +ypxfr: Exiting: Map successfully transferred +Transferring ypservers... +ypxfr: Exiting: Map successfully transferred +Transferring hosts.byname... +ypxfr: Exiting: Map successfully transferred + +coltrane has been setup as an YP slave server without any errors. +Don't forget to update map ypservers on ellington. + + You should now have a directory called + /var/yp/test-domain. Copies of the NIS + master server's maps should be in this directory. You will + need to make sure that these stay updated. The following + /etc/crontab entries on your slave + servers should do the job: + + 20 * * * * root /usr/libexec/ypxfr passwd.byname +21 * * * * root /usr/libexec/ypxfr passwd.byuid + + These two lines force the slave to sync its maps with + the maps on the master server. Although these entries are + not mandatory, since the master server attempts to ensure + any changes to its NIS maps are communicated to its slaves + and because password information is vital to systems + depending on the server, it is a good idea to force the + updates. This is more important on busy networks where map + updates might not always complete. + + Now, run the command /etc/netstart on the + slave server as well, which again starts the NIS server. + + + + + NIS Clients + + An NIS client establishes what is called a binding to a + particular NIS server using the + ypbind daemon. + ypbind checks the system's default + domain (as set by the domainname command), + and begins broadcasting RPC requests on the local network. + These requests specify the name of the domain for which + ypbind is attempting to establish a binding. + If a server that has been configured to serve the requested + domain receives one of the broadcasts, it will respond to + ypbind, which will record the server's + address. If there are several servers available (a master and + several slaves, for example), ypbind will + use the address of the first one to respond. From that point + on, the client system will direct all of its NIS requests to + that server. ypbind will + occasionally ping the server to make sure it is + still up and running. If it fails to receive a reply to one of + its pings within a reasonable amount of time, + ypbind will mark the domain as unbound and + begin broadcasting again in the hopes of locating another + server. + + + Setting Up a NIS Client + + NIS + client configuration + + Setting up a FreeBSD machine to be a NIS client is fairly + straightforward. + + + + Edit the file /etc/rc.conf and + add the following lines in order to set the NIS domainname + and start ypbind upon network + startup: + + nisdomainname="test-domain" +nis_client_enable="YES" + + + + To import all possible password entries from the NIS + server, remove all user accounts from your + /etc/master.passwd file and use + vipw to add the following line to + the end of the file: + + +::::::::: + + + This line will afford anyone with a valid account in + the NIS server's password maps an account. There are + many ways to configure your NIS client by changing this + line. See the netgroups + section below for more information. + For more detailed reading see O'Reilly's book on + Managing NFS and NIS. + + + + You should keep at least one local account (i.e. + not imported via NIS) in your + /etc/master.passwd and this + account should also be a member of the group + wheel. If there is something + wrong with NIS, this account can be used to log in + remotely, become root, and fix things. + + + + + To import all possible group entries from the NIS + server, add this line to your + /etc/group file: + + +:*:: + + + + After completing these steps, you should be able to run + ypcat passwd and see the NIS server's + passwd map. + + + + + + NIS Security + + In general, any remote user can issue an RPC to + &man.ypserv.8; and retrieve the contents of your NIS maps, + provided the remote user knows your domainname. To prevent + such unauthorized transactions, &man.ypserv.8; supports a + feature called securenets which can be used to + restrict access to a given set of hosts. At startup, + &man.ypserv.8; will attempt to load the securenets information + from a file called + /var/yp/securenets. + + + This path varies depending on the path specified with the + option. This file contains entries that + consist of a network specification and a network mask separated + by white space. Lines starting with # are + considered to be comments. A sample securenets file might look + like this: + + + # allow connections from local host -- mandatory +127.0.0.1 255.255.255.255 +# allow connections from any host +# on the 192.168.128.0 network +192.168.128.0 255.255.255.0 +# allow connections from any host +# between 10.0.0.0 to 10.0.15.255 +# this includes the machines in the testlab +10.0.0.0 255.255.240.0 + + If &man.ypserv.8; receives a request from an address that + matches one of these rules, it will process the request + normally. If the address fails to match a rule, the request + will be ignored and a warning message will be logged. If the + /var/yp/securenets file does not exist, + ypserv will allow connections from any + host. + + The ypserv program also has support for + Wietse Venema's TCP Wrapper package. + This allows the administrator to use the + TCP Wrapper configuration files for + access control instead of + /var/yp/securenets. + + + While both of these access control mechanisms provide some + security, they, like the privileged port test, are + vulnerable to IP spoofing attacks. All + NIS-related traffic should be blocked at your firewall. + + Servers using /var/yp/securenets + may fail to serve legitimate NIS clients with archaic TCP/IP + implementations. Some of these implementations set all + host bits to zero when doing broadcasts and/or fail to + observe the subnet mask when calculating the broadcast + address. While some of these problems can be fixed by + changing the client configuration, other problems may force + the retirement of the client systems in question or the + abandonment of /var/yp/securenets. + + Using /var/yp/securenets on a + server with such an archaic implementation of TCP/IP is a + really bad idea and will lead to loss of NIS functionality + for large parts of your network. + + TCP Wrappers + The use of the TCP Wrapper + package increases the latency of your NIS server. The + additional delay may be long enough to cause timeouts in + client programs, especially in busy networks or with slow + NIS servers. If one or more of your client systems + suffers from these symptoms, you should convert the client + systems in question into NIS slave servers and force them + to bind to themselves. + + + + + Barring Some Users from Logging On + + In our lab, there is a machine basie that + is supposed to be a faculty only workstation. We do not want + to take this machine out of the NIS domain, yet the + passwd file on the master NIS server + contains accounts for both faculty and students. What can we + do? + + There is a way to bar specific users from logging on to a + machine, even if they are present in the NIS database. To do + this, all you must do is add + -username to the + end of the /etc/master.passwd file on the + client machine, where username is + the username of the user you wish to bar from logging in. + This should preferably be done using vipw, + since vipw will sanity check your changes + to /etc/master.passwd, as well as + automatically rebuild the password database when you finish + editing. For example, if we wanted to bar user + bill from logging on to + basie we would: + + basie&prompt.root; vipw +[add -bill to the end, exit] +vipw: rebuilding the database... +vipw: done + +basie&prompt.root; cat /etc/master.passwd + +root:[password]:0:0::0:0:The super-user:/root:/bin/csh +toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh +daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin +operator:*:2:5::0:0:System &:/:/sbin/nologin +bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin +tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin +kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin +games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin +news:*:8:8::0:0:News Subsystem:/:/sbin/nologin +man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin +bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin +uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico +xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin +pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin +nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin ++::::::::: +-bill + +basie&prompt.root; + + + + + + + Udo + Erdelhoff + Contributed by + + + + + Using Netgroups + netgroups + + The method shown in the previous section works reasonably + well if you need special rules for a very small number of + users and/or machines. On larger networks, you + will forget to bar some users from logging + onto sensitive machines, or you may even have to modify each + machine separately, thus losing the main benefit of NIS: + centralized administration. + + The NIS developers' solution for this problem is called + netgroups. Their purpose and semantics + can be compared to the normal groups used by &unix; file + systems. The main differences are the lack of a numeric ID + and the ability to define a netgroup by including both user + accounts and other netgroups. + + Netgroups were developed to handle large, complex networks + with hundreds of users and machines. On one hand, this is + a Good Thing if you are forced to deal with such a situation. + On the other hand, this complexity makes it almost impossible to + explain netgroups with really simple examples. The example + used in the remainder of this section demonstrates this + problem. + + Let us assume that your successful introduction of NIS in + your laboratory caught your superiors' interest. Your next + job is to extend your NIS domain to cover some of the other + machines on campus. The two tables contain the names of the + new users and new machines as well as brief descriptions of + them. + + + + + + User Name(s) + Description + + + + + + alpha, beta + Normal employees of the IT department + + + + charlie, delta + The new apprentices of the IT department + + + + echo, foxtrott, golf, ... + Ordinary employees + + + + able, baker, ... + The current interns + + + + + + + + + + Machine Name(s) + Description + + + + + + + + war, death, + famine, + pollution + Your most important servers. Only the IT + employees are allowed to log onto these + machines. + + + + + pride, greed, + envy, wrath, + lust, sloth + Less important servers. All members of the IT + department are allowed to login onto these + machines. + + + + one, two, + three, four, + ... + + Ordinary workstations. Only the + real employees are allowed to use + these machines. + + + + trashcan + A very old machine without any critical data. + Even the intern is allowed to use this box. + + + + + + If you tried to implement these restrictions by separately + blocking each user, you would have to add one + -user line to + each system's passwd for each user who is + not allowed to login onto that system. If you forget just one + entry, you could be in trouble. It may be feasible to do this + correctly during the initial setup, however you + will eventually forget to add the lines + for new users during day-to-day operations. After all, Murphy + was an optimist. + + Handling this situation with netgroups offers several + advantages. Each user need not be handled separately; you + assign a user to one or more netgroups and allow or forbid + logins for all members of the netgroup. If you add a new + machine, you will only have to define login restrictions for + netgroups. If a new user is added, you will only have to add + the user to one or more netgroups. Those changes are + independent of each other: no more for each combination + of user and machine do... If your NIS setup is planned + carefully, you will only have to modify exactly one central + configuration file to grant or deny access to machines. + + The first step is the initialization of the NIS map + netgroup. FreeBSD's &man.ypinit.8; does not create this map by + default, but its NIS implementation will support it once it has + been created. To create an empty map, simply type + + ellington&prompt.root; vi /var/yp/netgroup + + and start adding content. For our example, we need at + least four netgroups: IT employees, IT apprentices, normal + employees and interns. + + IT_EMP (,alpha,test-domain) (,beta,test-domain) +IT_APP (,charlie,test-domain) (,delta,test-domain) +USERS (,echo,test-domain) (,foxtrott,test-domain) \ + (,golf,test-domain) +INTERNS (,able,test-domain) (,baker,test-domain) + + IT_EMP, IT_APP etc. + are the names of the netgroups. Each bracketed group adds + one or more user accounts to it. The three fields inside a + group are: + + + + The name of the host(s) where the following items are + valid. If you do not specify a hostname, the entry is + valid on all hosts. If you do specify a hostname, you + will enter a realm of darkness, horror and utter confusion. + + + + The name of the account that belongs to this + netgroup. + + + + The NIS domain for the account. You can import + accounts from other NIS domains into your netgroup if you + are one of the unlucky fellows with more than one NIS + domain. + + + + Each of these fields can contain wildcards. See + &man.netgroup.5; for details. + + + netgroups + Netgroup names longer than 8 characters should not be + used, especially if you have machines running other + operating systems within your NIS domain. The names are + case sensitive; using capital letters for your netgroup + names is an easy way to distinguish between user, machine + and netgroup names. + + Some NIS clients (other than FreeBSD) cannot handle + netgroups with a large number of entries. For example, some + older versions of &sunos; start to cause trouble if a netgroup + contains more than 15 entries. You can + circumvent this limit by creating several sub-netgroups with + 15 users or less and a real netgroup that consists of the + sub-netgroups: + + BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] +BIGGRP2 (,joe16,domain) (,joe17,domain) [...] +BIGGRP3 (,joe31,domain) (,joe32,domain) +BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3 + + You can repeat this process if you need more than 225 + users within a single netgroup. + + + Activating and distributing your new NIS map is + easy: + + ellington&prompt.root; cd /var/yp +ellington&prompt.root; make + + This will generate the three NIS maps + netgroup, + netgroup.byhost and + netgroup.byuser. Use &man.ypcat.1; to + check if your new NIS maps are available: + + ellington&prompt.user; ypcat -k netgroup +ellington&prompt.user; ypcat -k netgroup.byhost +ellington&prompt.user; ypcat -k netgroup.byuser + + The output of the first command should resemble the + contents of /var/yp/netgroup. The second + command will not produce output if you have not specified + host-specific netgroups. The third command can be used to + get the list of netgroups for a user. + + The client setup is quite simple. To configure the server + war, you only have to start + &man.vipw.8; and replace the line + + +::::::::: + + with + + +@IT_EMP::::::::: + + Now, only the data for the users defined in the netgroup + IT_EMP is imported into + war's password database and only + these users are allowed to login. + + Unfortunately, this limitation also applies to the + ~ function of the shell and all routines + converting between user names and numerical user IDs. In + other words, cd + ~user will not work, + ls -l will show the numerical ID instead of + the username and find . -user joe -print + will fail with No such user. To fix + this, you will have to import all user entries + without allowing them to login onto your + servers. + + This can be achieved by adding another line to + /etc/master.passwd. This line should + contain: + + +:::::::::/sbin/nologin, meaning + Import all entries but replace the shell with + /sbin/nologin in the imported + entries. You can replace any field in the + passwd entry by placing a default value in + your /etc/master.passwd. + + + + Make sure that the line + +:::::::::/sbin/nologin is placed after + +@IT_EMP:::::::::. Otherwise, all user + accounts imported from NIS will have /sbin/nologin as their + login shell. + + + After this change, you will only have to change one NIS + map if a new employee joins the IT department. You could use + a similar approach for the less important servers by replacing + the old +::::::::: in their local version + of /etc/master.passwd with something like + this: + + +@IT_EMP::::::::: ++@IT_APP::::::::: ++:::::::::/sbin/nologin + + The corresponding lines for the normal workstations + could be: + + +@IT_EMP::::::::: ++@USERS::::::::: ++:::::::::/sbin/nologin + + And everything would be fine until there is a policy + change a few weeks later: The IT department starts hiring + interns. The IT interns are allowed to use the normal + workstations and the less important servers; and the IT + apprentices are allowed to login onto the main servers. You + add a new netgroup IT_INTERN, add the new + IT interns to this netgroup and start to change the + configuration on each and every machine... As the old saying + goes: Errors in centralized planning lead to global + mess. + + NIS' ability to create netgroups from other netgroups can + be used to prevent situations like these. One possibility + is the creation of role-based netgroups. For example, you + could create a netgroup called + BIGSRV to define the login + restrictions for the important servers, another netgroup + called SMALLSRV for the less + important servers and a third netgroup called + USERBOX for the normal + workstations. Each of these netgroups contains the netgroups + that are allowed to login onto these machines. The new + entries for your NIS map netgroup should look like this: + + BIGSRV IT_EMP IT_APP +SMALLSRV IT_EMP IT_APP ITINTERN +USERBOX IT_EMP ITINTERN USERS + + This method of defining login restrictions works + reasonably well if you can define groups of machines with + identical restrictions. Unfortunately, this is the exception + and not the rule. Most of the time, you will need the ability + to define login restrictions on a per-machine basis. + + Machine-specific netgroup definitions are the other + possibility to deal with the policy change outlined above. In + this scenario, the /etc/master.passwd of + each box contains two lines starting with +. + The first of them adds a netgroup with the accounts allowed to + login onto this machine, the second one adds all other + accounts with /sbin/nologin as shell. It + is a good idea to use the ALL-CAPS version of + the machine name as the name of the netgroup. In other words, + the lines should look like this: + + +@BOXNAME::::::::: ++:::::::::/sbin/nologin + + Once you have completed this task for all your machines, + you will not have to modify the local versions of + /etc/master.passwd ever again. All + further changes can be handled by modifying the NIS map. Here + is an example of a possible netgroup map for this + scenario with some additional goodies: + + # Define groups of users first +IT_EMP (,alpha,test-domain) (,beta,test-domain) +IT_APP (,charlie,test-domain) (,delta,test-domain) +DEPT1 (,echo,test-domain) (,foxtrott,test-domain) +DEPT2 (,golf,test-domain) (,hotel,test-domain) +DEPT3 (,india,test-domain) (,juliet,test-domain) +ITINTERN (,kilo,test-domain) (,lima,test-domain) +D_INTERNS (,able,test-domain) (,baker,test-domain) +# +# Now, define some groups based on roles +USERS DEPT1 DEPT2 DEPT3 +BIGSRV IT_EMP IT_APP +SMALLSRV IT_EMP IT_APP ITINTERN +USERBOX IT_EMP ITINTERN USERS +# +# And a groups for a special tasks +# Allow echo and golf to access our anti-virus-machine +SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain) +# +# machine-based netgroups +# Our main servers +WAR BIGSRV +FAMINE BIGSRV +# User india needs access to this server +POLLUTION BIGSRV (,india,test-domain) +# +# This one is really important and needs more access restrictions +DEATH IT_EMP +# +# The anti-virus-machine mentioned above +ONE SECURITY +# +# Restrict a machine to a single user +TWO (,hotel,test-domain) +# [...more groups to follow] + + If you are using some kind of database to manage your user + accounts, you should be able to create the first part of the + map with your database's report tools. This way, new users + will automatically have access to the boxes. + + One last word of caution: It may not always be advisable + to use machine-based netgroups. If you are deploying a couple of + dozen or even hundreds of identical machines for student labs, + you should use role-based netgroups instead of machine-based + netgroups to keep the size of the NIS map within reasonable + limits. + + + + Important Things to Remember + + There are still a couple of things that you will need to do + differently now that you are in an NIS environment. + + + + Every time you wish to add a user to the lab, you + must add it to the master NIS server only, + and you must remember to rebuild the NIS + maps. If you forget to do this, the new user will + not be able to login anywhere except on the NIS master. + For example, if we needed to add a new user + jsmith to the lab, we would: + + &prompt.root; pw useradd jsmith +&prompt.root; cd /var/yp +&prompt.root; make test-domain + + You could also run adduser jsmith instead + of pw useradd jsmith. + + + Keep the administration accounts out of the + NIS maps. You do not want to be propagating + administrative accounts and passwords to machines that + will have users that should not have access to those + accounts. + + + Keep the NIS master and slave secure, and + minimize their downtime. If somebody either + hacks or simply turns off these machines, they have + effectively rendered many people without the ability to + login to the lab. + + This is the chief weakness of any centralized administration + system. If you do + not protect your NIS servers, you will have a lot of angry + users! + + + + + + NIS v1 Compatibility + + FreeBSD's ypserv has some + support for serving NIS v1 clients. FreeBSD's NIS + implementation only uses the NIS v2 protocol, however other + implementations include support for the v1 protocol for + backwards compatibility with older systems. The + ypbind daemons supplied with these + systems will try to establish a binding to an NIS v1 server + even though they may never actually need it (and they may + persist in broadcasting in search of one even after they + receive a response from a v2 server). Note that while support + for normal client calls is provided, this version of + ypserv does not handle v1 map + transfer requests; consequently, it cannot be used as a master + or slave in conjunction with older NIS servers that only + support the v1 protocol. Fortunately, there probably are not + any such servers still in use today. + + + + NIS Servers That Are Also NIS Clients + + Care must be taken when running + ypserv in a multi-server domain + where the server machines are also NIS clients. It is + generally a good idea to force the servers to bind to + themselves rather than allowing them to broadcast bind + requests and possibly become bound to each other. Strange + failure modes can result if one server goes down and others + are dependent upon it. Eventually all the clients will time + out and attempt to bind to other servers, but the delay + involved can be considerable and the failure mode is still + present since the servers might bind to each other all over + again. + + You can force a host to bind to a particular server by running + ypbind with the + flag. If you do not want to do this manually each time you + reboot your NIS server, you can add the following lines to + your /etc/rc.conf: + + nis_client_enable="YES" # run client stuff as well +nis_client_flags="-S NIS domain,server" + + See &man.ypbind.8; for further information. + + + + Password Formats + + NIS + password formats + + One of the most common issues that people run into when trying + to implement NIS is password format compatibility. If your NIS + server is using DES encrypted passwords, it will only support + clients that are also using DES. For example, if you have + &solaris; NIS clients in your network, then you will almost certainly + need to use DES encrypted passwords. + + To check which format your servers + and clients are using, look at /etc/login.conf. + If the host is configured to use DES encrypted passwords, then the + default class will contain an entry like this: + + default:\ + :passwd_format=des:\ + :copyright=/etc/COPYRIGHT:\ + [Further entries elided] + + Other possible values for the passwd_format + capability include blf and md5 + (for Blowfish and MD5 encrypted passwords, respectively). + + If you have made changes to + /etc/login.conf, you will also need to + rebuild the login capability database, which is achieved by + running the following command as + root: + + &prompt.root; cap_mkdb /etc/login.conf + + The format of passwords already in + /etc/master.passwd will not be updated + until a user changes his password for the first time + after the login capability database is + rebuilt. + + Next, in order to ensure that passwords are encrypted with + the format that you have chosen, you should also check that + the crypt_default in + /etc/auth.conf gives precedence to your + chosen password format. To do this, place the format that you + have chosen first in the list. For example, when using DES + encrypted passwords, the entry would be: + + crypt_default = des blf md5 + + Having followed the above steps on each of the &os; based + NIS servers and clients, you can be sure that they all agree + on which password format is used within your network. If you + have trouble authenticating on an NIS client, this is a pretty + good place to start looking for possible problems. Remember: + if you want to deploy an NIS server for a heterogenous + network, you will probably have to use DES on all systems + because it is the lowest common standard. + + + + + + + + Greg + Sutter + Written by + + + + Automatic Network Configuration (DHCP) + + + What Is DHCP? + + Dynamic Host Configuration Protocol + DHCP + + + Internet Software Consortium (ISC) + + + DHCP, the Dynamic Host Configuration Protocol, describes + the means by which a system can connect to a network and obtain the + necessary information for communication upon that network. FreeBSD + versions prior to 6.0 use the ISC (Internet Software + Consortium) DHCP client (&man.dhclient.8;) implementation. + Later versions use the OpenBSD dhclient + taken from OpenBSD 3.7. All + information here regarding dhclient is for + use with either of the ISC or OpenBSD DHCP clients. The DHCP + server is the one included in the ISC distribution. + + + + What This Section Covers + + This section describes both the client-side components of the ISC and OpenBSD DHCP client and + server-side components of the ISC DHCP system. The + client-side program, dhclient, comes + integrated within FreeBSD, and the server-side portion is + available from the net/isc-dhcp3-server port. The + &man.dhclient.8;, &man.dhcp-options.5;, and + &man.dhclient.conf.5; manual pages, in addition to the + references below, are useful resources. + + + + How It Works + UDP + When dhclient, the DHCP client, is + executed on the client machine, it begins broadcasting + requests for configuration information. By default, these + requests are on UDP port 68. The server replies on UDP 67, + giving the client an IP address and other relevant network + information such as netmask, router, and DNS servers. All of + this information comes in the form of a DHCP + lease and is only valid for a certain time + (configured by the DHCP server maintainer). In this manner, + stale IP addresses for clients no longer connected to the + network can be automatically reclaimed. + + DHCP clients can obtain a great deal of information from + the server. An exhaustive list may be found in + &man.dhcp-options.5;. + + + + FreeBSD Integration + + &os; fully integrates the ISC or OpenBSD DHCP client, + dhclient (according to the &os; version you run). DHCP client support is provided + within both the installer and the base system, obviating the need + for detailed knowledge of network configurations on any network + that runs a DHCP server. dhclient has been + included in all FreeBSD distributions since 3.2. + + sysinstall + + + DHCP is supported by + sysinstall. When configuring a + network interface within + sysinstall, the second question + asked is: Do you want to try DHCP configuration of + the interface?. Answering affirmatively will + execute dhclient, and if successful, will + fill in the network configuration information + automatically. + + There are two things you must do to have your system use + DHCP upon startup: + + DHCP + requirements + + + + Make sure that the bpf + device is compiled into your kernel. To do this, add + device bpf to your kernel + configuration file, and rebuild the kernel. For more + information about building kernels, see . The + bpf device is already part of + the GENERIC kernel that is supplied + with FreeBSD, so if you do not have a custom kernel, you + should not need to create one in order to get DHCP + working. + + For those who are particularly security conscious, + you should be warned that bpf + is also the device that allows packet sniffers to work + correctly (although they still have to be run as + root). bpf + is required to use DHCP, but if + you are very sensitive about security, you probably + should not add bpf to your + kernel in the expectation that at some point in the + future you will be using DHCP. + + + + Edit your /etc/rc.conf to + include the following: + + ifconfig_fxp0="DHCP" + + + Be sure to replace fxp0 with the + designation for the interface that you wish to dynamically + configure, as described in + . + + + If you are using a different location for + dhclient, or if you wish to pass additional + flags to dhclient, also include the + following (editing as necessary): + + dhcp_program="/sbin/dhclient" +dhcp_flags="" + + + + + DHCP + server + + The DHCP server, dhcpd, is included + as part of the net/isc-dhcp3-server port in the ports + collection. This port contains the ISC DHCP server and + documentation. + + + + Files + + DHCP + configuration files + + + /etc/dhclient.conf + dhclient requires a configuration file, + /etc/dhclient.conf. Typically the file + contains only comments, the defaults being reasonably sane. This + configuration file is described by the &man.dhclient.conf.5; + manual page. + + + /sbin/dhclient + dhclient is statically linked and + resides in /sbin. The &man.dhclient.8; + manual page gives more information about + dhclient. + + + /sbin/dhclient-script + dhclient-script is the FreeBSD-specific + DHCP client configuration script. It is described in + &man.dhclient-script.8;, but should not need any user + modification to function properly. + + + /var/db/dhclient.leases + The DHCP client keeps a database of valid leases in this + file, which is written as a log. &man.dhclient.leases.5; + gives a slightly longer description. + + + + + + Further Reading + + The DHCP protocol is fully described in + RFC 2131. + An informational resource has also been set up at + . + + + + Installing and Configuring a DHCP Server + + + What This Section Covers + + This section provides information on how to configure + a FreeBSD system to act as a DHCP server using the ISC + (Internet Software Consortium) implementation of the DHCP + server. + + The server is not provided as part of + FreeBSD, and so you will need to install the + net/isc-dhcp3-server + port to provide this service. See for + more information on using the Ports Collection. + + + + DHCP Server Installation + + DHCP + installation + + In order to configure your FreeBSD system as a DHCP + server, you will need to ensure that the &man.bpf.4; + device is compiled into your kernel. To do this, add + device bpf to your kernel + configuration file, and rebuild the kernel. For more + information about building kernels, see . + + The bpf device is already + part of the GENERIC kernel that is + supplied with FreeBSD, so you do not need to create a custom + kernel in order to get DHCP working. + + + Those who are particularly security conscious + should note that bpf + is also the device that allows packet sniffers to work + correctly (although such programs still need privileged + access). bpf + is required to use DHCP, but if + you are very sensitive about security, you probably + should not include bpf in your + kernel purely because you expect to use DHCP at some + point in the future. + + + The next thing that you will need to do is edit the sample + dhcpd.conf which was installed by the + net/isc-dhcp3-server port. + By default, this will be + /usr/local/etc/dhcpd.conf.sample, and you + should copy this to + /usr/local/etc/dhcpd.conf before proceeding + to make changes. + + + + Configuring the DHCP Server + + DHCP + dhcpd.conf + + dhcpd.conf is + comprised of declarations regarding subnets and hosts, and is + perhaps most easily explained using an example : + + option domain-name "example.com"; +option domain-name-servers 192.168.4.100; +option subnet-mask 255.255.255.0; + +default-lease-time 3600; +max-lease-time 86400; +ddns-update-style none; + +subnet 192.168.4.0 netmask 255.255.255.0 { + range 192.168.4.129 192.168.4.254; + option routers 192.168.4.1; +} + +host mailhost { + hardware ethernet 02:03:04:05:06:07; + fixed-address mailhost.example.com; +} + + + + This option specifies the domain that will be provided + to clients as the default search domain. See + &man.resolv.conf.5; for more information on what this + means. + + + + This option specifies a comma separated list of DNS + servers that the client should use. + + + + The netmask that will be provided to clients. + + + + A client may request a specific length of time that a + lease will be valid. Otherwise the server will assign + a lease with this expiry value (in seconds). + + + + This is the maximum length of time that the server will + lease for. Should a client request a longer lease, a lease + will be issued, although it will only be valid for + max-lease-time seconds. + + + + This option specifies whether the DHCP server should + attempt to update DNS when a lease is accepted or released. + In the ISC implementation, this option is + required. + + + + This denotes which IP addresses should be used in + the pool reserved for allocating to clients. IP + addresses between, and including, the ones stated are + handed out to clients. + + + + Declares the default gateway that will be provided to + clients. + + + + The hardware MAC address of a host (so that the DHCP server + can recognize a host when it makes a request). + + + + Specifies that the host should always be given the + same IP address. Note that using a hostname is + correct here, since the DHCP server will resolve the + hostname itself before returning the lease + information. + + + + Once you have finished writing your + dhcpd.conf, + you should enable the DHCP server in + /etc/rc.conf, i.e. by adding: + + dhcpd_enable="YES" +dhcpd_ifaces="dc0" + + Replace the dc0 interface name with the + interface (or interfaces, separated by whitespace) that your DHCP + server should listen on for DHCP client requests. + + Then, you can proceed to start the server by issuing the + following command: + + &prompt.root; /usr/local/etc/rc.d/isc-dhcpd.sh start + + Should you need to make changes to the configuration of your + server in the future, it is important to note that sending a + SIGHUP signal to + dhcpd does not + result in the configuration being reloaded, as it does with most + daemons. You will need to send a SIGTERM + signal to stop the process, and then restart it using the command + above. + + + + Files + + DHCP + configuration files + + + /usr/local/sbin/dhcpd + dhcpd is statically linked and + resides in /usr/local/sbin. The + &man.dhcpd.8; manual page installed with the + port gives more information about + dhcpd. + + + /usr/local/etc/dhcpd.conf + dhcpd requires a configuration + file, /usr/local/etc/dhcpd.conf before it + will start providing service to clients. This file needs to + contain all the information that should be provided to clients + that are being serviced, along with information regarding the + operation of the server. This configuration file is described + by the &man.dhcpd.conf.5; manual page installed + by the port. + + + /var/db/dhcpd.leases + The DHCP server keeps a database of leases it has issued + in this file, which is written as a log. The manual page + &man.dhcpd.leases.5;, installed by the port + gives a slightly longer description. + + + /usr/local/sbin/dhcrelay + dhcrelay is used in advanced + environments where one DHCP server forwards a request from a + client to another DHCP server on a separate network. If you + require this functionality, then install the net/isc-dhcp3-relay port. The + &man.dhcrelay.8; manual page provided with the + port contains more detail. + + + + + + + + + + + + + Chern + Lee + Contributed by + + + + Tom + Rhodes + + + + Daniel + Gerzo + + + + Domain Name System (<acronym>DNS</acronym>) + + + Overview + BIND + + &os; utilizes, by default, a version of BIND (Berkeley + Internet Name Domain), which is the most common implementation + of the DNS protocol. DNS + is the protocol through which names are mapped to + IP addresses, and vice versa. For example, a + query for www.FreeBSD.org will + receive a reply with the IP address of The + &os; Project's web server, whereas, a query for ftp.FreeBSD.org will return the + IP address of the corresponding + FTP machine. Likewise, the opposite can + happen. A query for an IP address can + resolve its hostname. It is not necessary to run a name server + to perform DNS lookups on a system. + + &os; currently comes with BIND9 + DNS server software by default. Our + installation provides enhanced security features, a new file + system layout and automated &man.chroot.8; configuration. + + DNS + DNS is coordinated across the Internet + through a somewhat complex system of authoritative root, Top + Level Domain (TLD), and other smaller-scale + name servers which host and cache individual domain + information. + + Currently, BIND is maintained by the + Internet Software Consortium + . + + + + Terminology + + To understand this document, some terms related to + DNS must be understood. + + resolver + reverse DNS + root zone + + + + + + + + + Term + Definition + + + + + + Forward DNS + Mapping of hostnames to IP addresses. + + + + Origin + Refers to the domain covered in a particular zone + file. + + + + named, BIND, name server + Common names for the BIND name server package within + &os;. + + + + Resolver + A system process through which a + machine queries a name server for zone information. + + + + Reverse DNS + The opposite of forward DNS; + mapping of IP addresses to + hostnames. + + + + Root zone + + The beginning of the Internet zone hierarchy. + All zones fall under the root zone, similar to how + all files in a file system fall under the root + directory. + + + + Zone + An individual domain, subdomain, or portion of the + DNS administered by the same + authority. + + + + + + + zones + examples + + + Examples of zones: + + + + . is the root zone. + + + + org. is a Top Level Domain + (TLD) under the root zone. + + + + example.org. is a + zone under the org. + TLD. + + + + 1.168.192.in-addr.arpa is a zone + referencing all IP addresses which fall + under the 192.168.1.* + IP space. + + + + As one can see, the more specific part of a hostname appears + to its left. For example, example.org. is more specific than + org., as org. is more specific + than the root zone. The layout of each part of a hostname is + much like a file system: the + /dev directory falls + within the root, and so on. + + + + Reasons to Run a Name Server + + Name servers usually come in two forms: an authoritative + name server, and a caching name server. + + An authoritative name server is needed when: + + + + One wants to serve DNS information to + the world, replying authoritatively to queries. + + + + A domain, such as example.org, is registered and + IP addresses need to be assigned to + hostnames under it. + + + + An IP address block requires reverse + DNS entries (IP to + hostname). + + + + A backup or second name server, called a slave, will + reply to queries. + + + + A caching name server is needed when: + + + + A local DNS server may cache and + respond more quickly than querying an outside name + server. + + + + When one queries for www.FreeBSD.org, the resolver usually + queries the uplink ISP's name server, and + retrieves the reply. With a local, caching + DNS server, the query only has to be made + once to the outside world by the caching DNS + server. Every additional query will not have to look to the + outside of the local network, since the information is cached + locally. + + + + How It Works + In &os;, the BIND daemon is called + named for obvious reasons. + + + + + + File + Description + + + + + + &man.named.8; + The BIND daemon. + + + + &man.rndc.8; + Name server control utility. + + + + /etc/namedb + Directory where BIND zone information resides. + + + + /etc/namedb/named.conf + Configuration file of the daemon. + + + + + + Depending on how a given zone is configured on the server, + the files related to that zone can be found in the master, slave, or dynamic subdirectories of the + /etc/namedb directory. + These files contain the DNS information that + will be given out by the name server in response to queries. + + + + Starting BIND + + BIND + starting + + + Since BIND is installed by default, configuring it all is + relatively simple. + + The default named configuration + is that of a basic resolving name server, ran in a + &man.chroot.8; environment. To start the server one time with + this configuration, use the following command: + + &prompt.root; /etc/rc.d/named forcestart + + To ensure the named daemon is + started at boot each time, put the following line into the + /etc/rc.conf: + + named_enable="YES" + + There are obviously many configuration options for + /etc/namedb/named.conf that are beyond the + scope of this document. However, if you are interested in the + startup options for named on &os;, + take a look at the + named_* flags in + /etc/defaults/rc.conf and consult the + &man.rc.conf.5; manual page. The + section is also a good read. + + + + Configuration Files + + BIND + configuration files + + + Configuration files for named + currently reside in + /etc/namedb directory and + will need modification before use, unless all that is needed is + a simple resolver. This is where most of the configuration will + be performed. + + + Using <command>make-localhost</command> + + To configure a master zone for the localhost visit the + /etc/namedb directory + and run the following command: + + &prompt.root; sh make-localhost + + If all went well, a new file should exist in the + master subdirectory. + The filenames should be localhost.rev for + the local domain name and localhost-v6.rev + for IPv6 configurations. As the default + configuration file, required information will + be present in the named.conf file. + + + + <filename>/etc/namedb/named.conf</filename> + + // $FreeBSD$ +// +// Refer to the named.conf(5) and named(8) man pages, and the documentation +// in /usr/share/doc/bind9 for more details. +// +// If you are going to set up an authoritative server, make sure you +// understand the hairy details of how DNS works. Even with +// simple mistakes, you can break connectivity for affected parties, +// or cause huge amounts of useless Internet traffic. + +options { + directory "/etc/namedb"; + pid-file "/var/run/named/pid"; + dump-file "/var/dump/named_dump.db"; + statistics-file "/var/stats/named.stats"; + +// If named is being used only as a local resolver, this is a safe default. +// For named to be accessible to the network, comment this option, specify +// the proper IP address, or delete this option. + listen-on { 127.0.0.1; }; + +// If you have IPv6 enabled on this system, uncomment this option for +// use as a local resolver. To give access to the network, specify +// an IPv6 address, or the keyword "any". +// listen-on-v6 { ::1; }; + +// In addition to the "forwarders" clause, you can force your name +// server to never initiate queries of its own, but always ask its +// forwarders only, by enabling the following line: +// +// forward only; + +// If you've got a DNS server around at your upstream provider, enter +// its IP address here, and enable the line below. This will make you +// benefit from its cache, thus reduce overall DNS traffic in the Internet. +/* + forwarders { + 127.0.0.1; + }; +*/ + + Just as the comment says, to benefit from an uplink's + cache, forwarders can be enabled here. + Under normal circumstances, a name server will recursively + query the Internet looking at certain name servers until it + finds the answer it is looking for. Having this enabled will + have it query the uplink's name server (or name server + provided) first, taking advantage of its cache. If the uplink + name server in question is a heavily trafficked, fast name + server, enabling this may be worthwhile. + + + 127.0.0.1 will + not work here. Change this + IP address to a name server at your + uplink. + + + /* + * If there is a firewall between you and nameservers you want + * to talk to, you might need to uncomment the query-source + * directive below. Previous versions of BIND always asked + * questions using port 53, but BIND versions 8 and later + * use a pseudo-random unprivileged UDP port by default. + */ + // query-source address * port 53; +}; + +// If you enable a local name server, don't forget to enter 127.0.0.1 +// first in your /etc/resolv.conf so this server will be queried. +// Also, make sure to enable it in /etc/rc.conf. + +zone "." { + type hint; + file "named.root"; +}; + +zone "0.0.127.IN-ADDR.ARPA" { + type master; + file "master/localhost.rev"; +}; + +// RFC 3152 +zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA" { + type master; + file "master/localhost-v6.rev"; +}; + +// NB: Do not use the IP addresses below, they are faked, and only +// serve demonstration/documentation purposes! +// +// Example slave zone config entries. It can be convenient to become +// a slave at least for the zone your own domain is in. Ask +// your network administrator for the IP address of the responsible +// primary. +// +// Never forget to include the reverse lookup (IN-ADDR.ARPA) zone! +// (This is named after the first bytes of the IP address, in reverse +// order, with ".IN-ADDR.ARPA" appended.) +// +// Before starting to set up a primary zone, make sure you fully +// understand how DNS and BIND works. There are sometimes +// non-obvious pitfalls. Setting up a slave zone is simpler. +// +// NB: Don't blindly enable the examples below. :-) Use actual names +// and addresses instead. + +/* An example master zone +zone "example.net" { + type master; + file "master/example.net"; +}; +*/ + +/* An example dynamic zone +key "exampleorgkey" { + algorithm hmac-md5; + secret "sf87HJqjkqh8ac87a02lla=="; +}; +zone "example.org" { + type master; + allow-update { + key "exampleorgkey"; + }; + file "dynamic/example.org"; +}; +*/ + +/* Examples of forward and reverse slave zones +zone "example.com" { + type slave; + file "slave/example.com"; + masters { + 192.168.1.1; + }; +}; +zone "1.168.192.in-addr.arpa" { + type slave; + file "slave/1.168.192.in-addr.arpa"; + masters { + 192.168.1.1; + }; +}; +*/ + + In named.conf, these are examples of + slave entries for a forward and reverse zone. + + For each new zone served, a new zone entry must be added + to named.conf. + + For example, the simplest zone entry for + example.org can look + like: + + zone "example.org" { + type master; + file "master/example.org"; +}; + + The zone is a master, as indicated by the + statement, holding its zone information + in /etc/namedb/master/example.org + indicated by the statement. + + zone "example.org" { + type slave; + file "slave/example.org"; +}; + + In the slave case, the zone information is transferred + from the master name server for the particular zone, and saved + in the file specified. If and when the master server dies or + is unreachable, the slave name server will have the + transferred zone information and will be able to serve + it. + + + + Zone Files + + BIND + zone files + + + An example master zone file for example.org (existing within + /etc/namedb/master/example.org) is as + follows: + + $TTL 3600 ; 1 hour +example.org. IN SOA ns1.example.org. admin.example.org. ( + 2006051501 ; Serial + 10800 ; Refresh + 3600 ; Retry + 604800 ; Expire + 86400 ; Minimum TTL + ) + +; DNS Servers + IN NS ns1.example.org. + IN NS ns2.example.org. + +; MX Records + IN MX 10 mx.example.org. + IN MX 20 mail.example.org. + + IN A 192.168.1.1 + +; Machine Names +localhost IN A 127.0.0.1 +ns1 IN A 192.168.1.2 +ns2 IN A 192.168.1.3 +mx IN A 192.168.1.4 +mail IN A 192.168.1.5 + +; Aliases +www IN CNAME @ + + + Note that every hostname ending in a . is an + exact hostname, whereas everything without a trailing + . is referenced to the origin. For example, + www is translated into + www.origin. + In our fictitious zone file, our origin is + example.org., so www + would translate to www.example.org. + + + + The format of a zone file follows: + + recordname IN recordtype value + + + DNS + records + + + The most commonly used DNS records: + + + + + SOA + + start of zone authority + + + + NS + + an authoritative name server + + + + A + + a host address + + + + CNAME + + the canonical name for an alias + + + + MX + + mail exchanger + + + + PTR + + a domain name pointer (used in reverse DNS) + + + + + +example.org. IN SOA ns1.example.org. admin.example.org. ( + 2006051501 ; Serial + 10800 ; Refresh after 3 hours + 3600 ; Retry after 1 hour + 604800 ; Expire after 1 week + 86400 ) ; Minimum TTL of 1 day + + + + + + example.org. + + the domain name, also the origin for this + zone file. + + + + ns1.example.org. + + the primary/authoritative name server for this + zone. + + + + admin.example.org. + + the responsible person for this zone, + email address with @ + replaced. (admin@example.org becomes + admin.example.org) + + + + + 2006051501 + + the serial number of the file. This + must be incremented each time the zone file is + modified. Nowadays, many admins prefer a + yyyymmddrr format for the serial + number. 2006051501 would mean + last modified 05/15/2006, the latter + 01 being the first time the zone + file has been modified this day. The serial number + is important as it alerts slave name servers for a + zone when it is updated. + + + + + + IN NS ns1.example.org. + + + This is an NS entry. Every name server that is going to reply + authoritatively for the zone must have one of these entries. + + + +localhost IN A 127.0.0.1 +ns1 IN A 192.168.1.2 +ns2 IN A 192.168.1.3 +mx IN A 192.168.1.4 +mail IN A 192.168.1.5 + + + The A record indicates machine names. As seen above, + ns1.example.org would resolve + to 192.168.1.2. + + + + IN A 192.168.1.1 + + This line assigns IP address + 192.168.1.1 to the current origin, + in this case example.org. + + +www IN CNAME @ + + + The canonical name record is usually used for giving aliases + to a machine. In the example, www is + aliased to the master machine which name equals + to domain name example.org + (192.168.1.1). + CNAMEs can be used to provide alias + hostnames, or round robin one hostname among multiple + machines. + + + + MX record + + + + IN MX 10 mail.example.org. + + + The MX record indicates which mail + servers are responsible for handling incoming mail for the + zone. mail.example.org is the + hostname of the mail server, and 10 being the priority of + that mail server. + + + + One can have several mail servers, with priorities of 10, + 20 and so on. A mail server attempting to deliver to example.org would first try the + highest priority MX (the record with the lowest priority + number), then the second highest, etc, until the mail can be + properly delivered. + + + + For in-addr.arpa zone files (reverse DNS), the same format is + used, except with PTR entries instead of + A or CNAME. + + + $TTL 3600 + +1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. ( + 2006051501 ; Serial + 10800 ; Refresh + 3600 ; Retry + 604800 ; Expire + 3600 ) ; Minimum + + IN NS ns1.example.org. + IN NS ns2.example.org. + +1 IN PTR example.org. +2 IN PTR ns1.example.org. +3 IN PTR ns2.example.org. +4 IN PTR mx.example.org. +5 IN PTR mail.example.org. + + This file gives the proper IP address to hostname + mappings of our above fictitious domain. + + + + + Caching Name Server + + BIND + caching name server + + + A caching name server is a name server that is not + authoritative for any zones. It simply asks queries of its + own, and remembers them for later use. To set one up, just + configure the name server as usual, omitting any inclusions of + zones. + + + + Security + + Although BIND is the most common implementation of DNS, + there is always the issue of security. Possible and + exploitable security holes are sometimes found. + + + While &os; automatically drops + named into a &man.chroot.8; + environment; there are several other security mechanisms in + place which could help to lure off possible + DNS service attacks. + + It is always good idea to read CERT's security advisories + and to subscribe to the &a.security-notifications; to stay up to + date with the current Internet and &os; security issues. + + + If a problem arises, keeping sources up to date and + having a fresh build of named would + not hurt. + + + + + Further Reading + + BIND/named manual pages: + &man.rndc.8; &man.named.8; &man.named.conf.5; + + + + Official ISC BIND + Page + + + + Official ISC BIND + Forum + + + + + BIND FAQ + + + + O'Reilly + DNS and BIND 5th Edition + + + + RFC1034 + - Domain Names - Concepts and Facilities + + + + RFC1035 + - Domain Names - Implementation and Specification + + + + + + + + + + Murray + Stokely + Contributed by + + + + Apache HTTP Server + + web servers + setting up + Apache + + + Overview + + &os; is used to run some of the busiest web sites in the + world. The majority of web servers on the Internet are using + the Apache HTTP Server. + Apache software packages should be + included on your FreeBSD installation media. If you did not + install Apache when you first + installed FreeBSD, then you can install it from the www/apache13 or www/apache20 port. + + Once Apache has been installed + successfully, it must be configured. + + This section covers version 1.3.X of the + Apache HTTP Server as that is the + most widely used version for &os;. Apache 2.X introduces many + new technologies but they are not discussed here. For more + information about Apache 2.X, please see . + + + + + Configuration + + Apache + configuration file + + The main Apache HTTP Server configuration file is + installed as + /usr/local/etc/apache/httpd.conf on &os;. + This file is a typical &unix; text configuration file with + comment lines beginning with the # + character. A comprehensive description of all possible + configuration options is outside the scope of this book, so + only the most frequently modified directives will be described + here. + + + + ServerRoot "/usr/local" + + + This specifies the default directory hierarchy for + the Apache installation. Binaries are stored in the + bin and + sbin subdirectories + of the server root, and configuration files are stored in + etc/apache. + + + + + ServerAdmin you@your.address + + + The address to which problems with the server should + be emailed. This address appears on some + server-generated pages, such as error documents. + + + + + ServerName www.example.com + + + ServerName allows you to set a host name which is + sent back to clients for your server if it is different + to the one that the host is configured with (i.e., use www + instead of the host's real name). + + + + + DocumentRoot "/usr/local/www/data" + + + DocumentRoot: The directory out of which you will + serve your documents. By default, all requests are taken + from this directory, but symbolic links and aliases may + be used to point to other locations. + + + + + It is always a good idea to make backup copies of your + Apache configuration file before making changes. Once you are + satisfied with your initial configuration you are ready to + start running Apache. + + + + + + + + + + Running <application>Apache</application> + + Apache + starting or stopping + + Apache does not run from the + inetd super server as many other + network servers do. It is configured to run standalone for + better performance for incoming HTTP requests from client web + browsers. A shell script wrapper is included to make + starting, stopping, and restarting the server as simple as + possible. To start up Apache for + the first time, just run: + + &prompt.root; /usr/local/sbin/apachectl start + + You can stop the server at any time by typing: + + &prompt.root; /usr/local/sbin/apachectl stop + + After making changes to the configuration file for any + reason, you will need to restart the server: + + &prompt.root; /usr/local/sbin/apachectl restart + + To restart Apache without + aborting current connections, run: + + &prompt.root; /usr/local/sbin/apachectl graceful + + Additional information available at + &man.apachectl.8; manual page. + + To launch Apache at system + startup, add the following line to + /etc/rc.conf: + + apache_enable="YES" + + If you would like to supply additional command line + options for the Apache + httpd program started at system boot, you + may specify them with an additional line in + rc.conf: + + apache_flags="" + + Now that the web server is running, you can view your web + site by pointing a web browser to + http://localhost/. The default web page + that is displayed is + /usr/local/www/data/index.html. + + + + + Virtual Hosting + + Apache supports two different + types of Virtual Hosting. The first method is Name-based + Virtual Hosting. Name-based virtual hosting uses the clients + HTTP/1.1 headers to figure out the hostname. This allows many + different domains to share the same IP address. + + To setup Apache to use + Name-based Virtual Hosting add an entry like the following to + your httpd.conf: + + NameVirtualHost * + + If your webserver was named www.domain.tld and + you wanted to setup a virtual domain for + www.someotherdomain.tld then you would add + the following entries to + httpd.conf: + + <VirtualHost *> +ServerName www.domain.tld +DocumentRoot /www/domain.tld +</VirtualHost> + +<VirtualHost *> +ServerName www.someotherdomain.tld +DocumentRoot /www/someotherdomain.tld +</VirtualHost> + + Replace the addresses with the addresses you want to use + and the path to the documents with what you are using. + + For more information about setting up virtual hosts, + please consult the official Apache + documentation at: . + + + + + Apache Modules + + Apache + modules + + There are many different Apache modules available to add + functionality to the basic server. The FreeBSD Ports + Collection provides an easy way to install + Apache together with some of the + more popular add-on modules. + + + mod_ssl + + web servers + secure + SSL + cryptography + + The mod_ssl module uses the OpenSSL library to provide + strong cryptography via the Secure Sockets Layer (SSL v2/v3) + and Transport Layer Security (TLS v1) protocols. This + module provides everything necessary to request a signed + certificate from a trusted certificate signing authority so + that you can run a secure web server on &os;. + + If you have not yet installed + Apache, then a version of Apache + 1.3.X that includes mod_ssl may be installed with the www/apache13-modssl port. SSL + support is also available for Apache 2.X in the + www/apache20 port, + where it is enabled by default. + + + + + + + + Dynamic Websites with Perl & PHP + In the past few years, more businesses have turned to the + Internet in order to enhance their revenue and increase + exposure. This has also increased the need for interactive + web content. While some companies, such as µsoft;, have + introduced solutions into their proprietary products, the + open source community answered the call. Two options for + dynamic web content include + mod_perl & + mod_php. + + + mod_perl + + + mod_perl + Perl + + + The Apache/Perl integration project brings together the + full power of the Perl programming language and the Apache + HTTP Server. With the mod_perl module it is possible to + write Apache modules entirely in Perl. In addition, the + persistent interpreter embedded in the server avoids the + overhead of starting an external interpreter and the penalty + of Perl start-up time. + + mod_perl is available a few + different ways. To use mod_perl + remember that mod_perl 1.0 only + works with Apache 1.3 and + mod_perl 2.0 only works with + Apache 2. + mod_perl 1.0 is available in + www/mod_perl and a + statically compiled version is available in + www/apache13-modperl. + mod_perl 2.0 is avaliable in + www/mod_perl2. + + + + + + + Tom + Rhodes + Written by + + + + mod_php + + + mod_php + PHP + + + PHP, also known as PHP: + Hypertext Preprocessor is a general-purpose scripting + language that is especially suited for Web development. + Capable of being embedded into HTML its + syntax draws upon C, &java;, and Perl with the intention of + allowing web developers to write dynamically generated + webpages quickly. + + To gain support for PHP5 for the + Apache web server, begin by + installing the + www/mod_php5 + port. + + This will install and configure the modules required + to support dynamic PHP applications. Check + to ensure the following sections have been added to + /usr/local/etc/apache/httpd.conf: + + LoadModule php5_module libexec/apache/libphp5.so + + AddModule mod_php5.c + <IfModule mod_php5.c> + DirectoryIndex index.php index.html + </IfModule> + <IfModule mod_php5.c> + AddType application/x-httpd-php .php + AddType application/x-httpd-php-source .phps + </IfModule> + + Once completed, a simple call to the + apachectl command for a graceful + restart is needed to load the PHP + module: + + &prompt.root; apachectl graceful + + The PHP support in &os; is extremely + modular so the base install is very limited. It is very easy + to add support using the + lang/php5-extensions port. + This port provides a menu driven interface to + PHP extension installation. + Alternatively, individual extensions can be installed using + the appropriate port. + + For instance, to add support for the + MySQL database server to + PHP5, simply install the + databases/php5-mysql + port. + + After installing an extension, the + Apache server must be reloaded to + pick up the new configuration changes: + + &prompt.root; apachectl graceful + + + + + + + + + + Murray + Stokely + Contributed by + + + + File Transfer Protocol (FTP) + + FTP servers + + + Overview + + The File Transfer Protocol (FTP) provides users with a + simple way to transfer files to and from an FTP server. &os; + includes FTP + server software, ftpd, in the base + system. This makes setting up and administering an FTP server on FreeBSD + very straightforward. + + + + Configuration + + The most important configuration step is deciding which + accounts will be allowed access to the FTP server. A normal + FreeBSD system has a number of system accounts used for + various daemons, but unknown users should not be allowed to + log in with these accounts. The + /etc/ftpusers file is a list of users + disallowed any FTP access. By default, it includes the + aforementioned system accounts, but it is possible to add + specific users here that should not be allowed access to + FTP. + + You may want to restrict the access of some users without + preventing them completely from using FTP. This can be + accomplished with the /etc/ftpchroot + file. This file lists users and groups subject to FTP access + restrictions. The &man.ftpchroot.5; manual page has all of + the details so it will not be described in detail here. + + + FTP + anonymous + + + If you would like to enable anonymous FTP access to your + server, then you must create a user named + ftp on your &os; system. Users will then + be able to log on to your FTP server with a username of + ftp or anonymous and + with any password (by convention an email address for the user + should be used as the password). The FTP server will call + &man.chroot.2; when an anonymous user logs in, to restrict + access to only the home directory of the + ftp user. + + There are two text files that specify welcome messages to + be displayed to FTP clients. The contents of the file + /etc/ftpwelcome will be displayed to + users before they reach the login prompt. After a successful + login, the contents of the file + /etc/ftpmotd will be displayed. Note + that the path to this file is relative to the login environment, so the + file ~ftp/etc/ftpmotd would be displayed + for anonymous users. + + Once the FTP server has been configured properly, it must + be enabled in /etc/inetd.conf. All that + is required here is to remove the comment symbol + # from in front of the existing + ftpd line : + + ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l + + As explained in , + the inetd configuration must be reloaded + after this configuration file is changed. + + You can now log on to your FTP server by typing: + + &prompt.user; ftp localhost + + + + + Maintaining + + syslog + log files + FTP + + The ftpd daemon uses + &man.syslog.3; to log messages. By default, the system log + daemon will put messages related to FTP in the + /var/log/xferlog file. The location of + the FTP log can be modified by changing the following line in + /etc/syslog.conf: + + ftp.info /var/log/xferlog + + + FTP + anonymous + + + Be aware of the potential problems involved with running + an anonymous FTP server. In particular, you should think + twice about allowing anonymous users to upload files. You may + find that your FTP site becomes a forum for the trade of + unlicensed commercial software or worse. If you do need to + allow anonymous FTP uploads, then you should set up the + permissions so that these files can not be read by other + anonymous users until they have been reviewed. + + + + + + + + + Murray + Stokely + Contributed by + + + + File and Print Services for µsoft.windows; clients (Samba) + + Samba server + Microsoft Windows + + file server + Windows clients + + + print server + Windows clients + + + + Overview + + Samba is a popular open source + software package that provides file and print services for + µsoft.windows; clients. Such clients can connect to and + use FreeBSD filespace as if it was a local disk drive, or + FreeBSD printers as if they were local printers. + + Samba software packages should + be included on your FreeBSD installation media. If you did + not install Samba when you first + installed FreeBSD, then you can install it from the net/samba3 port or package. + + + + + + + Configuration + + A default Samba configuration + file is installed as + /usr/local/etc/smb.conf.default. This + file must be copied to + /usr/local/etc/smb.conf and customized + before Samba can be used. + + The smb.conf file contains runtime + configuration information for + Samba, such as definitions of the + printers and file system shares that you would + like to share with &windows; clients. The + Samba package includes a web based + tool called swat which provides a + simple way of configuring the smb.conf + file. + + + Using the Samba Web Administration Tool (SWAT) + + The Samba Web Administration Tool (SWAT) runs as a + daemon from inetd. Therefore, the + following line in /etc/inetd.conf + should be uncommented before swat can be + used to configure Samba: + + swat stream tcp nowait/400 root /usr/local/sbin/swat + As explained in , + the inetd must be reloaded after this configuration + file is changed. + + Once swat has been enabled in + inetd.conf, you can use a browser to + connect to . You will + first have to log on with the system root account. + + + + Once you have successfully logged on to the main + Samba configuration page, you can + browse the system documentation, or begin by clicking on the + Globals tab. The Globals section corresponds to the + variables that are set in the [global] + section of + /usr/local/etc/smb.conf. + + + + Global Settings + + Whether you are using swat or + editing /usr/local/etc/smb.conf + directly, the first directives you are likely to encounter + when configuring Samba + are: + + + + workgroup + + + NT Domain-Name or Workgroup-Name for the computers + that will be accessing this server. + + + + + netbios name + NetBIOS + + + This sets the NetBIOS name by which a Samba server + is known. By default it is the same as the first + component of the host's DNS name. + + + + + server string + + + This sets the string that will be displayed with + the net view command and some other + networking tools that seek to display descriptive text + about the server. + + + + + + + Security Settings + + Two of the most important settings in + /usr/local/etc/smb.conf are the + security model chosen, and the backend password format for + client users. The following directives control these + options: + + + + security + + + The two most common options here are + security = share and security + = user. If your clients use usernames that + are the same as their usernames on your &os; machine + then you will want to use user level security. This + is the default security policy and it requires clients + to first log on before they can access shared + resources. + + In share level security, client do not need to log + onto the server with a valid username and password + before attempting to connect to a shared resource. + This was the default security model for older versions + of Samba. + + + + + passdb backend + + NIS+ + LDAP + SQL database + + + Samba has several + different backend authentication models. You can + authenticate clients with LDAP, NIS+, a SQL database, + or a modified password file. The default + authentication method is smbpasswd, + and that is all that will be covered here. + + + + + Assuming that the default smbpasswd + backend is used, the + /usr/local/private/smbpasswd file must + be created to allow Samba to + authenticate clients. If you would like to give all of + your &unix; user accounts access from &windows; clients, use the + following command: + + &prompt.root; grep -v "^#" /etc/passwd | make_smbpasswd > /usr/local/private/smbpasswd +&prompt.root; chmod 600 /usr/local/private/smbpasswd + + Please see the Samba + documentation for additional information about configuration + options. With the basics outlined here, you should have + everything you need to start running + Samba. + + + + + Starting <application>Samba</application> + + To enable Samba when your + system boots, add the following line to + /etc/rc.conf: + + samba_enable="YES" + + You can then start Samba at any + time by typing: + + &prompt.root; /usr/local/etc/rc.d/samba.sh start +Starting SAMBA: removing stale tdbs : +Starting nmbd. +Starting smbd. + + Samba actually consists of + three separate daemons. You should see that both the + nmbd and smbd daemons + are started by the samba.sh script. If + you enabled winbind name resolution services in + smb.conf, then you will also see that + the winbindd daemon is started. + + You can stop Samba at any time + by typing : + + &prompt.root; /usr/local/etc/rc.d/samba.sh stop + + Samba is a complex software + suite with functionality that allows broad integration with + µsoft.windows; networks. For more information about + functionality beyond the basic installation described here, + please see . + + + + + + + + + Tom + Hukins + Contributed by + + + + Clock Synchronization with NTP + + NTP + + + Overview + + Over time, a computer's clock is prone to drift. The + Network Time Protocol (NTP) is one way to ensure your clock stays + accurate. + + Many Internet services rely on, or greatly benefit from, + computers' clocks being accurate. For example, a web server + may receive requests to send a file if it has been modified since a + certain time. In a local area network environment, it is + essential that computers sharing files from the same file + server have synchronized clocks so that file timestamps stay + consistent. Services such as &man.cron.8; also rely on + an accurate system clock to run commands at the specified + times. + + + NTP + ntpd + + FreeBSD ships with the &man.ntpd.8; NTP server which can be used to query + other NTP + servers to set the clock on your machine or provide time + services to others. + + + + Choosing Appropriate NTP Servers + + + NTP + choosing servers + + + In order to synchronize your clock, you will need to find + one or more NTP servers to use. Your network + administrator or ISP may have set up an NTP server for this + purpose—check their documentation to see if this is the + case. There is an online + list of publicly accessible NTP servers which you can + use to find an NTP server near to you. Make sure you are + aware of the policy for any servers you choose, and ask for + permission if required. + + Choosing several unconnected NTP servers is a good idea in + case one of the servers you are using becomes unreachable or + its clock is unreliable. &man.ntpd.8; uses the responses it + receives from other servers intelligently—it will favor + unreliable servers less than reliable ones. + + + + Configuring Your Machine + + + NTP + configuration + + + + Basic Configuration + ntpdate + + If you only wish to synchronize your clock when the + machine boots up, you can use &man.ntpdate.8;. This may be + appropriate for some desktop machines which are frequently + rebooted and only require infrequent synchronization, but + most machines should run &man.ntpd.8;. + + Using &man.ntpdate.8; at boot time is also a good idea + for machines that run &man.ntpd.8;. The &man.ntpd.8; + program changes the clock gradually, whereas &man.ntpdate.8; + sets the clock, no matter how great the difference between a + machine's current clock setting and the correct time. + + To enable &man.ntpdate.8; at boot time, add + ntpdate_enable="YES" to + /etc/rc.conf. You will also need to + specify all servers you wish to synchronize with and any + flags to be passed to &man.ntpdate.8; in + ntpdate_flags. + + + + + NTP + ntp.conf + + + General Configuration + + NTP is configured by the + /etc/ntp.conf file in the format + described in &man.ntp.conf.5;. Here is a simple + example: + + server ntplocal.example.com prefer +server timeserver.example.org +server ntp2a.example.net + +driftfile /var/db/ntp.drift + + The server option specifies which + servers are to be used, with one server listed on each line. + If a server is specified with the prefer + argument, as with ntplocal.example.com, that server is + preferred over other servers. A response from a preferred + server will be discarded if it differs significantly from + other servers' responses, otherwise it will be used without + any consideration to other responses. The + prefer argument is normally used for NTP + servers that are known to be highly accurate, such as those + with special time monitoring hardware. + + The driftfile option specifies which + file is used to store the system clock's frequency offset. + The &man.ntpd.8; program uses this to automatically + compensate for the clock's natural drift, allowing it to + maintain a reasonably correct setting even if it is cut off + from all external time sources for a period of time. + + The driftfile option specifies which + file is used to store information about previous responses + from the NTP servers you are using. This file contains + internal information for NTP. It should not be modified by + any other process. + + + + Controlling Access to Your Server + + By default, your NTP server will be accessible to all + hosts on the Internet. The restrict + option in /etc/ntp.conf allows you to + control which machines can access your server. + + If you want to deny all machines from accessing your NTP + server, add the following line to + /etc/ntp.conf: + + restrict default ignore + + If you only want to allow machines within your own + network to synchronize their clocks with your server, but + ensure they are not allowed to configure the server or used + as peers to synchronize against, add + + restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap + + instead, where 192.168.1.0 is + an IP address on your network and 255.255.255.0 is your network's + netmask. + + /etc/ntp.conf can contain multiple + restrict options. For more details, see + the Access Control Support subsection of + &man.ntp.conf.5;. + + + + + Running the NTP Server + + To ensure the NTP server is started at boot time, add the + line ntpd_enable="YES" to + /etc/rc.conf. If you wish to pass + additional flags to &man.ntpd.8;, edit the + ntpd_flags parameter in + /etc/rc.conf. + + To start the server without rebooting your machine, run + ntpd being sure to specify any additional + parameters from ntpd_flags in + /etc/rc.conf. For example: + + &prompt.root; ntpd -p /var/run/ntpd.pid + + + + Using ntpd with a Temporary Internet + Connection + + The &man.ntpd.8; program does not need a permanent + connection to the Internet to function properly. However, if + you have a temporary connection that is configured to dial out + on demand, it is a good idea to prevent NTP traffic from + triggering a dial out or keeping the connection alive. If you + are using user PPP, you can use filter + directives in /etc/ppp/ppp.conf. For + example: + + set filter dial 0 deny udp src eq 123 + # Prevent NTP traffic from initiating dial out + set filter dial 1 permit 0 0 + set filter alive 0 deny udp src eq 123 + # Prevent incoming NTP traffic from keeping the connection open + set filter alive 1 deny udp dst eq 123 + # Prevent outgoing NTP traffic from keeping the connection open + set filter alive 2 permit 0/0 0/0 + + For more details see the PACKET + FILTERING section in &man.ppp.8; and the examples in + /usr/share/examples/ppp/. + + + Some Internet access providers block low-numbered ports, + preventing NTP from functioning since replies never + reach your machine. + + + + + Further Information + + Documentation for the NTP server can be found in + /usr/share/doc/ntp/ in HTML + format. + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/pgpkeys/Makefile b/pl_PL.ISO8859-2/books/handbook/pgpkeys/Makefile new file mode 100644 index 0000000000..7c61203aff --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/pgpkeys/Makefile @@ -0,0 +1,19 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= pgpkeys/chapter.sgml + +PGPKEYS!= perl -ne 'm/\"([\w-]+.key)\"/ && print "$$1\n"' \ + ${DOC_PREFIX}/share/pgpkeys/pgpkeys.ent +SRCS+= ${PGPKEYS} + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/pgpkeys/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/pgpkeys/chapter.sgml new file mode 100644 index 0000000000..7c1fc562eb --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/pgpkeys/chapter.sgml @@ -0,0 +1,50 @@ + + + + PGP Keys + + pgp keys + In case you need to verify a signature or send encrypted email + to one of the officers or developers a number of keys are provided + here for your convenience. A complete keyring of FreeBSD.org + users is available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt. + + + Officers + + §ion.pgpkeys-officers; + + + + Core Team Members + + §ion.pgpkeys-core; + + + + Developers + + §ion.pgpkeys-developers; + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/ports/Makefile b/pl_PL.ISO8859-2/books/handbook/ports/Makefile new file mode 100644 index 0000000000..93280bcae8 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/ports/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= ports/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/ports/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/ports/chapter.sgml new file mode 100644 index 0000000000..3a9120c972 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/ports/chapter.sgml @@ -0,0 +1,1489 @@ + + + + + + + Cezary + Morga + T³umaczy³ + + + + + Instalacja programów: pakiety i porty + + + Strzeszczenie + + porty + pakiety + System FreeBSD rozprowadzany jest wraz z bogat± kolekcj± + narzêdzi systemowych. Tym nie mniej, stanowi to absolutne minimum. + Szybko pojawia siê bowiem potrzeba zainstalowania dodatkowego + oprogramowania, by móc rozpocz±æ prawdziw± pracê z systemem. + FreeBSD dostarcza dwóch dope³niaj±cych siê metod instalacji + oprogramowania: kolekcjê portów FreeBSD (kompilacja programów + ze ¼róde³) i system pakietów (instalacja z gotowych binariów). + Ka¿da z tych metod mo¿e zostaæ wykorzystana do intalacji najnowszych + wersji ulubionego oprogramowania z lokalnych no¶ników b±d¼ + bezpo¶rednio z sieci. + + Przeczytawszy ten rozdia³ dowiemy siê: + + + + Jak instalowaæ oprogramowanie innych producentów + dostarczane w postaci binarnej. + + + Jak kompilowaæ oprogrmowanie innych producentów + z wykorzystaniem kolekcji portów. + + + Jak usun±æ poprzednio zainstalowane pakiety b±d¼ + porty. + + + Kak zmieniæ domy¶lne warto¶ci wykorzystywane + przy kompilacji portów. + + + Jak odnale¿æ w³a¶ciwe oprogramowanie. + + + Jak zaktualizaowaæ wykorzystywane aplikacje. + + + + + + Omówienie instalacji oprogramowania + + Osoby, które ju¿ wcze¶niej pracowa³y z systemami &unix; + wiedz±, ¿e typowy proces instalacji oprogramowania sprowadza + siê mniej wiêcej do nastêpuj±cych punktów: + + + + Pobranie programu, który mo¿e byæ rozprowadzany + w postaci kodu ¼ród³owego b±d¼ binarnej. + + + + Rozpakowania programu z formatu w jakim jest + rozprowadzany (najcze¶ciej jest to plik tar skompresowany + za pomoc± &man.compress.1;, &man.gzip.1; lub + &man.bzip2.1;). + + + + Odnalezienie dokumentacji (najczê¶ciej plik + INSTALL lub README + b±d¼ pliki w podkatalogu doc/) + i zapoznanie siê z instrukcjami instalacji programu. + + + + Kompilacja programu, je¶li rozprowadzany jest w postaci + ¼ród³owej. Mo¿e to wymagaæ równie¿ wykonania dodatkowych + czynno¶ci, jak np. edycji pliku Makefile + b±d¼ uruchomienia skryptu configure. + + + + Weryfikacja i instalacja aplikacji. + + + + Wszystko to przy za³o¿eniu, ¿e w miêdzy czasie nie pojawi³y + siê ¿adne trudno¶ci. Instalacja oprogramowania, które nie by³o + przygotowywane z my¶l± o FreeBSD mo¿e wymagaæ nawet modyfikacji + kodu ¼ród³owego nim zacznie poprawnie funkcjonowaæ. + + Oczywi¶cie, we FreeBSD mo¿na instalowaæ oprogramowanie + tradycyjnym sposobem. Jednak¿e system ten + posiada dwa rozwi±zania, które potrafi± zaoszczêdziæ mnóstwo + czasu i trudu: pakiety i porty. W chwili pisania tego tekstu, + dostêpnych za pomoc± tych systemów jest przesz³o &os.numports; + aplikacji. + + Dla ka¿dego programu dostêpny jest do pobrania pojedynczy + pakiet, który zawiera skompilowane kopie plików aplikacji, + zarówno plików uruchomieniowych jak i konfiguracyjnych czy + dokumentacji. Pobranym plikiem mo¿na manipulowaæ za pomoc± + poleceñ &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, + itp. Nowe programy mo¿na instalowaæ za pomoc± zaledwie + jednego polecenia. + + Port natomiast, jest zbiorem plików maj±cych za zadanie + zautomatyzowaæ proces kompilacji danego programu z kodu + ¼ród³owego. + + O ile typowa kompilacja programu sk³ada siê z wielu czynno¶ci + wykonywanych przez u¿ytkownika, o tyle pliki sk³adaj±ce siê na + port zawieraj± dostateczn± ilo¶æ informacji aby pozwoliæ + systemowi zrobiæ to za nas. Wystarczy wprowadziæ kilka prostych + poleceñ a system automatycznie pobierze kod ¼ród³owy programu, + rozpakuje, na³o¿y ³atki, skompiluje i zainstaluje za nas. + + Ponadto system portów mo¿e równie¿ pos³u¿yæ do przygotowania + pakietów, którymi nastêpnie mo¿na manipulowaæ za pomoc± + pkg_add i innymi poleceniami + zarz±dzaj±cych pakietami. + + Obydwa systemy potrafi± analizowaæ zale¿no¶ci + wystêpuj±ce pomiêdzy aplikacjami. Za³ó¿my, ¿e chcemy zainstalowaæ + program, który zale¿y od pewnej biblioteki. Zarówno program jak + i biblioteka dostêpne s± w systemach portów i pakietów FreeBSD. + Niezale¿nie od tego czy wykorzystamy polecenie pkg_add + czy porty, by zainstalowaæ program, to obydwa systemy spostrzeg±, + ¿e biblioteka nie zosta³a zainstalowana i automatycznie zainstaluj± + najpierw bibliotekê. + + Mo¿na by siê zastanawiaæ dlaczego FreeBSD wykorzystuje obydwa + systemy, skoro ich dzia³anie jest tak bardzo podobne. Tak pakiety + jak i porty posiadaj± pewne zalety. Który system wykorzystamy zale¿y + od naszych w³asnych upodobañ. + + + Zalety pakietów + + + Skompresowany plik pakietu zajmuje z regu³y mniej miejsca + ni¿ skompresowany plik zawieraj±cy kod ¼ród³owy. + + + + Instalacja pakietów nie wymaga dodatkowej kompilacji. + W przypadku du¿ych aplikacji, jak np. Mozilla, + KDE czy GNOME + mo¿e to byæ istotne. Szczególnie gdy pracuje siê na do¶æ wolnej + maszynie. + + + + Stosowanie pakietów nie wymaga ¿adnej wiedzy o procesie + kompilowania oprogramowania w systemie FreeBSD. + + + + + Zalety portów + + + Pakiety s± z regu³y kompilowane z do¶æ typowymi opcjami, + poniewa¿ powinny byæ przydatne do wykorzystania na maksymalnej + liczbie komputerów. Instaluj±c programy z portów mamy mo¿liwo¶æ + podkrêcenia opcji kompilacji, by (przyk³adowo) + skompilowaæ program zoptymalizowany dla procesorów Pentium IV + lub Athlon. + + + + Niektóre aplikacje posiadaj± pewne opcje kompilacji + zwi±zane z zadaniami, które maja realizowaæ. Przyk³adowo + Apache mo¿e zostaæ skompilowany + z wieloma róznorodnymi opcjami. Kompiluj±c go z portów nie + musimy zgadzaæ siê na domy¶lne opcje mog±c samemu dokonaæ + wyboru. + + W niektórych przypadkach dostêpnych jest kilka pakietów + tej samej aplikacji skompilowanych z ró¿nymi parametrami. + Na przyk³ad program Ghostscript + dostêpny jest jako pakiet ghostscript + oraz ghostscript-nox11, zale¿nie od + tego czy mamy zainstalowany serwer X11. O ile tego typu + rozwi±zania s± teoretycznie mo¿liwe do zrealizowania w + systemie pakietów, o tyle staje siê to praktycznie niemo¿liwe + gdy aplikacja posiada wiêcej ni¿ kilka ró¿nych opcji + kompilacji. + + + + Warunki licencji niektórych aplikacji zabraniaj± + rozprowadzania w postaci binarnej. Musz± byæ zatem rozprowadzane + jako kod ¼ród³owy. + + + + Niektórzy nie ufaj± pakietom binarnym. W przypadku + kodu ¼ród³owego mo¿na (przynajmniej w teorii) przejrzeæ + go i samemu poszukaæ potencjalnych luk. + + + + Je¶li posiadamy w³asne ³aty bêdziemy potrzebowali + kodu ¼ród³owego aby je nanie¶æ do programu. + + + + Jeszcze inni po prostu lubi± mieæ pod rêk± kod ¼ród³owy, + by móc go poczytaæ gdy siê nudz±, zmodyfikowaæ czy zapo¿yczyæ + pewne rozwi±zania (o ile pozwala na to licencja), itd. + + + + Najlepszym sposobem ¶ledzenia zmian dokonywanych w systemie + portów jest zapisanie siê na &a.pl.ports.b; oraz + &a.pl.ports-bugs.b;. + + + Przed instalacj± jakiejkolwiek aplikacji nale¿y sprawdziæ + na stronie + czy w danym programie istniej± luki zwi±zane bezpieczeñstem. + + Alternatywnie mo¿emy zainstalowaæ security/portaudit, który automatycznie + sprawdza wszystkie instalowane programy pod wzglêdem znanych + luk bezpieczeñstwa; weryfikowane s± równie¿ porty przed kompilacj±. + W miêdzy czasie mo¿na wykorzystaæ polecenie portaudit + -F -a, by sprawdziæ zainstalowane ju¿ pakiety. + + + Pozosta³a czê¶æ niniejszego rozdzia³u ma za zadanie wyja¶niæ + jak z wykorzystaniem systemu pakietów i portów instalowaæ w systemie + FreeBSD oprogramowanie innych producentów. + + + + Odnalezienie programu dla siebie + + Nim przyst±pimy do instalacji programów musimy wiedzieæ + co chcemy zainstalowaæ i jak siê nazywa. + + Lista dostêpnych we FreeBSD programów ro¶nie ca³y czas. + Na szczê¶cie jest wiele sposobów na odnalezienie tego czego + szukamy: + + + + Na stronie internetowej FreeBSD pod adresem http://www.FreeBSD.org/ports/ + znajduje jest aktualna lista dostêpnych programów. Listê mo¿na + dowolnie przeszukiwaæ wed³ug kilku kryteriów, np. nazwy (je¶li + j± znamy). Mo¿liwe jest równie¿ przejrzenie spisu wszystkich + aplikacji znajduj±cych siê w danej kategorii. + + + FreshPorts + + + Dziêki stronie FreshPorts () prowadzonej + przez Dana Langille'a mo¿liwe jest bie¿±ce ¶ledzenie zmian + aplikacji w drzewie portów. Witryna umo¿liwia otrzymywanie + informacji drog± emailow± o zmianach w wybranych + portach. + + + FreshMeat + + + Je¶li nie znamy nazwy programu, który chcemy zainstalowaæ, + warto poszukaæ go na stronach pokroju FreshMeat () a nastêpnie + sprawdziæ na stronie FreeBSD czy zosta³ przygotowany + odpowiedni port. + + + + Je¶li znamy dok³adn± nazwê portu a chcemy sprawdziæ + z jakiej pochodzi kategorii, mo¿na skorzystaæ z polecenia + &man.whereis.1;. Wystarczy wpisaæ whereis + plik, gdzie + plik jest nazw± programu, którego + poszukujemy. Otrzymany wynik bêdzie postaci: + + &prompt.root; whereis lsof +lsof: /usr/ports/sysutils/lsof + + Przyk³ad ten informuje nas, ¿e program lsof + (narzêdzie systemowe) znajduje siê w katalogu + /usr/ports/sysutils/lsof. + + + Jeszcze innym sposobem na odnalezienie danego portu jest + wykorzystanie mechanizmu przeszukiwania kolekcji portów. + By skorzystaæ z tej funkcji nale¿y przej¶æ do katalogu + /usr/ports. Nastêpnie wpisaæ + make search + name=nazwa-programu, + gdzie program-name jest nazw± + poszukiwanej aplikacji. Przyk³adowo, szukaj±c + lsof: + + &prompt.root; cd /usr/ports +&prompt.root; make search name=lsof +Port: lsof-4.56.4 +Path: /usr/ports/sysutils/lsof +Info: Lists information about open files (similar to fstat(1)) +Maint: obrien@FreeBSD.org +Index: sysutils +B-deps: +R-deps: + + Czê¶æ wyniku, która nas interesuje to wiersz zaczynaj±cy + siê od Path:, a okre¶laj±cy lokalizacjê portu. + Pozosta³e z uzyskanych w ten sposób informacji nie zostan± + tutaj opisane, gdy¿ nie s± potrzebne do instalacji + programu. + + Szersze przeszukanie kolekcji portów mo¿liwe jest + wykorzystuj±c make + search key=zwrot, + gdzie zwrot jest dowolnym wyrazem. + Opcja ta przeszukuje nazwy portów, komentarze, opisy i listy + zale¿no¶ci. Moze byæ wykorzystana do odnalezienia portów + zwi±zanych z danym zagadnieniem gdy nie znamy nazwy + poszukiwanego programu. + + W obydwu przypadkach nie s± rozró¿niane ma³e i du¿e + litery w poszukiwanym ci±gu. Szukaj±c zatem LSOF + oraz lsof otrzymamy takie same wyniki. + + + + + + + + + + Chern + Lee + Napisa³ + + + + + + Aleksander + Fafu³a + T³umaczy³ + + + + + Cezary + Morga + Przek³ad uzupe³ni³ + + + + + Korzystanie z systemu pakietów + + + Instalacja pakietów + + pakiety + instalacja + + + + pkg_add + + Programu &man.pkg.add.1; mo¿na u¿yæ do instalacji + programów zarówno z dysku lokalnego, jak i z sieci. + + + Rêczne pobranie pakietu i instalacja lokalna + + &prompt.root; ftp -a ftp2.FreeBSD.org +Connected to ftp2.FreeBSD.org. +220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready. +331 Guest login ok, send your email address as password. +230- +230- This machine is in Vienna, VA, USA, hosted by Verio. +230- Questions? E-mail freebsd@vienna.verio.net. +230- +230- +230 Guest login ok, access restrictions apply. +Remote system type is UNIX. +Using binary mode to transfer files. +ftp> cd /pub/FreeBSD/ports/packages/sysutils/ +250 CWD command successful. +ftp> get lsof-4.56.4.tgz +local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz +200 PORT command successful. +150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes). +100% |**************************************************| 92375 00:00 ETA +226 Transfer complete. +92375 bytes received in 5.60 seconds (16.11 KB/s) +ftp> exit +&prompt.root; pkg_add lsof-4.56.4.tgz + + + Je¶li nie posiadamy lokalnego ¼ród³a programów (np na + p³ytach CD FreeBSD), bêdzie Ci prawdopodobnie ³atwiej u¿yæ komendy + &man.pkg.add.1; z opcj± . Spowoduje to, + ¿e program samodzielnie okre¶li odpowiedni± wersjê oprogramowania + dla naszej wersji systemu. Nastêpnie pobierze odpowiedni plik + z sieci oraz go zainstaluje. + + + pkg_add + &prompt.root; pkg_add -r lsof + + W powy¿szym przyk³adzie program pobierze w³a¶ciwy pakiet + i zainstaluje go bez jakiejkolwiek dalszej ingerencji u¿ytkownika. + Je¶li chcemy wskazaæ programowi alternatywny serwer lustrzany, + nale¿y odpowiednio zdefiniowaæ zmienn± ¶rodowiskow± + PACKAGESITE. Program &man.pkg.add.1; do pobierania + plików z serwerów wykorzystuje &man.fetch.3;, który z kolei + wykorzystuje ró¿norodne zmienne ¶rodowiskowe, m.in. + FTP_PASSIVE_MODE, FTP_PROXY oraz + FTP_PASSWORD. Mo¿e siê okazaæ, ¿e bêdziemy musieli + zdefiniowaæ niektóre z nich je¶li nasz komputer znajduje siê za + zapor± ogniow±, b±d¼ musi korzystaæ z serwera po¶rednicz±cego + FTP/HTTP proxy. Wiêcej informacji znale¼æ mo¿na w podrêczniku + systemowym programu &man.fetch.3;. Warto zauwa¿yæ, i¿ w + powy¿szym przyk³adzie jako nazwê pakietu podano jedynie + lsof zamiast lsof-4.56.4. + Przy zdalnym pobieraniu pakietów nie nale¿y podawaæ numeru wersji + pakietu. Program &man.pkg.add.1; automatycznie pobie¿e najnowsz± + wersjê aplikacji. + + + Program &man.pkg.add.1; pobierze najnowsz± wersjie aplikacji + jedynie, gdy wykorzystujemy &os.current; albo &os.stable;. W przypadku + -RELEASE pobrana zostanie wersja pakietu zbudowana dla danego wydania. + Ograniczenie to mo¿na obej¶æ modyfikuj±æ zmienn± ¶rodowiskow± + PACKAGESITE. Na przyk³ad, je¶li korzystamy z + &os; 5.4-RELEASE domy¶lnie &man.pkg.add.1; bêdzie pobiera³ + pakiety z + ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-5.4-release/Latest/. + By zmusiæ go do pobierania pakietów zbudowanych dla + &os; 5-STABLE nale¿y zmodyfikowaæ zmienn± PACKAGESITE + by wskazywa³a na + ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-5-stable/Latest/. + + + Pakiety rozpowszechniane s± w formacie .tgz + oraz .tbz. Mo¿emy je pobraæ z + , + w Polsce z , + b±d¼ odnale¼æ na p³ytach CDROM FreeBSD. Ka¿da p³yta z cztero p³ytowej + dystrybucji (tak¿e PowerPak'a itp) zawiera pakiety w katalogu + /packages. Struktura katalogu podobna jest + do drzewa portów /usr/ports. Ka¿da kategoria ma + swój w³asny katalog, ponadto ka¿dy pakiet mo¿e zostaæ odnaleziony + w katalogu All (Wszystkie). + + Struktura katalogów pakietów jest identyczna wzglêdem + struktury katalogów portów. Porty i pakiety kooperuj± za sob±, + tworz±c wspólnie ca³y system pakietów/portów. + + + + + Zarz±dzanie pakietami + + + pakiety + zarz±dzanie + + Narzêdziem s³u¿±cym do przedstawienia informacji + o zainstalowanych pakietach oraz wy¶wietlaj±cym ich krótki + opis jest &man.pkg.info.1;. + + + pkg_info + + &prompt.root; pkg_info +cvsup-16.1 A general network file distribution system optimized for CV +docbook-1.2 Meta-port for the different versions of the DocBook DTD +... + Program &man.pkg.version.1; jest natomiast narzêdziem, + które podsumowuje wersje wszystkich zainstalowanych pakietów. + Porównuje je nastêpnie z tymi które znajduj± siê w drzewie portów. + + pkg_version + + &prompt.root; pkg_version +cvsup = +docbook = +... + + Symbol w drugiej kolumnie okre¶la wiek zainstalowanej wersji + oprogramowania wzglêdem wersji odnalezionej w portach. + + + + + + Symbol + Znaczenie + + + + + + = Wersja odnaleziona w portach jest + identyczna./entry> + + + < + Wersja jest starsza, ni¿ ta odnaleziona w portach. + + + >Zainstalowana wersja jest nowsza, + ni¿ znaleziona w portach. (Prawdopodobnie lokalne drzewo portów + nie zosta³o zaktualizowane.) + + ?Zainstalowany pakiet nie mo¿e zostaæ + odnaleziony w drzewie portów. (Mo¿e to mieæ miejsce np. w sytuacji + gdy zainstalowany port zosta³ usuniêty z kolekcji portów, b±d¼ + zmieni³ nazwê.) + + *Istnieje wiele wersji tego programu. + + + + + + + + Usuwanie pakietów + + pkg_delete + + + pakiety + usuwanie + + Aby usun±æ uprzednio zainstalowane oprogramowanie u¿yj &man.pkg.delete.1;. + + &prompt.root; pkg_delete xchat-1.7.1 + + + + Dodatkowe informacje + Wszystkie informacje o pakietach znajduj± siê w katalogu + /var/db/pkg. Lista zainstalowanych plików, + a tak¿e opis ka¿dej paczki mo¿na odnale¼æ w³a¶nie w tym katalogu. + + + + + + + + + Aleksander + Fafu³a + T³umaczy³ + + + + + Cezary + Morga + Przek³ad uzupe³ni³ + + + + + Korzystanie z kolekcji portów + + Poni¿szy podrozdzia³ dostarcza podstawowych informacji + z zakresu u¿ywania kolekcji portów, w stopniu umo¿liwiaj±cym + instalowanie lub odinstalowywanie programów z w³asnego systemu. + Szczegó³owy opis parametrów polecenia make + i zmiennych ¶rodowiskowych dostêpny jest w podrêczniku + systemowym &man.ports.7;. + + + Pozyskanie kolekcji portów + + Zanim zainstalujemy jakikolwiek port, musimy pobraæ + kolekcjê portów, która w zasadzie jest zestawem plików + Makefiles, ³at i opisowych. Kolekcja + znajduje siê w katalogu /usr/ports. + + W trakcie instalacji FreeBSD, sysinstall + zapyta³ czy chcemy zainstalowaæ kolekcjê portów. Je¶li wybrali¶my + nie, poni¿sze instrukcje pomog± nam w³asnorêcznie zainstalowaæ + kolekcjê portów: + + + Metoda CVSup + + Jest to prosta i szybka metoda pobrania kolekcji portów + wykorzystuj±ca system CVSup. + Wiêcej informacji o CVSup dostêpnych + jest w podrozdziale Korzystanie z + CVSup. + + Bardzo wa¿nym jest, aby upewniæ siê, ¿e katalog + /usr/ports jest pusty + nim po raz pierwszy uruchomimy CVSup! + Jesli posiadamy ju¿ kolekcjê portów pozyskan± z innego ¼ród³a + CVSup nie usunie nieu¿ywanych + plików ³at. + + + Zainstaluj pakiet net/cvsup-without-gui: + + &prompt.root; pkg_add -r cvsup-without-gui + + Wiêcej informacji w podrozdziale Instalacja CVSup (). + + + + Uruchom cvsup: + + &prompt.root; cvsup -L 2 -h cvsup.FreeBSD.org /usr/share/examples/cvsup/ports-supfile + + Warto zast±piæ cvsup.FreeBSD.org + adresem serwera CVSup zlokalizowanego bli¿ej nas. Kompletna lista + serwerów lustrzanych dostêpna jest w podrozdziale + Serwery lustrzane CVSup + (). + + + Mo¿na wykorzystaæ w³asny plik ports-supfile, + by np. unikn±æ konieczno¶ci podawania adresu serwera + CVSup z linii poleceñ. + + + + W takim wypadku, jako u¿ytkownik root, + skopiuj plik + /usr/share/examples/cvsup/ports-supfile + do innego katalogu, np. /root b±d¼ w³asnego + katalogu domowego. + + + + Zmodyfikuj plik ports-supfile. + + + + Zmieñ wpis + CHANGE_THIS.FreeBSD.orgna adres + wybranego serwera lustrzanego CVSup. + Kompletna lista serwerów lustrzanych dostêpna jest w podrozdziale + Serwery lustrzane + CVSup (). + + + + Teraz uruchom cvsup u¿ywaj±c + polecenia:: + + &prompt.root; cvsup -L 2 /root/ports-supfile + + + + + + + Pó¼niejsze wpisanie polecenia &man.cvsup.1; spowoduje + sprawdzenie zmian dokonanych w kolekcji portów i aktualizacjê + lokalnej wersji. Nie spowoduje to natomiast automatycznie ponownego + skompilowania wykorzystywanych przez nas portów. + + + + + Metoda Portsnap + + Portsnap jest alternatywnym + systemem dystrybucji kolekcji portów. Po raz pierwszy zosta³ + do³±czony do FreeBSD 6.0. W starszych wersjach mo¿e zostaæ + zainstalowany z pakietu sysutils/portsnap: + + &prompt.root; pkg_add -r portsnap + + Szczegó³owe informacje o mo¿liwo¶ciach programu dostêpne + s± w podrozdziale Korzystanie z + Portsnap. + + + Ten punkt mo¿emy pomin±æ je¶li posiadamy &os; 6.1-RELEASE + b±d¼ najnowsz± wersjê programu Portsnap. + Przy pierwszym uruchomieniu programu &man.portsnap.8; zostanie + automatycznie utworzony katalog /usr/ports. W starszych wersjach programu + wymagane jest w³asnorêczne utworzenie katalogu: + + &prompt.root; mkdir /usr/ports + + + + Pobierz skompresowan± migawkê kolekcji portów do katalogu + /var/db/portsnap. Mo¿na nastêpnie + zakoñczyæ po³±czenie z Internetem, je¶li jest taka potrzeba. + + &prompt.root; portsnap fetch + + + + Je¶li uruchamiany Portsnap po raz + pierwszy nale¿y rozpakowaæ migawkê do katalogu + /usr/ports: + + + &prompt.root; portsnap extract + + Je¶li posiadamy ju¿ kolekcjê portów w /usr/ports i jedynie j± aktualizujemy, + wpisujemy polecenie: + + &prompt.root; portsnap update + + + + + + Metoda sysinstall + + Metoda ta instaluje kolekcjê portów z lokalnego no¶nika pos³uguj±c + siê programem sysinstall. Zainstalowana + zostanie kopia kolekcji z dnia, w którym przygotowana zosta³a dana wersja + FreeBSD. Je¶li dysponujemy po³±czeniem z Internetem powinni¶my zawsze + stosowaæ jedn± z metod opisanych powy¿ej. + + + Uruchom sysinstall jako u¿ytkownik + root (/stand/sysinstall + w wersjach &os; starszych ni¿ 5.2): + + &prompt.root; sysinstall + + + + Przejd¼ w dó³, wybierz Configure, + i naci¶nij Enter. + + + + Przejd¼ w dó³, wybierz + Distributions i naci¶nij + Enter. + + + + Przejd¼ w dó³ do opcji ports i naci¶nij + Spacjê. + + + + Przejd¼ do góry do opcji Exit i naci¶nij + Enter. + + + + Ustaw wybrany przez siebie typ medium instalacji, jak np. p³ytê CDROM, + serwer FTP, itd. + + + + Przejd¼ do góry do opcji Exit i naci¶nij + Enter. + + + + Naci¶ni X by wyj¶æ z programu + sysinstall. + + + + + + Instalacja Portów + + + porty + instalacja + + Pierwsza rzecz o jakiej nale¿y wspomnieæ omawiaj±c + kolekcjê portów, jest szkielet. Mówi±c w + skrócie, szkielet portu jest minimalnym zestawem plików, + które informuj± FreeBSD, jak poprawnie skompilowaæ i + zainstalowaæ program. Ka¿dy szkielet portu zawiera: + + + + Plik Makefile. Plik ten zawiera + ró¿ne dane okre¶laj±ce jak skompilowaæ aplikacjê oraz gdzie + j± zainstalowaæ w systemie. + + + + Plik distinfo Plik ten zawiera informacje + dotycz±ce plików, które musz± zostaæ pobrane, by skompilowaæ + port. Ponadto zawiera sumy kontrolne, na podstawie których + &man.md5.1; potrafi sprawdziæ, czy pliki nie uleg³y uszkodzeniu + w trakcie pobierania z sieci. + + + + Katalog files, który zawiera ³aty + pozwalaj±ce skompilowaæ i zainstalowaæ program w naszym + systemie FreeBSD. £aty s± ma³ymi plikami, w których okre¶lone + s± zmiany dotycz±ce konkretnych plików. S± to pliki tekstowe i po + prostu mówi± Usuñ liniê 10 lub Zmieñ liniê + 26 na to: .... £atki s± tak¿e znane jako diffs + (ang. skrót od ró¿nice) poniewa¿ s± generowane przez program + &man.diff.1;. + + Ten katalog mo¿e zawieraæ tak¿e inne pliki u¿ywane do + kompilacji portu. + + + + Plik opisu pkg-descr. Jest to bardziej + szczegó³owy, nierzadko wieloliniowy opis programu. + + + + Plik listy pkg-plist. Jest to lista wszystkich + plików, które zostan± zainstalowane przez port. Jest to tak¿e lista plików, + które nale¿y usun±æ w przypadku odinstalowywania. + + + + Niekiedy porty zawieraj± równie¿ inne pliki, jak na przyk³ad + pkg-message (message-wiadomo¶æ). + System portów u¿ywa tych plików w specjalnych sytuacjach. Je¶li potrzebujesz + wiêcej informacji na temat tych plików i portów w ogóle, zajrzyj do podrêcznika + FreeBSD + Porter's Handbook. + + Jak ju¿ raz powiedziano, porty zawieraj± instrukcje odno¶nie + kompilacji programów z kodu ¼ród³owego. Jednak¿e nie zawieraj± + one samego kodu. Kod pobraæ mo¿na z p³yty CD b±d¼ z Internetu. + Rozprowadzany mo¿e byæ w dowolnej postaci jak± wybierze sobie + jego producent, przy czym najczê¶ciej jest to spakowany plik tar + skompresowany dodatkowo gzipem. Kod ¼ród³owy programu nazywany + jest distfile. Poni¿ej przedstawione zosta³y dwie + metody instalacji portów we &os;. + + + By móc zainstalowaæ port musimy byæ zalogowania jako + u¿ytkownik root. + + + + Przed instalacj± jakiegokolwiek portu nale¿y upewniæ siê, + ¿e dysponujemy aktualn± kolekcj± portów oraz sprawdziæ potencjalne + luki bezpieczeñstwa zwi±zane z danym portem na stronie . + + Istnieje mo¿liwo¶æ zautomatyzowania procesu weryfikacji + potencjalnych luk bezpieczeñstwa przed instalacj± portu. Do tego + celu mo¿na wykorzystaæ program portaudit, + dostêpny równie¿ w kolekcji portów (security/portaudit). Wydanie polecenia + portaudit -F przed instalacj± nowego portu + spowoduje pobranie aktualnej bazy luk bezpieczeñstwa. Mo¿liwe jest + równie¿ wykonywanie regularnych aktualizacji bazy i rewizji + zainstalowanego oprogramowania w trakcie codziennego przegl±du + bezpieczeñstwa systemu. Wiêcej informacji dostêpnych jest na stronach + podrêcznika systemowego &man.portaudit.1; i &man.periodic.8;. + + + Sposób funkcjonowania kolekcji portów wi±¿e siê z za³o¿eniem, + ¿e posiadamy po³±czenie z Internetem. Je¶li nie, bêdziemy musieli + rêcznie pobieraæ kod ¼ród³owy distfile i umieszczaæ + w katalogu /usr/ports/distfiles dla ka¿dego + instalowanego portu. + + By rozpocz±æ instalacjê nale¿y przej¶æ do katalogu + wybranego portu: + + &prompt.root; cd /usr/ports/sysutils/lsof + + Wewn±trz katalogu lsof znajduje siê + szkielet portu. Nastêpnym krokiem jest kompilacja programu, co + sprowadza siê do wpisania polecenia make. + Efekt dzia³ania polecenia powinien byæ zbli¿ony do: + + &prompt.root; make +>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +>> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/. +===> Extracting for lsof-4.57 +... +[extraction output snipped] +... +>> Checksum OK for lsof_4.57D.freebsd.tar.gz. +===> Patching for lsof-4.57 +===> Applying FreeBSD patches for lsof-4.57 +===> Configuring for lsof-4.57 +... +[configure output snipped] +... +===> Building for lsof-4.57 +... +[compilation output snipped] +... +&prompt.root; + + Po skoñczeniu kompilacji powracamy do linii poleceñ. + Kolejnym krokiem jest instalacja portu poprzez wpisanie polecenia + make wraz ze s³owem + install: + + &prompt.root; make install +===> Installing for lsof-4.57 +... +[installation output snipped] +... +===> Generating temporary packing list +===> Compressing manual pages for lsof-4.57 +===> Registering installation for lsof-4.57 +===> SECURITY NOTE: + This port has installed the following binaries which execute with + increased privileges. +&prompt.root; + + Gdy ponownie powrócimy do linii poleceñ, powinni¶my + byæ ju¿ w stanie uruchomiæ w³a¶nie zainstalowan± aplikacjê. + Ostrze¿enie jakie pojawi siê na ekranie zwi±zane jest z faktem, + ¿e lsof jest programem pracuj±cym ze zwiêkszonymi przywilejami. + W trakcie kompilacji i instalacji portów powinni¶my zwracaæ uwagê + na wszystkie pojawiaj±ce siê ostrze¿enia. + + Dobrym pomys³em, jest równie¿ usuniêcie podkatalogu + zawieraj±cego wszystkie tymczasowe pliki wykorzystywane + w trakcie kompilacji. Nie tylko dlatego, ¿e niepotrzebnie zajmuje + miejsce na dysku, ale równie¿ dlatego, ¿e mo¿e byæ przyczyn± + problemów podczas aktualizacji programu do nowszej wersji. + + &prompt.root; make clean +===> Cleaning for lsof-4.57 +&prompt.root; + + + Mo¿na sobie oszczêdziæ dwóch naddatkowych kroków wpisuj±c + od razu make install clean zamiast trzech + osobnych poleceñ make, + make install oraz + make clean. + + + + Niektóre pow³oki utrzymuj± bufor listy poleceñ + z katalogów znajduj±cych siê w zmiennej ¶rodowiskowej + PATH. Ma to za zadanie przy¶pieszyæ + wyszukiwanie plików binarnych tych¿e poleceñ. + Je¶li korzystamy z jednej z takich w³a¶nie pow³ok + mo¿e okazaæ siê niezbêdnym wydaæ polecenie + rehash po instalacji portu, + nim bêdziemy mogli wykorzystaæ nowo zainstalowany + program. Polecenie to dostêpne jest przy wykorzystaniu + pow³oki typu tcsh. Natomiast + dla pow³oki typu sh odpowiednikiem + jest hash -r. Wiêcej informacji + dostêpnych jest w dokumentacji pow³oki. + + + Niektóre wydawnictwa na p³ytach DVD-ROM, jak np. FreeBSD + Toolkit z FreeBSD + Mall, zawieraj± ¼ród³a distfile. Mog± byæ one + wykorzystane z kolekcj± portów. Wystarczy zamontowaæ p³ytê + DVD w /cdrom. Je¶li natomiast u¿ywamy + innego punktu montowania dla p³yt musimy zmodyfikowaæ zmienn± + CD_MOUNTPTS by wskazywa³a na w³a¶ciwe + miejsce. Niezbêdne ¼ród³a distfile zostan± automatycznie + wykorzystane je¶li znajduj± siê na p³ycie. + + + Mimo wszystko nale¿y mieæ w pamiêci, ¿e licencje + nielicznych portów nie zezwalaj± na za³±czenie ich na + p³ycie CD-ROM. Mo¿e to byæ np. z powodu konieczno¶ci + wcze¶niejszej rejestracji przed pobraniem ¼róde³ b±d¼ + ich redystrybucja nie jest dozwolona. Je¶li chcemy + zainstalowaæ port, który nie znajduje siê na p³ycie + CD musimy mieæ po³±czenie z Internetem. + + + System portów do pobierania plików wykorzystuje + program &man.fetch.1;, który z kolei potrafi korzystaæ + z wielu zmiennych ¶rodowiskowych, m.in. + FTP_PASSIVE_MODE, FTP_PROXY + czy FTP_PASSWORD. Je¶li znajdujemy siê + za zapor± ogniow±, b±d¼ musimy korzystaæ z serwera + po¶rednicz±cego FTP/HTTP proxy, mo¿e siê okazaæ, + ¿e bêdziemy musieli ustawiæ niektóre z tych zmiennych. + Kompletna lista wykorzystywanych zmiennych dostêpna + jest w podrêczniku systemowym &man.fetch.3;. + + Dla u¿ytkowników nie mog±cych byæ ca³y czas po³±czonych + z Internetem dostêpne jest polecenie + make fetch. + Wystarczy wpisaæ to polecenie znajduj±c siê w g³ównym + katalogu drzewa portów (/usr/ports) + a wymagane pliki zostan± automatycznie pobrane. Polecenie + to bêdzie równie¿ funkcjonowaæ w podkatalogach, np. + /usr/ports/net. Jednak¿e, w takiej + sytuacji nie zostan± automatycznie + pobrane ¼ród³a bibliotek, od których zale¿y dany port. + Zamieniaj±c parametr fetch na + fetch-recursive spowodujemy + pobranie równie¿ ¼róde³ wszystkich portów, od których + zale¿y instalowany program. + + Mo¿liwe jest kompilowanie ka¿dego portu z osobna + w danej kategorii, b±d¼ wszystkich na raz poprzez polecenie + make wykonane, analogicznie do + make fetch, + w g³ównym katalogu kategorii. Jednak¿e jest to niebezpieczna + metoda, gdy¿ niektóre porty nie mog± jednocze¶nie funkcjonowaæ + w systemie, b±d¼ mog± zainstalowaæ ró¿ne pliki o tej samej + nazwie. + + W naprawdê ¿adkich przypadkach, u¿ytkownicy mog± pozyskaæ + pliki distfile z innego ¼ród³a ni¿ MASTER_SITES + (miejsce sk±d je pobiera system portów). Opcjê + MASTER_SITES mo¿na zast±piæ za + pomoc± nastêpuj±cego polecenia: + + &prompt.root; cd /usr/ports/directory +&prompt.root; make MASTER_SITE_OVERRIDE= \ +ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch + + W tym przyk³adzie zast±pili¶my opcjê + MASTER_SITES adresem ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/. + + Niektóre porty umo¿liwiaj± (a nawet wymagaj±) + podanie pewnych opcji kompilacji, które mog± w³±czyæ + b±d¼ wy³±czyæ nie potrzebne czê¶ci aplikacji, pewne + opcje bezpieczeñstwa i inne parametry. Z przychodz±cych + na my¶l tego typu programów to + www/mozilla, security/gpgme oraz mail/sylpheed-claws. Za ka¿dym + razem gdy dostêpne bêd± tego typu opcje wy¶wietlony + zostanie komunikat. + + + Ignorowanie domy¶lnych katalogów portów + + Czasami okazuje siê byæ przydatne (a nawet wymagane) + by skorzystaæ z innych katalogów tymczasowych i docelowych. + Domy¶lne katalogi mo¿na zast±piæ wykorzystuj±c zmienne + WRKDIRPREFIX i PREFIX. + Na przyk³ad: + + &prompt.root; make WRKDIRPREFIX=/usr/home/example/ports install + + spowoduje skompilowanie portu w katalogu + /usr/home/example/ports i instalacjê + w podkatalogach /usr/local. + + &prompt.root; make PREFIX=/usr/home/example/local install + + spowoduje natomiast kompilacjê w katalogu + /usr/ports oraz instalacjê + w podkatalogach + /usr/home/example/local. + + I oczywi¶cie, + + &prompt.root; make WRKDIRPREFIX=../ports PREFIX=../local install + + spowoduje po³±cznie obydwu powy¿szych + ustawien (jest to za d³ugie by ca³kowicie zmie¶ci³o + siê na stronie, ale powinno daæ ogólne wyobra¿enie). + + Alternatywnie, obydwie zmienne mog± byæ + równie¿ okre¶lone jako zmienne ¶rodowiskowe. + Informacje o definiowaniu zmiennych ¶rodowiskowych + dostêpne s± w podrêczniku systemowym naszej + pow³oki. + + + + Jak poradziæ sobie z <command>imake</command> + + Niektóre porty wykorzystuj±ce imake + (czê¶æ Systemu okien X) nie wspó³pracuj± ze zmienn± + PREFIX i mimo wszystko bêd± + instalowa³y programy w /usr/X11R6. + Podobnie niektóre z portów napisanych w jêzyku Perl + ingoruj± zmienn± PREFIX + i instaluj± programy w g³ównym drzewie Perla. + Zmuszenie tych portów do wspó³pracy ze zmienn± + PREFIX jest niezmiernie trudne, + albo wrêcz niemo¿liwe. + + + + + + Usuwanie zainstalowanych portów + + + porty + usuwanie + + Teraz, gdy wiesz ju¿ jak instalowaæ porty, + zastanawiasz siê prawdopodobnie jak je usuwaæ, + na przyk³ad w wypadku, gdy zainstalowali¶my port, + ale okaza³o siê jednak, ¿e to nie by³ ten którego + szukali¶my. W ramach przyk³adu usuniemy port, + który instalowali¶my poprzednio (dla tych którzy + nie uwa¿aj±, by³ to lsof). + Podobnie jak w przypadku pakietów (szerzej opisane + w podrozdziale traktuj±cym o pakietach), + równie¿ porty usuwane s± za pomoc± polecenia + &man.pkg.delete.1;: + + &prompt.root; pkg_delete lsof-4.57 + + + + + Aktualizacja portów + + + porty + aktualizacja + + Na wstêpie musimy wy¶wietliæ zdezaktualizowane porty w kolekcji. + Wykorzystamy do tego polecenie &man.pkg.version.1;: + + &prompt.root; pkg_version -v + + + <filename>/usr/ports/UPDATING</filename> + + Po zaktualizowaniu kolekcji, a przed prób± aktualizacji + jakichkolwiek portów, nale¿y zapoznaæ siê z zawarto¶ci± pliku + /usr/ports/UPDATING. Plik ten opisuje + ró¿ne zagadnienia i dodatkowe kroki, na które mo¿na natkn±æ + siê i bêdzie trzeba wykonaæ podczas aktualizacji, np. + zmiany formatu plików czy zmiany w lokalizacji plików + konfiguracyjnych. + + Je¶li opis w pliku UPDATING mówi co¶ innego + ni¿ ten tekst, nale¿y zastosowaæ siê do opisu. + + + + Aktualizacja portów z wykorzystaniem programu Portupgrade + + + portupgrade + + + Program portupgrade zosta³ + zaprojektowany by u³atwiæ aktualizacjê zainstalowanych w + systemie portów. Dostêpny jest z portu sysutils/portupgrade. + Jego instalacja przebiega dok³adnie tak samo, jak ka¿dego + innego portu, wykorzystuj±c polecenie + make install + clean command: + + &prompt.root; cd /usr/ports/sysutils/portupgrade +&prompt.root; make install clean + + Przeskanujmy nastêpnie listê zainstalowanych portów + za pomoc± polecenia pkgdb -F i usuñmy + wszystkie niezgodno¶ci jakie nam zwróci skanowanie. + Regularne skanowanie przed ka¿d± aktualizacj± jest + zdecydowanie dobrym pomys³em. + + Wydanie polecenia portupgrade -a + spowoduje, ¿e program portupgrade + rozpocznie aktualizacjê wszystkich przedawnionych portów + zainstalowanych w naszym systemie. Parametr + pozwoli przej¶æ w tryb interaktywny, gdzie bêdziemy musieli + potwierdziæ aktualizacjê ka¿dego portu. + + &prompt.root; portupgrade -ai + + By zaktualizowaæ jedynie wybran± aplikacjê zamiast wszystkich + portów nale¿y wykorzystaæ polecenie portupgrade + nazwa_programu. + Opcja oznacza, ¿e portupgrade powinien + najpierw zaktualizowaæ wszystkie porty, od których + zale¿y dany program. + + &prompt.root; portupgrade -R firefox + + By do instalacji wykorzystaæ pakiety zamiast portów + nale¿y dodaæ parametr . Wówczas + portupgrade przeszuka katalogi + zawarte w zmiennej PKG_PATH. Je¶li pakiet + nie zostanie odnaleziony lokalnie zostanie pobrany z Internetu. + Je¶li nie bêdzie mo¿liwe ¿adne z powy¿szych, wówczas + portupgrade wykorzystan do + aktualizacji porty. By temu zapobiec nale¿y zastosowaæ + parametr . + + &prompt.root; portupgrade -PR gnome2 + + Aby pobraæ jedynie pliki ¼ród³owe distfiles + (b±d¼ pakiety, gdy wykorzystamy opcjê ) + bez kompilacji czy instalacji czegokolwiek nale¿y u¿yæ + parametru . Wiêcej informacji + dostepnych jest w &man.portupgrade.1;. + + + + Aktualizacja portów z wykorzystaniem programu Portmanager + + + portmanager + + + Kolejnym narzêdziem u³atwiaj±cym aktualizacjê zainstalowanych + portów jest Portmanager, dostêpny z portu + sysutils/portmanager: + + &prompt.root; cd /usr/ports/sysutils/portmanager +&prompt.root; make install clean + + Wszystkie zainstalowane porty mog± zostaæ zaktualizowane + za pomoc± polecenia: + + &prompt.root; portmanager -u + + Wykorzystuj±c parametr przechodzimy w tryb + interaktywny, gdzie bêdziemy pytani o potwierdzenie ka¿dej operacji + wykonywanej przez Portmanager. + Program ten mo¿e byæ z równym powodzeniem wykorzystywany do instalacji + nowych portów w systemie. W przeciwieñstwe do polecenia + make install clean program + Portmanager zaktualizuje wszystkie + zale¿no¶ci nim skompiluje i zainstaluje wybrany port. + + &prompt.root; portmanager x11/gnome2 + + Gdy wyst±pi± problemy z zale¿no¶ciamy wybranego portu + mo¿na wykorzystaæ Portmanagera, + by ponownie skompilowa³ je we w³a¶ciwej kolejno¶ci. Na + koniec zostanie równie¿ ponownie skompilowany port + stwarzaj±cy problemy. + + &prompt.root; portmanager graphics/gimp -f + + Wiêcej informacji dostêpnych jest na stronach podrêcznika + systemowego Portmanagera. + + + + + Porty i przestrzeñ na dysku + + + porty + przestrzeñ na dysku + + Korzystanie z kolekcji portów z czasem odbije siê na + wolnym miejscu na dysku. Dlatego te¿ zawsze po skompilowaniu + i zainstalowaniu programu z portu powinni¶my pamiêtaæ + o usuniêciu tymczasowych katalogów roboczych (ang. + work directories) + wykorzystuj±c do tego polecenie make + clean. Ca³± kolekcjê natomiast + mo¿na oczy¶ciæ wpisuj±ce polecenie: + + &prompt.root; portsclean -C + + Z czasem uzbiera nam siê wiele katalogów + distfiles, które + bêd± jedynie zajmowaæ przestreñ na dysku. Mo¿emy je rêcznie + usuwaæ b±d¼ pos³u¿yæ siê nastêpuj±cym popleceniem, by usun±æ + wszystkie katalogi distfiles nie powi±zane aktualnie z + ¿adnym portem: + + &prompt.root; portsclean -D + + + Program portsclean jest czê¶ci± pakietu + portupgrade. + + + Pamiêtajmy równie¿ o usuwaniu instalowanych portów gdy + ju¿ ich nie potrzebujemy. Przydatne narzêdzie pozwalaj±ce + zautomatyzowaæ te czynno¶ci znajduje siê w + sysutils/pkg_cutleaves. + + + + + + Czynno¶ci po-instalacyjne + + Po zainstalowaniu nowego programu z regu³y chcemy + zapoznaæ siê z dostarczon± z nim dokumentacj±, zmodyfikowaæ + wymagane pliki konfiguracyjne, upewniæ siê, ¿e program + (je¶li jest to demon) bêdzie uruchamiany w trakcie + ³adowania systemu, itp. + + Oczywi¶cie, szczegó³owe kroki jakie nale¿y podj±æ + konfiguruj±c ka¿d± aplikacjê bêd± ró¿ne. Tym nie mniej, + je¶li w³a¶nie zainstalowali¶my nowy program i zastanawiamy + siê Co dalej? poni¿sze uwagi mog± + okazaæ siê pomocne: + + + + Za pomoc± &man.pkg.info.1; mo¿emy sprawdziæ gdzie + i jakie pliki zosta³y zainstalowane. Na przyk³ad, je¶li + zainstalowali¶my wersjê 1.0.0 pakietu FooPackage, + polecenie + + &prompt.root; pkg_info -L foopackage-1.0.0 | less + + wy¶wietli nam wszystkie pliki zainstalowane + z pakietu. Szczególn± uwagê warto zwróciæ na pliki + zainstalowane w katalogach: man/ + zawieraj±cym strony podrêcznika systemowego, + etc/ zawieraj±cym pliki + konfiguracyjne, oraz doc/, + gdzie znajdowaæ siê bêdzie du¿o obszerniejsza + dokumentacja. + + Je¶li nie jeste¶my pewni, któr± wersj± programu + zainstalowali¶my, polecenie + + &prompt.root; pkg_info | grep -i foopackage + + wy¶wietli wszystkie zainstalowane pakiety + zawieraj±ce foopackage + w nazwie. Oczywi¶cie foopackage + nale¿y zast±piæ nazw± poszukiwanego pakietu. + + + + Gdy ju¿ uda³o siê ustaliæ jakie strony podrêcznika + systemowego zosta³y zainstalowane przez dany pakiet, + mo¿na je przeczytaæ za pomoc± polecenia &man.man.1;. + Warto równie¿ obejrzeæ przyk³adowe pliki konfiguracyjne + i wszelk± dodatkow± dokumentacjê. + + + + Je¶li dana aplikacja posiada w³asn± witrynê internetow± + warto jest równie¿ tam poszukaæ dodatkowej dokumentacji + czy odpowiedzi na czêsto zadawane pytania (FAQ). Je¶li nie + znamy w³a¶ciwego adresu internetowego mo¿e byæ on podany + w wyniku polecenia + + &prompt.root; pkg_info foopackage-1.0.0 + + Wiersz WWW:, je¶li w ogóle jest + podany, powinien zawieraæ informacje o adresie witryny. + + + + Programy, które powinny byæ uruchamiane podczas + ³adowania systemu (np. serwery internetowe) z regu³y + instaluj± przyk³adowy skrypt w + /usr/local/etc/rc.d. Powinni¶my + sprawdziæ zawarto¶æ tego skryptu oraz w razie potrzeby + zmodyfikowaæ go b±d¼ zmieniæ nazwê. Szczegó³owe informacje + dostêpne s± w podro¼dziale Uruchamianie + us³ug. + + + + + + Jak radziæ sobie ze ¼le przygotowanymi portami + + Je¶li natknêli¶my siê na port, który z jakich¶ + powodów nie dzia³a na naszym komputerze, mo¿emy zrobiæ + kilka nastêpuj±cych rzeczy: + + + + Sprawdziæ w bazie + danych zg³oszonych problemów czy jest przygotowywana + poprawka dla danego portu. Je¶li tak, mo¿e uda siê nam + zastosowaæ tê poprawkê. + + + + Poprosiæ o pomoc opiekuna danego portu. Adres + email opiekuna mo¿na znale¼æ przegl±daj±æ plik + Makefile w katalogu portu b±d¼ + wpisuj±æ polecenie make maintainer. + Wysy³aj±c wiadomo¶æ pamiêtajmy o zawarciu informacji + o nazwie i wersji portu (najlepiej jest zawrzeæ ca³y + wiersz z pliku Makefile zaczynaj±cy + siê od $FreeBSD:), oraz opis + b³êdu i wynik dzia³ania programu w momencie + zaistnienia b³êdu. + + + Niektóre porty nie s± przygotowywane przez pojedyncze + osoby, ale raczej przez grupy + dyskusyjne. Wiele adresów takich grup, choæ nie + wszystkie, ma postaæ + freebsd-listname@FreeBSD.org. + Nale¿y mieæ równie¿ to na uwadze formuuj±æ swoje pytania. + + Porty przygotowywane przez + freebsd-ports@FreeBSD.org + w rzeczywisto¶ci nie posiadaj± ¿adnego konkretnego opiekuna, + ani grupy opiekunów. Poprawki i pomoc dla takich portów + przygotowuj± osoby zapisane na tê listê dyskusyjn±. Nowi + ochotnicy s± zawsze mile widziani! + + + W przypadku braku odpowiedzi mo¿na równie¿ przes³aæ + zg³oszenie b³êdu poprzez &man.send-pr.1; (szczegó³y w artykule + Writing + FreeBSD Problem Reports). + + + + Naprawiæ b³±d samemu! Podrêcznik Porter's + Handbook (ang.) zawiera szczegó³owe informacje + o strukurze Portów, dziêki czemu mo¿na samemu + naprawiæ b³±d lub przygotowaæ w³asny port! + + + + Pobraæ pakiet z najbli¿szego serwera FTP. + G³ówne repozytorium pakietów znajduje + siê na serwerze ftp.FreeBSD.org w katalogu packages. + Tym nie mniej warto jest najpierw odszkukaæ lokalny serwer + lustrzany. Szanse na to, ¿e gotowe pakiety + bêd± dzia³aæ poprawnie s± wiêksze ni¿ w przypadku + kompilowania programów. Pakiety mo¿na zainstalowaæ + za pomoc± programu &man.pkg.add.1;. + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/Makefile b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/Makefile new file mode 100644 index 0000000000..1a44fcbd0c --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= ppp-and-slip/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/chapter.sgml new file mode 100644 index 0000000000..01748e264f --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/chapter.sgml @@ -0,0 +1,3173 @@ + + + + + + + Jim + Mock + Restructured, reorganized, and updated by + + + + + + PPP and SLIP + + + Synopsis + + PPP + + + SLIP + + + FreeBSD has a number of ways to link one computer to + another. To establish a network or Internet connection through a + dial-up modem, or to allow others to do so through you, requires + the use of PPP or SLIP. This chapter describes setting up + these modem-based communication services in detail. + + After reading this chapter, you will know: + + + + How to set up user PPP. + + + How to set up kernel PPP. + + + How to set up PPPoE (PPP over + Ethernet). + + + How to set up PPPoA (PPP over + ATM). + + + How to configure and set up a SLIP client and + server. + + + + + PPP + user PPP + + + PPP + kernel PPP + + + PPP + over Ethernet + + + Before reading this chapter, you should: + + + + Be familiar with basic network terminology. + + + Understand the basics and purpose of a dialup connection + and PPP and/or SLIP. + + + + You may be wondering what the main difference is between user + PPP and kernel PPP. The answer is simple: user PPP processes the + inbound and outbound data in userland rather than in the kernel. + This is expensive in terms of copying the data between the kernel + and userland, but allows a far more feature-rich PPP implementation. + User PPP uses the tun device to communicate + with the outside world whereas kernel PPP uses the + ppp device. + + + Throughout in this chapter, user PPP will simply be + referred to as ppp unless a distinction needs to be made between it + and any other PPP software such as pppd. + Unless otherwise stated, all of the commands explained in this + chapter should be executed as root. + + + + + + + + Tom + Rhodes + Updated and enhanced by + + + + + Brian + Somers + Originally contributed by + + + + + Nik + Clayton + With input from + + + Dirk + Frömberg + + + Peter + Childs + + + + + Using User PPP + + + User PPP + + + Assumptions + + This document assumes you have the following: + + + + ISP + + + PPP + + + An account with an Internet Service Provider (ISP) which + you connect to using PPP. + + + + You have a modem or + other device connected to your system and configured + correctly which allows you to connect to your ISP. + + + + The dial-up number(s) of your ISP. + + + + PAP + + + CHAP + + + UNIX + + + login name + + + password + + + Your login name and password. (Either a + regular &unix; style login and password pair, or a PAP or CHAP + login and password pair.) + + + + nameserver + + + The IP address of one or more name servers. + Normally, you will be given two IP addresses by your ISP to + use for this. If they have not given you at least one, then + you can use the enable dns command in + ppp.conf and + ppp will set the name servers for + you. This feature depends on your ISPs PPP implementation + supporting DNS negotiation. + + + + The following information may be supplied by your ISP, but + is not completely necessary: + + + + The IP address of your ISP's gateway. The gateway is + the machine to which you will connect and will be set up as + your default route. If you do not have + this information, we can make one up and your ISP's PPP + server will tell us the correct value when we connect. + + This IP number is referred to as + HISADDR by + ppp. + + + + The netmask you should use. If your ISP has not + provided you with one, you can safely use 255.255.255.255. + + + + static IP address + + + If your ISP provides you with a static IP address and + hostname, you can enter it. Otherwise, we simply let the + peer assign whatever IP address it sees fit. + + + + If you do not have any of the required information, contact + your ISP. + + + Throughout this section, many of the examples showing + the contents of configuration files are numbered by line. + These numbers serve to aid in the presentation and + discussion only and are not meant to be placed in the actual + file. Proper indentation with tab and space characters is + also important. + + + + + + Automatic <application>PPP</application> Configuration + + PPPconfiguration + Both ppp and pppd + (the kernel level implementation of PPP) use the configuration + files located in the /etc/ppp directory. + Examples for user ppp can be found in + /usr/share/examples/ppp/. + + Configuring ppp requires that you edit a + number of files, depending on your requirements. What you put + in them depends to some extent on whether your ISP allocates IP + addresses statically (i.e., you get given one IP address, and + always use that one) or dynamically (i.e., your IP address + changes each time you connect to your ISP). + + + PPP and Static IP Addresses + + PPPwith static IP addresses + You will need to edit the + /etc/ppp/ppp.conf configuration file. It + should look similar to the example below. + + + Lines that end in a : start in + the first column (beginning of the line)— all other + lines should be indented as shown using spaces or + tabs. + + + 1 default: +2 set log Phase Chat LCP IPCP CCP tun command +3 ident user-ppp VERSION (built COMPILATIONDATE) +4 set device /dev/cuaa0 +5 set speed 115200 +6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \ +7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT" +8 set timeout 180 +9 enable dns +10 +11 provider: +12 set phone "(123) 456 7890" +13 set authname foo +14 set authkey bar +15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp" +16 set timeout 300 +17 set ifaddr x.x.x.x y.y.y.y 255.255.255.255 0.0.0.0 +18 add default HISADDR + + + + Line 1: + + + Identifies the default entry. Commands in this + entry are executed automatically when ppp is run. + + + + + Line 2: + + + Enables logging parameters. When the configuration + is working satisfactorily, this line should be reduced + to saying + + set log phase tun + + in order to avoid excessive log file sizes. + + + + + Line 3: + + + Tells PPP how to identify itself to the peer. + PPP identifies itself to the peer if it has any trouble + negotiating and setting up the link, providing information + that the peers administrator may find useful when + investigating such problems. + + + + + Line 4: + + + Identifies the device to which the modem is + connected. COM1 is + /dev/cuaa0 and + COM2 is + /dev/cuaa1. + + + + + Line 5: + + + Sets the speed you want to connect at. If 115200 + does not work (it should with any reasonably new modem), + try 38400 instead. + + + + + Line 6 & 7: + + PPPuser PPP + + The dial string. User PPP uses an expect-send + syntax similar to the &man.chat.8; program. Refer to + the manual page for information on the features of this + language. + + Note that this command continues onto the next line + for readability. Any command in + ppp.conf may do this if the last + character on the line is a ``\'' character. + + + + + Line 8: + + + Sets the idle timeout for the link. 180 seconds + is the default, so this line is purely cosmetic. + + + + + Line 9: + + + Tells PPP to ask the peer to confirm the local + resolver settings. If you run a local name server, this + line should be commented out or removed. + + + + + Line 10: + + + A blank line for readability. Blank lines are ignored + by PPP. + + + + + Line 11: + + + Identifies an entry for a provider called + provider. This could be changed + to the name of your ISP so + that later you can use the + to start the connection. + + + + + Line 12: + + + Sets the phone number for this provider. Multiple + phone numbers may be specified using the colon + (:) or pipe character + (|)as a separator. The difference + between the two separators is described in &man.ppp.8;. + To summarize, if you want to rotate through the numbers, + use a colon. If you want to always attempt to dial the + first number first and only use the other numbers if the + first number fails, use the pipe character. Always + quote the entire set of phone numbers as shown. + + You must enclose the phone number in quotation marks + (") if there is any intention on using + spaces in the phone number. This can cause a simple, yet + subtle error. + + + + + Line 13 & 14: + + + Identifies the user name and password. When + connecting using a &unix; style login prompt, these + values are referred to by the set + login command using the \U and \P + variables. When connecting using PAP or CHAP, these + values are used at authentication time. + + + + + Line 15: + + + PAP + CHAP + If you are using PAP or CHAP, there will be no login + at this point, and this line should be commented out or + removed. See PAP and CHAP + authentication for further details. + + The login string is of the same chat-like syntax as + the dial string. In this example, the string works for + a service whose login session looks like this: + + J. Random Provider +login: foo +password: bar +protocol: ppp + + You will need to alter this script to suit your + own needs. When you write this script for the first + time, you should ensure that you have enabled + chat logging so you can determine if + the conversation is going as expected. + + + + + Line 16: + + timeout + + Sets the default idle timeout (in seconds) for the + connection. Here, the connection will be closed + automatically after 300 seconds of inactivity. If you + never want to timeout, set this value to zero or use + the command line switch. + + + + + Line 17: + ISP + + Sets the interface addresses. The string + x.x.x.x should be + replaced by the IP address that your provider has + allocated to you. The string + y.y.y.y should be + replaced by the IP address that your ISP indicated + for their gateway (the machine to which you + connect). If your ISP has not given you a gateway + address, use 10.0.0.2/0. If you need to + use a guessed address, make sure that + you create an entry in + /etc/ppp/ppp.linkup as per the + instructions for PPP and Dynamic IP + addresses. If this line is omitted, + ppp cannot run in + mode. + + + + + Line 18: + + + Adds a default route to your ISP's gateway. The + special word HISADDR is replaced with + the gateway address specified on line 17. It is + important that this line appears after line 17, + otherwise HISADDR will not yet be + initialized. + + If you do not wish to run ppp in , + this line should be moved to the + ppp.linkup file. + + + + + It is not necessary to add an entry to + ppp.linkup when you have a static IP + address and are running ppp in mode as your + routing table entries are already correct before you connect. + You may however wish to create an entry to invoke programs after + connection. This is explained later with the sendmail + example. + + Example configuration files can be found in the + /usr/share/examples/ppp/ directory. + + + + PPP and Dynamic IP Addresses + PPPwith dynamic IP addresses + IPCP + If your service provider does not assign static IP + addresses, ppp can be configured to + negotiate the local and remote addresses. This is done by + guessing an IP address and allowing + ppp to set it up correctly using the IP + Configuration Protocol (IPCP) after connecting. The + ppp.conf configuration is the same as + PPP and Static IP + Addresses, with the following change: + + 17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255 + + Again, do not include the line number, it is just for + reference. Indentation of at least one space is + required. + + + + Line 17: + + + The number after the / character + is the number of bits of the address that ppp will + insist on. You may wish to use IP numbers more + appropriate to your circumstances, but the above example + will always work. + + The last argument (0.0.0.0) tells + PPP to start negotiations using address 0.0.0.0 rather than 10.0.0.1 and is necessary for some + ISPs. Do not use 0.0.0.0 as the first + argument to set ifaddr as it prevents + PPP from setting up an initial route in + mode. + + + + + If you are not running in mode, you + will need to create an entry in + /etc/ppp/ppp.linkup. + ppp.linkup is used after a connection has + been established. At this point, ppp will + have assigned the interface addresses and it will now be + possible to add the routing table entries: + + 1 provider: +2 add default HISADDR + + + + Line 1: + + + On establishing a connection, + ppp will look for an entry in + ppp.linkup according to the + following rules: First, try to match the same label + as we used in ppp.conf. If + that fails, look for an entry for the IP address of + our gateway. This entry is a four-octet IP style + label. If we still have not found an entry, look + for the MYADDR entry. + + + + + Line 2: + + + This line tells ppp to add a + default route that points to + HISADDR. + HISADDR will be replaced with the + IP number of the gateway as negotiated by the + IPCP. + + + + + See the pmdemand entry in the files + /usr/share/examples/ppp/ppp.conf.sample + and + /usr/share/examples/ppp/ppp.linkup.sample + for a detailed example. + + + + Receiving Incoming Calls + PPPreceiving + incoming calls + When you configure ppp to + receive incoming calls on a machine connected to a LAN, you + must decide if you wish to forward packets to the LAN. If you + do, you should allocate the peer an IP number from your LAN's + subnet, and use the command enable proxy in + your /etc/ppp/ppp.conf file. You should + also confirm that the /etc/rc.conf file + contains the following: + + gateway_enable="YES" + + + + Which getty? + + Configuring FreeBSD for Dial-up + Services provides a good description on enabling + dial-up services using &man.getty.8;. + + An alternative to getty is mgetty, + a smarter version of getty designed + with dial-up lines in mind. + + The advantages of using mgetty is + that it actively talks to modems, + meaning if port is turned off in + /etc/ttys then your modem will not answer + the phone. + + Later versions of mgetty (from + 0.99beta onwards) also support the automatic detection of + PPP streams, allowing your clients script-less access to + your server. + + Refer to Mgetty and + AutoPPP for more information on + mgetty. + + + + <application>PPP</application> Permissions + + The ppp command must normally be + run as the root user. If however, + you wish to allow ppp to run in + server mode as a normal user by executing + ppp as described below, that user + must be given permission to run ppp + by adding them to the network group + in /etc/group. + + You will also need to give them access to one or more + sections of the configuration file using the + allow command: + + allow users fred mary + + If this command is used in the default + section, it gives the specified users access to + everything. + + + + PPP Shells for Dynamic-IP Users + PPP shells + + Create a file called + /etc/ppp/ppp-shell containing the + following: + + #!/bin/sh +IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'` +CALLEDAS="$IDENT" +TTY=`tty` + +if [ x$IDENT = xdialup ]; then + IDENT=`basename $TTY` +fi + +echo "PPP for $CALLEDAS on $TTY" +echo "Starting PPP for $IDENT" + +exec /usr/sbin/ppp -direct $IDENT + + This script should be executable. Now make a symbolic + link called ppp-dialup to this script + using the following commands: + + &prompt.root; ln -s ppp-shell /etc/ppp/ppp-dialup + + You should use this script as the + shell for all of your dialup users. + This is an example from /etc/passwd + for a dialup PPP user with username + pchilds (remember do not directly edit + the password file, use &man.vipw.8;). + + pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup + + Create a /home/ppp directory that + is world readable containing the following 0 byte + files: + + -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin +-r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts + + which prevents /etc/motd from being + displayed. + + + + PPP Shells for Static-IP Users + PPP shells + + Create the ppp-shell file as above, + and for each account with statically assigned IPs create a + symbolic link to ppp-shell. + + For example, if you have three dialup customers, + fred, sam, and + mary, that you route class C networks + for, you would type the following: + + &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred +&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam +&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary + + Each of these users dialup accounts should have their + shell set to the symbolic link created above (for example, + mary's shell should be + /etc/ppp/ppp-mary). + + + + Setting Up <filename>ppp.conf</filename> for Dynamic-IP Users + + The /etc/ppp/ppp.conf file should + contain something along the lines of: + + default: + set debug phase lcp chat + set timeout 0 + +ttyd0: + set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255 + enable proxy + +ttyd1: + set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255 + enable proxy + + + The indenting is important. + + + The default: section is loaded for + each session. For each dialup line enabled in + /etc/ttys create an entry similar to + the one for ttyd0: above. Each line + should get a unique IP address from your pool of IP + addresses for dynamic users. + + + + Setting Up <filename>ppp.conf</filename> for Static-IP + Users + + Along with the contents of the sample + /usr/share/examples/ppp/ppp.conf + above you should add a section for each of the + statically assigned dialup users. We will continue with + our fred, sam, + and mary example. + + fred: + set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255 + +sam: + set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255 + +mary: + set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255 + + The file /etc/ppp/ppp.linkup + should also contain routing information for each static + IP user if required. The line below would add a route + for the 203.14.101.0 + class C via the client's ppp link. + + fred: + add 203.14.101.0 netmask 255.255.255.0 HISADDR + +sam: + add 203.14.102.0 netmask 255.255.255.0 HISADDR + +mary: + add 203.14.103.0 netmask 255.255.255.0 HISADDR + + + + <command>mgetty</command> and AutoPPP + + mgetty + + AutoPPP + LCP + + Configuring and compiling mgetty + with the AUTO_PPP option enabled + allows mgetty to detect the LCP phase + of PPP connections and automatically spawn off a ppp + shell. However, since the default login/password + sequence does not occur it is necessary to authenticate + users using either PAP or CHAP. + + This section assumes the user has successfully + configured, compiled, and installed a version of + mgetty with the + AUTO_PPP option (v0.99beta or + later). + + Make sure your + /usr/local/etc/mgetty+sendfax/login.config + file has the following in it: + + /AutoPPP/ - - /etc/ppp/ppp-pap-dialup + + This will tell mgetty to run the + ppp-pap-dialup script for detected + PPP connections. + + Create a file called + /etc/ppp/ppp-pap-dialup containing the + following (the file should be executable): + + #!/bin/sh +exec /usr/sbin/ppp -direct pap$IDENT + + For each dialup line enabled in + /etc/ttys, create a corresponding entry + in /etc/ppp/ppp.conf. This will + happily co-exist with the definitions we created + above. + + pap: + enable pap + set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 + enable proxy + + Each user logging in with this method will need to have + a username/password in + /etc/ppp/ppp.secret file, or + alternatively add the following option to authenticate users + via PAP from the /etc/passwd file. + + enable passwdauth + + If you wish to assign some users a static IP number, + you can specify the number as the third argument in + /etc/ppp/ppp.secret. See + /usr/share/examples/ppp/ppp.secret.sample + for examples. + + + + MS Extensions + DNS + NetBIOS + PPPMicrosoft extensions + It is possible to configure PPP to supply DNS and + NetBIOS nameserver addresses on demand. + + To enable these extensions with PPP version 1.x, the + following lines might be added to the relevant section of + /etc/ppp/ppp.conf. + + enable msext +set ns 203.14.100.1 203.14.100.2 +set nbns 203.14.100.5 + + And for PPP version 2 and above: + + accept dns +set dns 203.14.100.1 203.14.100.2 +set nbns 203.14.100.5 + + This will tell the clients the primary and secondary + name server addresses, and a NetBIOS nameserver host. + + In version 2 and above, if the + set dns line is omitted, PPP will use the + values found in /etc/resolv.conf. + + + + PAP and CHAP Authentication + PAP + CHAP + Some ISPs set their system up so that the authentication + part of your connection is done using either of the PAP or + CHAP authentication mechanisms. If this is the case, your ISP + will not give a login: prompt when you + connect, but will start talking PPP immediately. + + PAP is less secure than CHAP, but security is not normally + an issue here as passwords, although being sent as plain text + with PAP, are being transmitted down a serial line only. + There is not much room for crackers to + eavesdrop. + + Referring back to the PPP + and Static IP addresses or PPP and Dynamic IP addresses + sections, the following alterations must be made: + + 13 set authname MyUserName +14 set authkey MyPassword +15 set login + + + + Line 13: + + + This line specifies your PAP/CHAP user name. You + will need to insert the correct value for + MyUserName. + + + + + Line 14: + password + + This line specifies your PAP/CHAP password. You + will need to insert the correct value for + MyPassword. You may want to + add an additional line, such as: + + 16 accept PAP + + or + + 16 accept CHAP + + to make it obvious that this is the intention, but + PAP and CHAP are both accepted by default. + + + + + Line 15: + + + Your ISP will not normally require that you log into + the server if you are using PAP or CHAP. You must + therefore disable your set login + string. + + + + + + + Changing Your <command>ppp</command> Configuration on the + Fly + + It is possible to talk to the ppp + program while it is running in the background, but only if a + suitable diagnostic port has been set up. To do this, add the + following line to your configuration: + + set server /var/run/ppp-tun%d DiagnosticPassword 0177 + + This will tell PPP to listen to the specified + &unix; domain socket, asking clients for the specified + password before allowing access. The + %d in the name is replaced with the + tun device number that is in + use. + + Once a socket has been set up, the &man.pppctl.8; + program may be used in scripts that wish to manipulate the + running program. + + + + + Using PPP Network Address Translation Capability + PPPNAT + + PPP has ability to use internal NAT without kernel diverting + capabilities. This functionality may be enabled by the following + line in /etc/ppp/ppp.conf: + + nat enable yes + + Alternatively, PPP NAT may be enabled by command-line + option -nat. There is also + /etc/rc.conf knob named + ppp_nat, which is enabled by default. + + If you use this feature, you may also find useful + the following /etc/ppp/ppp.conf options + to enable incoming connections forwarding: + + nat port tcp 10.0.0.2:ftp ftp +nat port tcp 10.0.0.2:http http + + or do not trust the outside at all + + nat deny_incoming yes + + + + Final System Configuration + PPPconfiguration + + You now have ppp configured, but there + are a few more things to do before it is ready to work. They + all involve editing the /etc/rc.conf + file. + + Working from the top down in this file, make sure the + hostname= line is set, e.g.: + + hostname="foo.example.com" + + If your ISP has supplied you with a static IP address and + name, it is probably best that you use this name as your host + name. + + Look for the network_interfaces variable. + If you want to configure your system to dial your ISP on demand, + make sure the tun0 device is added to + the list, otherwise remove it. + + network_interfaces="lo0 tun0" +ifconfig_tun0= + + + The ifconfig_tun0 variable should be + empty, and a file called + /etc/start_if.tun0 should be created. + This file should contain the line: + + ppp -auto mysystem + + This script is executed at network configuration time, + starting your ppp daemon in automatic mode. If you have a LAN + for which this machine is a gateway, you may also wish to use + the switch. Refer to the manual page + for further details. + + + Make sure that the router program is set to NO with + the following line in your + /etc/rc.conf: + + router_enable="NO" + + + routed + + It is important that the routed daemon is + not started, as + routed tends to delete the default routing + table entries created by ppp. + + It is probably worth your while ensuring that the + sendmail_flags line does not include the + option, otherwise + sendmail will attempt to do a network lookup + every now and then, possibly causing your machine to dial out. + You may try: + + sendmail_flags="-bd" + + + sendmail + + The downside of this is that you must force + sendmail to re-examine the mail queue + whenever the ppp link is up by typing: + + &prompt.root; /usr/sbin/sendmail -q + + You may wish to use the !bg command in + ppp.linkup to do this automatically: + + 1 provider: +2 delete ALL +3 add 0 0 HISADDR +4 !bg sendmail -bd -q30m + + SMTP + If you do not like this, it is possible to set up a + dfilter to block SMTP traffic. Refer to the + sample files for further details. + + All that is left is to reboot the machine. After rebooting, + you can now either type: + + &prompt.root; ppp + + and then dial provider to start the PPP + session, or, if you want ppp to establish + sessions automatically when there is outbound traffic (and + you have not created the start_if.tun0 + script), type: + + &prompt.root; ppp -auto provider + + + + Summary + + To recap, the following steps are necessary when setting up + ppp for the first time: + + Client side: + + + + Ensure that the tun device is + built into your kernel. + + + + Ensure that the + tunN device + file is available in the /dev + directory. + + + + Create an entry in + /etc/ppp/ppp.conf. The + pmdemand example should suffice for + most ISPs. + + + + If you have a dynamic IP address, create an entry in + /etc/ppp/ppp.linkup. + + + + Update your /etc/rc.conf + file. + + + + Create a start_if.tun0 script if + you require demand dialing. + + + + Server side: + + + + Ensure that the tun device is + built into your kernel. + + + + Ensure that the + tunN device + file is available in the /dev + directory. + + + + Create an entry in /etc/passwd + (using the &man.vipw.8; program). + + + + Create a profile in this users home directory that runs + ppp -direct direct-server or + similar. + + + + Create an entry in + /etc/ppp/ppp.conf. The + direct-server example should + suffice. + + + + Create an entry in + /etc/ppp/ppp.linkup. + + + + Update your /etc/rc.conf + file. + + + + + + + + + + + Gennady B. + Sorokopud + Parts originally contributed by + + + Robert + Huff + + + + + Using Kernel PPP + + + Setting Up Kernel PPP + PPPkernel PPP + + Before you start setting up PPP on your machine, make sure + that pppd is located in + /usr/sbin and the directory + /etc/ppp exists. + + pppd can work in two modes: + + + + As a client — you want to connect your + machine to the outside world via a PPP serial connection or + modem line. + + + PPPserver + + As a server — your machine is located on + the network, and is used to connect other computers using + PPP. + + + + In both cases you will need to set up an options file + (/etc/ppp/options or + ~/.ppprc if you have more than one user on + your machine that uses PPP). + + You will also need some modem/serial software (preferably + comms/kermit), so you can dial and + establish a connection with the remote host. + + + + + + + Trev + Roydhouse + Based on information provided by + + + + + + Using <command>pppd</command> as a Client + PPPclient + Cisco + The following /etc/ppp/options might be + used to connect to a Cisco terminal server PPP line. + + crtscts # enable hardware flow control +modem # modem control line +noipdefault # remote PPP server must supply your IP address + # if the remote host does not send your IP during IPCP + # negotiation, remove this option +passive # wait for LCP packets +domain ppp.foo.com # put your domain name here + +:<remote_ip> # put the IP of remote PPP host here + # it will be used to route packets via PPP link + # if you didn't specified the noipdefault option + # change this line to <local_ip>:<remote_ip> + +defaultroute # put this if you want that PPP server will be your + # default router + + To connect: + + Kermit + modem + + + Dial to the remote host using Kermit (or some other modem + program), and enter your user name and password (or whatever + is needed to enable PPP on the remote host). + + + + Exit Kermit (without + hanging up the line). + + + + Enter the following: + + &prompt.root; /usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200 + + Be sure to use the appropriate speed and device name. + + + + Now your computer is connected with PPP. If the connection + fails, you can add the option to the + /etc/ppp/options file, and check console messages + to track the problem. + + Following /etc/ppp/pppup script will make + all 3 stages automatic: + + #!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.dial +pppd /dev/tty01 19200 + + Kermit + /etc/ppp/kermit.dial is a Kermit + script that dials and makes all necessary authorization on the + remote host (an example of such a script is attached to the end + of this document). + + Use the following /etc/ppp/pppdown script + to disconnect the PPP line: + + #!/bin/sh +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ X${pid} != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill -TERM ${pid} +fi + +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +/sbin/ifconfig ppp0 down +/sbin/ifconfig ppp0 delete +kermit -y /etc/ppp/kermit.hup +/etc/ppp/ppptest + + Check to see if pppd is still running by executing + /usr/etc/ppp/ppptest, which should look like + this: + + #!/bin/sh +pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` +if [ X${pid} != "X" ] ; then + echo 'pppd running: PID=' ${pid-NONE} +else + echo 'No pppd running.' +fi +set -x +netstat -n -I ppp0 +ifconfig ppp0 + + To hang up the modem, execute + /etc/ppp/kermit.hup, which should + contain: + + set line /dev/tty01 ; put your modem device here +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +echo \13 +exit + + Here is an alternate method using chat + instead of kermit: + + The following two files are sufficient to accomplish a + pppd connection. + + /etc/ppp/options: + + /dev/cuaa1 115200 + +crtscts # enable hardware flow control +modem # modem control line +connect "/usr/bin/chat -f /etc/ppp/login.chat.script" +noipdefault # remote PPP serve must supply your IP address + # if the remote host doesn't send your IP during + # IPCP negotiation, remove this option +passive # wait for LCP packets +domain <your.domain> # put your domain name here + +: # put the IP of remote PPP host here + # it will be used to route packets via PPP link + # if you didn't specified the noipdefault option + # change this line to <local_ip>:<remote_ip> + +defaultroute # put this if you want that PPP server will be + # your default router + + /etc/ppp/login.chat.script: + + + The following should go on a single line. + + + ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number> + CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id> + TIMEOUT 5 sword: <password> + + Once these are installed and modified correctly, all you need + to do is run pppd, like so: + + &prompt.root; pppd + + + + Using <command>pppd</command> as a Server + + /etc/ppp/options should contain something + similar to the following: + + crtscts # Hardware flow control +netmask 255.255.255.0 # netmask (not required) +192.114.208.20:192.114.208.165 # IP's of local and remote hosts + # local ip must be different from one + # you assigned to the Ethernet (or other) + # interface on your machine. + # remote IP is IP address that will be + # assigned to the remote machine +domain ppp.foo.com # your domain +passive # wait for LCP +modem # modem line + + The following /etc/ppp/pppserv script + will tell pppd to behave as a + server: + + #!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +# reset ppp interface +ifconfig ppp0 down +ifconfig ppp0 delete + +# enable autoanswer mode +kermit -y /etc/ppp/kermit.ans + +# run ppp +pppd /dev/tty01 19200 + + Use this /etc/ppp/pppservdown script to + stop the server: + + #!/bin/sh +ps ax |grep pppd |grep -v grep +pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +ps ax |grep kermit |grep -v grep +pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.noans + + The following Kermit script + (/etc/ppp/kermit.ans) will enable/disable + autoanswer mode on your modem. It should look like this: + + set line /dev/tty01 +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +inp 5 OK +echo \13 +out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable + ; autoanswer mode +inp 5 OK +echo \13 +exit + + A script named /etc/ppp/kermit.dial is + used for dialing and authenticating on the remote host. You will + need to customize it for your needs. Put your login and password + in this script; you will also need to change the input statement + depending on responses from your modem and remote host. + + ; +; put the com line attached to the modem here: +; +set line /dev/tty01 +; +; put the modem speed here: +; +set speed 19200 +set file type binary ; full 8 bit file xfer +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none +set modem hayes +set dial hangup off +set carrier auto ; Then SET CARRIER if necessary, +set dial display on ; Then SET DIAL if necessary, +set input echo on +set input timeout proceed +set input case ignore +def \%x 0 ; login prompt counter +goto slhup + +:slcmd ; put the modem in command mode +echo Put the modem in command mode. +clear ; Clear unread characters from input buffer +pause 1 +output +++ ; hayes escape sequence +input 1 OK\13\10 ; wait for OK +if success goto slhup +output \13 +pause 1 +output at\13 +input 1 OK\13\10 +if fail goto slcmd ; if modem doesn't answer OK, try again + +:slhup ; hang up the phone +clear ; Clear unread characters from input buffer +pause 1 +echo Hanging up the phone. +output ath0\13 ; hayes command for on hook +input 2 OK\13\10 +if fail goto slcmd ; if no OK answer, put modem in command mode + +:sldial ; dial the number +pause 1 +echo Dialing. +output atdt9,550311\13\10 ; put phone number here +assign \%x 0 ; zero the time counter + +:look +clear ; Clear unread characters from input buffer +increment \%x ; Count the seconds +input 1 {CONNECT } +if success goto sllogin +reinput 1 {NO CARRIER\13\10} +if success goto sldial +reinput 1 {NO DIALTONE\13\10} +if success goto slnodial +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 60 goto look +else goto slhup + +:sllogin ; login +assign \%x 0 ; zero the time counter +pause 1 +echo Looking for login prompt. + +:slloop +increment \%x ; Count the seconds +clear ; Clear unread characters from input buffer +output \13 +; +; put your expected login prompt here: +; +input 1 {Username: } +if success goto sluid +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 10 goto slloop ; try 10 times to get a login prompt +else goto slhup ; hang up and start again if 10 failures + +:sluid +; +; put your userid here: +; +output ppp-login\13 +input 1 {Password: } +; +; put your password here: +; +output ppp-password\13 +input 1 {Entering SLIP mode.} +echo +quit + +:slnodial +echo \7No dialtone. Check the telephone line!\7 +exit 1 + +; local variables: +; mode: csh +; comment-start: "; " +; comment-start-skip: "; " +; end: + + + + + + + + Tom + Rhodes + Contributed by + + + + + Troubleshooting <acronym>PPP</acronym> Connections + + PPPtroubleshooting + + This section covers a few issues which may arise when + using PPP over a modem connection. For instance, perhaps you + need to know exactly what prompts the system you are dialing + into will present. Some ISPs present the + ssword prompt, and others will present + password; if the ppp + script is not written accordingly, the login attempt will + fail. The most common way to debug ppp + connections is by connecting manually. The following + information will walk you through a manual connection step by + step. + + + Check the Device Nodes + + If you reconfigured your kernel then you recall the + sio device. If you did not + configure your kernel, there is no reason to worry. Just + check the dmesg output for the modem + device with: + + &prompt.root; dmesg | grep sio + + You should get some pertinent output about the + sio devices. These are the COM + ports we need. If your modem acts like a standard serial + port then you should see it listed on + sio1, or COM2. If so, you are not + required to rebuild the kernel. + When matching up sio modem is on sio1 or + COM2 if you are in DOS, then your + modem device would be /dev/cuaa1. + + + + Connecting Manually + + Connecting to the Internet by manually controlling + ppp is quick, easy, and a great way to + debug a connection or just get information on how your + ISP treats ppp client + connections. Lets start PPP from + the command line. Note that in all of our examples we will + use example as the hostname of the + machine running PPP. You start + ppp by just typing + ppp: + + &prompt.root; ppp + + We have now started ppp. + + ppp ON example> set device /dev/cuaa1 + + We set our modem device, in this case it is + cuaa1. + + ppp ON example> set speed 115200 + + Set the connection speed, in this case we + are using 115,200 kbps. + + ppp ON example> enable dns + + Tell ppp to configure our + resolver and add the nameserver lines to + /etc/resolv.conf. If ppp + cannot determine our hostname, we can set one manually later. + + ppp ON example> term + + Switch to terminal mode so that we can manually + control the modem. + + deflink: Entering terminal mode on /dev/cuaa1 +type '~h' for help + + at +OK +atdt123456789 + + Use at to initialize the modem, + then use atdt and the number for your + ISP to begin the dial in process. + + CONNECT + + Confirmation of the connection, if we are going to have + any connection problems, unrelated to hardware, here is where + we will attempt to resolve them. + + ISP Login:myusername + + Here you are prompted for a username, return the + prompt with the username that was provided by the + ISP. + + ISP Pass:mypassword + + This time we are prompted for a password, just + reply with the password that was provided by the + ISP. Just like logging into + &os;, the password will not echo. + + Shell or PPP:ppp + + Depending on your ISP this prompt + may never appear. Here we are being asked if we wish to + use a shell on the provider, or to start + ppp. In this example, we have chosen + to use ppp as we want an Internet + connection. + + Ppp ON example> + + Notice that in this example the first + has been capitalized. This shows that we have successfully + connected to the ISP. + + PPp ON example> + + We have successfully authenticated with our + ISP and are waiting for the + assigned IP address. + + PPP ON example> + + We have made an agreement on an IP + address and successfully completed our connection. + + PPP ON example>add default HISADDR + + Here we add our default route, we need to do this before + we can talk to the outside world as currently the only + established connection is with the peer. If this fails due to + existing routes you can put a bang character + ! in front of the . + Alternatively, you can set this before making the actual + connection and it will negotiate a new route + accordingly. + + If everything went good we should now have an active + connection to the Internet, which could be thrown into the + background using CTRL + z If you notice the + PPP return to ppp then + we have lost our connection. This is good to know because it + shows our connection status. Capital P's show that we have a + connection to the ISP and lowercase p's + show that the connection has been lost for whatever reason. + ppp only has these 2 states. + + + Debugging + + If you have a direct line and cannot seem to make a + connection, then turn hardware flow + CTS/RTS to off with the . This is mainly the case if you are + connected to some PPP capable + terminal servers, where PPP hangs + when it tries to write data to your communication link, so + it would be waiting for a CTS, or Clear + To Send signal which may never come. If you use this option + however, you should also use the + option, which may be required to defeat hardware dependent + on passing certain characters from end to end, most of the + time XON/XOFF. See the &man.ppp.8; manual page for more + information on this option, and how it is used. + + If you have an older modem, you may need to use the + . Parity is set at none + be default, but is used for error checking (with a large + increase in traffic) on older modems and some + ISPs. You may need this option for + the Compuserve ISP. + + PPP may not return to the + command mode, which is usually a negotiation error where + the ISP is waiting for your side to start + negotiating. At this point, using the ~p + command will force ppp to start sending the configuration + information. + + If you never obtain a login prompt, then most likely you + need to use PAP or + CHAP authentication instead of the + &unix; style in the example above. To use + PAP or CHAP just add + the following options to PPP + before going into terminal mode: + + ppp ON example> set authname myusername + + Where myusername should be + replaced with the username that was assigned by the + ISP. + + ppp ON example> set authkey mypassword + + Where mypassword should be + replaced with the password that was assigned by the + ISP. + + If you connect fine, but cannot seem to find any domain + name, try to use &man.ping.8; with an IP + address and see if you can get any return information. If + you experience 100 percent (100%) packet loss, then it is most + likely that you were not assigned a default route. Double + check that the option + was set during the connection. If you can connect to a + remote IP address then it is possible + that a resolver address has not been added to the + /etc/resolv.conf. This file should + look like: + + domain example.com +nameserver x.x.x.x +nameserver y.y.y.y + + Where x.x.x.x and + y.y.y.y should be replaced with + the IP address of your + ISP's DNS servers. This information may + or may not have been provided when you signed up, but a + quick call to your ISP should remedy + that. + + You could also have &man.syslog.3; provide a logging + function for your PPP connection. + Just add: + + !ppp +*.* /var/log/ppp.log + + to /etc/syslog.conf. In most cases, this + functionality already exists. + + + + + + + + + + + + + Jim + Mock + Contributed (from http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by + + + + + + Using PPP over Ethernet (PPPoE) + PPPover Ethernet + + PPPoE + PPP, over Ethernet + + + This section describes how to set up PPP over Ethernet + (PPPoE). + + + Configuring the Kernel + + No kernel configuration is necessary for PPPoE any longer. If + the necessary netgraph support is not built into the kernel, it will + be dynamically loaded by ppp. + + + + Setting Up <filename>ppp.conf</filename> + + Here is an example of a working + ppp.conf: + + default: + set log Phase tun command # you can add more detailed logging if you wish + set ifaddr 10.0.0.1/0 10.0.0.2/0 + +name_of_service_provider: + set device PPPoE:xl1 # replace xl1 with your Ethernet device + set authname YOURLOGINNAME + set authkey YOURPASSWORD + set dial + set login + add default HISADDR + + + + + Running <application>ppp</application> + + As root, you can run: + + &prompt.root; ppp -ddial name_of_service_provider + + + + + Starting <application>ppp</application> at Boot + + Add the following to your /etc/rc.conf + file: + + ppp_enable="YES" +ppp_mode="ddial" +ppp_nat="YES" # if you want to enable nat for your local network, otherwise NO +ppp_profile="name_of_service_provider" + + + + Using a PPPoE Service Tag + + Sometimes it will be necessary to use a service tag to establish + your connection. Service tags are used to distinguish between + different PPPoE servers attached to a given network. + + You should have been given any required service tag information + in the documentation provided by your ISP. If you cannot locate + it there, ask your ISP's tech support personnel. + + As a last resort, you could try the method suggested by the + Roaring Penguin + PPPoE program which can be found in the Ports Collection. Bear in mind however, + this may de-program your modem and render it useless, so + think twice before doing it. Simply install the program shipped + with the modem by your provider. Then, access the + System menu from the program. The name of your + profile should be listed there. It is usually + ISP. + + The profile name (service tag) will be used in the PPPoE + configuration entry in ppp.conf as the provider + part of the set device command (see the &man.ppp.8; + manual page for full details). It should look like this: + + set device PPPoE:xl1:ISP + + Do not forget to change xl1 + to the proper device for your Ethernet card. + Do not forget to change ISP + to the profile you have just found above. + + For additional information, see: + + + + Cheaper + Broadband with FreeBSD on DSL by Renaud + Waldura. + + + + + Nutzung von T-DSL und T-Online mit FreeBSD + by Udo Erdelhoff (in German). + + + + + + + PPPoE with a &tm.3com; <trademark class="registered">HomeConnect</trademark> ADSL Modem Dual Link + + This modem does not follow RFC 2516 + (A Method for transmitting PPP over Ethernet + (PPPoE), written by L. Mamakos, K. Lidl, J. Evarts, + D. Carrel, D. Simone, and R. Wheeler). Instead, different packet + type codes have been used for the Ethernet frames. Please complain + to 3Com if you think it + should comply with the PPPoE specification. + + In order to make FreeBSD capable of communicating with this + device, a sysctl must be set. This can be done automatically at + boot time by updating /etc/sysctl.conf: + + net.graph.nonstandard_pppoe=1 + + or can be done immediately with the command: + + &prompt.root; sysctl net.graph.nonstandard_pppoe=1 + + Unfortunately, because this is a system-wide setting, it is + not possible to talk to a normal PPPoE client or server and a + &tm.3com; HomeConnect ADSL Modem at the same time. + + + + + + Using <application>PPP</application> over ATM (PPPoA) + PPPover ATM + + PPPoA + PPP, over ATM + + + The following describes how to set up PPP over ATM (PPPoA). + PPPoA is a popular choice among European DSL providers. + + + Using PPPoA with the Alcatel &speedtouch; USB + + PPPoA support for this device is supplied as a port in + FreeBSD because the firmware is distributed under Alcatel's + license agreement and can not be redistributed freely + with the base system of FreeBSD. + + To install the software, simply use the Ports Collection. Install the + net/pppoa port and follow the + instructions provided with it. + + Like many USB devices, the Alcatel &speedtouch; USB needs to + download firmware from the host computer to operate properly. + It is possible to automate this process in &os; so that this + transfer takes place whenever the device is plugged into a USB + port. The following information can be added to the + /etc/usbd.conf file to enable this + automatic firmware transfer. This file must be edited as the + root user. + + device "Alcatel SpeedTouch USB" + devname "ugen[0-9]+" + vendor 0x06b9 + product 0x4061 + attach "/usr/local/sbin/modem_run -f /usr/local/libdata/mgmt.o" + + To enable the USB daemon, usbd, + put the following the line into + /etc/rc.conf: + + usbd_enable="YES" + + It is also possible to set up + ppp to dial up at startup. To do + this add the following lines to + /etc/rc.conf. Again, for this procedure + you will need to be logged in as the root + user. + + ppp_enable="YES" +ppp_mode="ddial" +ppp_profile="adsl" + + For this to work correctly you will need to have used the + sample ppp.conf which is supplied with the + net/pppoa port. + + + + + Using mpd + + You can use mpd to connect to a + variety of services, in particular PPTP services. You can find + mpd in the Ports Collection, + net/mpd. Many ADSL modems + require that a PPTP tunnel is created between the modem and + computer, one such modem is the Alcatel &speedtouch; + Home. + + First you must install the port, and then you can + configure mpd to suit your + requirements and provider settings. The port places a set of + sample configuration files which are well documented in + PREFIX/etc/mpd/. + Note here that PREFIX means the directory + into which your ports are installed, this defaults to + /usr/local/. A complete guide to + configure mpd is available in + HTML format once the port has been installed. It is placed in + PREFIX/share/doc/mpd/. + Here is a sample configuration for connecting to an ADSL + service with mpd. The configuration + is spread over two files, first the + mpd.conf: + + default: + load adsl + +adsl: + new -i ng0 adsl adsl + set bundle authname username + set bundle password password + set bundle disable multilink + + set link no pap acfcomp protocomp + set link disable chap + set link accept chap + set link keep-alive 30 10 + + set ipcp no vjcomp + set ipcp ranges 0.0.0.0/0 0.0.0.0/0 + + set iface route default + set iface disable on-demand + set iface enable proxy-arp + set iface idle 0 + + open + + + + The username used to authenticate with your ISP. + + + The password used to authenticate with your ISP. + + + + The mpd.links file contains information about + the link, or links, you wish to establish. An example + mpd.links to accompany the above example is given + beneath: + + adsl: + set link type pptp + set pptp mode active + set pptp enable originate outcall + set pptp self 10.0.0.1 + set pptp peer 10.0.0.138 + + + + The IP address of your &os; computer which you will be + using mpd from. + + + The IP address of your ADSL modem. For the Alcatel + &speedtouch; Home this address defaults to 10.0.0.138. + + + + It is possible to initialize the connection easily by issuing the + following command as root: + + &prompt.root; mpd -b adsl + + You can see the status of the connection with the following + command: + + &prompt.user; ifconfig ng0 +ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 + inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff + + Using mpd is the recommended way to + connect to an ADSL service with &os;. + + + + + Using pptpclient + + It is also possible to use FreeBSD to connect to other PPPoA + services using + net/pptpclient. + + To use net/pptpclient to + connect to a DSL service, install the port or package and edit your + /etc/ppp/ppp.conf. You will need to be + root to perform both of these operations. An + example section of ppp.conf is given + below. For further information on ppp.conf + options consult the ppp manual page, + &man.ppp.8;. + + adsl: + set log phase chat lcp ipcp ccp tun command + set timeout 0 + enable dns + set authname username + set authkey password + set ifaddr 0 0 + add default HISADDR + + + + The username of your account with the DSL provider. + + + The password for your account. + + + + + Because you must put your account's password in the + ppp.conf file in plain text form you should + make sure than nobody can read the contents of this file. The + following series of commands will make sure the file is only + readable by the root account. Refer to the + manual pages for &man.chmod.1; and &man.chown.8; for further + information. + &prompt.root; chown root:wheel /etc/ppp/ppp.conf +&prompt.root; chmod 600 /etc/ppp/ppp.conf + + + This will open a tunnel for a PPP session to your DSL router. + Ethernet DSL modems have a preconfigured LAN IP address which you + connect to. In the case of the Alcatel &speedtouch; Home this address is + 10.0.0.138. Your router documentation + should tell you which address your device uses. To open the tunnel and + start a PPP session execute the following + command: + + &prompt.root; pptp address adsl + + + You may wish to add an ampersand (&) to the + end of the previous command because pptp + will not return your prompt to you otherwise. + + + A tun virtual tunnel device will be + created for interaction between the pptp + and ppp processes. Once you have been + returned to your prompt, or the pptp + process has confirmed a connection you can examine the tunnel like + so: + + &prompt.user; ifconfig tun0 +tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 + inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 + Opened by PID 918 + + If you are unable to connect, check the configuration of + your router, which is usually accessible via + telnet or with a web browser. If you still + cannot connect you should examine the output of the + pptp command and the contents of the + ppp log file, + /var/log/ppp.log for clues. + + + + + + + + Satoshi + Asami + Originally contributed by + + + + + Guy + Helmer + With input from + + + Piero + Serini + + + + + Using SLIP + SLIP + + + Setting Up a SLIP Client + SLIPclient + The following is one way to set up a FreeBSD machine for SLIP + on a static host network. For dynamic hostname assignments (your + address changes each time you dial up), you probably need to + have a more complex setup. + + First, determine which serial port your modem is connected to. + Many people set up a symbolic link, such as + /dev/modem, to point to the real device name, + /dev/cuaaN (or /dev/cuadN under &os; 6.X). This allows you to + abstract the actual device name should you ever need to move + the modem to a different port. It can become quite cumbersome when you + need to fix a bunch of files in /etc and + .kermrc files all over the system! + + + /dev/cuaa0 (or /dev/cuad0 under &os; 6.X) is + COM1, cuaa1 (or /dev/cuad1) is + COM2, etc. + + + Make sure you have the following in your kernel configuration + file: + + device sl + + It is included in the GENERIC kernel, so + this should not be a problem unless you have deleted it. + + + Things You Have to Do Only Once + + + + Add your home machine, the gateway and nameservers to + your /etc/hosts file. Ours looks like + this: + + 127.0.0.1 localhost loghost +136.152.64.181 water.CS.Example.EDU water.CS water +136.152.64.1 inr-3.CS.Example.EDU inr-3 slip-gateway +128.32.136.9 ns1.Example.EDU ns1 +128.32.136.12 ns2.Example.EDU ns2 + + + + Make sure you have hosts before + bind in your + /etc/host.conf on FreeBSD versions + prior to 5.0. Since FreeBSD 5.0, the system uses + the file /etc/nsswitch.conf instead, + make sure you have files before + dns in the line + of this file. Without these parameters funny + things may happen. + + + + Edit the /etc/rc.conf file. + + + + Set your hostname by editing the line that + says: + + hostname="myname.my.domain" + + Your machine's full Internet hostname should be + placed here. + + + default route + + Designate the default router by changing the + line: + + defaultrouter="NO" + + to: + + defaultrouter="slip-gateway" + + + + + + Make a file /etc/resolv.conf which + contains: + + domain CS.Example.EDU +nameserver 128.32.136.9 +nameserver 128.32.136.12 + + nameserver + domain name + As you can see, these set up the nameserver hosts. Of + course, the actual domain names and addresses depend on your + environment. + + + + Set the password for root and + toor (and any other + accounts that do not have a password). + + + + Reboot your machine and make sure it comes up with the + correct hostname. + + + + + + Making a SLIP Connection + SLIPconnecting with + + + Dial up, type slip at the prompt, + enter your machine name and password. What is required to + be entered depends on your environment. If you use + Kermit, you can try a script like this: + + # kermit setup +set modem hayes +set line /dev/modem +set speed 115200 +set parity none +set flow rts/cts +set terminal bytesize 8 +set file type binary +# The next macro will dial up and login +define slip dial 643-9600, input 10 =>, if failure stop, - +output slip\x0d, input 10 Username:, if failure stop, - +output silvia\x0d, input 10 Password:, if failure stop, - +output ***\x0d, echo \x0aCONNECTED\x0a + + Of course, you have to change the username and password + to fit yours. After doing so, you can just type + slip from the Kermit prompt to + connect. + + + Leaving your password in plain text anywhere in the + filesystem is generally a bad idea. + Do it at your own risk. + + + + + Leave the Kermit there (you can suspend it by + + Ctrl + z + ) and as root, type: + + &prompt.root; slattach -h -c -s 115200 /dev/modem + + If you are able to ping hosts on the + other side of the router, you are connected! If it does not + work, you might want to try instead of + as an argument to + slattach. + + + + + + How to Shutdown the Connection + + Do the following: + + &prompt.root; kill -INT `cat /var/run/slattach.modem.pid` + + to kill slattach. Keep in mind you must be + root to do the above. Then go back to + kermit (by running fg if you suspended it) and + exit from + it (q). + + The &man.slattach.8; manual page says you have + to use ifconfig sl0 down + to mark the interface down, but this does not + seem to make any difference. + (ifconfig sl0 reports the same thing.) + + Some times, your modem might refuse to drop the carrier. + In that case, simply start kermit and quit + it again. It usually goes out on the second try. + + + + Troubleshooting + + If it does not work, feel free to ask on &a.net.name; mailing list. The things that + people tripped over so far: + + + + Not using or in + slattach (This should not be fatal, + but some users have reported that this solves their + problems.) + + + + Using instead of + (might be hard to see the difference on + some fonts). + + + + Try ifconfig sl0 to see your + interface status. For example, you might get: + + &prompt.root; ifconfig sl0 +sl0: flags=10<POINTOPOINT> + inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00 + + + + If you get no route to host + messages from &man.ping.8;, there may be a problem with your + routing table. You can use the netstat -r + command to display the current routes : + + &prompt.root; netstat -r +Routing tables +Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks: + +(root node) +(root node) + +Route Tree for Protocol Family inet: +(root node) => +default inr-3.Example.EDU UG 8 224515 sl0 - - +localhost.Exampl localhost.Example. UH 5 42127 lo0 - 0.438 +inr-3.Example.ED water.CS.Example.E UH 1 0 sl0 - - +water.CS.Example localhost.Example. UGH 34 47641234 lo0 - 0.438 +(root node) + + The preceding examples are from a relatively busy system. + The numbers on your system will vary depending on + network activity. + + + + + + + + Setting Up a SLIP Server + SLIPserver + + This document provides suggestions for setting up SLIP Server + services on a FreeBSD system, which typically means configuring + your system to automatically start up connections upon login for + remote SLIP clients. + + + + + Prerequisites + TCP/IP networking + This section is very technical in nature, so background + knowledge is required. It is assumed that you are familiar with + the TCP/IP network protocol, and in particular, network and node + addressing, network address masks, subnetting, routing, and + routing protocols, such as RIP. Configuring SLIP services on a + dial-up server requires a knowledge of these concepts, and if + you are not familiar with them, please read a copy of either + Craig Hunt's TCP/IP Network Administration + published by O'Reilly & Associates, Inc. (ISBN Number + 0-937175-82-X), or Douglas Comer's books on the TCP/IP + protocol. + + modem + It is further assumed that you have already set up your + modem(s) and configured the appropriate system files to allow + logins through your modems. If you have not prepared your + system for this yet, please see for details on dialup services + configuration. + You may also want to check the manual pages for &man.sio.4; for + information on the serial port device driver and &man.ttys.5;, + &man.gettytab.5;, &man.getty.8;, & &man.init.8; for + information relevant to configuring the system to accept logins + on modems, and perhaps &man.stty.1; for information on setting + serial port parameters (such as clocal for + directly-connected serial interfaces). + + + + Quick Overview + + In its typical configuration, using FreeBSD as a SLIP server + works as follows: a SLIP user dials up your FreeBSD SLIP Server + system and logs in with a special SLIP login ID that uses + /usr/sbin/sliplogin as the special user's + shell. The sliplogin program browses the + file /etc/sliphome/slip.hosts to find a + matching line for the special user, and if it finds a match, + connects the serial line to an available SLIP interface and then + runs the shell script + /etc/sliphome/slip.login to configure the + SLIP interface. + + + An Example of a SLIP Server Login + + For example, if a SLIP user ID were + Shelmerg, Shelmerg's + entry in /etc/master.passwd would look + something like this: + + Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin + + When Shelmerg logs in, + sliplogin will search + /etc/sliphome/slip.hosts for a line that + had a matching user ID; for example, there may be a line in + /etc/sliphome/slip.hosts that + reads: + + Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp + + sliplogin will find that matching line, + hook the serial line into the next available SLIP interface, + and then execute /etc/sliphome/slip.login + like this: + + /etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp + + If all goes well, + /etc/sliphome/slip.login will issue an + ifconfig for the SLIP interface to which + sliplogin attached itself (SLIP interface + 0, in the above example, which was the first parameter in the + list given to slip.login) to set the + local IP address (dc-slip), remote IP address + (sl-helmer), network mask for the SLIP + interface (0xfffffc00), and + any additional flags (autocomp). If + something goes wrong, sliplogin usually + logs good informational messages via the + syslogd daemon facility, which usually logs + to /var/log/messages (see the manual + pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps + check /etc/syslog.conf to see to what + syslogd is logging and where it is + logging to). + + + + + Kernel Configuration + kernelconfiguration + SLIP + + &os;'s default kernel (GENERIC) + comes with SLIP (&man.sl.4;) support; in case of a custom + kernel, you have to add the following line to your kernel + configuration file: + + device sl + + By default, your &os; machine will not forward packets. + If you want your FreeBSD SLIP Server to act as a router, you + will have to edit the /etc/rc.conf file and + change the setting of the gateway_enable variable to + . + + You will then need to reboot for the new settings to take + effect. + + Please refer to on + Configuring the FreeBSD Kernel for help in + reconfiguring your kernel. + + + + Sliplogin Configuration + + As mentioned earlier, there are three files in the + /etc/sliphome directory that are part of + the configuration for /usr/sbin/sliplogin + (see &man.sliplogin.8; for the actual manual page for + sliplogin): slip.hosts, + which defines the SLIP users and their associated IP + addresses; slip.login, which usually just + configures the SLIP interface; and (optionally) + slip.logout, which undoes + slip.login's effects when the serial + connection is terminated. + + + <filename>slip.hosts</filename> Configuration + + /etc/sliphome/slip.hosts contains + lines which have at least four items separated by + whitespace: + + + + SLIP user's login ID + + + + Local address (local to the SLIP server) of the SLIP + link + + + + Remote address of the SLIP link + + + + Network mask + + + + The local and remote addresses may be host names + (resolved to IP addresses by + /etc/hosts or by the domain name + service, depending on your specifications in the file + /etc/nsswitch.conf), and the network mask may be + a name that can be resolved by a lookup into + /etc/networks. On a sample system, + /etc/sliphome/slip.hosts looks like + this: + + # +# login local-addr remote-addr mask opt1 opt2 +# (normal,compress,noicmp) +# +Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp + + At the end of the line is one or more of the + options: + + + + — no header + compression + + + + — compress + headers + + + + — compress headers if + the remote end allows it + + + + — disable ICMP packets + (so any ping packets will be dropped instead + of using up your bandwidth) + + + + SLIP + TCP/IP networking + Your choice of local and remote addresses for your SLIP + links depends on whether you are going to dedicate a TCP/IP + subnet or if you are going to use proxy ARP on + your SLIP server (it is not true proxy ARP, but + that is the terminology used in this section to describe it). + If you are not sure which method to select or how to assign IP + addresses, please refer to the TCP/IP books referenced in + the SLIP Prerequisites () + and/or consult your IP network manager. + + If you are going to use a separate subnet for your SLIP + clients, you will need to allocate the subnet number out of + your assigned IP network number and assign each of your SLIP + client's IP numbers out of that subnet. Then, you will + probably need to configure a static route to the SLIP + subnet via your SLIP server on your nearest IP router. + + Ethernet + Otherwise, if you will use the proxy ARP + method, you will need to assign your SLIP client's IP + addresses out of your SLIP server's Ethernet subnet, and you + will also need to adjust your + /etc/sliphome/slip.login and + /etc/sliphome/slip.logout scripts to use + &man.arp.8; to manage the proxy-ARP entries in the SLIP + server's ARP table. + + + + <filename>slip.login</filename> Configuration + + The typical /etc/sliphome/slip.login + file looks like this: + + #!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 + + This slip.login file merely runs + ifconfig for the appropriate SLIP interface + with the local and remote addresses and network mask of the + SLIP interface. + + If you have decided to use the proxy ARP + method (instead of using a separate subnet for your SLIP + clients), your /etc/sliphome/slip.login + file will need to look something like this: + + #!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 +# Answer ARP requests for the SLIP client with our Ethernet addr +/usr/sbin/arp -s $5 00:11:22:33:44:55 pub + + The additional line in this + slip.login, arp -s + $5 00:11:22:33:44:55 pub, creates an ARP entry + in the SLIP server's ARP table. This ARP entry causes the + SLIP server to respond with the SLIP server's Ethernet MAC + address whenever another IP node on the Ethernet asks to + speak to the SLIP client's IP address. + + EthernetMAC address + When using the example above, be sure to replace the + Ethernet MAC address (00:11:22:33:44:55) with the MAC address of + your system's Ethernet card, or your proxy ARP + will definitely not work! You can discover your SLIP server's + Ethernet MAC address by looking at the results of running + netstat -i; the second line of the output + should look something like: + + ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116 + + This indicates that this particular system's Ethernet MAC + address is 00:02:c1:28:5f:4a + — the periods in the Ethernet MAC address given by + netstat -i must be changed to colons and + leading zeros should be added to each single-digit hexadecimal + number to convert the address into the form that &man.arp.8; + desires; see the manual page on &man.arp.8; for complete + information on usage. + + + When you create + /etc/sliphome/slip.login and + /etc/sliphome/slip.logout, the + execute bit (i.e., chmod 755 + /etc/sliphome/slip.login /etc/sliphome/slip.logout) + must be set, or sliplogin will be unable + to execute it. + + + + + <filename>slip.logout</filename> Configuration + + /etc/sliphome/slip.logout is not + strictly needed (unless you are implementing proxy + ARP), but if you decide to create it, this is an + example of a basic + slip.logout script: + + #!/bin/sh - +# +# slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down + + If you are using proxy ARP, you will want to + have /etc/sliphome/slip.logout remove the + ARP entry for the SLIP client: + + #!/bin/sh - +# +# @(#)slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down +# Quit answering ARP requests for the SLIP client +/usr/sbin/arp -d $5 + + The arp -d $5 removes the ARP entry + that the proxy ARP + slip.login added when the SLIP client + logged in. + + It bears repeating: make sure + /etc/sliphome/slip.logout has the execute + bit set after you create it (i.e., chmod 755 + /etc/sliphome/slip.logout). + + + + + Routing Considerations + + SLIP + routing + + If you are not using the proxy ARP method for + routing packets between your SLIP clients and the rest of your + network (and perhaps the Internet), you will probably + have to add static routes to your closest default router(s) to + route your SLIP clients subnet via your SLIP server. + + + Static Routes + static routes + + Adding static routes to your nearest default routers + can be troublesome (or impossible if you do not have + authority to do so...). If you have a multiple-router + network in your organization, some routers, such as those + made by Cisco and Proteon, may not only need to be + configured with the static route to the SLIP subnet, but + also need to be told which static routes to tell other + routers about, so some expertise and + troubleshooting/tweaking may be necessary to get + static-route-based routing to work. + + + + Running <application>&gated;</application> + + &gated; + + + + &gated; is proprietary software now and + will not be available as source code to the public anymore + (more info on the &gated; website). This + section only exists to ensure backwards compatibility for + those that are still using an older version. + + + An alternative to the headaches of static routes is to + install &gated; on your FreeBSD SLIP server + and configure it to use the appropriate routing protocols + (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP + subnet. + You will need to write a /etc/gated.conf + file to configure your &gated;; here is a sample, similar to + what the author used on a FreeBSD SLIP server: + + # +# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5 +# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface +# +# +# tracing options +# +traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ; + +rip yes { + interface sl noripout noripin ; + interface ed ripin ripout version 1 ; + traceoptions route ; +} ; + +# +# Turn on a bunch of tracing info for the interface to the kernel: +kernel { + traceoptions remnants request routes info interface ; +} ; + +# +# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP +# + +export proto rip interface ed { + proto direct { + xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections + } ; +} ; + +# +# Accept routes from RIP via ed Ethernet interfaces + +import proto rip interface ed { + all ; +} ; + + RIP + The above sample gated.conf file + broadcasts routing information regarding the SLIP subnet + xxx.xxx.yy via RIP onto the + Ethernet; if you are using a different Ethernet driver than + the ed driver, you will need to + change the references to the ed + interface appropriately. This sample file also sets up + tracing to /var/tmp/gated.output for + debugging &gated;'s activity; you can + certainly turn off the tracing options if + &gated; works correctly for you. You will need to + change the xxx.xxx.yy's into the + network address of your own SLIP subnet (be sure to change the + net mask in the proto direct clause as + well). + + Once you have installed and configured + &gated; on your system, you will need to + tell the FreeBSD startup scripts to run + &gated; in place of + routed. The easiest way to accomplish + this is to set the router and + router_flags variables in + /etc/rc.conf. Please see the manual + page for &gated; for information on + command-line parameters. + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/preface/preface.sgml b/pl_PL.ISO8859-2/books/handbook/preface/preface.sgml new file mode 100644 index 0000000000..c80eb9e2df --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/preface/preface.sgml @@ -0,0 +1,612 @@ + + + + Przedmowa + + Docelowy + czytelnik + + Osoba poznaj±ca dopiero system FreeBSD odnajdzie w pierwszej + czê¶ci niniejszej ksi±¿ki szereg porad prowadz±cych u¿ytkownika + przez proces instalacji i delikatnie prezentuj±cych pewne koncepcje + i konwencje stoj±ce u podstaw systemów &unix;. Przebrniêcie przez + tê czê¶æ wymaga niewiele wiêcej ni¿ chêæ poznania i umiejêtno¶æ + przyswajania sobie nowych koncepcji w miarê jak bêd± one + prezentowane. + + Po dotrwaniu do drugiej, zdecydowanie obszerniejszej czê¶ci + Podrêcznika, czytelnik bêdzie mia³ do dyspozycji pe³n± wiedzê z + zakresu wszystkich zagadnieñ znajdujacych siê w polu zainteresowañ + administratorów systemów FreeBSD. Niektóre z zawartych tutaj + rozdzia³ów mog± wymagaæ wcze¶niejszego zapoznania siê z odpowiedni± + literatur±. W takich przypadkach, bêdzie to wyszczególnione w + streszczeniu na pocz±tku ka¿dego rozdzia³u. + + zawiera listê dodatkowych ¼róde³ + informacji. + + Zmiany od wydania + drugiego + + Niniejsze trzecie wydanie stanowi punkt kulminacyjny przesz³o + dwuletniej pracy oddanych cz³onków Projektu Dokumentacji FreeBSD. + G³ówne zmiany jakie w tym okresie zosta³y dokonane to: + + + + , Konfiguracja i dostrajanie zosta³ + poszerzony o nowe informacje o zarz±dzaniu moc± i zasobami APCI, + opis narzêdzia cron i kolejn± porcjê opcji dostrajania j±dra. + + + + , Bezpieczeñstwo, zosta³ poszerzony + o nowe informacje odno¶nie wirtualnych sieci prywatnych (VPN), + list kontroli dostêpu do systemu plików, i biuletynach + bezpieczeñstwa. + + + + , Mandatory Access Control (MAC), is + a new chapter with this edition. It explains what MAC is + and how this mechanism can be used to secure a FreeBSD + system. + + + + , Storage, has been expanded with + new information about USB storage devices, file system + snapshots, file system quotas, file and network backed + filesystems, and encrypted disk partitions. + + + + , Vinum, is a new chapter + with this edition. It describes how to use Vinum, a logical + volume manager which provides device-independent logical + disks, and software RAID-0, RAID-1 and RAID-5. + + + + A troubleshooting section has been added to , PPP and SLIP. + + + + , Electronic Mail, has been + expanded with new information about using alternative + transport agents, SMTP authentication, UUCP, fetchmail, + procmail, and other advanced topics. + + + + , Network Servers, is + all new with this edition. This chapter includes + information about setting up the Apache HTTP Server, FTPd, + and setting up a server for Microsoft Windows clients with + Samba. Some sections from , Advanced Networking, were + moved here to improve the presentation. + + + + , Advanced + Networking, has been expanded with new information about + using Bluetooth devices with FreeBSD, setting up wireless + networks, and Asynchronous Transfer Mode (ATM) + networking. + + + + Definicje i wykorzystywane w ksi±¿ce terminy techniczne + zosta³y zebrane razem w formie leksykonu. + + + + Dokonano wielu estetycznych poprawek tabel i rysunków. + + + + Zmiany od wydania pierwszego + + Wydanie drugie stanowi³o punkt kulminacyjny przesz³o dwuletniej pracy + oddanych cz³onków Projektu Dokumentacji FreeBSD. G³ówne zmiany jakie w tym + okresie zosta³y dokonane to: + + + + + + Dodano indeks. + + + Wszystkie diagramy ASCII zosta³y zast±pione rysunkami graficznymi. + + + Dodano standardowe streszczenie do wszystkich rozdzia³ów, informuj±ce + jakie informacje rozdzia³ zawiera i co powinien wiedzieæ czytelnik nim + przyst±pi do czytania. + + + Zawarto¶æ podrêcznika zosta³a zreorganizowana w trzy logiczne czê¶ci: + Pierwsze kroki, Administracja systemem oraz + Dodatki. + + + (Instalacja FreeBSD) zosta³ ca³kowicie + przepisany na nowo.Do³±czono wiele zrzutów ekranu, by u³atwiæ nowym u¿ytkownikom + przyswojenie tekstu. + + + (Podstawy Uniksa) zosta³ poszerzony + o dodatkow informacje o procesach, demonach i sygna³ach. + + + (Instalacja programów) zosta³ poszerzony + o dodatkowe informacje o zarz±dzaniu pakietami binarnymi. + + + (System okien X) zosta³ w ca³ko¶ci + napisany od nowa k³ad±c nacisk na wspó³czesne ¶rodowiska graficzne we &xfree86; 4.X, + takie jak KDE i GNOME. + + + (Proces uruchamiania FreeBSD) zosta³ + poszerzony. + + + (Pamiêæ) zosta³ napisany na podstawie + rozdzia³ów Dyski oraz Kopie zapasowe. Uwa¿amy, ¿e + zagadnienia te ³atwiej jest zrozumieæ, gdy s± przedstawiane jako jeden rozdzia³. + Dodano równie¿ podrozdzia³ traktuj±cy o RAID (zarówno sprzêtowym jak + i programowym). + + + (Komunikacja szeregowa) zosta³ ca³kowicie + zreorganizowany i zaktualizowany dla FreeBSD 4.X/5.X. + + + (PPP i SLIP) zosta³y zasadniczo + zaktualizowane. + + + (Advanced Networking) zosta³ + zaktualizowany. + + + (Poczta elektroniczna) zosta³ rozszerzony materia³y + traktuj±ce o konfiguracji programu sendmail. + + + (Kompatybilno¶æ z Linuksem) zosta³ poszerzony + o informacje o instalacji bazy &oracle; oraz + &sap.r3;. + + + W drugim wydaniu dodano nowe rozdzia³y: + + + Konfiguracja i dostrajanie (). + + + Multimedia () + + + + + + Uk³ad ksi±¿ki + + Niniejsza ksi±¿ka zosta³a podzielona na piêæ logicznych + czê¶ci. Czê¶æ pierwsza, Pierwsze kroki, opisuje + proces instalacji oraz podstawy u¿ytkowania systemu FreeBSD. Zaleca + siê aby czytelnik zapozna³ siê z tymi rozdzia³ami kolejno, + pomijaj±c jedynie znane tematy. Czê¶æ druga, Codzienne + czynno¶ci, prezentuje niektóre z najczê¶ciej wykorzystywanych + funkcji FreeBSD. Ta czê¶æ, wraz kolejnymi, mo¿e byæ czytania bez + okre¶lonej kolejno¶ci. Ka¿dy z wchodz±cych w jej sk³ad rozdzia³ów + zaczyna siê od zwiêz³ego strzeszczenia zawarto¶ci i przedstawienia + co czytelnik powinien ju¿ wiedzieæ. Celem takiego uk³adu jest pozwolenie + zwyk³emu czytelnikowi pomin±æ pewne rozdzia³y, by prej¶æ od razu do + najbardziej interesuj±cych. Czê¶æ trzecia, Administracja + Systemem, opisuje zagadnienia administracyjne. Czê¶æ czwarta, + Komunikacja sieciowa, zawiera tematy zwi±zane z prac± + w sieci oraz obs³ug± serwerów. Czê¶æ pi±ta zawiera dodatki. + + + + + + + , Wprowadzenie + + Wprowadza nowego u¿ytkownika w ¶wiat FreeBSD. Streszcza historiê + Projektu FreeBSD, stawiane przed nim cele oraz model rozwoju. + + + + , Instalacja + + Przeprowadza u¿ytkownika przez ca³y proces instalacji. Opisuje + równie¿ kilka zaawansowanych zagadnieñ, jak np. instalacjê przez + konsolê szeregow±. + + + + , Podstawy Uniksa + + Przedstawia podstawowe polecenie i funkcje systemu operacyjnego + FreeBSD. Je¶li pracowali¶my w Linuksie b±d¼ w innym systemie typu + &unix; najprawdopodobniej mo¿emy pomin±æ ten rozdzia³. + + + + , Instalacja programów + + Opisuje metody instalacji dodatkowego oprogramowania we FreeBSD + za pomoc± systemu Kolekcji portów oraz typowych + pakietów binarnych. + + + + , System okien X + + Opisuje ogólnie System okien X oraz wykorzystanie X11 we FreeBSD. + Ponadto, przedstawia typowe ¶rodowiska graficzne jak np. + KDE czy GNOME. + + + + + + + , Aplikacje biurowe + + Lists some common desktop applications, such as web browsers + and productivity suites, and describes how to install them on + FreeBSD. + + + + , Multimedia + + Shows how to set up sound and video playback support for your + system. Also describes some sample audio and video applications. + + + + , Configuring the FreeBSD + Kernel + + Explains why you might need to configure a new kernel + and provides detailed instructions for configuring, building, + and installing a custom kernel. + + + + , Printing + + Describes managing printers on FreeBSD, including + information about banner pages, printer accounting, and + initial setup. + + + + , &linux; Binary Compatibility + + Describes the &linux; compatibility features of FreeBSD. + Also provides detailed installation instructions for many + popular &linux; applications such as &oracle;, &sap.r3;, and + &mathematica;. + + + + + + + , Configuration and Tuning + + Describes the parameters available for system + administrators to tune a FreeBSD system for optimum + performance. Also describes the various configuration files + used in FreeBSD and where to find them. + + + + , Booting Process + + Describes the FreeBSD boot process and explains + how to control this process with configuration options. + + + + , Users and Basic Account + Management + + Describes the creation and manipulation of user + accounts. Also discusses resource limitations that can be + set on users and other account management tasks. + + + + , Security + + Describes many different tools available to help keep your + FreeBSD system secure, including Kerberos, IPsec and OpenSSH. + + + + , Mandatory Access Control + + Explains what Mandatory Access Control (MAC) is and how this + mechanism can be used to secure a FreeBSD system. + + + + , Storage + + Describes how to manage storage media and filesystems + with FreeBSD. This includes physical disks, RAID arrays, + optical and tape media, memory-backed disks, and network + filesystems. + + + + , GEOM + + Describes what the GEOM framework in FreeBSD is and how + to configure various supported RAID levels. + + + + , Vinum + + Describes how to use Vinum, a logical volume manager + which provides device-independent logical disks, and + software RAID-0, RAID-1 and RAID-5. + + + + , Localization + + Describes how to use FreeBSD in languages other than + English. Covers both system and application level + localization. + + + + , The Cutting Edge + + Explains the differences between FreeBSD-STABLE, + FreeBSD-CURRENT, and FreeBSD releases. Describes which users + would benefit from tracking a development system and outlines + that process. + + + + + + + , Serial Communications + + Explains how to connect terminals and modems to your + FreeBSD system for both dial in and dial out connections. + + + + , PPP and SLIP + + Describes how to use PPP, SLIP, or PPP over Ethernet to + connect to remote systems with FreeBSD. + + + + , Electronic Mail + + Explains the different components of an email server and + dives into simple configuration topics for the most popular + mail server software: + sendmail. + + + + , Network Servers + + Provides detailed instructions and example configuration + files to set up your FreeBSD machine as a network filesystem + server, domain name server, network information system + server, or time synchronization server. + + + + , Firewalls + + Explains the philosophy behind software-based firewalls and + provides detailed information about the configuration of the + different firewalls available for FreeBSD. + + + + , Advanced Networking + + Describes many networking topics, including sharing an + Internet connection with other computers on your LAN, advanced + routing topics, wireless networking, bluetooth, ATM, IPv6, and + much more. + + + + + + + , Obtaining FreeBSD + + Lists different sources for obtaining FreeBSD media on CDROM + or DVD as well as different sites on the Internet that allow + you to download and install FreeBSD. + + + + , Bibliography + + This book touches on many different subjects that may + leave you hungry for a more detailed explanation. The + bibliography lists many excellent books that are referenced in + the text. + + + + , Resources on the Internet + + Describes the many forums available for FreeBSD users to + post questions and engage in technical conversations about + FreeBSD. + + + + , PGP Keys + + Lists the PGP fingerprints of several FreeBSD Developers. + + + + + Konwencje u¿yte w tej ksi±¿ce + + W celu utrzymania jednolito¶ci i ³atwo¶ci czytania + niniejszego tekstu w ksi±¿ce zastosowane zosta³y nastêpuj±ce + konwencje. + + Konwencje typograficzne + + + + Kursywa + + Czcionka pochy³a stosowana jest do wskazania + plików, adresów URL, szczególnie akcentowanych fragmentów i pierwszego + zastosowania zwrotów technicznych. + + + + Sta³a szeroko¶æ + + Czcionka o sta³ej szeroko¶ci stosowana jest do + przedstawienia komunikatów o b³êdach, poleceñ, zmiennych ¶rodowiskowych, + nazw portów, nazw komputerów, nazw u¿ytkowników i grup, nazw urz±dzeñ, + zmiennych i fragmentów kodu. + + + + Pogrubienie + + Czcionka pogrubiona stosowana jest do + nazw programów, poleceñ i klawiszy. + + + + + + Zadania u¿ytkownika + + Zgodnie z konwencj± typograficzn±, klawisze, które ma nacisn±æ + u¿ytkownik w trakcie pracy z opisywanym programem, zosta³y oznaczone + pogrubieniem by wyró¿nia³y siê z reszty tekstu. + Kombinacje klawiszy, które nale¿y nacisn±æ jednocze¶nie zawieraj± znak + `+' pomiêdzy, np.: + + + + Ctrl + Alt + Del + + + + Oznacza, ¿e u¿ytkownik powinien nacisn±æ Ctrl, + Alt i Del jednocze¶nie. + + Klawisze, które nale¿y nacisn±æ kolejno bêd± oddzielone + przecinkiem, np.: + + + + Ctrl + X + , + + Ctrl + S + + + + Co oznacza, ¿e u¿ytkownik powinien nacisn±æ klawisze + Ctrl i X jednocze¶nie, + a nastêpnie Ctrl i S. + + + Przyk³ady + + Przyk³ady zaczynaj±ce siê od E:\> + wskazuj± polecenie systemu &ms-dos;. Je¶li nie jest wyra¼nie zaznaczone, + ¿e jest inaczej, polecenia te mog± byæ wprowadzane bezpo¶rednio w + oknie Linii poleceñ w ¶rodowisku µsoft.windows;. + + E:\> tools\fdimage floppies\kern.flp A: + + Przyk³ady zaczynaj±ce siê od &prompt.root; wskazuj± polecenie, + które musi byæ wprowadzone przez u¿ytkownika z uprawnieniami + administratora systemu FreeBSD. Mo¿esz zalogowaæ siê jako root + i wprowadziæ polecenie, b±d¼ zalogowaæ jako zwyk³y u¿ytkownik i wykorzystaæ + &man.su.1; by uzyskaæ prawa administratora. + + &prompt.root; dd if=kern.flp of=/dev/fd0 + + Przyk³ady zaczynaj±ce siê od &prompt.user; wskazuj±, i¿ polecenie + powinno byæ wprowadzone przez zwyk³ego u¿ytkownika. Je¶li nie jest + inaczej zaznaczone, stosowana jest sk³adnia pow³oki C (csh) do ustawiania + zmiennych ¶rodowiskowych i uruchamiania innych poleceñ pow³oki. + + &prompt.user; top + + Podziêkowania + + Niniejsza ksi±¿ka jest efektem pracy setek ludzi z ca³ego ¶wiata. + Niezale¿nie czy przys³ali poprawkê literówki czy ca³y rozdzia³, ka¿dy + wk³ad jest doceniany. + + Kilka firm wspar³o rozwój tego dokumentu op³acaj±c autorów, + by mogli pracowaæ nad ni± w pe³nym wymiarze czasowym, finansuj±c + publikacjê w formie papierowej, itd. Pragniemy wymieniæ przede + wszystkim BSDi (przejête pó¼niej przez + Wind River Systems), + które op³aci³o pracê cz³onków Projektu Dokumentacji FreeBSD nad korektami + ksi±¿ki, przygotowuj±c j± do pierwszej publikacji drukowanej + w Marcu 2000 r. (ISBN 1-57176-241-8). Nastêpnie, Wind River Systems + sfinansowa³o pracê kolejnych osób przygotowuj±cych nowe rozdzia³y, + a tak¿e format wydruku. Kulminacj± ich pracy jest drugie wydanie, które ujrza³o + ¶wiat³o dzienne w Listopadzie 2001 r. (ISBN 1-57176-303-1). W latach 2003-2004, + FreeBSD Mall, Inc sfinansowa³o + prace nad korekt± Podrêcznika, przygotowywanego do trzeciego wydania + w postaci drukowanej. + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/printing/Makefile b/pl_PL.ISO8859-2/books/handbook/printing/Makefile new file mode 100644 index 0000000000..72d9e9b80a --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/printing/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= printing/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/printing/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/printing/chapter.sgml new file mode 100644 index 0000000000..42215483ec --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/printing/chapter.sgml @@ -0,0 +1,4876 @@ + + + + + + + Sean + Kelly + Contributed by + + + + + + Jim + Mock + Restructured and updated by + + + + + + Printing + + + Synopsis + LPD spooling system + printing + + FreeBSD can be used to print with a wide variety of printers, from the + oldest impact printer to the latest laser printers, and everything in + between, allowing you to produce high-quality printed output from the + applications you run. + + FreeBSD can also be configured to act as a print server on a + network; in this capacity FreeBSD can receive print jobs from a variety + of other computers, including other FreeBSD computers, &windows; and &macos; + hosts. FreeBSD will ensure that one job at a time is printed, and can + keep statistics on which users and machines are doing the most printing, + produce banner pages showing who's printout is who's, and + more. + + After reading this chapter, you will know: + + + + How to configure the FreeBSD print spooler. + + + + How to install print filters, to handle special print jobs + differently, including converting incoming documents to print + formats that your printers understand. + + + + How to enable header, or banner pages on your printout. + + + + How to print with printers connected to other computers. + + + + How to print with printers connected directly to the + network. + + + + How to control printer restrictions, including limiting the size + of print jobs, and preventing certain users from printing. + + + + How to keep printer statistics, and account for printer + usage. + + + + How to troubleshoot printing problems. + + + + Before reading this chapter, you should: + + + + Know how to configure and install a new kernel + (). + + + + + + Introduction + + In order to use printers with FreeBSD, you may set + them up to work with the Berkeley line printer spooling system, + also known as the LPD spooling system, + or just LPD. + It is the standard printer control system in FreeBSD. This + chapter introduces LPD and + will guide you through its configuration. + + If you are already familiar with + LPD or another printer spooling + system, you may wish to skip to section Basic Setup. + + LPD controls everything about a + host's printers. It is responsible for a number of things: + + + + It controls access to attached printers and printers + attached to other hosts on the network. + + + print jobs + + It enables users to submit files to be printed; these + submissions are known as jobs. + + + + It prevents multiple users from accessing a printer at the + same time by maintaining a queue for each + printer. + + + + It can print header pages (also known + as banner or burst + pages) so users can easily find jobs they have printed in a + stack of printouts. + + + + It takes care of communications parameters for printers + connected on serial ports. + + + + It can send jobs over the network to a + LPD spooler on another host. + + + + It can run special filters to format jobs to be printed for + various printer languages or printer capabilities. + + + + It can account for printer usage. + + + + Through a configuration file + (/etc/printcap), and by providing the special + filter programs, you can enable the LPD + system to do all or some + subset of the above for a great variety of printer hardware. + + + Why You Should Use the Spooler + + If you are the sole user of your system, you may be wondering + why you should bother with the spooler when you do not need access + control, header pages, or printer accounting. While it is + possible to enable direct access to a printer, you should use the + spooler anyway since: + + + + LPD prints jobs in the background; + you do not have to wait + for data to be copied to the printer. + + + &tex; + + LPD can conveniently run a job + to be printed through + filters to add date/time headers or convert a special file + format (such as a &tex; DVI file) into a format the printer will + understand. You will not have to do these steps + manually. + + + + Many free and commercial programs that provide a print + feature usually expect to talk to the spooler on your system. + By setting up the spooling system, you will more easily + support other software you may later add or already + have. + + + + + + + Basic Setup + + To use printers with the LPD spooling + system, you will need to + set up both your printer hardware and the + LPD software. This + document describes two levels of setup: + + + + See section Simple Printer + Setup to learn how to connect a printer, tell + LPD how to + communicate with it, and print plain text files to the + printer. + + + + See section Advanced + Printer Setup to learn how to print a variety of + special file formats, to print header pages, to print across a + network, to control access to printers, and to do printer + accounting. + + + + + Simple Printer Setup + + This section tells how to configure printer hardware and the + LPD software to use the printer. + It teaches the basics: + + + + Section Hardware + Setup gives some hints on connecting the printer to a + port on your computer. + + + + Section Software + Setup shows how to set up the + LPD spooler configuration + file (/etc/printcap). + + + + If you are setting up a printer that uses a network protocol + to accept data to print instead of a computer's local interfaces, + see Printers With + Networked Data Stream Interfaces. + + Although this section is called Simple Printer + Setup, it is actually fairly complex. Getting the printer + to work with your computer and the LPD + spooler is the hardest + part. The advanced options like header pages and accounting are + fairly easy once you get the printer working. + + + Hardware Setup + + This section tells about the various ways you can connect a + printer to your PC. It talks about the kinds of ports and + cables, and also the kernel configuration you may need to enable + FreeBSD to speak to the printer. + + If you have already connected your printer and have + successfully printed with it under another operating system, you + can probably skip to section Software Setup. + + + Ports and Cables + + Printers sold for use on PC's today generally come + with one or more of the following three interfaces: + + + + printers + serial + + + Serial interfaces, also known + as RS-232 or COM ports, use a serial port + on your computer to send data to the printer. Serial + interfaces are common in the computer industry and cables + are readily available and also easy to construct. Serial + interfaces sometimes need special cables and might require + you to configure somewhat complex communications + options. Most PC serial ports have a maximum + transmission rate of 115200 bps, which makes printing + large graphic print jobs with them impractical. + + + + printers + parallel + + + Parallel interfaces use a + parallel port on your computer to send data to the + printer. Parallel interfaces are common in the PC market + and are faster than RS-232 serial. + Cables are readily available but more difficult to + construct by hand. There are usually no communications + options with parallel interfaces, making their + configuration exceedingly simple. + + + centronics + parallel printers + + Parallel interfaces are sometimes known as + Centronics interfaces, named after the + connector type on the printer. + + + + printers + USB + + + USB interfaces, named for the Universal Serial + Bus, can run at even faster speeds than parallel or + RS-232 serial interfaces. Cables are simple and cheap. + USB is superior to RS-232 Serial and to Parallel for + printing, but it is not as well supported under &unix; + systems. A way to avoid this problem is to purchase a + printer that has both a USB interface and a Parallel + interface, as many printers do. + + + + In general, Parallel interfaces usually offer just + one-way communication (computer to printer) while serial + and USB gives you two-way. Newer parallel ports (EPP and + ECP) and printers + can communicate in both directions under FreeBSD when a + IEEE-1284-compliant cable is used. + + PostScript + + Two-way communication to the printer over a parallel + port is generally done in one of two ways. The first method + uses a custom-built printer driver for FreeBSD that speaks + the proprietary language used by the printer. This is + common with inkjet printers and can be used for reporting + ink levels and other status information. The second + method is used when the printer supports + &postscript;. + + &postscript; jobs are + actually programs sent to the printer; they need not produce + paper at all and may return results directly to the computer. + &postscript; also uses two-way communication to tell the + computer about problems, such as errors in the &postscript; + program or paper jams. Your users may be appreciative of such + information. Furthermore, the best way to do effective + accounting with a &postscript; printer requires two-way + communication: you ask the printer for its page count (how + many pages it has printed in its lifetime), then send the + user's job, then ask again for its page count. Subtract the + two values and you know how much paper to charge to the + user. + + + + Parallel Ports + + To hook up a printer using a parallel interface, connect + the Centronics cable between the printer and the computer. + The instructions that came with the printer, the computer, or + both should give you complete guidance. + + Remember which parallel port you used on the computer. + The first parallel port is ppc0 to + FreeBSD; the second is ppc1, and so + on. The printer device name uses the same scheme: + /dev/lpt0 for the printer on the first + parallel ports etc. + + + + Serial Ports + + To hook up a printer using a serial interface, connect the + proper serial cable between the printer and the computer. The + instructions that came with the printer, the computer, or both + should give you complete guidance. + + If you are unsure what the proper serial + cable is, you may wish to try one of the following + alternatives: + + + + A modem cable connects each pin + of the connector on one end of the cable straight through + to its corresponding pin of the connector on the other + end. This type of cable is also known as a + DTE-to-DCE cable. + + + null-modem cable + + A null-modem cable connects some + pins straight through, swaps others (send data to receive + data, for example), and shorts some internally in each + connector hood. This type of cable is also known as a + DTE-to-DTE cable. + + + + A serial printer cable, required + for some unusual printers, is like the null-modem cable, + but sends some signals to their counterparts instead of + being internally shorted. + + + + baud rate + parity + flow control protocol + You should also set up the communications parameters for + the printer, usually through front-panel controls or DIP + switches on the printer. Choose the highest + bps (bits per second, sometimes + baud rate) that both your computer + and the printer can support. Choose 7 or 8 data bits; none, + even, or odd parity; and 1 or 2 stop bits. Also choose a flow + control protocol: either none, or XON/XOFF (also known as + in-band or software) flow control. + Remember these settings for the software configuration that + follows. + + + + + Software Setup + + This section describes the software setup necessary to print + with the LPD spooling system in FreeBSD. + + + Here is an outline of the steps involved: + + + + Configure your kernel, if necessary, for the port you + are using for the printer; section Kernel Configuration tells + you what you need to do. + + + + Set the communications mode for the parallel port, if + you are using a parallel port; section Setting the + Communication Mode for the Parallel Port gives + details. + + + + Test if the operating system can send data to the printer. + Section Checking Printer + Communications gives some suggestions on how to do + this. + + + + Set up LPD for the printer by + modifying the file + /etc/printcap. You will find out how + to do this later in this chapter. + + + + + Kernel Configuration + + The operating system kernel is compiled to work with a + specific set of devices. The serial or parallel interface for + your printer is a part of that set. Therefore, it might be + necessary to add support for an additional serial or parallel + port if your kernel is not already configured for one. + + To find out if the kernel you are currently using supports + a serial interface, type: + + &prompt.root; grep sioN /var/run/dmesg.boot + + Where N is the number of the + serial port, starting from zero. If you see output similar to + the following: + + sio2 at port 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A + + then the kernel supports the port. + + To find out if the kernel supports a parallel interface, + type: + + &prompt.root; grep ppcN /var/run/dmesg.boot + + Where N is the number of the + parallel port, starting from zero. If you see output similar + to the following: + + ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 +ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode +ppc0: FIFO with 16/16/8 bytes threshold + + then the kernel supports the port. + + You might have to reconfigure your kernel in order for the + operating system to recognize and use the parallel or serial + port you are using for the printer. + + To add support for a serial port, see the section on + kernel configuration. To add support for a parallel port, see + that section and the section that + follows. + + + + Setting the Communication Mode for the Parallel + Port + + When you are using the parallel interface, you can choose + whether FreeBSD should use interrupt-driven or polled + communication with the printer. The generic printer + device driver (&man.lpt.4;) on FreeBSD + uses the &man.ppbus.4; system, which controls the port + chipset with the &man.ppc.4; driver. + + + + The interrupt-driven method is + the default with the GENERIC kernel. With this method, + the operating system uses an IRQ line to determine when + the printer is ready for data. + + + + The polled method directs the + operating system to repeatedly ask the printer if it is + ready for more data. When it responds ready, the kernel + sends more data. + + + + The interrupt-driven method is usually somewhat faster + but uses up a precious IRQ line. Some newer HP printers + are claimed not to work correctly in interrupt mode, + apparently due to some (not yet exactly understood) timing + problem. These printers need polled mode. You should use + whichever one works. Some printers will work in both + modes, but are painfully slow in interrupt mode. + + You can set the communications mode in two ways: by + configuring the kernel or by using the &man.lptcontrol.8; + program. + + To set the communications mode by configuring + the kernel: + + + + Edit your kernel configuration file. Look for + an ppc0 entry. If you are setting up + the second parallel port, use ppc1 + instead. Use ppc2 for the third port, + and so on. + + + + If you want interrupt-driven mode, edit the following line: + + hint.ppc.0.irq="N" + + in the /boot/device.hints file + and replace N with the right + IRQ number. The kernel configuration file must + also contain the &man.ppc.4; driver: + + device ppc + + + + + If you want polled mode, remove in your + /boot/device.hints file, the + following line: + + hint.ppc.0.irq="N" + + In some cases, this is not enough to put the + port in polled mode under FreeBSD. Most of + time it comes from &man.acpi.4; driver, this latter + is able to probe and attach devices, and therefore, + control the access mode to the printer port. You + should check your &man.acpi.4; configuration to + correct this problem. + + + + + + Save the file. Then configure, build, and install the + kernel, then reboot. See kernel configuration for + more details. + + + + To set the communications mode with + &man.lptcontrol.8;: + + + + Type: + + &prompt.root; lptcontrol -i -d /dev/lptN + + to set interrupt-driven mode for + lptN. + + + + Type: + + &prompt.root; lptcontrol -p -d /dev/lptN + + to set polled-mode for + lptN. + + + + You could put these commands in your + /etc/rc.local file to set the mode each + time your system boots. See &man.lptcontrol.8; for more + information. + + + + Checking Printer Communications + + Before proceeding to configure the spooling system, you + should make sure the operating system can successfully send + data to your printer. It is a lot easier to debug printer + communication and the spooling system separately. + + To test the printer, we will send some text to it. For + printers that can immediately print characters sent to them, + the program &man.lptest.1; is perfect: it generates all 96 + printable ASCII characters in 96 lines. + + PostScript + For a &postscript; (or other language-based) printer, we + will need a more sophisticated test. A small &postscript; + program, such as the following, will suffice: + + %!PS +100 100 moveto 300 300 lineto stroke +310 310 moveto /Helvetica findfont 12 scalefont setfont +(Is this thing working?) show +showpage + + The above &postscript; code can be placed into a file and + used as shown in the examples appearing in the following + sections. + + PCL + + When this document refers to a printer language, it is + assuming a language like &postscript;, and not Hewlett + Packard's PCL. Although PCL has great functionality, you + can intermingle plain text with its escape sequences. + &postscript; cannot directly print plain text, and that is the + kind of printer language for which we must make special + accommodations. + + + + Checking a Parallel Printer + + + printers + parallel + + This section tells you how to check if FreeBSD can + communicate with a printer connected to a parallel + port. + + To test a printer on a parallel + port: + + + + Become root with &man.su.1;. + + + + Send data to the printer. + + + + If the printer can print plain text, then use + &man.lptest.1;. Type: + + &prompt.root; lptest > /dev/lptN + + Where N is the number + of the parallel port, starting from zero. + + + + If the printer understands &postscript; or other + printer language, then send a small program to the + printer. Type: + + &prompt.root; cat > /dev/lptN + + Then, line by line, type the program + carefully as you cannot edit a + line once you have pressed RETURN + or ENTER. When you have finished + entering the program, press + CONTROL+D, or whatever your end + of file key is. + + Alternatively, you can put the program in a file + and type: + + &prompt.root; cat file > /dev/lptN + + Where file is the + name of the file containing the program you want to + send to the printer. + + + + + + You should see something print. Do not worry if the + text does not look right; we will fix such things + later. + + + + Checking a Serial Printer + + + printers + serial + + This section tells you how to check if FreeBSD can + communicate with a printer on a serial port. + + To test a printer on a serial + port: + + + + Become root with &man.su.1;. + + + + Edit the file /etc/remote. Add + the following entry: + + printer:dv=/dev/port:br#bps-rate:pa=parity + + bits-per-second + serial port + parity + Where port is the device + entry for the serial port (ttyd0, + ttyd1, etc.), + bps-rate is the + bits-per-second rate at which the printer communicates, + and parity is the parity + required by the printer (either even, + odd, none, or + zero). + + Here is a sample entry for a printer connected via + a serial line to the third serial port at 19200 bps with + no parity: + + printer:dv=/dev/ttyd2:br#19200:pa=none + + + + Connect to the printer with &man.tip.1;. + Type: + + &prompt.root; tip printer + + If this step does not work, edit the file + /etc/remote again and try using + /dev/cuaaN + instead of + /dev/ttydN. + + + + Send data to the printer. + + + + If the printer can print plain text, then use + &man.lptest.1;. Type: + + &prompt.user; $lptest + + + + If the printer understands &postscript; or other + printer language, then send a small program to the + printer. Type the program, line by line, + very carefully as backspacing + or other editing keys may be significant to the + printer. You may also need to type a special + end-of-file key for the printer so it knows it + received the whole program. For &postscript; + printers, press CONTROL+D. + + Alternatively, you can put the program in a file + and type: + + &prompt.user; >file + + Where file is the + name of the file containing the program. After + &man.tip.1; sends the file, press any required + end-of-file key. + + + + + + You should see something print. Do not worry if the + text does not look right; we will fix that later. + + + + + Enabling the Spooler: the <filename>/etc/printcap</filename> + File + + At this point, your printer should be hooked up, your kernel + configured to communicate with it (if necessary), and you have + been able to send some simple data to the printer. Now, we are + ready to configure LPD to control access + to your printer. + + You configure LPD by editing the file + /etc/printcap. The + LPD spooling system + reads this file each time the spooler is used, so updates to the + file take immediate effect. + + + printers + capabilities + + The format of the &man.printcap.5; file is straightforward. + Use your favorite text editor to make changes to + /etc/printcap. The format is identical to + other capability files like + /usr/share/misc/termcap and + /etc/remote. For complete information + about the format, see the &man.cgetent.3;. + + The simple spooler configuration consists of the following + steps: + + + + Pick a name (and a few convenient aliases) for the + printer, and put them in the + /etc/printcap file; see the + Naming the Printer + section for more information on naming. + + + header pages + + Turn off header pages (which are on by default) by + inserting the sh capability; see the + Suppressing Header + Pages section for more information. + + + + Make a spooling directory, and specify its location with + the sd capability; see the Making the Spooling + Directory section for more information. + + + + Set the /dev entry to use for the + printer, and note it in /etc/printcap + with the lp capability; see the Identifying the Printer + Device for more information. Also, if the printer is + on a serial port, set up the communication parameters with + the ms# capability which is discussed in the Configuring Spooler + Communications Parameters section. + + + + Install a plain text input filter; see the Installing the Text + Filter section for details. + + + + Test the setup by printing something with the + &man.lpr.1; command. More details are available in the + Trying It Out and + Troubleshooting + sections. + + + + + Language-based printers, such as &postscript; printers, + cannot directly print plain text. The simple setup outlined + above and described in the following sections assumes that if + you are installing such a printer you will print only files + that the printer can understand. + + + Users often expect that they can print plain text to any of + the printers installed on your system. Programs that interface + to LPD to do their printing usually + make the same assumption. + If you are installing such a printer and want to be able to + print jobs in the printer language and + print plain text jobs, you are strongly urged to add an + additional step to the simple setup outlined above: install an + automatic plain-text-to-&postscript; (or other printer language) + conversion program. The section entitled Accommodating Plain + Text Jobs on &postscript; Printers tells how to do + this. + + + Naming the Printer + + The first (easy) step is to pick a name for your printer. + It really does not matter whether you choose functional or + whimsical names since you can also provide a number of aliases + for the printer. + + At least one of the printers specified in the + /etc/printcap should have the alias + lp. This is the default printer's name. + If users do not have the PRINTER environment + variable nor specify a printer name on the command line of any + of the LPD commands, + then lp will be the + default printer they get to use. + + Also, it is common practice to make the last alias for a + printer be a full description of the printer, including make + and model. + + Once you have picked a name and some common aliases, put + them in the /etc/printcap file. The name + of the printer should start in the leftmost column. Separate + each alias with a vertical bar and put a colon after the last + alias. + + In the following example, we start with a skeletal + /etc/printcap that defines two printers + (a Diablo 630 line printer and a Panasonic KX-P4455 &postscript; + laser printer): + + # +# /etc/printcap for host rose +# +rattan|line|diablo|lp|Diablo 630 Line Printer: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4: + + In this example, the first printer is named + rattan and has as aliases + line, diablo, + lp, and Diablo 630 Line + Printer. Since it has the alias + lp, it is also the default printer. The + second is named bamboo, and has as aliases + ps, PS, + S, panasonic, and + Panasonic KX-P4455 PostScript v51.4. + + + + Suppressing Header Pages + + printing + header pages + + + The LPD spooling system will + by default print a + header page for each job. The header + page contains the user name who requested the job, the host + from which the job came, and the name of the job, in nice + large letters. Unfortunately, all this extra text gets in the + way of debugging the simple printer setup, so we will suppress + header pages. + + To suppress header pages, add the sh + capability to the entry for the printer in + /etc/printcap. Here is an example + /etc/printcap with sh + added: + + # +# /etc/printcap for host rose - no header pages anywhere +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh: + + Note how we used the correct format: the first line starts + in the leftmost column, and subsequent lines are indented. + Every line in an entry except the last ends in + a backslash character. + + + + Making the Spooling Directory + printer spool + print jobs + + The next step in the simple spooler setup is to make a + spooling directory, a directory where + print jobs reside until they are printed, and where a number + of other spooler support files live. + + Because of the variable nature of spooling directories, it + is customary to put these directories under + /var/spool. It is not necessary to + backup the contents of spooling directories, either. + Recreating them is as simple as running &man.mkdir.1;. + + It is also customary to make the directory with a name + that is identical to the name of the printer, as shown + below: + + &prompt.root; mkdir /var/spool/printer-name + + However, if you have a lot of printers on your network, + you might want to put the spooling directories under a single + directory that you reserve just for printing with + LPD. We + will do this for our two example printers + rattan and + bamboo: + + &prompt.root; mkdir /var/spool/lpd +&prompt.root; mkdir /var/spool/lpd/rattan +&prompt.root; mkdir /var/spool/lpd/bamboo + + + If you are concerned about the privacy of jobs that + users print, you might want to protect the spooling + directory so it is not publicly accessible. Spooling + directories should be owned and be readable, writable, and + searchable by user daemon and group daemon, and no one else. + We will do this for our example printers: + + &prompt.root; chown daemon:daemon /var/spool/lpd/rattan +&prompt.root; chown daemon:daemon /var/spool/lpd/bamboo +&prompt.root; chmod 770 /var/spool/lpd/rattan +&prompt.root; chmod 770 /var/spool/lpd/bamboo + + + Finally, you need to tell LPD + about these directories + using the /etc/printcap file. You + specify the pathname of the spooling directory with the + sd capability: + + # +# /etc/printcap for host rose - added spooling directories +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo: + + Note that the name of the printer starts in the first + column but all other entries describing the printer should be + indented and each line end escaped with a + backslash. + + If you do not specify a spooling directory with + sd, the spooling system will use + /var/spool/lpd as a default. + + + + Identifying the Printer Device + + In the + Entries for the Ports + section, we identified which entry in the + /dev directory FreeBSD will use to + communicate with the printer. Now, we tell + LPD that + information. When the spooling system has a job to print, it + will open the specified device on behalf of the filter program + (which is responsible for passing data to the printer). + + List the /dev entry pathname in the + /etc/printcap file using the + lp capability. + + In our running example, let us assume that + rattan is on the first parallel port, and + bamboo is on a sixth serial port; here are + the additions to /etc/printcap: + + # +# /etc/printcap for host rose - identified what devices to use +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan:\ + :lp=/dev/lpt0: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:\ + :lp=/dev/ttyd5: + + If you do not specify the lp capability + for a printer in your /etc/printcap file, + LPD uses /dev/lp + as a default. + /dev/lp currently does not exist in + FreeBSD. + + If the printer you are installing is connected to a + parallel port, skip to the section entitled, Installing the Text + Filter. Otherwise, be sure to follow the instructions + in the next section. + + + + Configuring Spooler Communication Parameters + + printers + serial + + + For printers on serial ports, LPD + can set up the bps rate, + parity, and other serial communication parameters on behalf of + the filter program that sends data to the printer. This is + advantageous since: + + + + It lets you try different communication parameters by + simply editing the /etc/printcap + file; you do not have to recompile the filter + program. + + + + It enables the spooling system to use the same filter + program for multiple printers which may have different + serial communication settings. + + + + The following /etc/printcap + capabilities control serial communication parameters of the + device listed in the lp capability: + + + + br#bps-rate + + + Sets the communications speed of the device to + bps-rate, where + bps-rate can be 50, 75, 110, + 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, + 19200, 38400, 57600, or 115200 bits-per-second. + + + + + ms#stty-mode + + + Sets the options for the terminal device after + opening the device. &man.stty.1; explains the + available options. + + + + + When LPD opens the device + specified by the lp capability, it sets + the characteristics of the device to those specified with + the ms# capability. Of particular + interest will be the parenb, + parodd, cs5, + cs6, cs7, + cs8, cstopb, + crtscts, and ixon + modes, which are explained in the &man.stty.1; + manual page. + + Let us add to our example printer on the sixth serial + port. We will set the bps rate to 38400. For the mode, + we will set no parity with -parenb, + 8-bit characters with cs8, + no modem control with clocal and + hardware flow control with crtscts: + + bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts: + + + + Installing the Text Filter + + printing + filters + + + We are now ready to tell LPD + what text filter to use to + send jobs to the printer. A text filter, + also known as an input filter, is a + program that LPD runs when it + has a job to print. When LPD + runs the text filter for a printer, it sets the filter's + standard input to the job to print, and its standard output to + the printer device specified with the lp + capability. The filter is expected to read the job from + standard input, perform any necessary translation for the + printer, and write the results to standard output, which will + get printed. For more information on the text filter, see + the Filters + section. + + For our simple printer setup, the text filter can be a + small shell script that just executes + /bin/cat to send the job to the printer. + FreeBSD comes with another filter called + lpf that handles backspacing and + underlining for printers that might not deal with such + character streams well. And, of course, you can use any other + filter program you want. The filter lpf is + described in detail in section entitled lpf: a Text + Filter. + + First, let us make the shell script + /usr/local/libexec/if-simple be a simple + text filter. Put the following text into that file with your + favorite text editor: + + #!/bin/sh +# +# if-simple - Simple text input filter for lpd +# Installed in /usr/local/libexec/if-simple +# +# Simply copies stdin to stdout. Ignores all filter arguments. + +/bin/cat && exit 0 +exit 2 + + Make the file executable: + + &prompt.root; chmod 555 /usr/local/libexec/if-simple + + And then tell LPD to use it by specifying it with the + if capability in + /etc/printcap. We will add it to the two + printers we have so far in the example + /etc/printcap: + + # +# /etc/printcap for host rose - added text filter +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ + :if=/usr/local/libexec/if-simple: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:\ + :if=/usr/local/libexec/if-simple: + + + A copy of the if-simple script + can be found in the /usr/share/examples/printing + directory. + + + + + Turn on <application>LPD</application> + + &man.lpd.8; is run from /etc/rc, + controlled by the lpd_enable variable. This + variable defaults to NO. If you have not done + so already, add the line: + + lpd_enable="YES" + + to /etc/rc.conf, and then either restart + your machine, or just run &man.lpd.8;. + + &prompt.root; lpd + + + + Trying It Out + + You have reached the end of the simple + LPD setup. + Unfortunately, congratulations are not quite yet in order, + since we still have to test the setup and correct any + problems. To test the setup, try printing something. To + print with the LPD system, you + use the command &man.lpr.1;, + which submits a job for printing. + + You can combine &man.lpr.1; with the &man.lptest.1; + program, introduced in section Checking Printer + Communications to generate some test text. + + To test the simple LPD + setup: + + Type: + + &prompt.root; lptest 20 5 | lpr -Pprinter-name + + Where printer-name is a the + name of a printer (or an alias) specified in + /etc/printcap. To test the default + printer, type &man.lpr.1; without any + argument. Again, if you are testing a printer that expects + &postscript;, send a &postscript; program in that language instead + of using &man.lptest.1;. You can do so by putting the program + in a file and typing lpr + file. + + For a &postscript; printer, you should get the results of + the program. If you are using &man.lptest.1;, then your + results should look like the following: + + !"#$%&'()*+,-./01234 +"#$%&'()*+,-./012345 +#$%&'()*+,-./0123456 +$%&'()*+,-./01234567 +%&'()*+,-./012345678 + + To further test the printer, try downloading larger + programs (for language-based printers) or running + &man.lptest.1; with different arguments. For example, + lptest 80 60 will produce 60 lines of 80 + characters each. + + If the printer did not work, see the Troubleshooting + section. + + + + + + + Advanced Printer Setup + + This section describes filters for printing specially formatted + files, header pages, printing across networks, and restricting and + accounting for printer usage. + + + Filters + + printing + filters + + + Although LPD handles network protocols, + queuing, access control, + and other aspects of printing, most of the real + work happens in the filters. Filters are + programs that communicate with the printer and handle its device + dependencies and special requirements. In the simple printer setup, + we installed a plain text filter—an extremely simple one that + should work with most printers (section Installing the Text + Filter). + + However, in order to take advantage of format conversion, printer + accounting, specific printer quirks, and so on, you should understand + how filters work. It will ultimately be the filter's responsibility + to handle these aspects. And the bad news is that most of the time + you have to provide filters yourself. The good + news is that many are generally available; when they are not, they are + usually easy to write. + + Also, FreeBSD comes with one, + /usr/libexec/lpr/lpf, that works with many + printers that can print plain text. (It handles backspacing and tabs + in the file, and does accounting, but that is about all it does.) + There are also several filters and filter components in the FreeBSD + Ports Collection. + + Here is what you will find in this section: + + + + Section How Filters + Work, tries to give an overview of a filter's role in the + printing process. You should read this section to get an + understanding of what is happening under the hood + when LPD uses filters. This knowledge + could help you anticipate + and debug problems you might encounter as you install more and + more filters on each of your printers. + + + + LPD expects every printer to be + able to print plain text by + default. This presents a problem for &postscript; (or other + language-based printers) which cannot directly print plain text. + Section Accommodating + Plain Text Jobs on &postscript; Printers tells you what you + should do to overcome this problem. You should read this + section if you have a &postscript; printer. + + + + &postscript; is a popular output format for many programs. + Some people even write &postscript; code directly. Unfortunately, + &postscript; printers are expensive. Section Simulating &postscript; on + Non &postscript; Printers tells how you can further modify + a printer's text filter to accept and print &postscript; data on a + non &postscript; printer. You should read + this section if you do not have a &postscript; printer. + + + + Section Conversion + Filters tells about a way you can automate the conversion + of specific file formats, such as graphic or typesetting data, + into formats your printer can understand. After reading this + section, you should be able to set up your printers such that + users can type lpr -t to print troff data, or + lpr -d to print &tex; DVI data, or lpr + -v to print raster image data, and so forth. I + recommend reading this section. + + + + Section Output + Filters tells all about a not often used feature of + LPD: + output filters. Unless you are printing header pages (see Header Pages), + you can probably skip that section altogether. + + + + Section lpf: a Text + Filter describes lpf, a fairly + complete if simple text filter for line printers (and laser + printers that act like line printers) that comes with FreeBSD. If + you need a quick way to get printer accounting working for plain + text, or if you have a printer which emits smoke when it sees + backspace characters, you should definitely consider + lpf. + + + + + A copy of the various scripts described below can be + found in the /usr/share/examples/printing + directory. + + + + How Filters Work + + As mentioned before, a filter is an executable program started + by LPD to handle the device-dependent part of + communicating with the printer. + + When LPD wants to print a file in a + job, it starts a filter + program. It sets the filter's standard input to the file to print, + its standard output to the printer, and its standard error to the + error logging file (specified in the lf + capability in /etc/printcap, or + /dev/console by default). + + + troff + + Which filter LPD starts and the + filter's arguments depend on + what is listed in the /etc/printcap file and + what arguments the user specified for the job on the + &man.lpr.1; command line. For example, if the user typed + lpr -t, LPD would + start the troff filter, listed + in the tf capability for the destination printer. + If the user wanted to print plain text, it would start the + if filter (this is mostly true: see Output Filters for + details). + + There are three kinds of filters you can specify in + /etc/printcap: + + + + The text filter, confusingly called the + input filter in + LPD documentation, handles + regular text printing. Think of it as the default filter. + LPD + expects every printer to be able to print plain text by default, + and it is the text filter's job to make sure backspaces, tabs, + or other special characters do not confuse the printer. If you + are in an environment where you have to account for printer + usage, the text filter must also account for pages printed, + usually by counting the number of lines printed and comparing + that to the number of lines per page the printer supports. The + text filter is started with the following argument list: + + + filter-name + -c + -wwidth + -llength + -iindent + -n login + -h host + acct-file + + + where + + + + + + + appears if the job is submitted with lpr + -l + + + + + width + + + is the value from the pw (page + width) capability specified in + /etc/printcap, default 132 + + + + + length + + + is the value from the pl (page + length) capability, default 66 + + + + + indent + + + is the amount of the indentation from lpr + -i, default 0 + + + + + login + + + is the account name of the user printing the + file + + + + + host + + + is the host name from which the job was + submitted + + + + + acct-file + + + is the name of the accounting file from the + af capability. + + + + + + + + printing + filters + + + A conversion filter converts a specific + file format into one the printer can render onto paper. For + example, ditroff typesetting data cannot be directly printed, + but you can install a conversion filter for ditroff files to + convert the ditroff data into a form the printer can digest and + print. Section Conversion + Filters tells all about them. Conversion filters also + need to do accounting, if you need printer accounting. + Conversion filters are started with the following arguments: + + + filter-name + -xpixel-width + -ypixel-height + -n login + -h host + acct-file + + + where pixel-width is the value + from the px capability (default 0) and + pixel-height is the value from the + py capability (default 0). + + + + The output filter is used only if there + is no text filter, or if header pages are enabled. In my + experience, output filters are rarely used. Section Output Filters describe + them. There are only two arguments to an output filter: + + + filter-name + -wwidth + -llength + + + which are identical to the text filters and + arguments. + + + + Filters should also exit with the + following exit status: + + + + exit 0 + + + If the filter printed the file successfully. + + + + + exit 1 + + + If the filter failed to print the file but wants + LPD to + try to print the file again. LPD + will restart a filter if it exits with this status. + + + + + exit 2 + + + If the filter failed to print the file and does not want + LPD to try again. + LPD will throw out the file. + + + + + The text filter that comes with the FreeBSD release, + /usr/libexec/lpr/lpf, takes advantage of the + page width and length arguments to determine when to send a form + feed and how to account for printer usage. It uses the login, host, + and accounting file arguments to make the accounting entries. + + If you are shopping for filters, see if they are LPD-compatible. + If they are, they must support the argument lists described above. + If you plan on writing filters for general use, then have them + support the same argument lists and exit codes. + + + + Accommodating Plain Text Jobs on &postscript; Printers + print jobs + + If you are the only user of your computer and &postscript; (or + other language-based) printer, and you promise to never send plain + text to your printer and to never use features of various programs + that will want to send plain text to your printer, then you do not + need to worry about this section at all. + + But, if you would like to send both &postscript; and plain text + jobs to the printer, then you are urged to augment your printer + setup. To do so, we have the text filter detect if the arriving job + is plain text or &postscript;. All &postscript; jobs must start with + %! (for other printer languages, see your printer + documentation). If those are the first two characters in the job, + we have &postscript;, and can pass the rest of the job directly. If + those are not the first two characters in the file, then the filter + will convert the text into &postscript; and print the result. + + How do we do this? + + + printers + serial + + If you have got a serial printer, a great way to do it is to + install lprps. lprps is a + &postscript; printer filter which performs two-way communication with + the printer. It updates the printer's status file with verbose + information from the printer, so users and administrators can see + exactly what the state of the printer is (such as toner + low or paper jam). But more + importantly, it includes a program called psif + which detects whether the incoming job is plain text and calls + textps (another program that comes with + lprps) to convert it to &postscript;. It then uses + lprps to send the job to the printer. + + lprps is part of the FreeBSD Ports Collection + (see The Ports Collection). You can + fetch, build and install it yourself, of course. After installing + lprps, just specify the pathname to the + psif program that is part of + lprps. If you installed lprps + from the Ports Collection, use the following in the serial + &postscript; printer's entry in + /etc/printcap: + + :if=/usr/local/libexec/psif: + + You should also specify the rw capability; + that tells LPD to open the printer in + read-write mode. + + If you have a parallel &postscript; printer (and therefore cannot + use two-way communication with the printer, which + lprps needs), you can use the following shell + script as the text filter: + + #!/bin/sh +# +# psif - Print PostScript or plain text on a PostScript printer +# Script version; NOT the version that comes with lprps +# Installed in /usr/local/libexec/psif +# + +IFS="" read -r first_line +first_two_chars=`expr "$first_line" : '\(..\)'` + +if [ "$first_two_chars" = "%!" ]; then + # + # PostScript job, print it. + # + echo "$first_line" && cat && printf "\004" && exit 0 + exit 2 +else + # + # Plain text, convert it, then print it. + # + ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0 + exit 2 +fi + + In the above script, textps is a program we + installed separately to convert plain text to &postscript;. You can + use any text-to-&postscript; program you wish. The FreeBSD Ports + Collection (see The Ports Collection) + includes a full featured text-to-&postscript; program called + a2ps that you might want to investigate. + + + + Simulating &postscript; on Non &postscript; Printers + + PostScript + emulating + + + Ghostscript + &postscript; is the de facto standard for + high quality typesetting and printing. &postscript; is, however, an + expensive standard. Thankfully, Aladdin + Enterprises has a free &postscript; work-alike called + Ghostscript that runs with FreeBSD. + Ghostscript can read most &postscript; files and can render their + pages onto a variety of devices, including many brands of + non-PostScript printers. By installing Ghostscript and using a + special text filter for your printer, you can make your + non &postscript; printer act like a real &postscript; printer. + + Ghostscript is in the FreeBSD Ports Collection, if you + would like to install it from there. You can fetch, build, and + install it quite easily yourself, as well. + + To simulate &postscript;, we have the text filter detect if it is + printing a &postscript; file. If it is not, then the filter will pass + the file directly to the printer; otherwise, it will use Ghostscript + to first convert the file into a format the printer will + understand. + + Here is an example: the following script is a text filter + for Hewlett Packard DeskJet 500 printers. For other printers, + substitute the argument to the + gs (Ghostscript) command. (Type gs + -h to get a list of devices the current installation of + Ghostscript supports.) + + #!/bin/sh +# +# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500 +# Installed in /usr/local/libexec/ifhp + +# +# Treat LF as CR+LF (to avoid the "staircase effect" on HP/PCL +# printers): +# +printf "\033&k2G" || exit 2 + +# +# Read first two characters of the file +# +IFS="" read -r first_line +first_two_chars=`expr "$first_line" : '\(..\)'` + +if [ "$first_two_chars" = "%!" ]; then + # + # It is PostScript; use Ghostscript to scan-convert and print it. + # + /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \ + -sOutputFile=- - && exit 0 +else + # + # Plain text or HP/PCL, so just print it directly; print a form feed + # at the end to eject the last page. + # + echo "$first_line" && cat && printf "\033&l0H" && +exit 0 +fi + +exit 2 + + Finally, you need to notify LPD of + the filter via the if capability: + + :if=/usr/local/libexec/ifhp: + + That is it. You can type lpr plain.text and + lpr whatever.ps and both should print + successfully. + + + + Conversion Filters + + After completing the simple setup described in Simple Printer Setup, the first + thing you will probably want to do is install conversion filters for + your favorite file formats (besides plain ASCII text). + + + Why Install Conversion Filters? + + &tex; + printing DVI files + + + Conversion filters make printing various kinds of files easy. + As an example, suppose we do a lot of work with the &tex; + typesetting system, and we have a &postscript; printer. Every time + we generate a DVI file from &tex;, we cannot print it directly until + we convert the DVI file into &postscript;. The command sequence + goes like this: + + &prompt.user; dvips seaweed-analysis.dvi +&prompt.user; lpr seaweed-analysis.ps + + By installing a conversion filter for DVI files, we can skip + the hand conversion step each time by having + LPD do it for us. + Now, each time we get a DVI file, we are just one step away from + printing it: + + &prompt.user; lpr -d seaweed-analysis.dvi + + We got LPD to do the DVI file + conversion for us by specifying + the option. Section Formatting and Conversion + Options lists the conversion options. + + For each of the conversion options you want a printer to + support, install a conversion filter and + specify its pathname in /etc/printcap. A + conversion filter is like the text filter for the simple printer + setup (see section Installing + the Text Filter) except that instead of printing plain + text, the filter converts the file into a format the printer can + understand. + + + + Which Conversion Filters Should I Install? + + You should install the conversion filters you expect to use. + If you print a lot of DVI data, then a DVI conversion filter is in + order. If you have got plenty of troff to print out, then you + probably want a troff filter. + + The following table summarizes the filters that + LPD works + with, their capability entries for the + /etc/printcap file, and how to invoke them + with the lpr command: + + + + + + File type + /etc/printcap capability + lpr option + + + + + + cifplot + cf + + + + + DVI + df + + + + + plot + gf + + + + + ditroff + nf + + + + + FORTRAN text + rf + + + + + troff + tf + + + + + raster + vf + + + + + plain text + if + none, , or + + + + + + + In our example, using lpr -d means the + printer needs a df capability in its entry in + /etc/printcap. + + FORTRAN + Despite what others might contend, formats like FORTRAN text + and plot are probably obsolete. At your site, you can give new + meanings to these or any of the formatting options just by + installing custom filters. For example, suppose you would like to + directly print Printerleaf files (files from the Interleaf desktop + publishing program), but will never print plot files. You could + install a Printerleaf conversion filter under the + gf capability and then educate your users that + lpr -g mean print Printerleaf + files. + + + + Installing Conversion Filters + + Since conversion filters are programs you install outside of + the base FreeBSD installation, they should probably go under + /usr/local. The directory + /usr/local/libexec is a popular location, + since they are specialized programs that only + LPD will run; + regular users should not ever need to run them. + + To enable a conversion filter, specify its pathname under the + appropriate capability for the destination printer in + /etc/printcap. + + In our example, we will add the DVI conversion filter to the + entry for the printer named bamboo. Here is + the example /etc/printcap file again, with + the new df capability for the printer + bamboo. + + # +# /etc/printcap for host rose - added df filter for bamboo +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan:\ + :lp=/dev/lpt0:\ + :if=/usr/local/libexec/if-simple: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\ + :if=/usr/local/libexec/psif:\ + :df=/usr/local/libexec/psdf: + + The DVI filter is a shell script named + /usr/local/libexec/psdf. Here is that + script: + + #!/bin/sh +# +# psdf - DVI to PostScript printer filter +# Installed in /usr/local/libexec/psdf +# +# Invoked by lpd when user runs lpr -d +# +exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@" + + This script runs dvips in filter mode (the + argument) on standard input, which is the job + to print. It then starts the &postscript; printer filter + lprps (see section Accommodating Plain + Text Jobs on &postscript; Printers) with the arguments + LPD + passed to this script. lprps will use those + arguments to account for the pages printed. + + + + More Conversion Filter Examples + + Since there is no fixed set of steps to install conversion + filters, let me instead provide more examples. Use these as + guidance to making your own filters. Use them directly, if + appropriate. + + This example script is a raster (well, GIF file, actually) + conversion filter for a Hewlett Packard LaserJet III-Si + printer: + + #!/bin/sh +# +# hpvf - Convert GIF files into HP/PCL, then print +# Installed in /usr/local/libexec/hpvf + +PATH=/usr/X11R6/bin:$PATH; export PATH +giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ + && exit 0 \ + || exit 2 + + It works by converting the GIF file into a portable anymap, + converting that into a portable graymap, converting that into a + portable bitmap, and converting that into LaserJet/PCL-compatible + data. + + Here is the /etc/printcap file with an + entry for a printer using the above filter: + + # +# /etc/printcap for host orchid +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ + :if=/usr/local/libexec/hpif:\ + :vf=/usr/local/libexec/hpvf: + + The following script is a conversion filter for troff data + from the groff typesetting system for the &postscript; printer named + bamboo: + + #!/bin/sh +# +# pstf - Convert groff's troff data into PS, then print. +# Installed in /usr/local/libexec/pstf +# +exec grops | /usr/local/libexec/lprps "$@" + + The above script makes use of lprps again + to handle the communication with the printer. If the printer were + on a parallel port, we would use this script instead: + + #!/bin/sh +# +# pstf - Convert groff's troff data into PS, then print. +# Installed in /usr/local/libexec/pstf +# +exec grops + + That is it. Here is the entry we need to add to + /etc/printcap to enable the filter: + + :tf=/usr/local/libexec/pstf: + + Here is an example that might make old hands at FORTRAN blush. + It is a FORTRAN-text filter for any printer that can directly + print plain text. We will install it for the printer + teak: + + #!/bin/sh +# +# hprf - FORTRAN text filter for LaserJet 3si: +# Installed in /usr/local/libexec/hprf +# + +printf "\033&k2G" && fpr && printf "\033&l0H" && + exit 0 +exit 2 + + And we will add this line to the + /etc/printcap for the printer + teak to enable this filter: + + :rf=/usr/local/libexec/hprf: + + Here is one final, somewhat complex example. We will add a + DVI filter to the LaserJet printer teak + introduced earlier. First, the easy part: updating + /etc/printcap with the location of the DVI + filter: + + :df=/usr/local/libexec/hpdf: + + Now, for the hard part: making the filter. For that, we need + a DVI-to-LaserJet/PCL conversion program. The FreeBSD Ports + Collection (see The Ports Collection) + has one: dvi2xx is the name of the package. + Installing this package gives us the program we need, + dvilj2p, which converts DVI into LaserJet IIp, + LaserJet III, and LaserJet 2000 compatible codes. + + dvilj2p makes the filter + hpdf quite complex since + dvilj2p cannot read from standard input. It + wants to work with a filename. What is worse, the filename has to + end in .dvi so using + /dev/fd/0 for standard input is problematic. + We can get around that problem by linking (symbolically) a + temporary file name (one that ends in .dvi) + to /dev/fd/0, thereby forcing + dvilj2p to read from standard input. + + The only other fly in the ointment is the fact that we cannot + use /tmp for the temporary link. Symbolic + links are owned by user and group bin. The + filter runs as user daemon. And the + /tmp directory has the sticky bit set. The + filter can create the link, but it will not be able clean up when + done and remove it since the link will belong to a different + user. + + Instead, the filter will make the symbolic link in the current + working directory, which is the spooling directory (specified by + the sd capability in + /etc/printcap). This is a perfect place for + filters to do their work, especially since there is (sometimes) + more free disk space in the spooling directory than under + /tmp. + + Here, finally, is the filter: + + #!/bin/sh +# +# hpdf - Print DVI data on HP/PCL printer +# Installed in /usr/local/libexec/hpdf + +PATH=/usr/local/bin:$PATH; export PATH + +# +# Define a function to clean up our temporary files. These exist +# in the current directory, which will be the spooling directory +# for the printer. +# +cleanup() { + rm -f hpdf$$.dvi +} + +# +# Define a function to handle fatal errors: print the given message +# and exit 2. Exiting with 2 tells LPD to do not try to reprint the +# job. +# +fatal() { + echo "$@" 1>&2 + cleanup + exit 2 +} + +# +# If user removes the job, LPD will send SIGINT, so trap SIGINT +# (and a few other signals) to clean up after ourselves. +# +trap cleanup 1 2 15 + +# +# Make sure we are not colliding with any existing files. +# +cleanup + +# +# Link the DVI input file to standard input (the file to print). +# +ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0" + +# +# Make LF = CR+LF +# +printf "\033&k2G" || fatal "Cannot initialize printer" + +# +# Convert and print. Return value from dvilj2p does not seem to be +# reliable, so we ignore it. +# +dvilj2p -M1 -q -e- dfhp$$.dvi + +# +# Clean up and exit +# +cleanup +exit 0 + + + + Automated Conversion: an Alternative to Conversion + Filters + + All these conversion filters accomplish a lot for your + printing environment, but at the cost forcing the user to specify + (on the &man.lpr.1; command line) which one to use. + If your users are not particularly computer literate, having to + specify a filter option will become annoying. What is worse, + though, is that an incorrectly specified filter option may run a + filter on the wrong type of file and cause your printer to spew + out hundreds of sheets of paper. + + Rather than install conversion filters at all, you might want + to try having the text filter (since it is the default filter) + detect the type of file it has been asked to print and then + automatically run the right conversion filter. Tools such as + file can be of help here. Of course, it will + be hard to determine the differences between + some file types—and, of course, you can + still provide conversion filters just for them. + + apsfilter + + printing + filters + apsfilter + + The FreeBSD Ports Collection has a text filter that performs + automatic conversion called apsfilter. It can + detect plain text, &postscript;, and DVI files, run the proper + conversions, and print. + + + + + Output Filters + + The LPD spooling system supports one + other type of filter that + we have not yet explored: an output filter. An output filter is + intended for printing plain text only, like the text filter, but + with many simplifications. If you are using an output filter but no + text filter, then: + + + + LPD starts an output filter once + for the entire job instead + of once for each file in the job. + + + + LPD does not make any provision + to identify the start or the + end of files within the job for the output filter. + + + + LPD does not pass the user's + login or host to the filter, so + it is not intended to do accounting. In fact, it gets only two + arguments: + + + filter-name + -wwidth + -llength + + + Where width is from the + pw capability and + length is from the + pl capability for the printer in + question. + + + + Do not be seduced by an output filter's simplicity. If you + would like each file in a job to start on a different page an output + filter will not work. Use a text filter (also + known as an input filter); see section Installing the Text Filter. + Furthermore, an output filter is actually more + complex in that it has to examine the byte stream being + sent to it for special flag characters and must send signals to + itself on behalf of LPD. + + However, an output filter is necessary if + you want header pages and need to send escape sequences or other + initialization strings to be able to print the header page. (But it + is also futile if you want to charge header + pages to the requesting user's account, since + LPD does not give any + user or host information to the output filter.) + + On a single printer, LPD + allows both an output filter and text or other filters. In + such cases, LPD will start the + output filter + to print the header page (see section Header Pages) + only. LPD then expects the + output filter to stop + itself by sending two bytes to the filter: ASCII 031 + followed by ASCII 001. When an output filter sees these two bytes + (031, 001), it should stop by sending SIGSTOP + to itself. When + LPD's + done running other filters, it will restart the output filter by + sending SIGCONT to it. + + If there is an output filter but no text + filter and LPD is working on a plain + text job, LPD uses the output + filter to do the job. As stated before, the output filter will + print each file of the job in sequence with no intervening form + feeds or other paper advancement, and this is probably + not what you want. In almost all cases, you + need a text filter. + + The program lpf, which we introduced earlier + as a text filter, can also run as an output filter. If you need a + quick-and-dirty output filter but do not want to write the byte + detection and signal sending code, try lpf. You + can also wrap lpf in a shell script to handle any + initialization codes the printer might require. + + + + <command>lpf</command>: a Text Filter + + The program /usr/libexec/lpr/lpf that comes + with FreeBSD binary distribution is a text filter (input filter) + that can indent output (job submitted with lpr + -i), allow literal characters to pass (job submitted + with lpr -l), adjust the printing position for + backspaces and tabs in the job, and account for pages printed. It + can also act like an output filter. + + lpf is suitable for many printing + environments. And although it has no capability to send + initialization sequences to a printer, it is easy to write a shell + script to do the needed initialization and then execute + lpf. + + page accounting + + accounting + printer + + In order for lpf to do page accounting + correctly, it needs correct values filled in for the + pw and pl capabilities in the + /etc/printcap file. It uses these values to + determine how much text can fit on a page and how many pages were in + a user's job. For more information on printer accounting, see Accounting for Printer + Usage. + + + + + Header Pages + + If you have lots of users, all of them using + various printers, then you probably want to consider header + pages as a necessary evil. + + + banner pages + header pages + + header pages + Header pages, also known as banner or + burst pages identify to whom jobs belong after + they are printed. They are usually printed in large, bold letters, + perhaps with decorative borders, so that in a stack of printouts they + stand out from the real documents that comprise users' jobs. They + enable users to locate their jobs quickly. The obvious drawback to a + header page is that it is yet one more sheet that has to be printed + for every job, their ephemeral usefulness lasting not more than a few + minutes, ultimately finding themselves in a recycling bin or rubbish + heap. (Note that header pages go with each job, not each file in a + job, so the paper waste might not be that bad.) + + The LPD system can provide header + pages automatically for your + printouts if your printer can directly print + plain text. If you have a &postscript; printer, you will need an + external program to generate the header page; see Header Pages on + &postscript; Printers. + + + Enabling Header Pages + + In the Simple Printer + Setup section, we turned off header pages by specifying + sh (meaning suppress header) in the + /etc/printcap file. To enable header pages for + a printer, just remove the sh capability. + + Sounds too easy, right? + + You are right. You might have to provide + an output filter to send initialization strings to the printer. + Here is an example output filter for Hewlett Packard PCL-compatible + printers: + + #!/bin/sh +# +# hpof - Output filter for Hewlett Packard PCL-compatible printers +# Installed in /usr/local/libexec/hpof + +printf "\033&k2G" || exit 2 +exec /usr/libexec/lpr/lpf + + Specify the path to the output filter in the + of capability. See the Output Filters section for more + information. + + Here is an example /etc/printcap file for + the printer teak that we introduced earlier; we + enabled header pages and added the above output filter: + + # +# /etc/printcap for host orchid +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ + :if=/usr/local/libexec/hpif:\ + :vf=/usr/local/libexec/hpvf:\ + :of=/usr/local/libexec/hpof: + + Now, when users print jobs to teak, they get + a header page with each job. If users want to spend time searching + for their printouts, they can suppress header pages by submitting + the job with lpr -h; see the Header Page Options section for + more &man.lpr.1; options. + + + LPD prints a form feed character + after the header page. If + your printer uses a different character or sequence of characters + to eject a page, specify them with the ff + capability in /etc/printcap. + + + + + Controlling Header Pages + + By enabling header pages, LPD will + produce a long + header, a full page of large letters identifying the + user, host, and job. Here is an example (kelly printed the job + named outline from host rose): + + k ll ll + k l l + k l l + k k eeee l l y y + k k e e l l y y + k k eeeeee l l y y + kk k e l l y y + k k e e l l y yy + k k eeee lll lll yyy y + y + y y + yyyy + + + ll + t l i + t l + oooo u u ttttt l ii n nnn eeee + o o u u t l i nn n e e + o o u u t l i n n eeeeee + o o u u t l i n n e + o o u uu t t l i n n e e + oooo uuu u tt lll iii n n eeee + + + + + + + + + + r rrr oooo ssss eeee + rr r o o s s e e + r o o ss eeeeee + r o o ss e + r o o s s e e + r oooo ssss eeee + + + + + + + + Job: outline + Date: Sun Sep 17 11:04:58 1995 + + LPD appends a form feed after this + text so the job starts on a + new page (unless you have sf (suppress form + feeds) in the destination printer's entry in + /etc/printcap). + + If you prefer, LPD can make a + short header; + specify sb (short banner) in the + /etc/printcap file. The header page will look + like this: + + rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 + + Also by default, LPD prints the + header page first, then the job. + To reverse that, specify hl (header last) in + /etc/printcap. + + + + Accounting for Header Pages + + Using LPD's built-in header pages + enforces a particular paradigm + when it comes to printer accounting: header pages must be + free of charge. + + Why? + + Because the output filter is the only external program that will + have control when the header page is printed that could do + accounting, and it is not provided with any user or + host information or an accounting file, so it has no + idea whom to charge for printer use. It is also not enough to just + add one page to the text filter or any of the + conversion filters (which do have user and host information) since + users can suppress header pages with lpr -h. + They could still be charged for header pages they did not print. + Basically, lpr -h will be the preferred option of + environmentally-minded users, but you cannot offer any incentive to + use it. + + It is still not enough to have each of the + filters generate their own header pages (thereby being able to + charge for them). If users wanted the option of suppressing the + header pages with lpr -h, they will still get + them and be charged for them since LPD + does not pass any knowledge + of the option to any of the filters. + + So, what are your options? + + You can: + + + + Accept LPD's paradigm and make + header pages free. + + + + Install an alternative to LPD, + such as + LPRng. Section + Alternatives to the + Standard Spooler tells more about other spooling + software you can substitute for LPD. + + + + + Write a smart output filter. Normally, + an output filter is not meant to do anything more than + initialize a printer or do some simple character conversion. It + is suited for header pages and plain text jobs (when there is no + text (input) filter). But, if there is a text filter for the + plain text jobs, then LPD will start + the output filter only for + the header pages. And the output filter can parse the header + page text that LPD generates to + determine what user and host to + charge for the header page. The only other problem with this + method is that the output filter still does not know what + accounting file to use (it is not passed the name of the file + from the af capability), but if you have a + well-known accounting file, you can hard-code that into the + output filter. To facilitate the parsing step, use the + sh (short header) capability in + /etc/printcap. Then again, all that might + be too much trouble, and users will certainly appreciate the + more generous system administrator who makes header pages + free. + + + + + + Header Pages on &postscript; Printers + + As described above, LPD can generate + a plain text header page + suitable for many printers. Of course, &postscript; cannot directly + print plain text, so the header page feature of + LPD is + useless—or mostly so. + + One obvious way to get header pages is to have every conversion + filter and the text filter generate the header page. The filters + should use the user and host arguments to generate a suitable + header page. The drawback of this method is that users will always + get a header page, even if they submit jobs with lpr + -h. + + Let us explore this method. The following script takes three + arguments (user login name, host name, and job name) and makes a + simple &postscript; header page: + + #!/bin/sh +# +# make-ps-header - make a PostScript header page on stdout +# Installed in /usr/local/libexec/make-ps-header +# + +# +# These are PostScript units (72 to the inch). Modify for A4 or +# whatever size paper you are using: +# +page_width=612 +page_height=792 +border=72 + +# +# Check arguments +# +if [ $# -ne 3 ]; then + echo "Usage: `basename $0` <user> <host> <job>" 1>&2 + exit 1 +fi + +# +# Save these, mostly for readability in the PostScript, below. +# +user=$1 +host=$2 +job=$3 +date=`date` + +# +# Send the PostScript code to stdout. +# +exec cat <<EOF +%!PS + +% +% Make sure we do not interfere with user's job that will follow +% +save + +% +% Make a thick, unpleasant border around the edge of the paper. +% +$border $border moveto +$page_width $border 2 mul sub 0 rlineto +0 $page_height $border 2 mul sub rlineto +currentscreen 3 -1 roll pop 100 3 1 roll setscreen +$border 2 mul $page_width sub 0 rlineto closepath +0.8 setgray 10 setlinewidth stroke 0 setgray + +% +% Display user's login name, nice and large and prominent +% +/Helvetica-Bold findfont 64 scalefont setfont +$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto +($user) show + +% +% Now show the boring particulars +% +/Helvetica findfont 14 scalefont setfont +/y 200 def +[ (Job:) (Host:) (Date:) ] { +200 y moveto show /y y 18 sub def } +forall + +/Helvetica-Bold findfont 14 scalefont setfont +/y 200 def +[ ($job) ($host) ($date) ] { + 270 y moveto show /y y 18 sub def +} forall + +% +% That is it +% +restore +showpage +EOF + + Now, each of the conversion filters and the text filter can call + this script to first generate the header page, and then print the + user's job. Here is the DVI conversion filter from earlier in this + document, modified to make a header page: + + #!/bin/sh +# +# psdf - DVI to PostScript printer filter +# Installed in /usr/local/libexec/psdf +# +# Invoked by lpd when user runs lpr -d +# + +orig_args="$@" + +fail() { + echo "$@" 1>&2 + exit 2 +} + +while getopts "x:y:n:h:" option; do + case $option in + x|y) ;; # Ignore + n) login=$OPTARG ;; + h) host=$OPTARG ;; + *) echo "LPD started `basename $0` wrong." 1>&2 + exit 2 + ;; + esac +done + +[ "$login" ] || fail "No login name" +[ "$host" ] || fail "No host name" + +( /usr/local/libexec/make-ps-header $login $host "DVI File" + /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args + + Notice how the filter has to parse the argument list in order to + determine the user and host name. The parsing for the other + conversion filters is identical. The text filter takes a slightly + different set of arguments, though (see section How Filters + Work). + + As we have mentioned before, the above scheme, though fairly + simple, disables the suppress header page option (the + option) to lpr. If users + wanted to save a tree (or a few pennies, if you charge for header + pages), they would not be able to do so, since every filter's going + to print a header page with every job. + + To allow users to shut off header pages on a per-job basis, you + will need to use the trick introduced in section Accounting for + Header Pages: write an output filter that parses the + LPD-generated header page and produces a &postscript; version. If the + user submits the job with lpr -h, then + LPD will + not generate a header page, and neither will your output filter. + Otherwise, your output filter will read the text from + LPD and send + the appropriate header page &postscript; code to the printer. + + If you have a &postscript; printer on a serial line, you can make + use of lprps, which comes with an output filter, + psof, which does the above. Note that + psof does not charge for header pages. + + + + + Networked Printing + + + printers + network + + network printing + FreeBSD supports networked printing: sending jobs to remote + printers. Networked printing generally refers to two different + things: + + + + Accessing a printer attached to a remote host. You install a + printer that has a conventional serial or parallel interface on + one host. Then, you set up LPD to + enable access to the printer + from other hosts on the network. Section Printers Installed on + Remote Hosts tells how to do this. + + + + Accessing a printer attached directly to a network. The + printer has a network interface in addition (or in place of) a + more conventional serial or parallel interface. Such a printer + might work as follows: + + + + It might understand the LPD + protocol and can even queue + jobs from remote hosts. In this case, it acts just like a + regular host running LPD. Follow + the same procedure in + section Printers + Installed on Remote Hosts to set up such a + printer. + + + + It might support a data stream network connection. In this + case, you attach the printer to one host on the + network by making that host responsible for spooling jobs and + sending them to the printer. Section Printers with + Networked Data Stream Interfaces gives some + suggestions on installing such printers. + + + + + + + Printers Installed on Remote Hosts + + The LPD spooling system has built-in + support for sending jobs to + other hosts also running LPD (or are + compatible with LPD). This + feature enables you to install a printer on one host and make it + accessible from other hosts. It also works with printers that have + network interfaces that understand the + LPD protocol. + + To enable this kind of remote printing, first install a printer + on one host, the printer host, using the simple + printer setup described in the Simple + Printer Setup section. Do any advanced setup in Advanced Printer Setup that you + need. Make sure to test the printer and see if it works with the + features of LPD you have enabled. + Also ensure that the + local host has authorization to use the + LPD + service in the remote host (see Restricting Jobs + from Remote Printers). + + + printers + network + + network printing + If you are using a printer with a network interface that is + compatible with LPD, then the + printer host in + the discussion below is the printer itself, and the + printer name is the name you configured for the + printer. See the documentation that accompanied your printer and/or + printer-network interface. + + + If you are using a Hewlett Packard Laserjet then the printer + name text will automatically perform the LF to + CRLF conversion for you, so you will not require the + hpif script. + + + Then, on the other hosts you want to have access to the printer, + make an entry in their /etc/printcap files with + the following: + + + + Name the entry anything you want. For simplicity, though, + you probably want to use the same name and aliases as on the + printer host. + + + + Leave the lp capability blank, explicitly + (:lp=:). + + + + Make a spooling directory and specify its location in the + sd capability. LPD + will store jobs here + before they get sent to the printer host. + + + + Place the name of the printer host in the + rm capability. + + + + Place the printer name on the printer + host in the rp + capability. + + + + That is it. You do not need to list conversion filters, page + dimensions, or anything else in the + /etc/printcap file. + + Here is an example. The host rose has two + printers, bamboo and rattan. + We will enable users on the host orchid to print + to those printers. + Here is the /etc/printcap file for + orchid (back from section Enabling Header + Pages). It already had the entry for the printer + teak; we have added entries for the two printers + on the host rose: + + # +# /etc/printcap for host orchid - added (remote) printers on rose +# + +# +# teak is local; it is connected directly to orchid: +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ + :if=/usr/local/libexec/ifhp:\ + :vf=/usr/local/libexec/vfhp:\ + :of=/usr/local/libexec/ofhp: + +# +# rattan is connected to rose; send jobs for rattan to rose: +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: + +# +# bamboo is connected to rose as well: +# +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo: + + Then, we just need to make spooling directories on + orchid: + + &prompt.root; mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo +&prompt.root; chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo +&prompt.root; chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo + + Now, users on orchid can print to + rattan and bamboo. If, for + example, a user on orchid typed + + &prompt.user; lpr -P bamboo -d sushi-review.dvi + + the LPD system on orchid + would copy the job to the spooling + directory /var/spool/lpd/bamboo and note that it was a + DVI job. As soon as the host rose has room in its + bamboo spooling directory, the two + LPDs would transfer the + file to rose. The file would wait in rose's + queue until it was finally printed. It would be converted from DVI to + &postscript; (since bamboo is a &postscript; printer) on + rose. + + + + Printers with Networked Data Stream Interfaces + + Often, when you buy a network interface card for a printer, you + can get two versions: one which emulates a spooler (the more + expensive version), or one which just lets you send data to it as if + you were using a serial or parallel port (the cheaper version). + This section tells how to use the cheaper version. For the more + expensive one, see the previous section Printers Installed on + Remote Hosts. + + The format of the /etc/printcap file lets + you specify what serial or parallel interface to use, and (if you + are using a serial interface), what baud rate, whether to use flow + control, delays for tabs, conversion of newlines, and more. But + there is no way to specify a connection to a printer that is + listening on a TCP/IP or other network port. + + To send data to a networked printer, you need to develop a + communications program that can be called by the text and conversion + filters. Here is one such example: the script + netprint takes all data on standard input and + sends it to a network-attached printer. We specify the hostname of + the printer as the first argument and the port number to which to + connect as the second argument to netprint. Note + that this supports one-way communication only (FreeBSD to printer); + many network printers support two-way communication, and you might + want to take advantage of that (to get printer status, perform + accounting, etc.). + + #!/usr/bin/perl +# +# netprint - Text filter for printer attached to network +# Installed in /usr/local/libexec/netprint +# +$#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>"; + +$printer_host = $ARGV[0]; +$printer_port = $ARGV[1]; + +require 'sys/socket.ph'; + +($ignore, $ignore, $protocol) = getprotobyname('tcp'); +($ignore, $ignore, $ignore, $ignore, $address) + = gethostbyname($printer_host); + +$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address); + +socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol) + || die "Can't create TCP/IP stream socket: $!"; +connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!"; +while (<STDIN>) { print PRINTER; } +exit 0; + + We can then use this script in various filters. Suppose we had + a Diablo 750-N line printer connected to the network. The printer + accepts data to print on port number 5100. The host name of the + printer is scrivener. Here is the text filter for the + printer: + + #!/bin/sh +# +# diablo-if-net - Text filter for Diablo printer `scrivener' listening +# on port 5100. Installed in /usr/local/libexec/diablo-if-net +# +exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100 + + + + + Restricting Printer Usage + + + printers + restricting access to + + This section gives information on restricting printer usage. The + LPD system lets you control who can access + a printer, both locally or + remotely, whether they can print multiple copies, how large their jobs + can be, and how large the printer queues can get. + + + Restricting Multiple Copies + + The LPD system makes it easy for + users to print multiple copies + of a file. Users can print jobs with lpr -#5 + (for example) and get five copies of each file in the job. Whether + this is a good thing is up to you. + + If you feel multiple copies cause unnecessary wear and tear on + your printers, you can disable the option to + &man.lpr.1; by adding the sc capability to the + /etc/printcap file. When users submit jobs + with the option, they will see: + + lpr: multiple copies are not allowed + + + Note that if you have set up access to a printer remotely (see + section Printers + Installed on Remote Hosts), you need the + sc capability on the remote + /etc/printcap files as well, or else users will + still be able to submit multiple-copy jobs by using another + host. + + Here is an example. This is the + /etc/printcap file for the host + rose. The printer rattan is + quite hearty, so we will allow multiple copies, but the laser + printer bamboo is a bit more delicate, so we will + disable multiple copies by adding the sc + capability: + + # +# /etc/printcap for host rose - restrict multiple copies on bamboo +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan:\ + :lp=/dev/lpt0:\ + :if=/usr/local/libexec/if-simple: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:sc:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\ + :if=/usr/local/libexec/psif:\ + :df=/usr/local/libexec/psdf: + + Now, we also need to add the sc capability on + the host orchid's + /etc/printcap (and while we are at it, let us + disable multiple copies for the printer + teak): + + # +# /etc/printcap for host orchid - no multiple copies for local +# printer teak or remote printer bamboo +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\ + :if=/usr/local/libexec/ifhp:\ + :vf=/usr/local/libexec/vfhp:\ + :of=/usr/local/libexec/ofhp: + +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc: + + By using the sc capability, we prevent the + use of lpr -#, but that still does not prevent + users from running &man.lpr.1; + multiple times, or from submitting the same file multiple times in + one job like this: + + &prompt.user; lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign + + There are many ways to prevent this abuse (including ignoring + it) which you are free to explore. + + + + Restricting Access to Printers + + You can control who can print to what printers by using the &unix; + group mechanism and the rg capability in + /etc/printcap. Just place the users you want + to have access to a printer in a certain group, and then name that + group in the rg capability. + + Users outside the group (including root) + will be greeted with + + lpr: Not a member of the restricted group + + if they try to print to the controlled printer. + + As with the sc (suppress multiple copies) + capability, you need to specify rg on remote + hosts that also have access to your printers, if you feel it is + appropriate (see section Printers Installed on + Remote Hosts). + + For example, we will let anyone access the printer + rattan, but only those in group + artists can use bamboo. Here + is the familiar /etc/printcap for host + rose: + + # +# /etc/printcap for host rose - restricted group for bamboo +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan:\ + :lp=/dev/lpt0:\ + :if=/usr/local/libexec/if-simple: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\ + :if=/usr/local/libexec/psif:\ + :df=/usr/local/libexec/psdf: + + Let us leave the other example + /etc/printcap file (for the host + orchid) alone. Of course, anyone on + orchid can print to bamboo. It + might be the case that we only allow certain logins on + orchid anyway, and want them to have access to the + printer. Or not. + + + There can be only one restricted group per printer. + + + + + Controlling Sizes of Jobs Submitted + + print jobs + If you have many users accessing the printers, you probably need + to put an upper limit on the sizes of the files users can submit to + print. After all, there is only so much free space on the + filesystem that houses the spooling directories, and you also need + to make sure there is room for the jobs of other users. + + + print jobs + controlling + + LPD enables you to limit the maximum + byte size a file in a job + can be with the mx capability. The units are in + BUFSIZ blocks, which are 1024 bytes. If you put + a zero for this + capability, there will be no limit on file size; however, if no + mx capability is specified, then a default limit + of 1000 blocks will be used. + + + The limit applies to files in a job, and + not the total job size. + + + LPD will not refuse a file that is + larger than the limit you + place on a printer. Instead, it will queue as much of the file up + to the limit, which will then get printed. The rest will be + discarded. Whether this is correct behavior is up for + debate. + + Let us add limits to our example printers + rattan and bamboo. Since + those artists' &postscript; files tend to be large, we will limit them + to five megabytes. We will put no limit on the plain text line + printer: + + # +# /etc/printcap for host rose +# + +# +# No limit on job size: +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:mx#0:sd=/var/spool/lpd/rattan:\ + :lp=/dev/lpt0:\ + :if=/usr/local/libexec/if-simple: + +# +# Limit of five megabytes: +# +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:\ + :if=/usr/local/libexec/psif:\ + :df=/usr/local/libexec/psdf: + + Again, the limits apply to the local users only. If you have + set up access to your printers remotely, remote users will not get + those limits. You will need to specify the mx + capability in the remote /etc/printcap files as + well. See section Printers Installed on + Remote Hosts for more information on remote + printing. + + There is another specialized way to limit job sizes from remote + printers; see section Restricting Jobs + from Remote Printers. + + + + Restricting Jobs from Remote Printers + + The LPD spooling system provides + several ways to restrict print + jobs submitted from remote hosts: + + + + Host restrictions + + + You can control from which remote hosts a local + LPD accepts requests with the files + /etc/hosts.equiv and + /etc/hosts.lpd. + LPD checks to see if an + incoming request is from a host listed in either one of these + files. If not, LPD refuses the + request. + + The format of these files is simple: one host name per + line. Note that the file + /etc/hosts.equiv is also used by the + &man.ruserok.3; protocol, and affects programs like + &man.rsh.1; and &man.rcp.1;, so be careful. + + For example, here is the + /etc/hosts.lpd file on the host + rose: + + orchid +violet +madrigal.fishbaum.de + + This means rose will accept requests from + the hosts orchid, violet, + and madrigal.fishbaum.de. If any + other host tries to access rose's + LPD, the job will be refused. + + + + + Size restrictions + + + You can control how much free space there needs to remain + on the filesystem where a spooling directory resides. Make a + file called minfree in the spooling + directory for the local printer. Insert in that file a number + representing how many disk blocks (512 bytes) of free space + there has to be for a remote job to be accepted. + + This lets you insure that remote users will not fill your + filesystem. You can also use it to give a certain priority to + local users: they will be able to queue jobs long after the + free disk space has fallen below the amount specified in the + minfree file. + + For example, let us add a minfree + file for the printer bamboo. We examine + /etc/printcap to find the spooling + directory for this printer; here is bamboo's + entry: + + bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ + :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\ + :if=/usr/local/libexec/psif:\ + :df=/usr/local/libexec/psdf: + + The spooling directory is given in the sd + capability. We will make three megabytes (which is 6144 disk blocks) + the amount of free disk space that must exist on the filesystem for + LPD to accept remote jobs: + + &prompt.root; echo 6144 > /var/spool/lpd/bamboo/minfree + + + + + + User restrictions + + + You can control which remote users can print to local + printers by specifying the rs capability in + /etc/printcap. When + rs appears in the entry for a + locally-attached printer, LPD will + accept jobs from remote + hosts if the user submitting the job also + has an account of the same login name on the local host. + Otherwise, LPD refuses the job. + + This capability is particularly useful in an environment + where there are (for example) different departments sharing a + network, and some users transcend departmental boundaries. By + giving them accounts on your systems, they can use your + printers from their own departmental systems. If you would + rather allow them to use only your + printers and not your computer resources, you can give them + token accounts, with no home directory and a + useless shell like /usr/bin/false. + + + + + + + + Accounting for Printer Usage + + + accounting + printer + + So, you need to charge for printouts. And why not? Paper and ink + cost money. And then there are maintenance costs—printers are + loaded with moving parts and tend to break down. You have examined + your printers, usage patterns, and maintenance fees and have come up + with a per-page (or per-foot, per-meter, or per-whatever) cost. Now, + how do you actually start accounting for printouts? + + Well, the bad news is the LPD spooling + system does not provide + much help in this department. Accounting is highly dependent on the + kind of printer in use, the formats being printed, and + your requirements in charging for printer + usage. + + To implement accounting, you have to modify a printer's text + filter (to charge for plain text jobs) and the conversion filters (to + charge for other file formats), to count pages or query the printer + for pages printed. You cannot get away with using the simple output + filter, since it cannot do accounting. See section Filters. + + Generally, there are two ways to do accounting: + + + + Periodic accounting is the more common + way, possibly because it is easier. Whenever someone prints a + job, the filter logs the user, host, and number of pages to an + accounting file. Every month, semester, year, or whatever time + period you prefer, you collect the accounting files for the + various printers, tally up the pages printed by users, and charge + for usage. Then you truncate all the logging files, starting with + a clean slate for the next period. + + + + Timely accounting is less common, + probably because it is more difficult. This method has the + filters charge users for printouts as soon as they use the + printers. Like disk quotas, the accounting is immediate. You can + prevent users from printing when their account goes in the red, + and might provide a way for users to check and adjust their + print quotas. But this method requires some database + code to track users and their quotas. + + + + The LPD spooling system supports both + methods easily: since you + have to provide the filters (well, most of the time), you also have to + provide the accounting code. But there is a bright side: you have + enormous flexibility in your accounting methods. For example, you + choose whether to use periodic or timely accounting. You choose what + information to log: user names, host names, job types, pages printed, + square footage of paper used, how long the job took to print, and so + forth. And you do so by modifying the filters to save this + information. + + + Quick and Dirty Printer Accounting + + FreeBSD comes with two programs that can get you set up with + simple periodic accounting right away. They are the text filter + lpf, described in section lpf: a Text Filter, and + &man.pac.8;, a program to gather and total + entries from printer accounting files. + + As mentioned in the section on filters (Filters), + LPD starts + the text and the conversion filters with the name of the accounting + file to use on the filter command line. The filters can use this + argument to know where to write an accounting file entry. The name + of this file comes from the af capability in + /etc/printcap, and if not specified as an + absolute path, is relative to the spooling directory. + + LPD starts lpf + with page width and length + arguments (from the pw and pl + capabilities). lpf uses these arguments to + determine how much paper will be used. After sending the file to + the printer, it then writes an accounting entry in the accounting + file. The entries look like this: + + 2.00 rose:andy +3.00 rose:kelly +3.00 orchid:mary +5.00 orchid:mary +2.00 orchid:zhang + + You should use a separate accounting file for each printer, as + lpf has no file locking logic built into it, and + two lpfs might corrupt each other's entries if + they were to write to the same file at the same time. An easy way + to insure a separate accounting file for each printer is to use + af=acct in /etc/printcap. + Then, each accounting file will be in the spooling directory for a + printer, in a file named acct. + + When you are ready to charge users for printouts, run the + &man.pac.8; program. Just change to the spooling directory for + the printer you want to collect on and type pac. + You will get a dollar-centric summary like the following: + + Login pages/feet runs price +orchid:kelly 5.00 1 $ 0.10 +orchid:mary 31.00 3 $ 0.62 +orchid:zhang 9.00 1 $ 0.18 +rose:andy 2.00 1 $ 0.04 +rose:kelly 177.00 104 $ 3.54 +rose:mary 87.00 32 $ 1.74 +rose:root 26.00 12 $ 0.52 + +total 337.00 154 $ 6.74 + + These are the arguments &man.pac.8; expects: + + + + + + + Which printer to summarize. + This option works only if there is an absolute path in the + af capability in + /etc/printcap. + + + + + + + + Sort the output by cost instead of alphabetically by user + name. + + + + + + + + Ignore host name in the accounting files. With this + option, user smith on host + alpha is the same user + smith on host gamma. + Without, they are different users. + + + + + + + + Compute charges with price + dollars per page or per foot instead of the price from the + pc capability in + /etc/printcap, or two cents (the + default). You can specify price as + a floating point number. + + + + + + + + Reverse the sort order. + + + + + + + + Make an accounting summary file and truncate the + accounting file. + + + + + name + … + + + Print accounting information for the given user + names only. + + + + + In the default summary that &man.pac.8; produces, you see the + number of pages printed by each user from various hosts. If, at + your site, host does not matter (because users can use any host), + run pac -m, to produce the following + summary: + + Login pages/feet runs price +andy 2.00 1 $ 0.04 +kelly 182.00 105 $ 3.64 +mary 118.00 35 $ 2.36 +root 26.00 12 $ 0.52 +zhang 9.00 1 $ 0.18 + +total 337.00 154 $ 6.74 + + + To compute the dollar amount due, + &man.pac.8; uses the pc capability in the + /etc/printcap file (default of 200, or 2 cents + per page). Specify, in hundredths of cents, the price per page or + per foot you want to charge for printouts in this capability. You + can override this value when you run &man.pac.8; with the + option. The units for the + option are in dollars, though, not hundredths of cents. For + example, + + &prompt.root; pac -p1.50 + + makes each page cost one dollar and fifty cents. You can really + rake in the profits by using this option. + + Finally, running pac -s will save the summary + information in a summary accounting file, which is named the same as + the printer's accounting file, but with _sum + appended to the name. It then truncates the accounting file. When + you run &man.pac.8; again, it rereads the + summary file to get starting totals, then adds information from the + regular accounting file. + + + + How Can You Count Pages Printed? + + In order to perform even remotely accurate accounting, you need + to be able to determine how much paper a job uses. This is the + essential problem of printer accounting. + + For plain text jobs, the problem is not that hard to solve: you + count how many lines are in a job and compare it to how many lines + per page your printer supports. Do not forget to take into account + backspaces in the file which overprint lines, or long logical lines + that wrap onto one or more additional physical lines. + + The text filter lpf (introduced in lpf: a Text Filter) takes + into account these things when it does accounting. If you are + writing a text filter which needs to do accounting, you might want + to examine lpf's source code. + + How do you handle other file formats, though? + + Well, for DVI-to-LaserJet or DVI-to-&postscript; conversion, you + can have your filter parse the diagnostic output of + dvilj or dvips and look to see + how many pages were converted. You might be able to do similar + things with other file formats and conversion programs. + + But these methods suffer from the fact that the printer may not + actually print all those pages. For example, it could jam, run out + of toner, or explode—and the user would still get + charged. + + So, what can you do? + + There is only one sure way to do + accurate accounting. Get a printer that can + tell you how much paper it uses, and attach it via a serial line or + a network connection. Nearly all &postscript; printers support this + notion. Other makes and models do as well (networked Imagen laser + printers, for example). Modify the filters for these printers to + get the page usage after they print each job and have them log + accounting information based on that value + only. There is no line counting nor + error-prone file examination required. + + Of course, you can always be generous and make all printouts + free. + + + + + + Using Printers + + + printers + usage + + This section tells you how to use printers you have set up with + FreeBSD. Here is an overview of the user-level commands: + + + + &man.lpr.1; + + + Print jobs + + + + + &man.lpq.1; + + + Check printer queues + + + + + &man.lprm.1; + + + Remove jobs from a printer's queue + + + + + There is also an administrative command, &man.lpc.8;, + described in the section Administering Printers, used to + control printers and their queues. + + All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1; + accept an option to specify on which + printer/queue to operate, as listed in the + /etc/printcap file. This enables you to submit, + remove, and check on jobs for various printers. If you do not use the + option, then these commands use the printer + specified in the PRINTER environment variable. Finally, + if you do not have a PRINTER environment variable, these + commands default to the printer named lp. + + Hereafter, the terminology default printer + means the printer named in the PRINTER environment + variable, or the printer named lp when there is no + PRINTER environment variable. + + + Printing Jobs + + To print files, type: + + &prompt.user; lpr filename ... + + printing + This prints each of the listed files to the default printer. If + you list no files, &man.lpr.1; reads data to + print from standard input. For example, this command prints some + important system files: + + &prompt.user; lpr /etc/host.conf /etc/hosts.equiv + + To select a specific printer, type: + + &prompt.user; lpr -P printer-name filename ... + + This example prints a long listing of the current directory to the + printer named rattan: + + &prompt.user; ls -l | lpr -P rattan + + Because no files were listed for the + &man.lpr.1; command, lpr read the data to print + from standard input, which was the output of the ls + -l command. + + The &man.lpr.1; command can also accept a wide variety of options + to control formatting, apply file conversions, generate multiple + copies, and so forth. For more information, see the section Printing Options. + + + + Checking Jobs + + print jobs + When you print with &man.lpr.1;, the data you wish to print is put + together in a package called a print job, which is sent + to the LPD spooling system. Each printer + has a queue of jobs, and + your job waits in that queue along with other jobs from yourself and + from other users. The printer prints those jobs in a first-come, + first-served order. + + To display the queue for the default printer, type &man.lpq.1;. + For a specific printer, use the option. For + example, the command + + &prompt.user; lpq -P bamboo + + shows the queue for the printer named bamboo. Here + is an example of the output of the lpq + command: + + bamboo is ready and printing +Rank Owner Job Files Total Size +active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes +2nd kelly 10 (standard input) 1635 bytes +3rd mary 11 ... 78519 bytes + + This shows three jobs in the queue for bamboo. + The first job, submitted by user kelly, got assigned job + number 9. Every job for a printer gets a unique job number. + Most of the time you can ignore the job number, but you will need it + if you want to cancel the job; see section Removing Jobs for details. + + Job number nine consists of two files; multiple files given on the + &man.lpr.1; command line are treated as part of a single job. It + is the currently active job (note the word active + under the Rank column), which means the printer should + be currently printing that job. The second job consists of data + passed as the standard input to the &man.lpr.1; command. The third + job came from user mary; it is a much larger + job. The pathname of the file she is trying to print is too long to + fit, so the &man.lpq.1; command just shows three dots. + + The very first line of the output from &man.lpq.1; is also useful: + it tells what the printer is currently doing (or at least what + LPD thinks the printer is doing). + + The &man.lpq.1; command also support a option + to generate a detailed long listing. Here is an example of + lpq -l: + + waiting for bamboo to become ready (offline ?) +kelly: 1st [job 009rose] + /etc/host.conf 73 bytes + /etc/hosts.equiv 15 bytes + +kelly: 2nd [job 010rose] + (standard input) 1635 bytes + +mary: 3rd [job 011rose] + /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes + + + + Removing Jobs + + If you change your mind about printing a job, you can remove the + job from the queue with the &man.lprm.1; command. Often, you can + even use &man.lprm.1; to remove an active job, but some or all of the + job might still get printed. + + To remove a job from the default printer, first use + &man.lpq.1; to find the job number. Then type: + + &prompt.user; lprm job-number + + To remove the job from a specific printer, add the + option. The following command removes job number + 10 from the queue for the printer bamboo: + + &prompt.user; lprm -P bamboo 10 + + The &man.lprm.1; command has a few shortcuts: + + + + lprm - + + + Removes all jobs (for the default printer) belonging to + you. + + + + + lprm user + + + Removes all jobs (for the default printer) belonging to + user. The superuser can remove other + users' jobs; you can remove only your own jobs. + + + + + lprm + + + With no job number, user name, or + appearing on the command line, + &man.lprm.1; removes the currently active job on the + default printer, if it belongs to you. The superuser can remove + any active job. + + + + + Just use the option with the above shortcuts + to operate on a specific printer instead of the default. For example, + the following command removes all jobs for the current user in the + queue for the printer named rattan: + + &prompt.user; lprm -P rattan - + + + If you are working in a networked environment, &man.lprm.1; will + let you remove jobs only from the + host from which the jobs were submitted, even if the same printer is + available from other hosts. The following command sequence + demonstrates this: + + &prompt.user; lpr -P rattan myfile +&prompt.user; rlogin orchid +&prompt.user; lpq -P rattan +Rank Owner Job Files Total Size +active seeyan 12 ... 49123 bytes +2nd kelly 13 myfile 12 bytes +&prompt.user; lprm -P rattan 13 +rose: Permission denied +&prompt.user; logout +&prompt.user; lprm -P rattan 13 +dfA013rose dequeued +cfA013rose dequeued + + + + + + Beyond Plain Text: Printing Options + + The &man.lpr.1; command supports a number of options that control + formatting text, converting graphic and other file formats, producing + multiple copies, handling of the job, and more. This section + describes the options. + + + Formatting and Conversion Options + + The following &man.lpr.1; options control formatting of the + files in the job. Use these options if the job does not contain + plain text or if you want plain text formatted through the + &man.pr.1; utility. + + &tex; + For example, the following command prints a DVI file (from the + &tex; typesetting system) named fish-report.dvi + to the printer named bamboo: + + &prompt.user; lpr -P bamboo -d fish-report.dvi + + These options apply to every file in the job, so you cannot mix + (say) DVI and ditroff files together in a job. Instead, submit the + files as separate jobs, using a different conversion option for each + job. + + + All of these options except and + require conversion filters installed for the + destination printer. For example, the option + requires the DVI conversion filter. Section Conversion + Filters gives details. + + + + + + + + Print cifplot files. + + + + + + + + Print DVI files. + + + + + + + + Print FORTRAN text files. + + + + + + + + Print plot data. + + + + + + + + Indent the output by number + columns; if you omit number, indent + by 8 columns. This option works only with certain conversion + filters. + + + Do not put any space between the and + the number. + + + + + + + + + Print literal text data, including control + characters. + + + + + + + + Print ditroff (device independent troff) data. + + + + + -p + + + Format plain text with &man.pr.1; before printing. See + &man.pr.1; for more information. + + + + + + + + Use title on the + &man.pr.1; header instead of the file name. This option has + effect only when used with the + option. + + + + + + + + Print troff data. + + + + + + + + Print raster data. + + + + + Here is an example: this command prints a nicely formatted + version of the &man.ls.1; manual page on the default printer: + + &prompt.user; zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t + + The &man.zcat.1; command uncompresses the source of the + &man.ls.1; manual page and passes it to the &man.troff.1; + command, which formats that source and makes GNU troff + output and passes it to &man.lpr.1;, which submits the job + to the LPD spooler. Because we + used the + option to &man.lpr.1;, the spooler will convert the GNU + troff output into a format the default printer can + understand when it prints the job. + + + + Job Handling Options + + The following options to &man.lpr.1; tell + LPD to handle the job + specially: + + + + -# copies + + + Produce a number of copies of + each file in the job instead of just one copy. An + administrator may disable this option to reduce printer + wear-and-tear and encourage photocopier usage. See section + Restricting + Multiple Copies. + + This example prints three copies of + parser.c followed by three copies of + parser.h to the default printer: + + &prompt.user; lpr -#3 parser.c parser.h + + + + + -m + + + Send mail after completing the print job. With this + option, the LPD system will send + mail to your account when it + finishes handling your job. In its message, it will tell you + if the job completed successfully or if there was an error, + and (often) what the error was. + + + + + -s + + + Do not copy the files to the spooling directory, but make + symbolic links to them instead. + + If you are printing a large job, you probably want to use + this option. It saves space in the spooling directory (your + job might overflow the free space on the filesystem where the + spooling directory resides). It saves time as well since + LPD + will not have to copy each and every byte of your job to the + spooling directory. + + There is a drawback, though: since + LPD will refer to the + original files directly, you cannot modify or remove them + until they have been printed. + + + If you are printing to a remote printer, + LPD will + eventually have to copy files from the local host to the + remote host, so the option will save + space only on the local spooling directory, not the remote. + It is still useful, though. + + + + + + -r + + + Remove the files in the job after copying them to the + spooling directory, or after printing them with the + option. Be careful with this + option! + + + + + + + Header Page Options + + These options to &man.lpr.1; adjust the text that normally + appears on a job's header page. If header pages are suppressed for + the destination printer, these options have no effect. See section + Header Pages + for information about setting up header pages. + + + + -C text + + + Replace the hostname on the header page with + text. The hostname is normally the + name of the host from which the job was submitted. + + + + + -J text + + + Replace the job name on the header page with + text. The job name is normally the + name of the first file of the job, or + stdin if you are printing standard + input. + + + + + -h + + + Do not print any header page. + + + At some sites, this option may have no effect due to the + way header pages are generated. See Header + Pages for details. + + + + + + + + + Administering Printers + + As an administrator for your printers, you have had to install, + set up, and test them. Using the &man.lpc.8; command, you + can interact with your printers in yet more ways. With &man.lpc.8;, + you can + + + + Start and stop the printers + + + + Enable and disable their queues + + + + Rearrange the order of the jobs in each queue. + + + + First, a note about terminology: if a printer is + stopped, it will not print anything in its queue. + Users can still submit jobs, which will wait in the queue until the + printer is started or the queue is + cleared. + + If a queue is disabled, no user (except + root) can submit jobs for the printer. An + enabled queue allows jobs to be submitted. A + printer can be started for a disabled queue, in + which case it will continue to print jobs in the queue until the queue + is empty. + + In general, you have to have root privileges + to use the &man.lpc.8; command. Ordinary users can use the &man.lpc.8; + command to get printer status and to restart a hung printer only. + + Here is a summary of the &man.lpc.8; commands. Most of the + commands take a printer-name argument to + tell on which printer to operate. You can use all + for the printer-name to mean all printers + listed in /etc/printcap. + + + + abort + printer-name + + + Cancel the current job and stop the printer. Users can + still submit jobs if the queue is enabled. + + + + + clean + printer-name + + + Remove old files from the printer's spooling directory. + Occasionally, the files that make up a job are not properly + removed by LPD, particularly if + there have been errors during + printing or a lot of administrative activity. This command + finds files that do not belong in the spooling directory and + removes them. + + + + + disable + printer-name + + + Disable queuing of new jobs. If the printer is running, it + will continue to print any jobs remaining in the queue. The + superuser (root) can always submit jobs, + even to a disabled queue. + + This command is useful while you are testing a new printer + or filter installation: disable the queue and submit jobs as + root. Other users will not be able to submit + jobs until you complete your testing and re-enable the queue with + the enable command. + + + + + down printer-name + message + + + Take a printer down. Equivalent to + disable followed by stop. + The message appears as the printer's + status whenever a user checks the printer's queue with + &man.lpq.1; or status with lpc + status. + + + + + enable + printer-name + + + Enable the queue for a printer. Users can submit jobs but + the printer will not print anything until it is started. + + + + + help + command-name + + + Print help on the command + command-name. With no + command-name, print a summary of the + commands available. + + + + + restart + printer-name + + + Start the printer. Ordinary users can use this command if + some extraordinary circumstance hangs + LPD, but they cannot start + a printer stopped with either the stop or + down commands. The + restart command is equivalent to + abort followed by + start. + + + + + start + printer-name + + + Start the printer. The printer will print jobs in its + queue. + + + + + stop + printer-name + + + Stop the printer. The printer will finish the current job + and will not print anything else in its queue. Even though the + printer is stopped, users can still submit jobs to an enabled + queue. + + + + + topq printer-name + job-or-username + + + Rearrange the queue for + printer-name by placing the jobs with + the listed job numbers or the jobs + belonging to username at the top of + the queue. For this command, you cannot use + all as the + printer-name. + + + + + up + printer-name + + + Bring a printer up; the opposite of the + down command. Equivalent to + start followed by + enable. + + + + + &man.lpc.8; accepts the above commands on the command line. If + you do not enter any commands, &man.lpc.8; enters an interactive mode, + where you can enter commands until you type exit, + quit, or end-of-file. + + + + + Alternatives to the Standard Spooler + + If you have been reading straight through this manual, by now you + have learned just about everything there is to know about the + LPD + spooling system that comes with FreeBSD. You can probably appreciate + many of its shortcomings, which naturally leads to the question: + What other spooling systems are out there (and work with + FreeBSD)? + + + + LPRng + + LPRng + + LPRng, which purportedly means + LPR: the Next + Generation is a complete rewrite of PLP. Patrick Powell + and Justin Mason (the principal maintainer of PLP) collaborated to + make LPRng. The main site for + LPRng is . + + + + CUPS + + CUPS + + CUPS, the Common UNIX Printing + System, provides a portable printing layer for &unix;-based + operating systems. It has been developed by Easy Software + Products to promote a standard printing solution for all &unix; + vendors and users. + + CUPS uses the Internet Printing + Protocol (IPP) as the basis for managing + print jobs and queues. The Line Printer Daemon + (LPD), Server Message Block + (SMB), and AppSocket (a.k.a. JetDirect) + protocols are also supported with reduced functionality. CUPS + adds network printer browsing and PostScript Printer Description + (PPD) based printing options to support + real-world printing under &unix;. + + The main site for CUPS is . + + + + + + + Troubleshooting + + After performing the simple test with &man.lptest.1;, you might + have gotten one of the following results instead of the correct + printout: + + + + It worked, after awhile; or, it did not eject a full + sheet. + + + The printer printed the above, but it sat for awhile and + did nothing. In fact, you might have needed to press a + PRINT REMAINING or FORM FEED button on the printer to get any + results to appear. + + If this is the case, the printer was probably waiting to + see if there was any more data for your job before it printed + anything. To fix this problem, you can have the text filter + send a FORM FEED character (or whatever is necessary) to the + printer. This is usually sufficient to have the printer + immediately print any text remaining in its internal buffer. + It is also useful to make sure each print job ends on a full + sheet, so the next job does not start somewhere on the middle + of the last page of the previous job. + + The following replacement for the shell script + /usr/local/libexec/if-simple prints a + form feed after it sends the job to the printer: + + #!/bin/sh +# +# if-simple - Simple text input filter for lpd +# Installed in /usr/local/libexec/if-simple +# +# Simply copies stdin to stdout. Ignores all filter arguments. +# Writes a form feed character (\f) after printing job. + +/bin/cat && printf "\f" && exit 0 +exit 2 + + + + + It produced the staircase effect. + + + You got the following on paper: + + !"#$%&'()*+,-./01234 + "#$%&'()*+,-./012345 + #$%&'()*+,-./0123456 + + MS-DOS + OS/2 + ASCII + You have become another victim of the staircase + effect, caused by conflicting interpretations of + what characters should indicate a new line. &unix; style + operating systems use a single character: ASCII code 10, the + line feed (LF). &ms-dos;, &os2;, and others uses a pair of + characters, ASCII code 10 and ASCII code + 13 (the carriage return or CR). Many printers use the &ms-dos; + convention for representing new-lines. + + When you print with FreeBSD, your text used just the line + feed character. The printer, upon seeing a line feed + character, advanced the paper one line, but maintained the + same horizontal position on the page for the next character + to print. That is what the carriage return is for: to move + the location of the next character to print to the left edge + of the paper. + + Here is what FreeBSD wants your printer to do: + + + + + + Printer received CR + Printer prints CR + + + + Printer received LF + Printer prints CR + LF + + + + + + Here are some ways to achieve this: + + + + Use the printer's configuration switches or control + panel to alter its interpretation of these characters. + Check your printer's manual to find out how to do + this. + + + If you boot your system into other operating systems + besides FreeBSD, you may have to + reconfigure the printer to use a an + interpretation for CR and LF characters that those other + operating systems use. You might prefer one of the other + solutions, below. + + + + + Have FreeBSD's serial line driver automatically + convert LF to CR+LF. Of course, this works with printers + on serial ports only. To enable this + feature, use the ms# capability and + set the onlcr mode + in the /etc/printcap file + for the printer. + + + + Send an escape code to the + printer to have it temporarily treat LF characters + differently. Consult your printer's manual for escape + codes that your printer might support. When you find the + proper escape code, modify the text filter to send the + code first, then send the print job. + + PCL + Here is an example text filter for printers that + understand the Hewlett-Packard PCL escape codes. This + filter makes the printer treat LF characters as a LF and + CR; then it sends the job; then it sends a form feed to + eject the last page of the job. It should work with + nearly all Hewlett Packard printers. + + #!/bin/sh +# +# hpif - Simple text input filter for lpd for HP-PCL based printers +# Installed in /usr/local/libexec/hpif +# +# Simply copies stdin to stdout. Ignores all filter arguments. +# Tells printer to treat LF as CR+LF. Ejects the page when done. + +printf "\033&k2G" && cat && printf "\033&l0H" && exit 0 +exit 2 + + Here is an example /etc/printcap + from a host called orchid. It has a single printer + attached to its first parallel port, a Hewlett Packard + LaserJet 3Si named teak. It is using the + above script as its text filter: + + # +# /etc/printcap for host orchid +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ + :if=/usr/local/libexec/hpif: + + + + + + + It overprinted each line. + + + The printer never advanced a line. All of the lines of + text were printed on top of each other on one line. + + This problem is the opposite of the + staircase effect, described above, and is much rarer. + Somewhere, the LF characters that FreeBSD uses to end a line + are being treated as CR characters to return the print + location to the left edge of the paper, but not also down a + line. + + Use the printer's configuration switches or control panel + to enforce the following interpretation of LF and CR + characters: + + + + + + Printer receives + Printer prints + + + + + + CR + CR + + + + LF + CR + LF + + + + + + + + + The printer lost characters. + + + While printing, the printer did not print a few characters + in each line. The problem might have gotten worse as the + printer ran, losing more and more characters. + + The problem is that the printer cannot keep up with the + speed at which the computer sends data over a serial line + (this problem should not occur with printers on parallel + ports). There are two ways to overcome the problem: + + + + If the printer supports XON/XOFF flow control, have + FreeBSD use it by specifying the ixon mode + in the ms# capability. + + + + If the printer supports carrier flow control, specify + the crtscts mode in the + ms# capability. + Make sure the cable connecting the printer to the computer + is correctly wired for carrier flow control. + + + + + + + It printed garbage. + + + The printer printed what appeared to be random garbage, + but not the desired text. + + This is usually another symptom of incorrect + communications parameters with a serial printer. Double-check + the bps rate in the br capability, and the + parity setting in the + ms# capability; make sure the printer is + using the same settings as specified in the + /etc/printcap file. + + + + + Nothing happened. + + + If nothing happened, the problem is probably within + FreeBSD and not the hardware. Add the log file + (lf) capability to the entry for the + printer you are debugging in the + /etc/printcap file. For example, here is + the entry for rattan, with the + lf capability: + + rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=/var/spool/lpd/rattan:\ + :lp=/dev/lpt0:\ + :if=/usr/local/libexec/if-simple:\ + :lf=/var/log/rattan.log + + Then, try printing again. Check the log file (in our + example, /var/log/rattan.log) to see any + error messages that might appear. Based on the messages you + see, try to correct the problem. + + If you do not specify a lf capability, + LPD uses + /dev/console as a default. + + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/security/Makefile b/pl_PL.ISO8859-2/books/handbook/security/Makefile new file mode 100644 index 0000000000..bbf01aa7ab --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/security/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= security/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/security/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/security/chapter.sgml new file mode 100644 index 0000000000..c28bc1878c --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/security/chapter.sgml @@ -0,0 +1,4987 @@ + + + + + + + Matthew + Dillon + Much of this chapter has been taken from the + security(7) manual page by + + + + + Security + security + + + Synopsis + + This chapter will provide a basic introduction to system security + concepts, some general good rules of thumb, and some advanced topics + under &os;. A lot of the topics covered here can be applied + to system and Internet security in general as well. The Internet + is no longer a friendly place in which everyone + wants to be your kind neighbor. Securing your system is imperative + to protect your data, intellectual property, time, and much more + from the hands of hackers and the like. + + &os; provides an array of utilities and mechanisms to ensure + the integrity and security of your system and network. + + After reading this chapter, you will know: + + + + Basic system security concepts, in respect to &os;. + + + + About the various crypt mechanisms available in &os;, + such as DES and MD5. + + + + How to set up one-time password authentication. + + + + How to configure TCP Wrappers for use + with inetd. + + + + How to set up KerberosIV on &os; + releases prior to 5.0. + + + + How to set up Kerberos5 on + &os;. + + + + How to configure IPsec and create a VPN between + &os;/&windows; machines. + + + + How to configure and use OpenSSH, &os;'s SSH + implementation. + + + + What file system ACLs are and how to use them. + + + + How to use the Portaudit + utility to audit third party software packages installed + from the Ports Collection. + + + + How to utilize the &os; security advisories + publications. + + + + Have an idea of what Process Accounting is and how to + enable it on &os;. + + + + Before reading this chapter, you should: + + + + Understand basic &os; and Internet concepts. + + + + Additional security topics are covered throughout this book. + For example, Mandatory Access Control is discussed in and Internet Firewalls are discussed in . + + + + Introduction + + Security is a function that begins and ends with the system + administrator. While all BSD &unix; multi-user systems have some + inherent security, the job of building and maintaining additional + security mechanisms to keep those users honest is + probably one of the single largest undertakings of the sysadmin. + Machines are only as secure as you make them, and security concerns + are ever competing with the human necessity for convenience. &unix; + systems, in general, are capable of running a huge number of + simultaneous processes and many of these processes operate as + servers — meaning that external entities can connect and talk + to them. As yesterday's mini-computers and mainframes become + today's desktops, and as computers become networked and + internetwork, security becomes an even bigger issue. + + Security is best implemented through a layered + onion approach. In a nutshell, what you want to do is + to create as many layers of security as are convenient and then + carefully monitor the system for intrusions. You do not want to + overbuild your security or you will interfere with the detection + side, and detection is one of the single most important aspects of + any security mechanism. For example, it makes little sense to set + the schg flag (see &man.chflags.1;) on every + system binary because + while this may temporarily protect the binaries, it prevents an + attacker who has broken in from making an easily detectable change + that may result in your security mechanisms not detecting the attacker + at all. + + System security also pertains to dealing with various forms of + attack, including attacks that attempt to crash, or otherwise make a + system unusable, but do not attempt to compromise the + root account (break root). + Security concerns + can be split up into several categories: + + + + Denial of service attacks. + + + + User account compromises. + + + + Root compromise through accessible servers. + + + + Root compromise via user accounts. + + + + Backdoor creation. + + + + + DoS attacks + Denial of Service (DoS) + + + security + DoS attacks + Denial of Service (DoS) + + Denial of Service (DoS) + + A denial of service attack is an action that deprives the + machine of needed resources. Typically, DoS attacks are + brute-force mechanisms that attempt to crash or otherwise make a + machine unusable by overwhelming its servers or network stack. Some + DoS attacks try to take advantage of bugs in the networking + stack to crash a machine with a single packet. The latter can only + be fixed by applying a bug fix to the kernel. Attacks on servers + can often be fixed by properly specifying options to limit the load + the servers incur on the system under adverse conditions. + Brute-force network attacks are harder to deal with. A + spoofed-packet attack, for example, is nearly impossible to stop, + short of cutting your system off from the Internet. It may not be + able to take your machine down, but it can saturate your + Internet connection. + + + security + account compromises + + + A user account compromise is even more common than a DoS + attack. Many sysadmins still run standard + telnetd, rlogind, + rshd, + and ftpd servers on their machines. + These servers, by default, do + not operate over encrypted connections. The result is that if you + have any moderate-sized user base, one or more of your users logging + into your system from a remote location (which is the most common + and convenient way to login to a system) will have his or her + password sniffed. The attentive system admin will analyze his + remote access logs looking for suspicious source addresses even for + successful logins. + + One must always assume that once an attacker has access to a + user account, the attacker can break root. + However, the reality is that in a well secured and maintained system, + access to a user account does not necessarily give the attacker + access to root. The distinction is important + because without access to root the attacker + cannot generally hide his tracks and may, at best, be able to do + nothing more than mess with the user's files, or crash the machine. + User account compromises are very common because users tend not to + take the precautions that sysadmins take. + + + security + backdoors + + + System administrators must keep in mind that there are + potentially many ways to break root on a machine. + The attacker may know the root password, + the attacker may find a bug in a root-run server and be able + to break root over a network + connection to that server, or the attacker may know of a bug in + a suid-root program that allows the attacker to break + root once he has broken into a user's account. + If an attacker has found a way to break root + on a machine, the attacker may not have a need + to install a backdoor. Many of the root holes + found and closed to date involve a considerable amount of work + by the attacker to cleanup after himself, so most attackers install + backdoors. A backdoor provides the attacker with a way to easily + regain root access to the system, but it + also gives the smart system administrator a convenient way + to detect the intrusion. + Making it impossible for an attacker to install a backdoor may + actually be detrimental to your security, because it will not + close off the hole the attacker found to break in the first + place. + + + Security remedies should always be implemented with a + multi-layered onion peel approach and can be + categorized as follows: + + + + Securing root and staff accounts. + + + + Securing root–run servers + and suid/sgid binaries. + + + + Securing user accounts. + + + + Securing the password file. + + + + Securing the kernel core, raw devices, and + file systems. + + + + Quick detection of inappropriate changes made to the + system. + + + + Paranoia. + + + + The next section of this chapter will cover the above bullet + items in greater depth. + + + + Securing &os; + + security + securing &os; + + + + Command vs. Protocol + Throughout this document, we will use + bold text to refer to an + application, and a monospaced font to refer + to specific commands. Protocols will use a normal font. This + typographical distinction is useful for instances such as ssh, + since it is + a protocol as well as command. + + + The sections that follow will cover the methods of securing your + &os; system that were mentioned in the last section of this chapter. + + + Securing the <username>root</username> Account and + Staff Accounts + + su + + + First off, do not bother securing staff accounts if you have + not secured the root account. + Most systems have a password assigned to the root + account. The first thing you do is assume + that the password is always compromised. + This does not mean that you should remove the password. The + password is almost always necessary for console access to the + machine. What it does mean is that you should not make it + possible to use the password outside of the console or possibly + even with the &man.su.1; command. For example, make sure that + your ptys are specified as being insecure in the + /etc/ttys file so that direct + root logins + via telnet or rlogin are + disallowed. If using other login services such as + sshd, make sure that direct + root logins are disabled there as well. + You can do this by editing + your /etc/ssh/sshd_config file, and making + sure that PermitRootLogin is set to + NO. Consider every access method — + services such as FTP often fall through the cracks. + Direct root logins should only be allowed + via the system console. + + wheel + + + Of course, as a sysadmin you have to be able to get to + root, so we open up a few holes. + But we make sure these holes require additional password + verification to operate. One way to make root + accessible is to add appropriate staff accounts to the + wheel group (in + /etc/group). The staff members placed in the + wheel group are allowed to + su to root. + You should never give staff + members native wheel access by putting them in the + wheel group in their password entry. Staff + accounts should be placed in a staff group, and + then added to the wheel group via the + /etc/group file. Only those staff members + who actually need to have root access + should be placed in the + wheel group. It is also possible, when using + an authentication method such as Kerberos, to use Kerberos' + .k5login file in the root + account to allow a &man.ksu.1; to root + without having to place anyone at all in the + wheel group. This may be the better solution + since the wheel mechanism still allows an + intruder to break root if the intruder + has gotten hold of your + password file and can break into a staff account. While having + the wheel mechanism is better than having + nothing at all, it is not necessarily the safest option. + + + + An indirect way to secure staff accounts, and ultimately + root access is to use an alternative + login access method and + do what is known as starring out the encrypted + password for the staff accounts. Using the &man.vipw.8; + command, one can replace each instance of an encrypted password + with a single * character. + This command will update the /etc/master.passwd + file and user/password database to disable password-authenticated + logins. + + A staff account entry such as: + + foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh + + Should be changed to this: + + foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh + + This change will prevent normal logins from occurring, + since the encrypted password will never match + *. With this done, + staff members must use + another mechanism to authenticate themselves such as + &man.kerberos.1; or &man.ssh.1; using a public/private key + pair. When using something like Kerberos, one generally must + secure the machines which run the Kerberos servers and your + desktop workstation. When using a public/private key pair + with ssh, one must generally secure + the machine used to login from (typically + one's workstation). An additional layer of protection can be + added to the key pair by password protecting the key pair when + creating it with &man.ssh-keygen.1;. Being able to + star out the passwords for staff accounts also + guarantees that staff members can only login through secure + access methods that you have set up. This forces all staff + members to use secure, encrypted connections for all of their + sessions, which closes an important hole used by many + intruders: sniffing the network from an unrelated, + less secure machine. + + The more indirect security mechanisms also assume that you are + logging in from a more restrictive server to a less restrictive + server. For example, if your main box is running all sorts of + servers, your workstation should not be running any. In order for + your workstation to be reasonably secure you should run as few + servers as possible, up to and including no servers at all, and + you should run a password-protected screen blanker. Of course, + given physical access to a workstation an attacker can break any + sort of security you put on it. This is definitely a problem that + you should consider, but you should also consider the fact that the + vast majority of break-ins occur remotely, over a network, from + people who do not have physical access to your workstation or + servers. + KerberosIV + + Using something like Kerberos also gives you the ability to + disable or change the password for a staff account in one place, + and have it immediately affect all the machines on which the staff + member may have an account. If a staff member's account gets + compromised, the ability to instantly change his password on all + machines should not be underrated. With discrete passwords, + changing a password on N machines can be a mess. You can also + impose re-passwording restrictions with Kerberos: not only can a + Kerberos ticket be made to timeout after a while, but the Kerberos + system can require that the user choose a new password after a + certain period of time (say, once a month). + + + + Securing Root-run Servers and SUID/SGID Binaries + + + ntalk + + + comsat + + + finger + + + sandboxes + + + sshd + + + telnetd + + + rshd + + + rlogind + + + The prudent sysadmin only runs the servers he needs to, no + more, no less. Be aware that third party servers are often the + most bug-prone. For example, running an old version of + imapd or + popper is like giving a universal + root ticket out to the entire world. + Never run a server that you have not checked out carefully. + Many servers do not need to be run as root. + For example, the ntalk, + comsat, and + finger daemons can be run in special + user sandboxes. A sandbox is not perfect, + unless you go through a large amount of trouble, but the onion + approach to security still stands: If someone is able to break + in through a server running in a sandbox, they still have to + break out of the sandbox. The more layers the attacker must + break through, the lower the likelihood of his success. Root + holes have historically been found in virtually every server + ever run as root, including basic system servers. + If you are running a machine through which people only login via + sshd and never login via + telnetd or + rshd or + rlogind, then turn off those + services! + + &os; now defaults to running + ntalkd, + comsat, and + finger in a sandbox. Another program + which may be a candidate for running in a sandbox is &man.named.8;. + /etc/defaults/rc.conf includes the arguments + necessary to run named in a sandbox in a + commented-out form. Depending on whether you are installing a new + system or upgrading an existing system, the special user accounts + used by these sandboxes may not be installed. The prudent + sysadmin would research and implement sandboxes for servers + whenever possible. + + sendmail + + + There are a number of other servers that typically do not run + in sandboxes: sendmail, + popper, + imapd, ftpd, + and others. There are alternatives to some of these, but + installing them may require more work than you are willing to + perform (the convenience factor strikes again). You may have to + run these servers as root and rely on other + mechanisms to detect break-ins that might occur through them. + + The other big potential root holes in a + system are the + suid-root and sgid binaries installed on the system. Most of + these binaries, such as rlogin, reside + in /bin, /sbin, + /usr/bin, or /usr/sbin. + While nothing is 100% safe, the system-default suid and sgid + binaries can be considered reasonably safe. Still, + root holes are occasionally found in these + binaries. A root hole was found in + Xlib in 1998 that made + xterm (which is typically suid) + vulnerable. It is better to be safe than sorry and the prudent + sysadmin will restrict suid binaries, that only staff should run, + to a special group that only staff can access, and get rid of + (chmod 000) any suid binaries that nobody uses. + A server with no display generally does not need an + xterm binary. Sgid binaries can be + almost as dangerous. If an intruder can break an sgid-kmem binary, + the intruder might be able to read /dev/kmem + and thus read the encrypted password file, potentially compromising + any passworded account. Alternatively an intruder who breaks + group kmem can monitor keystrokes sent through + ptys, including ptys used by users who login through secure + methods. An intruder that breaks the tty + group can write to + almost any user's tty. If a user is running a terminal program or + emulator with a keyboard-simulation feature, the intruder can + potentially generate a data stream that causes the user's terminal + to echo a command, which is then run as that user. + + + + Securing User Accounts + + User accounts are usually the most difficult to secure. While + you can impose Draconian access restrictions on your staff and + star out their passwords, you may not be able to + do so with any general user accounts you might have. If you do + have sufficient control, then you may win out and be able to secure + the user accounts properly. If not, you simply have to be more + vigilant in your monitoring of those accounts. Use of + ssh and Kerberos for user accounts is + more problematic, due to the extra administration and technical + support required, but still a very good solution compared to a + crypted password file. + + + + Securing the Password File + + The only sure fire way is to * out as many + passwords as you can and use ssh or + Kerberos for access to those accounts. Even though the encrypted + password file (/etc/spwd.db) can only be read + by root, it may be possible for an intruder + to obtain read access to that file even if the attacker cannot + obtain root-write access. + + Your security scripts should always check for and report + changes to the password file (see the Checking file integrity section + below). + + + + Securing the Kernel Core, Raw Devices, and + File systems + + If an attacker breaks root he can do + just about anything, but + there are certain conveniences. For example, most modern kernels + have a packet sniffing device driver built in. Under &os; it + is called the bpf device. An intruder + will commonly attempt to run a packet sniffer on a compromised + machine. You do not need to give the intruder the capability and + most systems do not have the need for the + bpf device compiled in. + + + sysctl + + But even if you turn off the bpf + device, you still have + /dev/mem and + /dev/kmem + to worry about. For that matter, the intruder can still write to + raw disk devices. Also, there is another kernel feature called + the module loader, &man.kldload.8;. An enterprising intruder can + use a KLD module to install his own bpf + device, or other sniffing + device, on a running kernel. To avoid these problems you have to + run the kernel at a higher secure level, at least securelevel 1. + The securelevel can be set with a sysctl on + the kern.securelevel variable. Once you have + set the securelevel to 1, write access to raw devices will be + denied and special chflags flags, + such as schg, + will be enforced. You must also ensure that the + schg flag is set on critical startup binaries, + directories, and script files — everything that gets run up + to the point where the securelevel is set. This might be overdoing + it, and upgrading the system is much more difficult when you + operate at a higher secure level. You may compromise and run the + system at a higher secure level but not set the + schg flag for every system file and directory + under the sun. Another possibility is to simply mount + / and /usr read-only. + It should be noted that being too Draconian in what you attempt to + protect may prevent the all-important detection of an + intrusion. + + + + Checking File Integrity: Binaries, Configuration Files, + Etc. + + When it comes right down to it, you can only protect your core + system configuration and control files so much before the + convenience factor rears its ugly head. For example, using + chflags to set the schg bit + on most of the files in / and + /usr is probably counterproductive, because + while it may protect the files, it also closes a detection window. + The last layer of your security onion is perhaps the most + important — detection. The rest of your security is pretty + much useless (or, worse, presents you with a false sense of + safety) if you cannot detect potential incursions. Half the job + of the onion is to slow down the attacker, rather than stop him, in + order to give the detection side of the equation a chance to catch + him in the act. + + The best way to detect an incursion is to look for modified, + missing, or unexpected files. The best way to look for modified + files is from another (often centralized) limited-access system. + Writing your security scripts on the extra-secure limited-access + system makes them mostly invisible to potential attackers, and this + is important. In order to take maximum advantage you generally + have to give the limited-access box significant access to the + other machines in the business, usually either by doing a + read-only NFS export of the other machines to the limited-access + box, or by setting up ssh key-pairs to + allow the limited-access box to ssh to + the other machines. Except for its network traffic, NFS is the + least visible method — allowing you to monitor the + file systems on each client box virtually undetected. If your + limited-access server is connected to the client boxes through a + switch, the NFS method is often the better choice. If your + limited-access server is connected to the client boxes through a + hub, or through several layers of routing, the NFS method may be + too insecure (network-wise) and using + ssh may be the better choice even with + the audit-trail tracks that ssh + lays. + + Once you give a limited-access box, at least read access to the + client systems it is supposed to monitor, you must write scripts + to do the actual monitoring. Given an NFS mount, you can write + scripts out of simple system utilities such as &man.find.1; and + &man.md5.1;. It is best to physically md5 the client-box files + at least once a day, and to test control files such as those + found in /etc and + /usr/local/etc even more often. When + mismatches are found, relative to the base md5 information the + limited-access machine knows is valid, it should scream at a + sysadmin to go check it out. A good security script will also + check for inappropriate suid binaries and for new or deleted files + on system partitions such as / and + /usr. + + When using ssh rather than NFS, + writing the security script is much more difficult. You + essentially have to scp the scripts to the client + box in order to + run them, making them visible, and for safety you also need to + scp the binaries (such as find) that those + scripts use. The ssh client on the + client box may already be compromised. All in all, using + ssh may be necessary when running over + insecure links, but it is also a lot harder to deal with. + + A good security script will also check for changes to user and + staff members access configuration files: + .rhosts, .shosts, + .ssh/authorized_keys and so forth… + files that might fall outside the purview of the + MD5 check. + + If you have a huge amount of user disk space, it may take too + long to run through every file on those partitions. In this case, + setting mount flags to disallow suid binaries and devices on those + partitions is a good idea. The nodev and + nosuid options (see &man.mount.8;) are what you + want to look into. You should probably scan them anyway, at least + once a week, since the object of this layer is to detect a break-in + whether or not the break-in is effective. + + Process accounting (see &man.accton.8;) is a relatively + low-overhead feature of the operating system which might help + as a post-break-in evaluation mechanism. It is especially + useful in tracking down how an intruder has actually broken into + a system, assuming the file is still intact after the break-in + occurs. + + Finally, security scripts should process the log files, and the + logs themselves should be generated in as secure a manner as + possible — remote syslog can be very useful. An intruder + tries to cover his tracks, and log files are critical to the + sysadmin trying to track down the time and method of the initial + break-in. One way to keep a permanent record of the log files is + to run the system console to a serial port and collect the + information on a continuing basis through a secure machine + monitoring the consoles. + + + + Paranoia + + A little paranoia never hurts. As a rule, a sysadmin can add + any number of security features, as long as they do not affect + convenience, and can add security features that + do affect convenience with some added thought. + Even more importantly, a security administrator should mix it up a + bit — if you use recommendations such as those given by this + document verbatim, you give away your methodologies to the + prospective attacker who also has access to this document. + + + + Denial of Service Attacks + Denial of Service (DoS) + + This section covers Denial of Service attacks. A DoS attack + is typically a packet attack. While there is not much you can do + about modern spoofed packet attacks that saturate your network, + you can generally limit the damage by ensuring that the attacks + cannot take down your servers. + + + + Limiting server forks. + + + + Limiting springboard attacks (ICMP response attacks, ping + broadcast, etc.). + + + + Kernel Route Cache. + + + + A common DoS attack is against a forking server that attempts + to cause the server to eat processes, file descriptors, and memory, + until the machine dies. inetd + (see &man.inetd.8;) has several + options to limit this sort of attack. It should be noted that + while it is possible to prevent a machine from going down, it is + not generally possible to prevent a service from being disrupted + by the attack. Read the inetd manual + page carefully and pay + specific attention to the , , + and options. Note that spoofed-IP attacks + will circumvent the option to + inetd, so + typically a combination of options must be used. Some standalone + servers have self-fork-limitation parameters. + + Sendmail has its + option, which tends to work + much better than trying to use sendmail's load limiting options + due to the load lag. You should specify a + MaxDaemonChildren parameter, when you start + sendmail, high enough to handle your + expected load, but not so high that the computer cannot handle that + number of sendmails without falling on + its face. It is also prudent to run sendmail in queued mode + () and to run the daemon + (sendmail -bd) separate from the queue-runs + (sendmail -q15m). If you still want real-time + delivery you can run the queue at a much lower interval, such as + , but be sure to specify a reasonable + MaxDaemonChildren option for + that sendmail to prevent cascade failures. + + Syslogd can be attacked directly + and it is strongly recommended that you use the + option whenever possible, and the option + otherwise. + + You should also be fairly careful with connect-back services + such as TCP Wrapper's reverse-identd, + which can be attacked directly. You generally do not want to use + the reverse-ident feature of + TCP Wrapper for this reason. + + It is a very good idea to protect internal services from + external access by firewalling them off at your border routers. + The idea here is to prevent saturation attacks from outside your + LAN, not so much to protect internal services from network-based + root compromise. + Always configure an exclusive firewall, i.e., + firewall everything except ports A, B, + C, D, and M-Z. This way you can firewall off all of your + low ports except for certain specific services such as + named (if you are primary for a zone), + ntalkd, + sendmail, and other Internet-accessible + services. If you try to configure the firewall the other way + — as an inclusive or permissive firewall, there is a good + chance that you will forget to close a couple of + services, or that you will add a new internal service and forget + to update the firewall. You can still open up the high-numbered + port range on the firewall, to allow permissive-like operation, + without compromising your low ports. Also take note that &os; + allows you to control the range of port numbers used for dynamic + binding, via the various net.inet.ip.portrange + sysctl's (sysctl -a | fgrep + portrange), which can also ease the complexity of your + firewall's configuration. For example, you might use a normal + first/last range of 4000 to 5000, and a hiport range of 49152 to + 65535, then block off everything under 4000 in your firewall + (except for certain specific Internet-accessible ports, of + course). + + Another common DoS attack is called a springboard attack + — to attack a server in a manner that causes the server to + generate responses which overloads the server, the local + network, or some other machine. The most common attack of this + nature is the ICMP ping broadcast attack. + The attacker spoofs ping packets sent to your LAN's broadcast + address with the source IP address set to the actual machine they + wish to attack. If your border routers are not configured to + stomp on ping's to broadcast addresses, your LAN winds up + generating sufficient responses to the spoofed source address to + saturate the victim, especially when the attacker uses the same + trick on several dozen broadcast addresses over several dozen + different networks at once. Broadcast attacks of over a hundred + and twenty megabits have been measured. A second common + springboard attack is against the ICMP error reporting system. + By constructing packets that generate ICMP error responses, an + attacker can saturate a server's incoming network and cause the + server to saturate its outgoing network with ICMP responses. This + type of attack can also crash the server by running it out of + mbuf's, especially if the server cannot drain the ICMP responses + it generates fast enough. + Use the sysctl + variable net.inet.icmp.icmplim to limit these attacks. + The last major class of springboard + attacks is related to certain internal + inetd services such as the + udp echo service. An attacker simply spoofs a UDP packet with the + source address being server A's echo port, and the destination + address being server B's echo port, where server A and B are both + on your LAN. The two servers then bounce this one packet back and + forth between each other. The attacker can overload both servers + and their LANs simply by injecting a few packets in this manner. + Similar problems exist with the internal + chargen port. A + competent sysadmin will turn off all of these inetd-internal test + services. + + Spoofed packet attacks may also be used to overload the kernel + route cache. Refer to the net.inet.ip.rtexpire, + rtminexpire, and rtmaxcache + sysctl parameters. A spoofed packet attack + that uses a random source IP will cause the kernel to generate a + temporary cached route in the route table, viewable with + netstat -rna | fgrep W3. These routes + typically timeout in 1600 seconds or so. If the kernel detects + that the cached route table has gotten too big it will dynamically + reduce the rtexpire but will never decrease it + to less than rtminexpire. There are two + problems: + + + + The kernel does not react quickly enough when a lightly + loaded server is suddenly attacked. + + + + The rtminexpire is not low enough for + the kernel to survive a sustained attack. + + + + If your servers are connected to the Internet via a T3 or + better, it may be prudent to manually override both + rtexpire and rtminexpire + via &man.sysctl.8;. Never set either parameter to zero (unless + you want to crash the machine). Setting both + parameters to 2 seconds should be sufficient to protect the route + table from attack. + + + + Access Issues with Kerberos and SSH + ssh + KerberosIV + + There are a few issues with both Kerberos and + ssh that need to be addressed if + you intend to use them. Kerberos V is an excellent + authentication protocol, but there are bugs in the kerberized + telnet and + rlogin applications that make them + unsuitable for dealing with binary streams. Also, by default + Kerberos does not encrypt a session unless you use the + option. ssh + encrypts everything by default. + + ssh works quite well in every + respect except that it forwards encryption keys by default. What + this means is that if you have a secure workstation holding keys + that give you access to the rest of the system, and you + ssh to an insecure machine, your keys + are usable. The actual keys themselves are not exposed, but + ssh installs a forwarding port for the + duration of your login, and if an attacker has broken + root on the + insecure machine he can utilize that port to use your keys to gain + access to any other machine that your keys unlock. + + We recommend that you use ssh in + combination with Kerberos whenever possible for staff logins. + ssh can be compiled with Kerberos + support. This reduces your reliance on potentially exposed + ssh keys while at the same time + protecting passwords via Kerberos. ssh + keys should only be used for automated tasks from secure machines + (something that Kerberos is unsuited to do). We also recommend that + you either turn off key-forwarding in the + ssh configuration, or that you make use + of the from=IP/DOMAIN option that + ssh allows in its + authorized_keys file to make the key only + usable to entities logging in from specific machines. + + + + + + + + Bill + Swingle + Parts rewritten and updated by + + + + + + DES, MD5, and Crypt + + security + crypt + + + crypt + DES + MD5 + + Every user on a &unix; system has a password associated with + their account. It seems obvious that these passwords need to be + known only to the user and the actual operating system. In + order to keep these passwords secret, they are encrypted with + what is known as a one-way hash, that is, they can + only be easily encrypted but not decrypted. In other words, what + we told you a moment ago was obvious is not even true: the + operating system itself does not really know + the password. It only knows the encrypted + form of the password. The only way to get the + plain-text password is by a brute force search of the + space of possible passwords. + + Unfortunately the only secure way to encrypt passwords when + &unix; came into being was based on DES, the Data Encryption + Standard. This was not such a problem for users resident in + the US, but since the source code for DES could not be exported + outside the US, &os; had to find a way to both comply with + US law and retain compatibility with all the other &unix; + variants that still used DES. + + The solution was to divide up the encryption libraries + so that US users could install the DES libraries and use + DES but international users still had an encryption method + that could be exported abroad. This is how &os; came to + use MD5 as its default encryption method. MD5 is believed to + be more secure than DES, so installing DES is offered primarily + for compatibility reasons. + + + Recognizing Your Crypt Mechanism + + Currently the library supports DES, MD5 and Blowfish hash + functions. By default &os; uses MD5 to encrypt + passwords. + + It is pretty easy to identify which encryption method + &os; is set up to use. Examining the encrypted passwords in + the /etc/master.passwd file is one way. + Passwords encrypted with the MD5 hash are longer than those + encrypted with the DES hash and also begin with the characters + $1$. Passwords starting with + $2a$ are encrypted with the + Blowfish hash function. DES password strings do not + have any particular identifying characteristics, but they are + shorter than MD5 passwords, and are coded in a 64-character + alphabet which does not include the $ + character, so a relatively short string which does not begin with + a dollar sign is very likely a DES password. + + The password format used for new passwords is controlled + by the passwd_format login capability in + /etc/login.conf, which takes values of + des, md5 or + blf. See the &man.login.conf.5; manual page + for more information about login capabilities. + + + + + + One-time Passwords + one-time passwords + + security + one-time passwords + + + By default, &os; includes suppor for OPIE (One-time Passwords + In Everything), which uses the MD5 hash by default. + + There are three different sorts of passwords which we will discuss + below. The first is your usual &unix; style or + Kerberos password; we will call this a &unix; password. + The second sort is the one-time password which is generated by the OPIE + &man.opiekey.1; program and accepted by the + &man.opiepasswd.1; program + and the login prompt; we will + call this a one-time password. The final sort of + password is the secret password which you give to the + opiekey program (and + sometimes the + opiepasswd programs) + which it uses to generate + one-time passwords; we will call it a secret password + or just unqualified password. + + The secret password does not have anything to do with your &unix; + password; they can be the same but this is not recommended. + OPIE secret passwords are not limited to 8 characters like old + &unix; passwordsUnder &os; the standard login + password may be up to 128 characters in length., + they can be as long as you like. Passwords of six or + seven word long phrases are fairly common. For the most part, the + OPIE system operates completely independently of the &unix; + password system. + + Besides the password, there are two other pieces of data that + are important to OPIE. One is what is known as the + seed or key, consisting of two letters + and five digits. The other is what is called the iteration + count, a number between 1 and 100. OPIE creates the + one-time password by concatenating the seed and the secret password, + then applying the MD5 hash as many times as specified by the + iteration count and turning the result into six short English words. + These six English words are your one-time password. The + authentication system (primarily PAM) keeps + track of the last one-time password used, and the user is + authenticated if the hash of the user-provided password is equal to + the previous password. Because a one-way hash is used it is + impossible to generate future one-time passwords if a successfully + used password is captured; the iteration count is decremented after + each successful login to keep the user and the login program in + sync. When the iteration count gets down to 1, OPIE must be + reinitialized. + + There are a few programs involved in each system + which we will discuss below. The + opiekey program accepts an iteration + count, a seed, and a secret password, and generates a one-time + password or a consecutive list of one-time passwords. The + opiepasswd + program is used to initialize OPIE, + and to change passwords, iteration counts, or seeds; it + takes either a secret passphrase, or an iteration count, + seed, and a one-time password. The + opieinfo program will examine the + relevant credentials files + (/etc/opiekeys) and print out the invoking user's + current iteration count and seed. + + There are four different sorts of operations we will cover. The + first is using + opiepasswd over a secure connection to set up + one-time-passwords for the first time, or to change your password + or seed. The second operation is using + opiepasswd over an insecure connection, in + conjunction with opiekey + over a secure connection, to do the same. The third is using + opiekey to log in over + an insecure connection. The fourth is using + opiekey to generate a number of keys which + can be written down or printed out to carry with you when going to + some location without secure connections to anywhere. + + + Secure Connection Initialization + To initialize OPIE for the first time, execute the + opiepasswd command: + + &prompt.user; opiepasswd -c +[grimreaper] ~ $ opiepasswd -f -c +Adding unfurl: +Only use this method from the console; NEVER from remote. If you are using +telnet, xterm, or a dial-in, type ^C now or exit with no password. +Then run opiepasswd without the -c parameter. +Using MD5 to compute responses. +Enter new secret pass phrase: +Again new secret pass phrase: +ID unfurl OTP key is 499 to4268 +MOS MALL GOAT ARM AVID COED + + + At the Enter new secret pass phrase: or + Enter secret password: prompts, you + should enter a password or phrase. Remember, this is not the + password that you will use to login with, this is used to generate + your one-time login keys. The ID line gives the + parameters of your particular instance: your login name, the + iteration count, and seed. When logging in the system + will remember these parameters and present them back to you so you + do not have to remember them. The last line gives the particular + one-time password which corresponds to those parameters and your + secret password; if you were to re-login immediately, this + one-time password is the one you would use. + + + + Insecure Connection Initialization + + To initialize or change your secret password over an + insecure connection, you will need to already have a secure + connection to some place where you can run + opiekey; this might be in the form of a shell + prompt on a machine you + trust. You will also need to make up an iteration count (100 is + probably a good value), and you may make up your own seed or use a + randomly-generated one. Over on the insecure connection (to the + machine you are initializing), use opiepasswd: + + &prompt.user; opiepasswd + +Updating unfurl: +You need the response from an OTP generator. +Old secret pass phrase: + otp-md5 498 to4268 ext + Response: GAME GAG WELT OUT DOWN CHAT +New secret pass phrase: + otp-md5 499 to4269 + Response: LINE PAP MILK NELL BUOY TROY + +ID mark OTP key is 499 gr4269 +LINE PAP MILK NELL BUOY TROY + + + To accept the default seed press Return. + Then before entering an + access password, move over to your secure connection and give it + the same parameters: + + &prompt.user; opiekey 498 to4268 +Using the MD5 algorithm to compute response. +Reminder: Don't use opiekey from telnet or dial-in sessions. +Enter secret pass phrase: +GAME GAG WELT OUT DOWN CHAT + + + Now switch back over to the insecure connection, and copy the + one-time password generated over to the relevant program. + + + + Generating a Single One-time Password + + Once you have initialized OPIE and login, you will be + presented with a prompt like this: + +&prompt.user; telnet example.com +Trying 10.0.0.1... +Connected to example.com +Escape character is '^]'. + +FreeBSD/i386 (example.com) (ttypa) + +login: <username> +otp-md5 498 gr4269 ext +Password: + + As a side note, the OPIE prompts have a useful feature + (not shown here): if you press Return + at the password prompt, the + prompter will turn echo on, so you can see what you are + typing. This can be extremely useful if you are attempting to + type in a password by hand, such as from a printout. + + MS-DOS + Windows + MacOS + + At this point you need to generate your one-time password to + answer this login prompt. This must be done on a trusted system + that you can run + opiekey on. (There are versions of these for DOS, + &windows; and &macos; as well.) They need the iteration count and + the seed as command line options. You can cut-and-paste these + right from the login prompt on the machine that you are logging + in to. + + On the trusted system: + + &prompt.user; opiekey 498 to4268 +Using the MD5 algorithm to compute response. +Reminder: Don't use opiekey from telnet or dial-in sessions. +Enter secret pass phrase: +GAME GAG WELT OUT DOWN CHAT + + Now that you have your one-time password you can continue + logging in. + + + + Generating Multiple One-time Passwords + + Sometimes you have to go places where you do not have + access to a trusted machine or secure connection. In this case, + it is possible to use the + opiekey command to + generate a number of one-time passwords beforehand to be printed + out and taken with you. For example: + + &prompt.user; opiekey -n 5 30 zz99999 +Using the MD5 algorithm to compute response. +Reminder: Don't use opiekey from telnet or dial-in sessions. +Enter secret pass phrase: <secret password> +26: JOAN BORE FOSS DES NAY QUIT +27: LATE BIAS SLAY FOLK MUCH TRIG +28: SALT TIN ANTI LOON NEAL USE +29: RIO ODIN GO BYE FURY TIC +30: GREW JIVE SAN GIRD BOIL PHI + + The requests five keys in sequence, the + specifies what the last iteration number + should be. Note that these are printed out in + reverse order of eventual use. If you are + really paranoid, you might want to write the results down by hand; + otherwise you can cut-and-paste into lpr. Note + that each line shows both the iteration count and the one-time + password; you may still find it handy to scratch off passwords as + you use them. + + + + Restricting Use of &unix; Passwords + + OPIE can restrict the use of &unix; passwords based on the IP + address of a login session. The relevant file + is /etc/opieaccess, which is present by default. + Please check &man.opieaccess.5; + for more information on this file and which security considerations + you should be aware of when using it. + + Here is a sample opieaccess file: + + permit 192.168.0.0 255.255.0.0 + + This line allows users whose IP source address (which is + vulnerable to spoofing) matches the specified value and mask, + to use &unix; passwords at any time. + + If no rules in opieaccess are matched, + the default is to deny non-OPIE logins. + + + + + + + + + Tom + Rhodes + Written by: + + + + + TCP Wrappers + + TCP Wrappers + + Anyone familiar with &man.inetd.8; has probably heard + of TCP Wrappers at some point. But few + individuals seem to fully comprehend its usefulness in a + network environment. It seems that everyone wants to + install a firewall to handle network connections. While a + firewall has a wide variety of uses, there are some things + that a firewall not handle such as sending text back to the + connection originator. The TCP software + does this and much more. In the next few sections many of + the TCP Wrappers features will be discussed, + and, when applicable, example configuration lines will be + provided. + + The TCP Wrappers software extends the + abilities of inetd to provide support for + every server daemon under its control. Using this method it + is possible to provide logging support, return messages to + connections, permit a daemon to only accept internal connections, + etc. While some of these features can be provided by implementing + a firewall, this will add not only an extra layer of protection + but go beyond the amount of control a firewall can + provide. + + The added functionality of TCP Wrappers + should not be considered a replacement for a good firewall. + TCP Wrappers can be used in conjunction + with a firewall or other security enhancements though and + it can serve nicely as an extra layer of protection + for the system. + + Since this is an extension to the configuration of + inetd, the reader is expected have + read the inetd configuration + section. + + + While programs run by &man.inetd.8; are not exactly + daemons, they have traditionally been called + daemons. This is the term we will use in this section too. + + + + Initial Configuration + + The only requirement of using TCP + Wrappers in &os; is to ensure the inetd + server is started from rc.conf with the + option; this is the default setting. Of + course, proper configuration of + /etc/hosts.allow is also expected, but + &man.syslogd.8; will throw messages in the system logs in + these cases. + + + Unlike other implementations of TCP + Wrappers, the use of hosts.deny has + been deprecated. All configuration options should be placed + in /etc/hosts.allow. + + + In the simplest configuration, daemon connection policies + are set to either be permitted or blocked depending on the + options in /etc/hosts.allow. The default + configuration in &os; is to allow a connection to every daemon + started with inetd. Changing this will be + discussed only after the basic configuration is covered. + + Basic configuration usually takes the form of + daemon : address : action. Where + daemon is the daemon name which + inetd started. The + address can be a valid hostname, an + IP address or an IPv6 address enclosed in + brackets ([ ]). The action field can be either allow + or deny to grant or deny access appropriately. Keep in mind + that configuration works off a first rule match semantic, + meaning that the configuration file is scanned in ascending + order for a matching rule. When a match is found the rule + is applied and the search process will halt. + + Several other options exist but they will be explained + in a later section. A simple configuration line may easily be + constructed from that information alone. For example, to + allow POP3 connections via the + mail/qpopper daemon, + the following lines should be appended to + hosts.allow: + + # This line is required for POP3 connections: +qpopper : ALL : allow + + After adding this line, inetd will need + restarted. This can be accomplished by use of the &man.kill.1; + command, or with the restart parameter + with /etc/rc.d/inetd. + + + + Advanced Configuration + + TCP Wrappers has advanced + options too; they will allow for more control over the + way connections are handled. In some cases it may be + a good idea to return a comment to certain hosts or + daemon connections. In other cases, perhaps a log file + should be recorded or an email sent to the administrator. + Other situations may require the use of a service for local + connections only. This is all possible through the use of + configuration options known as wildcards, + expansion characters and external command execution. The + next two sections are written to cover these situations. + + + External Commands + + Suppose that a situation occurs where a connection + should be denied yet a reason should be sent to the + individual who attempted to establish that connection. How + could it be done? That action can be made possible by + using the option. When a connection + attempt is made, will be called to + execute a shell command or script. An example already exists + in the hosts.allow file: + + # The rest of the daemons are protected. +ALL : ALL \ + : severity auth.info \ + : twist /bin/echo "You are not welcome to use %d from %h." + + This example shows that the message, + You are not allowed to use daemon + from hostname. will be returned + for any daemon not previously configured in the access file. + This is extremely useful for sending a reply back to the + connection initiator right after the established connection + is dropped. Note that any message returned + must be wrapped in quote + " characters; there are no exceptions to + this rule. + + + It may be possible to launch a denial of service attack + on the server if an attacker, or group of attackers could + flood these daemons with connection requests. + + + Another possibility is to use the + option in these cases. Like , the + implicitly denies the connection and + may be used to run external shell commands or scripts. + Unlike , will + not send a reply back to the individual who established the + connection. For an example, consider the following + configuration line: + + # We do not allow connections from example.com: +ALL : .example.com \ + : spawn (/bin/echo %a from %h attempted to access %d >> \ + /var/log/connections.log) \ + : deny + + This will deny all connection attempts from the + *.example.com domain; + simultaneously logging the hostname, IP + address and the daemon which they attempted to access in the + /var/log/connections.log file. + + Aside from the already explained substitution characters + above, e.g. %a, a few others exist. See the + &man.hosts.access.5; manual page for the complete list. + + + + Wildcard Options + + Thus far the ALL example has been used + continuously throughout the examples. Other options exist + which could extend the functionality a bit further. For + instance, ALL may be used to match every + instance of either a daemon, domain or an + IP address. Another wildcard available is + PARANOID which may be used to match any + host which provides an IP address that may + be forged. In other words, paranoid may + be used to define an action to be taken whenever a connection + is made from an IP address that differs + from its hostname. The following example may shed some more + light on this discussion: + + # Block possibly spoofed requests to sendmail: +sendmail : PARANOID : deny + + In that example all connection requests to + sendmail which have an + IP address that varies from its hostname + will be denied. + + + Using the PARANOID may severely + cripple servers if the client or server has a broken + DNS setup. Administrator discretion + is advised. + + + To learn more about wildcards and their associated + functionality, see the &man.hosts.access.5; manual + page. + + Before any of the specific configuration lines above will + work, the first configuration line should be commented out + in hosts.allow. This was noted at the + beginning of this section. + + + + + + + + + Mark + Murray + Contributed by + + + + + Mark + Dapoz + Based on a contribution by + + + + + <application>KerberosIV</application> + + Kerberos is a network add-on system/protocol that allows users to + authenticate themselves through the services of a secure server. + Services such as remote login, remote copy, secure inter-system file + copying and other high-risk tasks are made considerably safer and more + controllable. + + The following instructions can be used as a guide on how to set up + Kerberos as distributed for &os;. However, you should refer to the + relevant manual pages for a complete description. + + + Installing <application>KerberosIV</application> + + MIT + + KerberosIV + installing + + Kerberos is an optional component of &os;. The easiest + way to install this software is by selecting the krb4 or + krb5 distribution in sysinstall + during the initial installation of &os;. This will install + the eBones (KerberosIV) or Heimdal (Kerberos5) + implementation of Kerberos. These implementations are + included because they are developed outside the USA/Canada and + were thus available to system owners outside those countries + during the era of restrictive export controls on cryptographic + code from the USA. + + Alternatively, the MIT implementation of Kerberos is + available from the Ports Collection as + security/krb5. + + + + Creating the Initial Database + + This is done on the Kerberos server only. First make sure that + you do not have any old Kerberos databases around. You should change + to the directory /etc/kerberosIV and check that + only the following files are present: + + &prompt.root; cd /etc/kerberosIV +&prompt.root; ls +README krb.conf krb.realms + + If any additional files (such as principal.* + or master_key) exist, then use the + kdb_destroy command to destroy the old Kerberos + database, or if Kerberos is not running, simply delete the extra + files. + + You should now edit the krb.conf and + krb.realms files to define your Kerberos realm. + In this case the realm will be EXAMPLE.COM and the + server is grunt.example.com. We edit + or create the krb.conf file: + + &prompt.root; cat krb.conf +EXAMPLE.COM +EXAMPLE.COM grunt.example.com admin server +CS.BERKELEY.EDU okeeffe.berkeley.edu +ATHENA.MIT.EDU kerberos.mit.edu +ATHENA.MIT.EDU kerberos-1.mit.edu +ATHENA.MIT.EDU kerberos-2.mit.edu +ATHENA.MIT.EDU kerberos-3.mit.edu +LCS.MIT.EDU kerberos.lcs.mit.edu +TELECOM.MIT.EDU bitsy.mit.edu +ARC.NASA.GOV trident.arc.nasa.gov + + In this case, the other realms do not need to be there. They are + here as an example of how a machine may be made aware of multiple + realms. You may wish to not include them for simplicity. + + The first line names the realm in which this system works. The + other lines contain realm/host entries. The first item on a line is a + realm, and the second is a host in that realm that is acting as a + key distribution center. The words admin + server following a host's name means that host also + provides an administrative database server. For further explanation + of these terms, please consult the Kerberos manual pages. + + Now we have to add grunt.example.com + to the EXAMPLE.COM realm and also add an entry to + put all hosts in the .example.com + domain in the EXAMPLE.COM realm. The + krb.realms file would be updated as + follows: + + &prompt.root; cat krb.realms +grunt.example.com EXAMPLE.COM +.example.com EXAMPLE.COM +.berkeley.edu CS.BERKELEY.EDU +.MIT.EDU ATHENA.MIT.EDU +.mit.edu ATHENA.MIT.EDU + + Again, the other realms do not need to be there. They are here as + an example of how a machine may be made aware of multiple realms. You + may wish to remove them to simplify things. + + The first line puts the specific system into + the named realm. The rest of the lines show how to default systems of + a particular subdomain to a named realm. + + Now we are ready to create the database. This only needs to run + on the Kerberos server (or Key Distribution Center). Issue the + kdb_init command to do this: + + &prompt.root; kdb_init +Realm name [default ATHENA.MIT.EDU ]: EXAMPLE.COM +You will be prompted for the database Master Password. +It is important that you NOT FORGET this password. + +Enter Kerberos master key: + + Now we have to save the key so that servers on the local machine + can pick it up. Use the kstash command to do + this: + + &prompt.root; kstash + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + + This saves the encrypted master password in + /etc/kerberosIV/master_key. + + + + Making It All Run + + + KerberosIV + initial startup + + + Two principals need to be added to the database for + each system that will be secured with Kerberos. + Their names are kpasswd and rcmd. + These two principals are made for each system, with the instance being + the name of the individual system. + + These daemons, kpasswd and + rcmd allow other systems to change Kerberos + passwords and run commands like &man.rcp.1;, + &man.rlogin.1; and &man.rsh.1;. + + Now let us add these entries: + + &prompt.root; kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: passwd +Instance: grunt + +<Not found>, Create [y] ? y + +Principal: passwd, Instance: grunt, kdc_key_ver: 1 +New Password: <---- enter RANDOM here +Verifying password + +New Password: <---- enter RANDOM here + +Random password [y] ? y + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: rcmd +Instance: grunt + +<Not found>, Create [y] ? + +Principal: rcmd, Instance: grunt, kdc_key_ver: 1 +New Password: <---- enter RANDOM here +Verifying password + +New Password: <---- enter RANDOM here + +Random password [y] ? + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: <---- null entry here will cause an exit + + + + Creating the Server File + + We now have to extract all the instances which define the + services on each machine. For this we use the + ext_srvtab command. This will create a file + which must be copied or moved by secure + means to each Kerberos client's + /etc/kerberosIV directory. This file must + be present on each server and client, and is crucial to the + operation of Kerberos. + + + &prompt.root; ext_srvtab grunt +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Generating 'grunt-new-srvtab'.... + + Now, this command only generates a temporary file which must be + renamed to srvtab so that all the servers can pick + it up. Use the &man.mv.1; command to move it into place on + the original system: + + &prompt.root; mv grunt-new-srvtab srvtab + + If the file is for a client system, and the network is not deemed + safe, then copy the + client-new-srvtab to + removable media and transport it by secure physical means. Be sure to + rename it to srvtab in the client's + /etc/kerberosIV directory, and make sure it is + mode 600: + + &prompt.root; mv grumble-new-srvtab srvtab +&prompt.root; chmod 600 srvtab + + + + Populating the Database + + We now have to add some user entries into the database. First + let us create an entry for the user jane. Use the + kdb_edit command to do this: + + &prompt.root; kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: jane +Instance: + +<Not found>, Create [y] ? y + +Principal: jane, Instance: , kdc_key_ver: 1 +New Password: <---- enter a secure password here +Verifying password + +New Password: <---- re-enter the password here +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? +Attributes [ 0 ] ? +Edit O.K. +Principal name: <---- null entry here will cause an exit + + + + Testing It All Out + + First we have to start the Kerberos daemons. Note that if you + have correctly edited your /etc/rc.conf then this + will happen automatically when you reboot. This is only necessary on + the Kerberos server. Kerberos clients will automatically get what + they need from the /etc/kerberosIV + directory. + + &prompt.root; kerberos & +Kerberos server starting +Sleep forever on error +Log file is /var/log/kerberos.log +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + +Current Kerberos master key version is 1 +Local realm: EXAMPLE.COM +&prompt.root; kadmind -n & +KADM Server KADM0.0A initializing +Please do not use 'kill -9' to kill this job, use a +regular kill instead + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! + + Now we can try using the kinit command to get a + ticket for the ID jane that we created + above: + + &prompt.user; kinit jane +MIT Project Athena (grunt.example.com) +Kerberos Initialization for "jane" +Password: + + Try listing the tokens using klist to see if we + really have them: + + &prompt.user; klist +Ticket file: /tmp/tkt245 +Principal: jane@EXAMPLE.COM + + Issued Expires Principal +Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.EXAMPLE.COM@EXAMPLE.COM + + Now try changing the password using &man.passwd.1; to + check if the kpasswd daemon can get + authorization to the Kerberos database: + + &prompt.user; passwd +realm EXAMPLE.COM +Old password for jane: +New Password for jane: +Verifying password +New Password for jane: +Password changed. + + + + Adding <command>su</command> Privileges + + Kerberos allows us to give each user + who needs root privileges their own + separate &man.su.1; password. + We could now add an ID which is authorized to + &man.su.1; to root. This is + controlled by having an instance of root + associated with a principal. Using kdb_edit + we can create the entry jane.root in the + Kerberos database: + + &prompt.root; kdb_edit +Opening database... + +Enter Kerberos master key: + +Current Kerberos master key version is 1. + +Master key entered. BEWARE! +Previous or default values are in [brackets] , +enter return to leave the same, or new value. + +Principal name: jane +Instance: root + +<Not found>, Create [y] ? y + +Principal: jane, Instance: root, kdc_key_ver: 1 +New Password: <---- enter a SECURE password here +Verifying password + +New Password: <---- re-enter the password here + +Principal's new key version = 1 +Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? +Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short! +Attributes [ 0 ] ? +Edit O.K. +Principal name: <---- null entry here will cause an exit + + Now try getting tokens for it to make sure it works: + + &prompt.root; kinit jane.root +MIT Project Athena (grunt.example.com) +Kerberos Initialization for "jane.root" +Password: + + Now we need to add the user to root's + .klogin file: + + &prompt.root; cat /root/.klogin +jane.root@EXAMPLE.COM + + Now try doing the &man.su.1;: + + &prompt.user; su +Password: + + and take a look at what tokens we have: + + &prompt.root; klist +Ticket file: /tmp/tkt_root_245 +Principal: jane.root@EXAMPLE.COM + + Issued Expires Principal +May 2 20:43:12 May 3 04:43:12 krbtgt.EXAMPLE.COM@EXAMPLE.COM + + + + Using Other Commands + + In an earlier example, we created a principal called + jane with an instance root. + This was based on a user with the same name as the principal, and this + is a Kerberos default; that a + <principal>.<instance> of the form + <username>.root will allow + that <username> to &man.su.1; to + root if the necessary entries are in the + .klogin file in root's + home directory: + + &prompt.root; cat /root/.klogin +jane.root@EXAMPLE.COM + + Likewise, if a user has in their own home directory lines of the + form: + + &prompt.user; cat ~/.klogin +jane@EXAMPLE.COM +jack@EXAMPLE.COM + + This allows anyone in the EXAMPLE.COM realm + who has authenticated themselves as jane or + jack (via kinit, see above) + to access to jane's + account or files on this system (grunt) via + &man.rlogin.1;, &man.rsh.1; or + &man.rcp.1;. + + For example, jane now logs into another system using + Kerberos: + + &prompt.user; kinit +MIT Project Athena (grunt.example.com) +Password: +&prompt.user; rlogin grunt +Last login: Mon May 1 21:14:47 from grumble +Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 + The Regents of the University of California. All rights reserved. + +FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 + + Or jack logs into jane's account on the same machine + (jane having + set up the .klogin file as above, and the person + in charge of Kerberos having set up principal + jack with a null instance): + + &prompt.user; kinit +&prompt.user; rlogin grunt -l jane +MIT Project Athena (grunt.example.com) +Password: +Last login: Mon May 1 21:16:55 from grumble +Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 + The Regents of the University of California. All rights reserved. +FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 + + + + + + + + Tillman + Hodgson + Contributed by + + + + + Mark + Murray + Based on a contribution by + + + + + <application>Kerberos5</application> + + Every &os; release beyond &os;-5.1 includes support + only for Kerberos5. Hence + Kerberos5 is the only version + included, and its configuration is similar in many aspects + to that of KerberosIV. The following + information only applies to + Kerberos5 in post &os;-5.0 + releases. Users who wish to use the + KerberosIV package may install the + security/krb4 port. + + Kerberos is a network add-on + system/protocol that allows users to authenticate themselves + through the services of a secure server. Services such as remote + login, remote copy, secure inter-system file copying and other + high-risk tasks are made considerably safer and more + controllable. + + Kerberos can be described as an + identity-verifying proxy system. It can also be described as a + trusted third-party authentication system. + Kerberos provides only one + function — the secure authentication of users on the network. + It does not provide authorization functions (what users are + allowed to do) or auditing functions (what those users did). + After a client and server have used + Kerberos to prove their identity, they + can also encrypt all of their communications to assure privacy + and data integrity as they go about their business. + + Therefore it is highly recommended that + Kerberos be used with other security + methods which provide authorization and audit services. + + The following instructions can be used as a guide on how to set + up Kerberos as distributed for &os;. + However, you should refer to the relevant manual pages for a complete + description. + + For purposes of demonstrating a Kerberos + installation, the various name spaces will be handled as follows: + + + + The DNS domain (zone) + will be example.org. + + + + The Kerberos realm will be + EXAMPLE.ORG. + + + + + Please use real domain names when setting up + Kerberos even if you intend to run + it internally. This avoids DNS problems + and assures inter-operation with other + Kerberos realms. + + + + History + + Kerberos5 + history + + + Kerberos was created by + MIT as a solution to network security problems. + The Kerberos protocol uses strong + cryptography so that a client can prove its identity to a server + (and vice versa) across an insecure network connection. + + Kerberos is both the name of a + network authentication protocol and an adjective to describe + programs that implement the program + (Kerberos telnet, for example). The + current version of the protocol is version 5, described in + RFC 1510. + + Several free implementations of this protocol are available, + covering a wide range of operating systems. The Massachusetts + Institute of Technology (MIT), where + Kerberos was originally developed, + continues to develop their Kerberos + package. It is commonly used in the US + as a cryptography product, as such it + has historically been affected by US export + regulations. The MIT + Kerberos is available as a port + (security/krb5). Heimdal + Kerberos is another version 5 + implementation, and was explicitly developed outside of the + US to avoid export + regulations (and is thus often included in non-commercial &unix; + variants). The Heimdal Kerberos + distribution is available as a port + (security/heimdal), and a + minimal installation of it is included in the base &os; + install. + + In order to reach the widest audience, these instructions assume + the use of the Heimdal distribution included in &os;. + + + + + Setting up a Heimdal <acronym>KDC</acronym> + + Kerberos5 + Key Distribution Center + + + The Key Distribution Center (KDC) is the + centralized authentication service that + Kerberos provides — it is the + computer that issues Kerberos tickets. + The KDC is considered trusted by + all other computers in the Kerberos + realm, and thus has heightened security concerns. + + Note that while running the Kerberos + server requires very few computing resources, a dedicated machine + acting only as a KDC is recommended for security + reasons. + + To begin setting up a KDC, ensure that your + /etc/rc.conf file contains the correct + settings to act as a KDC (you may need to adjust + paths to reflect your own system): + + kerberos5_server_enable="YES" +kadmind5_server_enable="YES" + + Next we will set up your Kerberos + config file, /etc/krb5.conf: + + [libdefaults] + default_realm = EXAMPLE.ORG +[realms] + EXAMPLE.ORG = { + kdc = kerberos.example.org + admin_server = kerberos.example.org + } +[domain_realm] + .example.org = EXAMPLE.ORG + + Note that this /etc/krb5.conf file implies + that your KDC will have the fully-qualified + hostname of kerberos.example.org. + You will need to add a CNAME (alias) entry to your zone file to + accomplish this if your KDC has a different + hostname. + + + For large networks with a properly configured + BIND DNS server, the + above example could be trimmed to: + + [libdefaults] + default_realm = EXAMPLE.ORG + + With the following lines being appended to the + example.org zonefile: + + _kerberos._udp IN SRV 01 00 88 kerberos.example.org. +_kerberos._tcp IN SRV 01 00 88 kerberos.example.org. +_kpasswd._udp IN SRV 01 00 464 kerberos.example.org. +_kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org. +_kerberos IN TXT EXAMPLE.ORG + + + For clients to be able to find the + Kerberos services, you + must have either a fully configured + /etc/krb5.conf or a minimally configured + /etc/krb5.conf and a + properly configured DNS server. + + + Next we will create the Kerberos + database. This database contains the keys of all principals encrypted + with a master password. You are not + required to remember this password, it will be stored in a file + (/var/heimdal/m-key). To create the master + key, run kstash and enter a password. + + Once the master key has been created, you can initialize the + database using the kadmin program with the + -l option (standing for local). + This option instructs kadmin to modify the + database files directly rather than going through the + kadmind network service. This handles the + chicken-and-egg problem of trying to connect to the database + before it is created. Once you have the kadmin + prompt, use the init command to create your + realms initial database. + + Lastly, while still in kadmin, create your + first principal using the add command. Stick + to the defaults options for the principal for now, you can always + change them later with the modify command. + Note that you can use the ? command at any + prompt to see the available options. + + A sample database creation session is shown below: + + &prompt.root; kstash +Master key: xxxxxxxx +Verifying password - Master key: xxxxxxxx + +&prompt.root; kadmin -l +kadmin> init EXAMPLE.ORG +Realm max ticket life [unlimited]: +kadmin> add tillman +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +Password: xxxxxxxx +Verifying password - Password: xxxxxxxx + + Now it is time to start up the KDC services. + Run /etc/rc.d/kerberos start and + /etc/rc.d/kadmind start to bring up the + services. Note that you will not have any kerberized daemons running + at this point but you should be able to confirm the that the + KDC is functioning by obtaining and listing a + ticket for the principal (user) that you just created from the + command-line of the KDC itself: + + &prompt.user; k5init tillman +tillman@EXAMPLE.ORG's Password: + +&prompt.user; k5list +Credentials cache: FILE:/tmp/krb5cc_500 + Principal: tillman@EXAMPLE.ORG + + Issued Expires Principal +Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + + + + + <application>Kerberos</application> enabling a server with + Heimdal services + + + Kerberos5 + enabling services + + + First, we need a copy of the Kerberos + configuration file, /etc/krb5.conf. To do + so, simply copy it over to the client computer from the + KDC in a secure fashion (using network utilities, + such as &man.scp.1;, or physically via a + floppy disk). + + Next you need a /etc/krb5.keytab file. + This is the major difference between a server providing + Kerberos enabled daemons and a + workstation — the server must have a + keytab file. This file + contains the servers host key, which allows it and the + KDC to verify each others identity. It + must be transmitted to the server in a secure fashion, as the + security of the server can be broken if the key is made public. + This explicitly means that transferring it via a clear text + channel, such as FTP, is a very bad idea. + + Typically, you transfer to the keytab + to the server using the kadmin program. + This is handy because you also need to create the host principal + (the KDC end of the + krb5.keytab) using + kadmin. + + Note that you must have already obtained a ticket and that this + ticket must be allowed to use the kadmin + interface in the kadmind.acl. See the section + titled Remote administration in the Heimdal info + pages (info heimdal) for details on designing + access control lists. If you do not want to enable remote + kadmin access, you can simply securely connect + to the KDC (via local console, + &man.ssh.1; or Kerberos + &man.telnet.1;) and perform administration locally + using kadmin -l. + + After installing the /etc/krb5.conf file, + you can use kadmin from the + Kerberos server. The + add --random-key command will let you add the + servers host principal, and the ext command + will allow you to extract the servers host principal to its own + keytab. For example: + + &prompt.root; kadmin +kadmin> add --random-key host/myserver.example.org +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +kadmin> ext host/myserver.example.org +kadmin> exit + + Note that the ext command (short for + extract) stores the extracted key in + /etc/krb5.keytab by default. + + If you do not have kadmind running on the + KDC (possibly for security reasons) and thus + do not have access to kadmin remotely, you + can add the host principal + (host/myserver.EXAMPLE.ORG) directly on the + KDC and then extract it to a temporary file + (to avoid over-writing the /etc/krb5.keytab + on the KDC) using something like this: + + &prompt.root; kadmin +kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org +kadmin> exit + + You can then securely copy the keytab to the server + computer (using scp or a floppy, for + example). Be sure to specify a non-default keytab name + to avoid over-writing the keytab on the + KDC. + + At this point your server can communicate with the + KDC (due to its krb5.conf + file) and it can prove its own identity (due to the + krb5.keytab file). It is now ready for + you to enable some Kerberos services. + For this example we will enable the telnet + service by putting a line like this into your + /etc/inetd.conf and then restarting the + &man.inetd.8; service with + /etc/rc.d/inetd restart: + + telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user + + The critical bit is that the -a + (for authentication) type is set to user. Consult the + &man.telnetd.8; manual page for more details. + + + + + <application>Kerberos</application> enabling a client with Heimdal + + + Kerberos5 + configure clients + + + Setting up a client computer is almost trivially easy. As + far as Kerberos configuration goes, + you only need the Kerberos + configuration file, located at /etc/krb5.conf. + Simply securely copy it over to the client computer from the + KDC. + + Test your client computer by attempting to use + kinit, klist, and + kdestroy from the client to obtain, show, and + then delete a ticket for the principal you created above. You + should also be able to use Kerberos + applications to connect to Kerberos + enabled servers, though if that does not work and obtaining a + ticket does the problem is likely with the server and not with + the client or the KDC. + + When testing an application like telnet, + try using a packet sniffer (such as &man.tcpdump.1;) + to confirm that your password is not sent in the clear. Try + using telnet with the -x + option, which encrypts the entire data stream (similar to + ssh). + + The core Kerberos client applications + (traditionally named kinit, + klist, kdestroy, and + kpasswd) are installed in + the base &os; install. Note that &os; versions prior to 5.0 + renamed them to k5init, + k5list, k5destroy, + k5passwd, and k5stash + (though it is typically only used once). + + Various non-core Kerberos client + applications are also installed by default. This is where the + minimal nature of the base Heimdal installation is + felt: telnet is the only + Kerberos enabled service. + + The Heimdal port adds some of the missing client applications: + Kerberos enabled versions of + ftp, rsh, + rcp, rlogin, and a few + other less common programs. The MIT port also + contains a full suite of Kerberos + client applications. + + + + + User configuration files: <filename>.k5login</filename> and <filename>.k5users</filename> + + + .k5login + + + + .k5users + + + Users within a realm typically have their + Kerberos principal (such as + tillman@EXAMPLE.ORG) mapped to a local + user account (such as a local account named + tillman). Client applications such as + telnet usually do not require a user name + or a principal. + + Occasionally, however, you want to grant access to a local + user account to someone who does not have a matching + Kerberos principal. For example, + tillman@EXAMPLE.ORG may need access to the + local user account webdevelopers. Other + principals may also need access to that local account. + + The .k5login and + .k5users files, placed in a users home + directory, can be used similar to a powerful combination of + .hosts and .rhosts, + solving this problem. For example, if a + .k5login with the following + contents: + + tillman@example.org +jdoe@example.org + + Were to be placed into the home directory of the local user + webdevelopers then both principals listed + would have access to that account without requiring a shared + password. + + Reading the manual pages for these commands is recommended. + Note that the ksu manual page covers + .k5users. + + + + + <application>Kerberos</application> Tips, Tricks, and Troubleshooting + + + Kerberos5 + troubleshooting + + + + + When using either the Heimdal or MIT + Kerberos ports ensure that your + PATH environment variable lists the + Kerberos versions of the client + applications before the system versions. + + + + Do all the computers in your realm have synchronized + time settings? If not, authentication may fail. + describes how to synchronize + clocks using NTP. + + + + MIT and Heimdal inter-operate nicely. + Except for kadmin, the protocol for + which is not standardized. + + + + If you change your hostname, you also need to change your + host/ principal and update your keytab. + This also applies to special keytab entries like the + www/ principal used for Apache's + www/mod_auth_kerb. + + + + All hosts in your realm must be resolvable (both forwards + and reverse) in DNS (or + /etc/hosts as a minimum). CNAMEs + will work, but the A and PTR records must be correct and in + place. The error message is not very intuitive: + Kerberos5 refuses authentication because Read req + failed: Key table entry not found. + + + + Some operating systems that may being acting as clients + to your KDC do not set the permissions + for ksu to be setuid + root. This means that + ksu does not work, which is a good + security idea but annoying. This is not a + KDC error. + + + + With MIT + Kerberos, if you want to allow a + principal to have a ticket life longer than the default ten + hours, you must use modify_principal in + kadmin to change the maxlife of both the + principal in question and the krbtgt + principal. Then the principal can use the + -l option with kinit + to request a ticket with a longer lifetime. + + + + If you run a packet sniffer on your + KDC to add in troubleshooting and then + run kinit from a workstation, you will + notice that your TGT is sent + immediately upon running kinit — + even before you type your password! The explanation is + that the Kerberos server freely + transmits a TGT (Ticket Granting + Ticket) to any unauthorized request; however, every + TGT is encrypted in a key derived from + the user's password. Therefore, when a user types their + password it is not being sent to the KDC, + it is being used to decrypt the TGT that + kinit already obtained. If the decryption + process results in a valid ticket with a valid time stamp, + the user has valid Kerberos + credentials. These credentials include a session key for + establishing secure communications with the + Kerberos server in the future, as + well as the actual ticket-granting ticket, which is actually + encrypted with the Kerberos + server's own key. This second layer of encryption is + unknown to the user, but it is what allows the + Kerberos server to verify + the authenticity of each TGT. + + + + If you want to use long ticket lifetimes (a week, for + example) and you are using OpenSSH + to connect to the machine where your ticket is stored, make + sure that Kerberos + is set to no + in your sshd_config or else your tickets + will be deleted when you log out. + + + + Remember that host principals can have a longer ticket + lifetime as well. If your user principal has a lifetime of a + week but the host you are connecting to has a lifetime of nine + hours, you will have an expired host principal in your cache + and the ticket cache will not work as expected. + + + + When setting up a krb5.dict file to + prevent specific bad passwords from being used (the manual page + for kadmind covers this briefly), remember + that it only applies to principals that have a password policy + assigned to them. The krb5.dict files + format is simple: one string per line. Creating a symbolic + link to /usr/share/dict/words might be + useful. + + + + + + + Differences with the <acronym>MIT</acronym> port + + The major difference between the MIT + and Heimdal installs relates to the kadmin + program which has a different (but equivalent) set of commands + and uses a different protocol. This has a large implications + if your KDC is MIT as you + will not be able to use the Heimdal kadmin + program to administer your KDC remotely + (or vice versa, for that matter). + + The client applications may also take slightly different + command line options to accomplish the same tasks. Following + the instructions on the MIT + Kerberos web site + () + is recommended. Be careful of path issues: the + MIT port installs into + /usr/local/ by default, and the + normal system applications may be run instead + of MIT if your PATH + environment variable lists the system directories first. + + With the MIT + security/krb5 port + that is provided by &os;, be sure to read the + /usr/local/share/doc/krb5/README.FreeBSD + file installed by the port if you want to understand why logins + via telnetd and klogind + behave somewhat oddly. Most importantly, correcting the + incorrect permissions on cache file behavior + requires that the login.krb5 binary be used + for authentication so that it can properly change ownership for + the forwarded credentials. + + + + + Mitigating limitations found in <application>Kerberos</application> + + + Kerberos5 + limitations and shortcomings + + + + <application>Kerberos</application> is an all-or-nothing approach + + Every service enabled on the network must be modified to + work with Kerberos (or be otherwise + secured against network attacks) or else the users credentials + could be stolen and re-used. An example of this would be + Kerberos enabling all remote shells + (via rsh and telnet, for + example) but not converting the POP3 mail + server which sends passwords in plain text. + + + + + <application>Kerberos</application> is intended for single-user workstations + + In a multi-user environment, + Kerberos is less secure. + This is because it stores the tickets in the + /tmp directory, which is readable by all + users. If a user is sharing a computer with several other + people simultaneously (i.e. multi-user), it is possible that + the user's tickets can be stolen (copied) by another + user. + + This can be overcome with the -c + filename command-line option or (preferably) the + KRB5CCNAME environment variable, but this + is rarely done. In principal, storing the ticket in the users + home directory and using simple file permissions can mitigate + this problem. + + + + + The KDC is a single point of failure + + By design, the KDC must be as secure as + the master password database is contained on it. The + KDC should have absolutely no other + services running on it and should be physically secured. The + danger is high because Kerberos + stores all passwords encrypted with the same key (the + master key), which in turn is stored as a file + on the KDC. + + As a side note, a compromised master key is not quite as + bad as one might normally fear. The master key is only used + to encrypt the Kerberos database + and as a seed for the random number generator. As long as + access to your KDC is secure, an attacker + cannot do much with the master key. + + Additionally, if the KDC is unavailable + (perhaps due to a denial of service attack or network problems) + the network services are unusable as authentication can not be + performed, a recipe for a denial-of-service attack. This can + alleviated with multiple KDCs (a single + master and one or more slaves) and with careful implementation + of secondary or fall-back authentication + (PAM is excellent for this). + + + + + <application>Kerberos</application> Shortcomings + + Kerberos allows users, hosts + and services to authenticate between themselves. It does not + have a mechanism to authenticate the KDC + to the users, hosts or services. This means that a trojanned + kinit (for example) could record all user + names and passwords. Something like + security/tripwire or + other file system integrity checking tools can alleviate + this. + + + + + + Resources and further information + + + Kerberos5 + external resources + + + + + + The Kerberos FAQ + + + + Designing + an Authentication System: a Dialog in Four Scenes + + + + RFC 1510, + The Kerberos Network Authentication Service + (V5) + + + + MIT + Kerberos home page + + + + Heimdal + Kerberos home page + + + + + + + + + + + Tom + Rhodes + Written by: + + + + OpenSSL + + security + OpenSSL + + + One feature that many users overlook is the + OpenSSL toolkit included + in &os;. OpenSSL provides an + encryption transport layer on top of the normal communications + layer; thus allowing it to be intertwined with many network + applications and services. + + Some uses of OpenSSL may include + encrypted authentication of mail clients, web based transactions + such as credit card payments and more. Many ports such as + www/apache13-ssl, and + mail/sylpheed-claws + will offer compilation support for building with + OpenSSL. + + + In most cases the Ports Collection will attempt to build + the security/openssl port + unless the WITH_OPENSSL_BASE make variable + is explicitly set to yes. + + + The version of OpenSSL included + in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3), + Transport Layer Security v1 (TLSv1) network security protocols + and can be used as a general cryptographic library. + + + While OpenSSL supports the + IDEA algorithm, it is disabled by default + due to United States patents. To use it, the license should + be reviewed and, if the restrictions are acceptable, the + MAKE_IDEA variable must be set in + make.conf. + + + One of the most common uses of + OpenSSL is to provide certificates for + use with software applications. These certificates ensure + that the credentials of the company or individual are valid + and not fraudulent. If the certificate in question has + not been verified by one of the several Certificate Authorities, + or CAs, a warning is usually produced. A + Certificate Authority is a company, such as VeriSign, which will + sign certificates in order to validate credentials of individuals + or companies. This process has a cost associated with it and + is definitely not a requirement for using certificates; however, + it can put some of the more paranoid users at ease. + + + Generating Certificates + + + OpenSSL + certificate generation + + + To generate a certificate, the following command is + available: + + &prompt.root; openssl req -new -nodes -out req.pem -keyout cert.pem +Generating a 1024 bit RSA private key +................++++++ +.......................................++++++ +writing new private key to 'cert.pem' +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:US +State or Province Name (full name) [Some-State]:PA +Locality Name (eg, city) []:Pittsburgh +Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company +Organizational Unit Name (eg, section) []:Systems Administrator +Common Name (eg, YOUR name) []:localhost.example.org +Email Address []:trhodes@FreeBSD.org + +Please enter the following 'extra' attributes +to be sent with your certificate request +A challenge password []:SOME PASSWORD +An optional company name []:Another Name + + Notice the response directly after the + Common Name prompt shows a domain name. + This prompt requires a server name to be entered for + verification purposes; placing anything but a domain name + would yield a useless certificate. Other options, for + instance expire time, alternate encryption algorithms, etc. + are available. A complete list may be obtained by viewing + the &man.openssl.1; manual page. + + Two files should now exist in + the directory in which the aforementioned command was issued. + The certificate request, req.pem, may be + sent to a certificate authority who will validate the credentials + that you entered, sign the request and return the certificate to + you. The second file created will be named cert.pem + and is the private key for the certificate and should be + protected at all costs; if this falls in the hands of others it + can be used to impersonate you (or your server). + + In cases where a signature from a CA is + not required, a self signed certificate can be created. First, + generate the RSA key: + + &prompt.root; openssl dsaparam -rand -genkey -out myRSA.key 1024 + + Next, generate the CA key: + + &prompt.root; openssl gendsa -des3 -out myca.key myRSA.key + + Use this key to create the certificate: + + &prompt.root; openssl req -new -x509 -days 365 -key myca.key -out new.crt + + Two new files should appear in the directory: a certificate + authority signature file, myca.key and the + certificate itself, new.crt. These should + be placed in a directory, preferably under + /etc, which is readable + only by root. Permissions of 0700 should be fine for this and + they can be set with the chmod + utility. + + + + Using Certificates, an Example + + So what can these files do? A good use would be to + encrypt connections to the Sendmail + MTA. This would dissolve the use of clear + text authentication for users who send mail via the local + MTA. + + + This is not the best use in the world as some + MUAs will present the user with an + error if they have not installed the certificate locally. + Refer to the documentation included with the software for + more information on certificate installation. + + + The following lines should be placed inside the + local .mc file: + + dnl SSL Options +define(`confCACERT_PATH',`/etc/certs')dnl +define(`confCACERT',`/etc/certs/new.crt')dnl +define(`confSERVER_CERT',`/etc/certs/new.crt')dnl +define(`confSERVER_KEY',`/etc/certs/myca.key')dnl +define(`confTLS_SRV_OPTIONS', `V')dnl + + Where /etc/certs/ + is the directory to be used for storing the certificate + and key files locally. The last few requirements are a rebuild + of the local .cf file. This is easily + achieved by typing make + install within the + /etc/mail + directory. Follow that up with make + restart which should start the + Sendmail daemon. + + If all went well there will be no error messages in the + /var/log/maillog file and + Sendmail will show up in the process + list. + + For a simple test, simply connect to the mail server + using the &man.telnet.1; utility: + + &prompt.root; telnet example.com 25 +Trying 192.0.34.166... +Connected to example.com. +Escape character is '^]'. +220 example.com ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT) +ehlo example.com +250-example.com Hello example.com [192.0.34.166], pleased to meet you +250-ENHANCEDSTATUSCODES +250-PIPELINING +250-8BITMIME +250-SIZE +250-DSN +250-ETRN +250-AUTH LOGIN PLAIN +250-STARTTLS +250-DELIVERBY +250 HELP +quit +221 2.0.0 example.com closing connection +Connection closed by foreign host. + + If the STARTTLS line appears in the output + then everything is working correctly. + + + + + + + + Nik + Clayton + +
nik@FreeBSD.org
+ + Written by + + + + + + IPsec + + + VPN over IPsec + Creating a VPN between two networks, separated by the + Internet, using FreeBSD gateways. + + + + + + Hiten M. + Pandya + +
hmp@FreeBSD.org
+ + Written by + + + + + Understanding IPsec + + This section will guide you through the process of setting + up IPsec, and to use it in an environment which consists of + FreeBSD and µsoft.windows; 2000/XP + machines, to make them communicate securely. In order to set up + IPsec, it is necessary that you are familiar with the concepts + of building a custom kernel (see + ). + + IPsec is a protocol which sits on top + of the Internet Protocol (IP) layer. It allows two or more + hosts to communicate in a secure manner (hence the name). The + FreeBSD IPsec network stack is based on the + KAME implementation, + which has support for both protocol families, IPv4 and + IPv6. + + + FreeBSD contains a hardware + accelerated IPsec stack, known as Fast + IPsec, that was obtained from OpenBSD. It employs + cryptographic hardware (whenever possible) via the + &man.crypto.4; subsystem to optimize the performance of IPsec. + This subsystem is new, and does not support all the features + that are available in the KAME version of IPsec. However, in + order to enable hardware-accelerated IPsec, the following + kernel option has to be added to your kernel configuration + file: + + + kernel options + FAST_IPSEC + + + +options FAST_IPSEC # new IPsec (cannot define w/ IPSEC) + + + Note, that it is not currently possible to use the + Fast IPsec subsystem in lieu of the KAME + implementation of IPsec. Consult the &man.fast.ipsec.4; + manual page for more information. + + + + To let firewalls properly track state for &man.gif.4; + tunnels too, you have to enable the + in your kernel + configuration: + + +options IPSEC_FILTERGIF #filter ipsec packets from a tunnel + + + + + IPsec + ESP + + + + IPsec + AH + + + IPsec consists of two sub-protocols: + + + + Encapsulated Security Payload + (ESP), protects the IP packet data from third + party interference, by encrypting the contents using + symmetric cryptography algorithms (like Blowfish, + 3DES). + + + Authentication Header (AH), + protects the IP packet header from third party interference + and spoofing, by computing a cryptographic checksum and + hashing the IP packet header fields with a secure hashing + function. This is then followed by an additional header + that contains the hash, to allow the information in the + packet to be authenticated. + + + + ESP and AH can + either be used together or separately, depending on the + environment. + + + VPN + + + + virtual private network + VPN + + + IPsec can either be used to directly encrypt the traffic + between two hosts (known as Transport + Mode); or to build virtual tunnels + between two subnets, which could be used for secure + communication between two corporate networks (known as + Tunnel Mode). The latter is more commonly + known as a Virtual Private Network (VPN). + The &man.ipsec.4; manual page should be consulted for detailed + information on the IPsec subsystem in FreeBSD. + + To add IPsec support to your kernel, add the following + options to your kernel configuration file: + + + kernel options + IPSEC + + + + kernel options + IPSEC_ESP + + + +options IPSEC #IP security +options IPSEC_ESP #IP security (crypto; define w/ IPSEC) + + + + kernel options + IPSEC_DEBUG + + + If IPsec debugging support is desired, the following + kernel option should also be added: + + +options IPSEC_DEBUG #debug for IP security + + + + + The Problem + + There is no standard for what constitutes a VPN. VPNs can + be implemented using a number of different technologies, each of + which have their own strengths and weaknesses. This section + presents a scenario, and the strategies used for implementing a + VPN for this scenario. + + + + The Scenario: Two networks, connected to the Internet, to + behave as one + + + VPN + creating + + + The premise is as follows: + + + + You have at least two sites + + + Both sites are using IP internally + + + Both sites are connected to the Internet, through a + gateway that is running FreeBSD. + + + The gateway on each network has at least one public IP + address. + + + The internal addresses of the two networks can be + public or private IP addresses, it does not matter. You can + be running NAT on the gateway machine if necessary. + + + The internal IP addresses of the two networks + do not collide. While I expect it is + theoretically possible to use a combination of VPN + technology and NAT to get this to work, I expect it to be a + configuration nightmare. + + + + If you find that you are trying to connect two networks, + both of which, internally, use the same private IP address range + (e.g. both of them use 192.168.1.x), then one of the networks will + have to be renumbered. + + The network topology might look something like this: + + + + + + + +Network #1 [ Internal Hosts ] Private Net, 192.168.1.2-254 + [ Win9x/NT/2K ] + [ UNIX ] + | + | + .---[fxp1]---. Private IP, 192.168.1.1 + | FreeBSD | + `---[fxp0]---' Public IP, A.B.C.D + | + | + -=-=- Internet -=-=- + | + | + .---[fxp0]---. Public IP, W.X.Y.Z + | FreeBSD | + `---[fxp1]---' Private IP, 192.168.2.1 + | + | +Network #2 [ Internal Hosts ] + [ Win9x/NT/2K ] Private Net, 192.168.2.2-254 + [ UNIX ] + + + + Notice the two public IP addresses. I will use the letters to + refer to them in the rest of this article. Anywhere you see those + letters in this article, replace them with your own public IP + addresses. Note also that internally, the two gateway + machines have .1 IP addresses, and that the two networks have + different private IP addresses (192.168.1.x and 192.168.2.x respectively). All the + machines on the private networks have been configured to use the + .1 machine as their default + gateway. + + The intention is that, from a network point of view, each + network should view the machines on the other network as though + they were directly attached the same router -- albeit a slightly + slow router with an occasional tendency to drop packets. + + This means that (for example), machine 192.168.1.20 should be able to run + + ping 192.168.2.34 + + and have it work, transparently. &windows; machines should + be able to see the machines on the other network, browse file + shares, and so on, in exactly the same way that they can browse + machines on the local network. + + And the whole thing has to be secure. This means that + traffic between the two networks has to be encrypted. + + Creating a VPN between these two networks is a multi-step + process. The stages are as follows: + + + + Create a virtual network link between the two + networks, across the Internet. Test it, using tools like + &man.ping.8;, to make sure it works. + + + + Apply security policies to ensure that traffic between + the two networks is transparently encrypted and decrypted as + necessary. Test this, using tools like &man.tcpdump.1;, to + ensure that traffic is encrypted. + + + + Configure additional software on the FreeBSD gateways, + to allow &windows; machines to see one another across the + VPN. + + + + + Step 1: Creating and testing a <quote>virtual</quote> + network link + + Suppose that you were logged in to the gateway machine on + network #1 (with public IP address A.B.C.D, private IP address 192.168.1.1), and you ran ping + 192.168.2.1, which is the private address of the machine + with IP address W.X.Y.Z. What + needs to happen in order for this to work? + + + + The gateway machine needs to know how to reach 192.168.2.1. In other words, it needs + to have a route to 192.168.2.1. + + + Private IP addresses, such as those in the 192.168.x range are not supposed to + appear on the Internet at large. Instead, each packet you + send to 192.168.2.1 will need + to be wrapped up inside another packet. This packet will need + to appear to be from A.B.C.D, + and it will have to be sent to W.X.Y.Z. This process is called + encapsulation. + + + Once this packet arrives at W.X.Y.Z it will need to + unencapsulated, and delivered to 192.168.2.1. + + + + You can think of this as requiring a tunnel + between the two networks. The two tunnel mouths are the IP + addresses A.B.C.D and W.X.Y.Z, and the tunnel must be told the + addresses of the private IP addresses that will be allowed to pass + through it. The tunnel is used to transfer traffic with private + IP addresses across the public Internet. + + This tunnel is created by using the generic interface, or + gif devices on FreeBSD. As you can + imagine, the gif interface on each + gateway host must be configured with four IP addresses; two for + the public IP addresses, and two for the private IP + addresses. + + Support for the gif device must be compiled in to the + &os; kernel on both machines. You can do this by adding the + line: + + device gif + + to the kernel configuration files on both machines, and + then compile, install, and reboot as normal. + + Configuring the tunnel is a two step process. First the + tunnel must be told what the outside (or public) IP addresses + are, using &man.ifconfig.8;. Then the private IP addresses must be + configured using &man.ifconfig.8;. + + On the gateway machine on network #1 you would run the + following two commands to configure the tunnel. + + ifconfig gif0 A.B.C.D W.X.Y.Z +ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff + + + On the other gateway machine you run the same commands, + but with the order of the IP addresses reversed. + + ifconfig gif0 W.X.Y.Z A.B.C.D +ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff + + + You can then run: + + ifconfig gif0 + + to see the configuration. For example, on the network #1 + gateway, you would see this: + + &prompt.root; ifconfig gif0 +gif0: flags=8011<UP,POINTTOPOINT,MULTICAST> mtu 1280 +inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff +physical address inet A.B.C.D --> W.X.Y.Z + + + As you can see, a tunnel has been created between the + physical addresses A.B.C.D and + W.X.Y.Z, and the traffic allowed + through the tunnel is that between 192.168.1.1 and 192.168.2.1. + + This will also have added an entry to the routing table + on both machines, which you can examine with the command netstat -rn. + This output is from the gateway host on network #1. + + &prompt.root; netstat -rn +Routing tables + +Internet: +Destination Gateway Flags Refs Use Netif Expire +... +192.168.2.1 192.168.1.1 UH 0 0 gif0 +... + + + As the Flags value indicates, this is a + host route, which means that each gateway knows how to reach the + other gateway, but they do not know how to reach the rest of + their respective networks. That problem will be fixed + shortly. + + It is likely that you are running a firewall on both + machines. This will need to be circumvented for your VPN + traffic. You might want to allow all traffic between both + networks, or you might want to include firewall rules that + protect both ends of the VPN from one another. + + It greatly simplifies testing if you configure the + firewall to allow all traffic through the VPN. You can always + tighten things up later. If you are using &man.ipfw.8; on the + gateway machines then a command like + + ipfw add 1 allow ip from any to any via gif0 + + will allow all traffic between the two end points of the + VPN, without affecting your other firewall rules. Obviously + you will need to run this command on both gateway hosts. + + This is sufficient to allow each gateway machine to ping + the other. On 192.168.1.1, you + should be able to run + + ping 192.168.2.1 + + and get a response, and you should be able to do the same + thing on the other gateway machine. + + However, you will not be able to reach internal machines + on either network yet. This is because of the routing -- + although the gateway machines know how to reach one another, + they do not know how to reach the network behind each one. + + To solve this problem you must add a static route on each + gateway machine. The command to do this on the first gateway + would be: + + route add 192.168.2.0 192.168.2.1 netmask 0xffffff00 + + + This says In order to reach the hosts on the + network 192.168.2.0, send the + packets to the host 192.168.2.1. You will need to + run a similar command on the other gateway, but with the + 192.168.1.x addresses + instead. + + IP traffic from hosts on one network will now be able to + reach hosts on the other network. + + That has now created two thirds of a VPN between the two + networks, in as much as it is virtual and it is a + network. It is not private yet. You can test + this using &man.ping.8; and &man.tcpdump.1;. Log in to the + gateway host and run + + tcpdump dst host 192.168.2.1 + + In another log in session on the same host run + + ping 192.168.2.1 + + You will see output that looks something like this: + + +16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request +16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply +16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request +16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply +16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request +16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply + + + As you can see, the ICMP messages are going back and forth + unencrypted. If you had used the parameter to + &man.tcpdump.1; to grab more bytes of data from the packets you + would see more information. + + Obviously this is unacceptable. The next section will + discuss securing the link between the two networks so that it + all traffic is automatically encrypted. + + + Summary: + + Configure both kernels with device gif. + + + Edit /etc/rc.conf on gateway host + #1 and add the following lines (replacing IP addresses as + necessary). + gifconfig_gif0="A.B.C.D W.X.Y.Z" +ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff" +static_routes="vpn" +route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00" + + + + + Edit your firewall script + (/etc/rc.firewall, or similar) on both + hosts, and add + + ipfw add 1 allow ip from any to any via gif0 + + + Make similar changes to + /etc/rc.conf on gateway host #2, + reversing the order of IP addresses. + + + + + + Step 2: Securing the link + + To secure the link we will be using IPsec. IPsec provides + a mechanism for two hosts to agree on an encryption key, and to + then use this key in order to encrypt data between the two + hosts. + + The are two areas of configuration to be considered here. + + + + There must be a mechanism for two hosts to agree on the + encryption mechanism to use. Once two hosts have agreed on + this mechanism there is said to be a security association + between them. + + + There must be a mechanism for specifying which traffic + should be encrypted. Obviously, you do not want to encrypt + all your outgoing traffic -- you only want to encrypt the + traffic that is part of the VPN. The rules that you put in + place to determine what traffic will be encrypted are called + security policies. + + + + Security associations and security policies are both + maintained by the kernel, and can be modified by userland + programs. However, before you can do this you must configure the + kernel to support IPsec and the Encapsulated Security Payload + (ESP) protocol. This is done by configuring a kernel with: + + + kernel options + IPSEC + + + options IPSEC +options IPSEC_ESP + + + and recompiling, reinstalling, and rebooting. As before + you will need to do this to the kernels on both of the gateway + hosts. + + + IKE + + + You have two choices when it comes to setting up security + associations. You can configure them by hand between two hosts, + which entails choosing the encryption algorithm, encryption keys, + and so forth, or you can use daemons that implement the Internet + Key Exchange protocol (IKE) to do this for you. + + I recommend the latter. Apart from anything else, it is + easier to set up. + + + IPsec + security policies + + + + setkey + + + Editing and displaying security policies is carried out + using &man.setkey.8;. By analogy, setkey is + to the kernel's security policy tables as &man.route.8; is to + the kernel's routing tables. setkey can + also display the current security associations, and to continue + the analogy further, is akin to netstat -r + in that respect. + + There are a number of choices for daemons to manage + security associations with FreeBSD. This article will describe + how to use one of these, racoon — which is available from + security/ipsec-tools in the &os; Ports + collection. + + + racoon + + + The racoon software must be run on both gateway hosts. On each host it + is configured with the IP address of the other end of the VPN, + and a secret key (which you choose, and must be the same on both + gateways). + + The two daemons then contact one another, confirm that they + are who they say they are (by using the secret key that you + configured). The daemons then generate a new secret key, and use + this to encrypt the traffic over the VPN. They periodically + change this secret, so that even if an attacker were to crack one + of the keys (which is as theoretically close to unfeasible as it + gets) it will not do them much good -- by the time they have cracked + the key the two daemons have chosen another one. + + The configuration file for racoon is stored in + ${PREFIX}/etc/racoon. You should find a + configuration file there, which should not need to be changed + too much. The other component of racoon's configuration, + which you will need to change, is the pre-shared + key. + + The default racoon configuration expects to find this in + the file ${PREFIX}/etc/racoon/psk.txt. It is important to note + that the pre-shared key is not the key that will be used to + encrypt your traffic across the VPN link, it is simply a token + that allows the key management daemons to trust one another. + + psk.txt contains a line for each + remote site you are dealing with. In this example, where there + are two sites, each psk.txt file will contain one line (because + each end of the VPN is only dealing with one other end). + + On gateway host #1 this line should look like this: + + W.X.Y.Z secret + + That is, the public IP address of the remote end, + whitespace, and a text string that provides the secret. + Obviously, you should not use secret as your key -- the normal + rules for choosing a password apply. + + On gateway host #2 the line would look like this + + A.B.C.D secret + + That is, the public IP address of the remote end, and the + same secret key. psk.txt must be mode + 0600 (i.e., only read/write to + root) before racoon will run. + + You must run racoon on both gateway machines. You will + also need to add some firewall rules to allow the IKE traffic, + which is carried over UDP to the ISAKMP (Internet Security Association + Key Management Protocol) port. Again, this should be fairly early in + your firewall ruleset. + + ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp +ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp + + + Once racoon is running you can try pinging one gateway host + from the other. The connection is still not encrypted, but + racoon will then set up the security associations between the two + hosts -- this might take a moment, and you may see this as a + short delay before the ping commands start responding. + + Once the security association has been set up you can + view it using &man.setkey.8;. Run + + setkey -D + + on either host to view the security association information. + + That's one half of the problem. They other half is setting + your security policies. + + To create a sensible security policy, let's review what's + been set up so far. This discussions hold for both ends of the + link. + + Each IP packet that you send out has a header that contains + data about the packet. The header includes the IP addresses of + both the source and destination. As we already know, private IP + addresses, such as the 192.168.x.y + range are not supposed to appear on the public Internet. + Instead, they must first be encapsulated inside another packet. + This packet must have the public source and destination IP + addresses substituted for the private addresses. + + So if your outgoing packet started looking like this: + + + + + + + + + .----------------------. + | Src: 192.168.1.1 | + | Dst: 192.168.2.1 | + | <other header info> | + +----------------------+ + | <packet data> | + `----------------------' + + + + Then it will be encapsulated inside another packet, looking + something like this: + + + + + + + + + .--------------------------. + | Src: A.B.C.D | + | Dst: W.X.Y.Z | + | <other header info> | + +--------------------------+ + | .----------------------. | + | | Src: 192.168.1.1 | | + | | Dst: 192.168.2.1 | | + | | <other header info> | | + | +----------------------+ | + | | <packet data> | | + | `----------------------' | + `--------------------------' + + + + This encapsulation is carried out by the + gif device. As + you can see, the packet now has real IP addresses on the outside, + and our original packet has been wrapped up as data inside the + packet that will be put out on the Internet. + + Obviously, we want all traffic between the VPNs to be + encrypted. You might try putting this in to words, as: + + If a packet leaves from A.B.C.D, and it is destined for W.X.Y.Z, then encrypt it, using the + necessary security associations. + + If a packet arrives from W.X.Y.Z, and it is destined for A.B.C.D, then decrypt it, using the + necessary security associations. + + That's close, but not quite right. If you did this, all + traffic to and from W.X.Y.Z, even + traffic that was not part of the VPN, would be encrypted. That's + not quite what you want. The correct policy is as follows + + If a packet leaves from A.B.C.D, and that packet is encapsulating + another packet, and it is destined for W.X.Y.Z, then encrypt it, using the + necessary security associations. + + If a packet arrives from W.X.Y.Z, and that packet is encapsulating + another packet, and it is destined for A.B.C.D, then decrypt it, using the + necessary security associations. + + A subtle change, but a necessary one. + + Security policies are also set using &man.setkey.8;. + &man.setkey.8; features a configuration language for defining the + policy. You can either enter configuration instructions via + stdin, or you can use the option to specify a + filename that contains configuration instructions. + + The configuration on gateway host #1 (which has the public + IP address A.B.C.D) to force all + outbound traffic to W.X.Y.Z to be + encrypted is: + + +spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require; + + + Put these commands in a file (e.g. + /etc/ipsec.conf) and then run + + &prompt.root; setkey -f /etc/ipsec.conf + + tells &man.setkey.8; that we want + to add a rule to the secure policy database. The rest of this + line specifies which packets will match this policy. A.B.C.D/32 and W.X.Y.Z/32 are the IP addresses and + netmasks that identify the network or hosts that this policy will + apply to. In this case, we want it to apply to traffic between + these two hosts. tells the kernel that + this policy should only apply to packets that encapsulate other + packets. says that this policy applies + to outgoing packets, and says that the + packet will be secured. + + The second line specifies how this packet will be + encrypted. is the protocol that will be + used, while indicates that the packet + will be further encapsulated in an IPsec packet. The repeated + use of A.B.C.D and W.X.Y.Z is used to select the security + association to use, and the final + mandates that packets must be encrypted if they match this + rule. + + This rule only matches outgoing packets. You will need a + similar rule to match incoming packets. + + spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require; + + Note the instead of + in this case, and the necessary reversal of + the IP addresses. + + The other gateway host (which has the public IP address + W.X.Y.Z) will need similar rules. + + spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require; +spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require; + + Finally, you need to add firewall rules to allow ESP and + IPENCAP packets back and forth. These rules will need to be + added to both hosts. + + ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z +ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D +ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z +ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D + + + Because the rules are symmetric you can use the same rules + on each gateway host. + + Outgoing packets will now look something like this: + + + + + + + + + .------------------------------. --------------------------. + | Src: A.B.C.D | | + | Dst: W.X.Y.Z | | + | <other header info> | | Encrypted + +------------------------------+ | packet. + | .--------------------------. | -------------. | contents + | | Src: A.B.C.D | | | | are + | | Dst: W.X.Y.Z | | | | completely + | | <other header info> | | | |- secure + | +--------------------------+ | | Encap'd | from third + | | .----------------------. | | -. | packet | party + | | | Src: 192.168.1.1 | | | | Original |- with real | snooping + | | | Dst: 192.168.2.1 | | | | packet, | IP addr | + | | | <other header info> | | | |- private | | + | | +----------------------+ | | | IP addr | | + | | | <packet data> | | | | | | + | | `----------------------' | | -' | | + | `--------------------------' | -------------' | + `------------------------------' --------------------------' + + + + + When they are received by the far end of the VPN they will + first be decrypted (using the security associations that have + been negotiated by racoon). Then they will enter the + gif interface, which will unwrap + the second layer, until you are left with the innermost + packet, which can then travel in to the inner network. + + You can check the security using the same &man.ping.8; test from + earlier. First, log in to the + A.B.C.D gateway machine, and + run: + + tcpdump dst host 192.168.2.1 + + In another log in session on the same host run + + ping 192.168.2.1 + + This time you should see output like the following: + + XXX tcpdump output + + Now, as you can see, &man.tcpdump.1; shows the ESP packets. If + you try to examine them with the option you will see + (apparently) gibberish, because of the encryption. + + Congratulations. You have just set up a VPN between two + remote sites. + + + Summary + + Configure both kernels with: + + options IPSEC +options IPSEC_ESP + + + + Install security/ipsec-tools. Edit + ${PREFIX}/etc/racoon/psk.txt on both + gateway hosts, adding an entry for the remote host's IP + address and a secret key that they both know. Make sure + this file is mode 0600. + + + Add the following lines to + /etc/rc.conf on each host: + + ipsec_enable="YES" +ipsec_file="/etc/ipsec.conf" + + + + Create an /etc/ipsec.conf on each + host that contains the necessary spdadd lines. On gateway + host #1 this would be: + + +spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec + esp/tunnel/A.B.C.D-W.X.Y.Z/require; +spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec + esp/tunnel/W.X.Y.Z-A.B.C.D/require; + + + On gateway host #2 this would be: + + +spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec + esp/tunnel/W.X.Y.Z-A.B.C.D/require; +spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec + esp/tunnel/A.B.C.D-W.X.Y.Z/require; + + + + Add firewall rules to allow IKE, ESP, and IPENCAP + traffic to both hosts: + + +ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp +ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp +ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z +ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D +ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z +ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D + + + + + The previous two steps should suffice to get the VPN up and + running. Machines on each network will be able to refer to one + another using IP addresses, and all traffic across the link will + be automatically and securely encrypted. + + + + + + + + + Chern + Lee + Contributed by + + + + + + OpenSSH + OpenSSH + + security + OpenSSH + + + OpenSSH is a set of network connectivity tools used to + access remote machines securely. It can be used as a direct + replacement for rlogin, + rsh, rcp, and + telnet. Additionally, TCP/IP + connections can be tunneled/forwarded securely through SSH. + OpenSSH encrypts all traffic to effectively eliminate eavesdropping, + connection hijacking, and other network-level attacks. + + OpenSSH is maintained by the OpenBSD project, and is based + upon SSH v1.2.12 with all the recent bug fixes and updates. It + is compatible with both SSH protocols 1 and 2. + + + Advantages of Using OpenSSH + + Normally, when using &man.telnet.1; or &man.rlogin.1;, + data is sent over the network in an clear, un-encrypted form. + Network sniffers anywhere in between the client and server can + steal your user/password information or data transferred in + your session. OpenSSH offers a variety of authentication and + encryption methods to prevent this from happening. + + + + Enabling sshd + + OpenSSH + enabling + + + The + sshd is an option presented during + a Standard install of &os;. To see if + sshd is enabled, check the + rc.conf file for: + sshd_enable="YES" + This will load &man.sshd.8;, the daemon program for OpenSSH, + the next time your system initializes. Alternatively, it is + possible to use /etc/rc.d/sshd &man.rc.8; + script to start OpenSSH: + + /etc/rc.d/sshd start + + + + SSH Client + + OpenSSH + client + + + The &man.ssh.1; utility works similarly to + &man.rlogin.1;. + + &prompt.root; ssh user@example.com +Host key not found from the list of known hosts. +Are you sure you want to continue connecting (yes/no)? yes +Host 'example.com' added to the list of known hosts. +user@example.com's password: ******* + + The login will continue just as it would have if a session was + created using rlogin or + telnet. SSH utilizes a key fingerprint + system for verifying the authenticity of the server when the + client connects. The user is prompted to enter + yes only when + connecting for the first time. Future attempts to login are all + verified against the saved fingerprint key. The SSH client + will alert you if the saved fingerprint differs from the + received fingerprint on future login attempts. The fingerprints + are saved in ~/.ssh/known_hosts, or + ~/.ssh/known_hosts2 for SSH v2 + fingerprints. + + By default, recent versions of the + OpenSSH servers only accept SSH v2 + connections. The client will use version 2 if possible and + will fall back to version 1. The client can also be forced to + use one or the other by passing it the or + for version 1 or version 2, respectively. + The version 1 compatibility is maintained in the client for + backwards compatibility with older versions. + + + + Secure Copy + + OpenSSH + secure copy + + scp + + The &man.scp.1; command works similarly to + &man.rcp.1;; it copies a file to or from a remote machine, + except in a secure fashion. + + &prompt.root; scp user@example.com:/COPYRIGHT COPYRIGHT +user@example.com's password: ******* +COPYRIGHT 100% |*****************************| 4735 +00:00 +&prompt.root; + Since the fingerprint was already saved for this host in the + previous example, it is verified when using &man.scp.1; + here. + + The arguments passed to &man.scp.1; are similar + to &man.cp.1;, with the file or files in the first + argument, and the destination in the second. Since the file is + fetched over the network, through SSH, one or more of the file + arguments takes on the form + . + + + + + Configuration + + OpenSSH + configuration + + + The system-wide configuration files for both the + OpenSSH daemon and client reside + within the /etc/ssh directory. + + ssh_config configures the client + settings, while sshd_config configures the + daemon. + + Additionally, the + (/usr/sbin/sshd by default), and + rc.conf + options can provide more levels of configuration. + + + + ssh-keygen + + Instead of using passwords, &man.ssh-keygen.1; can + be used to generate DSA or RSA keys to authenticate a user: + + &prompt.user; ssh-keygen -t dsa +Generating public/private dsa key pair. +Enter file in which to save the key (/home/user/.ssh/id_dsa): +Created directory '/home/user/.ssh'. +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /home/user/.ssh/id_dsa. +Your public key has been saved in /home/user/.ssh/id_dsa.pub. +The key fingerprint is: +bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com + + + &man.ssh-keygen.1; will create a public and private + key pair for use in authentication. The private key is stored in + ~/.ssh/id_dsa or + ~/.ssh/id_rsa, whereas the public key is + stored in ~/.ssh/id_dsa.pub or + ~/.ssh/id_rsa.pub, respectively for DSA and + RSA key types. The public key must be placed in + ~/.ssh/authorized_keys of the remote + machine in order for the setup to work. Similarly, RSA version + 1 public keys should be placed in + ~/.ssh/authorized_keys. + + This will allow connection to the remote machine based upon + SSH keys instead of passwords. + + If a passphrase is used in &man.ssh-keygen.1;, the user + will be prompted for a password each time in order to use the + private key. &man.ssh-agent.1; can alleviate the strain of + repeatedly entering long passphrases, and is explored in the + section below. + + The various options and files can be different + according to the OpenSSH version + you have on your system; to avoid problems you should consult + the &man.ssh-keygen.1; manual page. + + + + ssh-agent and ssh-add + + The &man.ssh-agent.1; and &man.ssh-add.1; utilities provide + methods for SSH keys to be loaded + into memory for use, without needing to type the passphrase + each time. + + The &man.ssh-agent.1; utility will handle the authentication + using the private key(s) that are loaded into it. + &man.ssh-agent.1; should be used to launch another application. + At the most basic level, it could spawn a shell or at a more + advanced level, a window manager. + + To use &man.ssh-agent.1; in a shell, first it will need to + be spawned with a shell as an argument. Secondly, the + identity needs to be added by running &man.ssh-add.1; and + providing it the passphrase for the private key. Once these + steps have been completed the user will be able to &man.ssh.1; + to any host that has the corresponding public key installed. + For example: + + &prompt.user; ssh-agent csh +&prompt.user; ssh-add +Enter passphrase for /home/user/.ssh/id_dsa: +Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) +&prompt.user; + + To use &man.ssh-agent.1; in X11, a call to + &man.ssh-agent.1; will need to be placed in + ~/.xinitrc. This will provide the + &man.ssh-agent.1; services to all programs launched in X11. + An example ~/.xinitrc file might look + like this: + + exec ssh-agent startxfce4 + + This would launch &man.ssh-agent.1;, which would in turn + launch XFCE, every time X11 starts. + Then once that is done and X11 has been restarted so that the + changes can take effect, simply run &man.ssh-add.1; to load + all of your SSH keys. + + + + SSH Tunneling + + OpenSSH + tunneling + + + OpenSSH has the ability to create a tunnel to encapsulate + another protocol in an encrypted session. + + The following command tells &man.ssh.1; to create a tunnel + for telnet: + + &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com +&prompt.user; + + The ssh command is used with the + following options: + + + + + + + Forces ssh to use version 2 of + the protocol. (Do not use if you are working with older + SSH servers) + + + + + + + + Indicates no command, or tunnel only. If omitted, + ssh would initiate a normal + session. + + + + + + + + Forces ssh to run in the + background. + + + + + + + + Indicates a local tunnel in + localport:remotehost:remoteport + fashion. + + + + + + + + The remote SSH server. + + + + + + An SSH tunnel works by creating a listen socket on + localhost on the specified port. + It then forwards any connection received + on the local host/port via the SSH connection to the specified + remote host and port. + + In the example, port 5023 on + localhost is being forwarded to port + 23 on localhost + of the remote machine. Since 23 is telnet, + this would create a secure telnet session through an SSH tunnel. + + This can be used to wrap any number of insecure TCP + protocols such as SMTP, POP3, FTP, etc. + + + Using SSH to Create a Secure Tunnel for SMTP + + &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com +user@mailserver.example.com's password: ***** +&prompt.user; telnet localhost 5025 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +220 mailserver.example.com ESMTP + + This can be used in conjunction with an + &man.ssh-keygen.1; and additional user accounts to create a + more seamless/hassle-free SSH tunneling environment. Keys + can be used in place of typing a password, and the tunnels + can be run as a separate user. + + + + Practical SSH Tunneling Examples + + + Secure Access of a POP3 Server + + At work, there is an SSH server that accepts + connections from the outside. On the same office network + resides a mail server running a POP3 server. The network, + or network path between your home and office may or may not + be completely trustable. Because of this, you need to check + your e-mail in a secure manner. The solution is to create + an SSH connection to your office's SSH server, and tunnel + through to the mail server. + + &prompt.user; ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com +user@ssh-server.example.com's password: ****** + + When the tunnel is up and running, you can point your + mail client to send POP3 requests to localhost + port 2110. A connection here will be forwarded securely across + the tunnel to mail.example.com. + + + + Bypassing a Draconian Firewall + + Some network administrators impose extremely draconian + firewall rules, filtering not only incoming connections, + but outgoing connections. You may be only given access + to contact remote machines on ports 22 and 80 for SSH + and web surfing. + + You may wish to access another (perhaps non-work + related) service, such as an Ogg Vorbis server to stream + music. If this Ogg Vorbis server is streaming on some other + port than 22 or 80, you will not be able to access it. + + The solution is to create an SSH connection to a machine + outside of your network's firewall, and use it to tunnel to + the Ogg Vorbis server. + + &prompt.user; ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org +user@unfirewalled-system.example.org's password: ******* + + Your streaming client can now be pointed to + localhost port 8888, which will be + forwarded over to music.example.com port + 8000, successfully evading the firewall. + + + + + + The <varname>AllowUsers</varname> Users Option + + It is often a good idea to limit which users can log in and + from where. The AllowUsers option is a good + way to accomplish this. For example, to only allow the + root user to log in from + 192.168.1.32, something like this + would be appropriate in the + /etc/ssh/sshd_config file: + + AllowUsers root@192.168.1.32 + + To allow the user admin to log in from + anywhere, just list the username by itself: + + AllowUsers admin + + Multiple users should be listed on the same line, like so: + + AllowUsers root@192.168.1.32 admin + + + It is important that you list each user that needs to + log in to this machine; otherwise they will be locked out. + + + After making changes to + /etc/ssh/sshd_config you must tell + &man.sshd.8; to reload its config files, by running: + + &prompt.root; /etc/rc.d/sshd reload + + + + Further Reading + OpenSSH + &man.ssh.1; &man.scp.1; &man.ssh-keygen.1; + &man.ssh-agent.1; &man.ssh-add.1; &man.ssh.config.5; + &man.sshd.8; &man.sftp-server.8; &man.sshd.config.5; + + + + + + + + Tom + Rhodes + Contributed by + + + + + ACL + + File System Access Control Lists + + In conjunction with file system enhancements like snapshots, FreeBSD 5.0 + and later offers the security of File System Access Control Lists + (ACLs). + + Access Control Lists extend the standard &unix; + permission model in a highly compatible (&posix;.1e) way. This feature + permits an administrator to make use of and take advantage of a + more sophisticated security model. + + To enable ACL support for UFS + file systems, the following: + + options UFS_ACL + + must be compiled into the kernel. If this option has + not been compiled in, a warning message will be displayed + when attempting to mount a file system supporting ACLs. + This option is included in the GENERIC kernel. + ACLs rely on extended attributes being enabled on + the file system. Extended attributes are natively supported in the next generation + &unix; file system, UFS2. + + A higher level of administrative overhead is required to + configure extended attributes on UFS1 than on + UFS2. The performance of extended attributes + on UFS2 is also substantially higher. As a + result, UFS2 is generally recommended in preference + to UFS1 for use with access control lists. + + ACLs are enabled by the mount-time administrative + flag, , which may be added to /etc/fstab. + The mount-time flag can also be automatically set in a persistent manner using + &man.tunefs.8; to modify a superblock ACLs flag in the + file system header. In general, it is preferred to use the superblock flag + for several reasons: + + + + The mount-time ACLs flag cannot be changed by a + remount (&man.mount.8; ), only by means of a complete + &man.umount.8; and fresh &man.mount.8;. This means that + ACLs cannot be enabled on the root file system after boot. + It also means that you cannot change the disposition of a file system once + it is in use. + + + + Setting the superblock flag will cause the file system to always be + mounted with ACLs enabled even if there is not an + fstab entry or if the devices re-order. This prevents + accidental mounting of the file system without ACLs + enabled, which can result in ACLs being improperly enforced, + and hence security problems. + + + + We may change the ACLs behavior to allow the flag to + be enabled without a complete fresh &man.mount.8;, but we consider it desirable to + discourage accidental mounting without ACLs enabled, because you + can shoot your feet quite nastily if you enable ACLs, then disable + them, then re-enable them without flushing the extended attributes. In general, once + you have enabled ACLs on a file system, they should not be disabled, + as the resulting file protections may not be compatible with those intended by the + users of the system, and re-enabling ACLs may re-attach the previous + ACLs to files that have since had their permissions changed, + resulting in other unpredictable behavior. + + File systems with ACLs enabled will show a + + (plus) sign in their permission settings when viewed. For example: + + drwx------ 2 robert robert 512 Dec 27 11:54 private +drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1 +drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2 +drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3 +drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html + + Here we see that the directory1, + directory2, and directory3 + directories are all taking advantage of ACLs. The + public_html directory is not. + + + Making Use of <acronym>ACL</acronym>s + + The file system ACLs can be viewed by the + &man.getfacl.1; utility. For instance, to view the + ACL settings on the test + file, one would use the command: + + &prompt.user; getfacl test + #file:test + #owner:1001 + #group:1001 + user::rw- + group::r-- + other::r-- + + To change the ACL settings on this file, + invoke the &man.setfacl.1; utility. Observe: + + &prompt.user; setfacl -k test + + The flag will remove all of the + currently defined ACLs from a file or file + system. The more preferable method would be to use + as it leaves the basic fields required for + ACLs to work. + + &prompt.user; setfacl -m u:trhodes:rwx,group:web:r--,o::--- test + + In the aforementioned command, the + option was used to modify the default ACL + entries. Since there were no pre-defined entries, as they were + removed by the previous command, this will restore the default + options and assign the options listed. Take care to notice that + if you add a user or group which does not exist on the system, + an Invalid argument error will be printed + to stdout. + + + + + + + + Tom + Rhodes + Contributed by + + + + + + Portaudit + + Monitoring Third Party Security Issues + + In recent years, the security world has made many improvements + to how vulnerability assessment is handled. The threat of system + intrusion increases as third party utilities are installed and + configured for virtually any operating system available + today. + + Vulnerability assessment is a key factor in security, and + while &os; releases advisories for the base system, doing so + for every third party utility is beyond the &os; Project's + capability. There is a way to mitigate third party + vulnerabilities and warn administrators of known security + issues. A &os; add on utility known as + Portaudit exists solely for this + purpose. + + The security/portaudit port + polls a database, updated and maintained by the &os; Security + Team and ports developers, for known security issues. + + To begin using Portaudit, one + must install it from the Ports Collection: + + &prompt.root; cd /usr/ports/security/portaudit && make install clean + + During the install process, the configuration files for + &man.periodic.8; will be updated, permitting + Portaudit output in the daily security + runs. Ensure the daily security run emails, which are sent to + root's email account, are being read. No + more configuration will be required here. + + After installation, an administrator can update the database + and view known vulnerabilities in installed packages by invoking + the following command: + + &prompt.root; portaudit -Fda + + + The database will automatically be updated during the + &man.periodic.8; run; thus, the previous command is completely + optional. It is only required for the following + examples. + + + To audit the third party utilities installed as part of + the Ports Collection at anytime, an administrator need only run + the following command: + + &prompt.root; portaudit -a + + Portaudit will produce something + like this for vulnerable packages: + + Affected package: cups-base-1.1.22.0_1 +Type of problem: cups-base -- HPGL buffer overflow vulnerability. +Reference: <http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html> + +1 problem(s) in your installed packages found. + +You are advised to update or deinstall the affected package(s) immediately. + + By pointing a web browser to the URL shown, + an administrator may obtain more information about the + vulnerability in question. This will include versions affected, + by &os; Port version, along with other web sites which may contain + security advisories. + + In short, Portaudit is a powerful + utility and extremely useful when coupled with the + Portupgrade port. + + + + + + + Tom + Rhodes + Contributed by + + + + + FreeBSD Security Advisories + + &os; Security Advisories + + Like many production quality operating systems, &os; publishes + Security Advisories. These advisories are usually + mailed to the security lists and noted in the Errata only + after the appropriate releases have been patched. This section + will work to explain what an advisory is, how to understand it, + and what measures to take in order to patch a system. + + + What does an advisory look like? + + The &os; security advisories look similar to the one below, + taken from the &a.security-notifications.name; mailing list. + + ============================================================================= +&os;-SA-XX:XX.UTIL Security Advisory + The &os; Project + +Topic: denial of service due to some problem + +Category: core +Module: sys +Announced: 2003-09-23 +Credits: Person@EMAIL-ADDRESS +Affects: All releases of &os; + &os; 4-STABLE prior to the correction date +Corrected: 2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE) + 2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6) + 2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15) + 2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8) + 2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18) + 2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21) + 2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33) + 2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43) + 2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) +CVE Name: CVE-XXXX-XXXX + +For general information regarding FreeBSD Security Advisories, +including descriptions of the fields above, security branches, and the +following sections, please visit +http://www.FreeBSD.org/security/. + +I. Background + + +II. Problem Description + + +III. Impact + + +IV. Workaround + + +V. Solution + + +VI. Correction details + + +VII. References + + + + + The Topic field indicates exactly what the problem is. + It is basically an introduction to the current security + advisory and notes the utility with the + vulnerability. + + + + The Category refers to the affected part of the system + which may be one of core, contrib, or ports. The core + category means that the vulnerability affects a core + component of the &os; operating system. The contrib + category means that the vulnerability affects software + contributed to the &os; Project, such as + sendmail. Finally the ports + category indicates that the vulnerability affects add on + software available as part of the Ports Collection. + + + + The Module field refers to the component location, for + instance sys. In this example, we see that the module, + sys, is affected; therefore, this vulnerability + affects a component used within the kernel. + + + + The Announced field reflects the date said security + advisory was published, or announced to the world. This + means that the security team has verified that the problem + does exist and that a patch has been committed to the &os; + source code repository. + + + + The Credits field gives credit to the individual or + organization who noticed the vulnerability and reported + it. + + + + The Affects field explains which releases of &os; are + affected by this vulnerability. For the kernel, a quick + look over the output from ident on the + affected files will help in determining the revision. + For ports, the version number is listed after the port name + in /var/db/pkg. If the system does not + sync with the &os; CVS repository and rebuild + daily, chances are that it is affected. + + + + The Corrected field indicates the date, time, time + offset, and release that was corrected. + + + + Reserved for the identification information used to look up + vulnerabilities in the Common Vulnerabilities Database system. + + + + The Background field gives information on exactly what + the affected utility is. Most of the time this is why + the utility exists in &os;, what it is used for, and a bit + of information on how the utility came to be. + + + + The Problem Description field explains the security hole + in depth. This can include information on flawed code, or + even how the utility could be maliciously used to open + a security hole. + + + + The Impact field describes what type of impact the + problem could have on a system. For example, this could + be anything from a denial of service attack, to extra + privileges available to users, or even giving the attacker + superuser access. + + + + The Workaround field offers a feasible workaround to + system administrators who may be incapable of upgrading + the system. This may be due to time constraints, network + availability, or a slew of other reasons. Regardless, + security should not be taken lightly, and an affected system + should either be patched or the security hole workaround + should be implemented. + + + + The Solution field offers instructions on patching the + affected system. This is a step by step tested and verified + method for getting a system patched and working + securely. + + + + The Correction Details field displays the + CVS branch or release name with the + periods changed to underscore characters. It also shows + the revision number of the affected files within each + branch. + + + + The References field usually offers sources of other + information. This can included web URLs, + books, mailing lists, and newsgroups. + + + + + + + + + + Tom + Rhodes + Contributed by + + + + + Process Accounting + + Process Accounting + + Process accounting is a security method in which an + administrator may keep track of system resources used, + their allocation among users, provide for system monitoring, + and minimally track a user's commands. + + This indeed has its own positive and negative points. One of + the positives is that an intrusion may be narrowed down + to the point of entry. A negative is the amount of logs + generated by process accounting, and the disk space they may + require. This section will walk an administrator through + the basics of process accounting. + + + Enable and Utilizing Process Accounting + Before making use of process accounting, it + must be enabled. To do this, execute the following + commands: + + &prompt.root; touch /var/account/acct + +&prompt.root; accton /var/account/acct + +&prompt.root; echo 'accounting_enable="YES"' >> /etc/rc.conf + + Once enabled, accounting will begin to track + CPU stats, commands, etc. All accounting + logs are in a non-human readable format and may be viewed + using the &man.sa.8; utility. If issued without any options, + sa will print information relating to the + number of per user calls, the total elapsed time in minutes, + total CPU and user time in minutes, average + number of I/O operations, etc. + + To view information about commands being issued, one + would use the &man.lastcomm.1; utility. The + lastcomm may be used to print out commands + issued by users on specific &man.ttys.5;, for example: + + &prompt.root; lastcomm ls + trhodes ttyp1 + + Would print out all known usage of the ls + by trhodes on the ttyp1 terminal. + + Many other useful options exist and are explained in the + &man.lastcomm.1;, &man.acct.5; and &man.sa.8; manual + pages. + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/serialcomms/Makefile b/pl_PL.ISO8859-2/books/handbook/serialcomms/Makefile new file mode 100644 index 0000000000..b83d9a27bb --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/serialcomms/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= serialcomms/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/serialcomms/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/serialcomms/chapter.sgml new file mode 100644 index 0000000000..8f1821c7cd --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/serialcomms/chapter.sgml @@ -0,0 +1,2857 @@ + + + + Serial Communications + + + Synopsis + + serial communications + &unix; has always had support for serial communications. In fact, + the very first &unix; machines relied on serial lines for user input + and output. Things have changed a lot from the days when the average + terminal consisted of a 10-character-per-second serial + printer and a keyboard. This chapter will cover some of the ways in + which FreeBSD uses serial communications. + + After reading this chapter, you will know: + + How to connect terminals to your FreeBSD + system. + How to use a modem to dial out to remote + hosts. + How to allow remote users to login to your + system with a modem. + How to boot your system from a serial + console. + + + Before reading this chapter, you should: + + Know how to configure and install a new kernel (). + Understand &unix; permissions and processes (). + Have access to the technical manual for the + serial hardware (modem or multi-port card) that you would like + to use with FreeBSD. + + + + + Introduction + + + + + Terminology + + + bits-per-second + + bps + + Bits per Second — the rate at which data is + transmitted + + + + + DTE + DTE + + Data Terminal Equipment — for example, your + computer + + + + + DCE + DCE + + Data Communications Equipment — your modem + + + + + RS-232 + RS-232C cables + + EIA standard for hardware serial communications + + + + + When talking about communications data rates, this section + does not use the term baud. Baud refers to the + number of electrical state transitions that may be made in a + period of time, while bps (bits per second) is + the correct term to use (at least it does not + seem to bother the curmudgeons quite as much). + + + + Cables and Ports + + To connect a modem or terminal to your FreeBSD system, you + will need a serial port on your computer and the proper cable to connect + to your serial device. If you are already familiar with your + hardware and the cable it requires, you can safely skip this + section. + + + Cables + + There are several different kinds of serial cables. The + two most common types for our purposes are null-modem cables + and standard (straight) RS-232 cables. The documentation + for your hardware should describe the type of cable + required. + + + Null-modem Cables + + + null-modem cable + + A null-modem cable passes some signals, such as Signal + Ground, straight through, but switches other signals. For + example, the Transmitted Data pin on one end goes to the + Received Data pin on the other end. + + You can also construct your own null-modem cable for use with + terminals (e.g., for quality purposes). This table shows the RS-232C + signals and the pin + numbers on a DB-25 connector. Note that the standard also calls for a + straight-through pin 1 to pin 1 Protective Ground + line, but it is often omitted. Some terminals work OK using only + pins 2, 3 and 7, while others require different configurations than + the examples shown below. + + + DB-25 to DB-25 Null-Modem Cable + + + + + Signal + Pin # + + Pin # + Signal + + + + + + SG + 7 + connects to + 7 + SG + + + + TD + 2 + connects to + 3 + RD + + + + RD + 3 + connects to + 2 + TD + + + + RTS + 4 + connects to + 5 + CTS + + + + CTS + 5 + connects to + 4 + RTS + + + + DTR + 20 + connects to + 6 + DSR + + + + DTR + 20 + connects to + 8 + DCD + + + + DSR + 6 + connects to + 20 + DTR + + + + DCD + 8 + connects to + 20 + DTR + + + +
+ + Here are two other schemes more common nowadays. + + + DB-9 to DB-9 Null-Modem Cable + + + + + Signal + Pin # + + Pin # + Signal + + + + + + RD + 2 + connects to + 3 + TD + + + + TD + 3 + connects to + 2 + RD + + + + DTR + 4 + connects to + 6 + DSR + + + + DTR + 4 + connects to + 1 + DCD + + + + SG + 5 + connects to + 5 + SG + + + + DSR + 6 + connects to + 4 + DTR + + + + DCD + 1 + connects to + 4 + DTR + + + + RTS + 7 + connects to + 8 + CTS + + + + CTS + 8 + connects to + 7 + RTS + + + +
+ + + DB-9 to DB-25 Null-Modem Cable + + + + + Signal + Pin # + + Pin # + Signal + + + + + + RD + 2 + connects to + 2 + TD + + + + TD + 3 + connects to + 3 + RD + + + + DTR + 4 + connects to + 6 + DSR + + + + DTR + 4 + connects to + 8 + DCD + + + + SG + 5 + connects to + 7 + SG + + + + DSR + 6 + connects to + 20 + DTR + + + + DCD + 1 + connects to + 20 + DTR + + + + RTS + 7 + connects to + 5 + CTS + + + + CTS + 8 + connects to + 4 + RTS + + + +
+ + + When one pin at one end connects to a pair of pins + at the other end, it is usually implemented with one short + wire between the pair of pins in their connector and a + long wire to the other single pin. + + + The above designs seems to be the most popular. In another + variation (explained in the book RS-232 Made + Easy) SG connects to SG, TD connects to RD, RTS and + CTS connect to DCD, DTR connects to DSR, and vice-versa. + + + + Standard RS-232C Cables + RS-232C cables + + A standard serial cable passes all of the RS-232C signals + straight through. That is, the Transmitted Data pin on one + end of the cable goes to the Transmitted Data pin on the + other end. This is the type of cable to use to connect a modem to your + FreeBSD system, and is also appropriate for some + terminals. + + + + + Ports + + Serial ports are the devices through which data is transferred + between the FreeBSD host computer and the terminal. This section + describes the kinds of ports that exist and how they are addressed + in FreeBSD. + + + Kinds of Ports + + Several kinds of serial ports exist. Before you purchase or + construct a cable, you need to make sure it will fit the ports on + your terminal and on the FreeBSD system. + + Most terminals will have DB-25 ports. Personal computers, + including PCs running FreeBSD, will have DB-25 or DB-9 ports. If you + have a multiport serial card for your PC, you may have RJ-12 or + RJ-45 ports. + + See the documentation that accompanied the hardware for + specifications on the kind of port in use. A visual inspection of + the port often works too. + + + + Port Names + + In FreeBSD, you access each serial port through an entry in + the /dev directory. There are two different + kinds of entries: + + + + Call-in ports are named + /dev/ttydN + where N is the port number, + starting from zero. Generally, you use the call-in port for + terminals. Call-in ports require that the serial line assert + the data carrier detect (DCD) signal to work correctly. + + + + Call-out ports are named + /dev/cuadN. + You usually do not use the call-out port for terminals, just + for modems. You may use the call-out port if the serial cable + or the terminal does not support the carrier detect + signal. + + Call-out ports are named + /dev/cuaaN in + &os; 5.X and older. + + + + If you have connected a terminal to the first serial port + (COM1 in &ms-dos;), then you will + use /dev/ttyd0 to refer to the terminal. If + the terminal is on the second serial port (also known as + COM2), use + /dev/ttyd1, and so forth. + + + + + + + Kernel Configuration + + FreeBSD supports four serial ports by default. In the + &ms-dos; world, these are known as + COM1, + COM2, + COM3, and + COM4. FreeBSD currently supports + dumb multiport serial interface cards, such as + the BocaBoard 1008 and 2016, as well as more + intelligent multi-port cards such as those made by Digiboard + and Stallion Technologies. However, the default kernel only looks + for the standard COM ports. + + To see if your kernel recognizes any of your serial ports, watch + for messages while the kernel is booting, or use the + /sbin/dmesg command to replay the kernel's boot + messages. In particular, look for messages that start with the + characters sio. + + To view just the messages that have the word + sio, use the command: + + &prompt.root; /sbin/dmesg | grep 'sio' + + + For example, on a system with four serial ports, these are the + serial-port specific kernel boot messages: + + sio0 at 0x3f8-0x3ff irq 4 on isa +sio0: type 16550A +sio1 at 0x2f8-0x2ff irq 3 on isa +sio1: type 16550A +sio2 at 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A +sio3 at 0x2e8-0x2ef irq 9 on isa +sio3: type 16550A + + If your kernel does not recognize all of your serial + ports, you will probably need to configure your kernel + in the /boot/device.hints file. You can + also comment-out or completely remove lines for devices you do not + have. + + Please refer to the &man.sio.4; manual page for + more information on serial ports and multiport boards configuration. + Be careful if you are using a configuration + file that was previously used for a different version of + FreeBSD because the device flags and the syntax have changed between + versions. + + + port IO_COM1 is a substitution for + port 0x3f8, IO_COM2 is + 0x2f8, IO_COM3 is + 0x3e8, and IO_COM4 is + 0x2e8, which are fairly common port addresses for + their respective serial ports; interrupts 4, 3, 5, and 9 are fairly + common interrupt request lines. Also note that regular serial ports + cannot share interrupts on ISA-bus PCs + (multiport boards have on-board electronics that allow all the + 16550A's on the board to share one or two interrupt request + lines). + + + + + + Device Special Files + + Most devices in the kernel are accessed through device + special files, which are located in the + /dev directory. The sio + devices are accessed through the + /dev/ttydN (dial-in) + and /dev/cuadN + (call-out) devices. FreeBSD also provides initialization devices + (/dev/ttydN.init and + /dev/cuadN.init on + &os; 6.X, + /dev/ttyidN and + /dev/cuaiaN on + &os; 5.X) and + locking devices + (/dev/ttydN.lock and + /dev/cuadN.lock on + &os; 6.X, + /dev/ttyldN and + /dev/cualaN on + &os; 5.X). The + initialization devices are used to initialize communications port + parameters each time a port is opened, such as + crtscts for modems which use + RTS/CTS signaling for flow control. The locking + devices are used to lock flags on ports to prevent users or programs + changing certain parameters; see the manual pages &man.termios.4;, + &man.sio.4;, and &man.stty.1; for + information on the terminal settings, locking and initializing + devices, and setting terminal options, respectively. + + + + + Serial Port Configuration + + ttyd + cuad + + The ttydN (or + cuadN) device is the + regular device you will want to open for your applications. When a + process opens the device, it will have a default set of terminal I/O + settings. You can see these settings with the command + + &prompt.root; stty -a -f /dev/ttyd1 + + When you change the settings to this device, the settings are in + effect until the device is closed. When it is reopened, it goes back to + the default set. To make changes to the default set, you can open and + adjust the settings of the initial state device. For + example, to turn on mode, 8 bit communication, + and flow control by default for + ttyd5, type: + + &prompt.root; stty -f /dev/ttyd5.init clocal cs8 ixon ixoff + + + rc files + rc.serial + + + System-wide initialization of the serial devices is + controlled in /etc/rc.d/serial. This file + affects the default settings of serial devices. + + To prevent certain settings from being changed by an + application, make adjustments to the lock state + device. For example, to lock the speed of + ttyd5 to 57600 bps, type: + + &prompt.root; stty -f /dev/ttyd5.lock 57600 + + Now, an application that opens + ttyd5 and tries to change the speed of + the port will be stuck with 57600 bps. + + Naturally, you should make the initial state and lock state devices + writable only by the root account. + + + + + + + + Sean + Kelly + Contributed by + + + + + Terminals + + terminals + + Terminals provide a convenient and low-cost way to access + your FreeBSD system when you are not at the computer's console or on + a connected network. This section describes how to use terminals with + FreeBSD. + + + Uses and Types of Terminals + + The original &unix; systems did not have consoles. Instead, people + logged in and ran programs through terminals that were connected to + the computer's serial ports. It is quite similar to using a modem and + terminal software to dial into a remote system to do text-only + work. + + Today's PCs have consoles capable of high quality graphics, but + the ability to establish a login session on a serial port still exists + in nearly every &unix; style operating system today; FreeBSD is no + exception. By using a terminal attached to an unused serial port, you + can log in and run any text program that you would normally run on the + console or in an xterm window in the X Window + System. + + For the business user, you can attach many terminals to a FreeBSD + system and place them on your employees' desktops. For a home user, a + spare computer such as an older IBM PC or a &macintosh; can be a + terminal wired into a more powerful computer running FreeBSD. You can + turn what might otherwise be a single-user computer into a powerful + multiple user system. + + For FreeBSD, there are three kinds of terminals: + + + + Dumb terminals + + + + PCs acting as terminals + + + + X terminals + + + + The remaining subsections describe each kind. + + + Dumb Terminals + + Dumb terminals are specialized pieces of hardware that let you + connect to computers over serial lines. They are called + dumb because they have only enough computational power + to display, send, and receive text. You cannot run any programs on + them. It is the computer to which you connect them that has all the + power to run text editors, compilers, email, games, and so + forth. + + There are hundreds of kinds of dumb terminals made by many + manufacturers, including Digital Equipment Corporation's VT-100 and + Wyse's WY-75. Just about any kind will work with FreeBSD. Some + high-end terminals can even display graphics, but only certain + software packages can take advantage of these advanced + features. + + Dumb terminals are popular in work environments where workers do + not need access to graphical applications such as those provided by + the X Window System. + + + + PCs Acting as Terminals + + If a dumb terminal has just + enough ability to display, send, and receive text, then certainly + any spare personal computer can be a dumb terminal. All you need is + the proper cable and some terminal emulation + software to run on the computer. + + Such a configuration is popular in homes. For example, if your + spouse is busy working on your FreeBSD system's console, you can do + some text-only work at the same time from a less powerful personal + computer hooked up as a terminal to the FreeBSD system. + + There are at least two utilities in the base-system of + &os; that can be used to work through a serial connection: + &man.cu.1; and &man.tip.1;. + + To connect from a client system that runs &os; to the + serial connection of another system, you can use: + + &prompt.root; cu -l serial-port-device + + Where serial-port-device is the name of a + special device file denoting a serial port of your system. + These device files are called + /dev/cuaaN + for &os; versions older than 6.0, and + /dev/cuadN + for 6.0 and later versions. + + The N-part of a device name is the serial + port number. + + + Note that device numbers in &os; start from zero and not + one (like they do, for instance in &ms-dos;-derived systems). + This means that what &ms-dos;-based systems + call COM1 is + usually /dev/cuad0 in &os;. + + + + Some people prefer to use other programs, available + through the Ports Collection. The Ports include quite a few + utilities which can work in ways similar to &man.cu.1; and + &man.tip.1;, + i.e. comms/minicom. + + + + + X Terminals + + X terminals are the most sophisticated kind of terminal + available. Instead of connecting to a serial port, they usually + connect to a network like Ethernet. Instead of being relegated to + text-only applications, they can display any X application. + + We introduce X terminals just for the sake of completeness. + However, this chapter does not cover setup, + configuration, or use of X terminals. + + + + + Configuration + + This section describes what you need to configure on your FreeBSD + system to enable a login session on a terminal. It assumes you have + already configured your kernel to support the serial port to which the + terminal is connected—and that you have connected it. + + Recall from that the + init process is responsible for all process + control and initialization at system startup. One of the + tasks performed by init is to read the + /etc/ttys file and start a + getty process on the available terminals. + The getty process is responsible for + reading a login name and starting the login + program. + + Thus, to configure terminals for your FreeBSD system the + following steps should be taken as root: + + + + Add a line to /etc/ttys for the entry in + the /dev directory for the serial port if it + is not already there. + + + + Specify that /usr/libexec/getty be run on + the port, and specify the appropriate + getty type from the + /etc/gettytab file. + + + + Specify the default terminal type. + + + + Set the port to on. + + + + Specify whether the port should be + secure. + + + + Force init to reread the + /etc/ttys file. + + + + As an optional step, you may wish to create a custom + getty type for use in step 2 by making an + entry in /etc/gettytab. This chapter does + not explain how to do so; you are encouraged to see the + &man.gettytab.5; and the &man.getty.8; manual pages for more + information. + + + Adding an Entry to <filename>/etc/ttys</filename> + + The /etc/ttys file lists all of the ports + on your FreeBSD system where you want to allow logins. For example, + the first virtual console ttyv0 has an entry in + this file. You can log in on the console using this entry. This + file also contains entries for the other virtual consoles, serial ports, + and pseudo-ttys. For a hardwired terminal, just list the serial + port's /dev entry without the + /dev part (for example, + /dev/ttyv0 would be listed as + ttyv0). + + A default FreeBSD install includes an + /etc/ttys file with support for the first + four serial ports: ttyd0 through + ttyd3. If you are attaching a terminal + to one of those ports, you do not need to add another entry. + + + Adding Terminal Entries to + <filename>/etc/ttys</filename> + + Suppose we would like to connect two terminals to the + system: a Wyse-50 and an old 286 IBM PC running + Procomm terminal software + emulating a VT-100 terminal. We connect the Wyse to the + second serial port and the 286 to the sixth serial port (a + port on a multiport serial card). The corresponding + entries in the /etc/ttys file would + look like this: + + ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure +ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure + + + + + The first field normally specifies the name of + the terminal special file as it is found in + /dev. + + + + The second field is the command to execute for + this line, which is usually &man.getty.8;. + getty initializes and opens the + line, sets the speed, prompts for a user name and then + executes the &man.login.1; program. + + The getty program accepts one + (optional) parameter on its command line, the + getty type. A + getty type configures + characteristics on the terminal line, like bps rate + and parity. The getty program reads + these characteristics from the file + /etc/gettytab. + + The file /etc/gettytab + contains lots of entries for terminal lines both old + and new. In almost all cases, the entries that start + with the text std will work for + hardwired terminals. These entries ignore parity. + There is a std entry for each bps + rate from 110 to 115200. Of course, you can add your + own entries to this file. The &man.gettytab.5; manual + page provides more information. + + When setting the getty + type in the /etc/ttys file, make + sure that the communications settings on the terminal + match. + + For our example, the Wyse-50 uses no parity and + connects at 38400 bps. The 286 PC uses no parity and + connects at 19200 bps. + + + + + + The third field is the type of terminal usually + connected to that tty line. For dial-up ports, + unknown or + dialup is typically used in this + field since users may dial up with practically any + type of terminal or software. For hardwired + terminals, the terminal type does not change, so you + can put a real terminal type from the &man.termcap.5; + database file in this field. + + For our example, the Wyse-50 uses the real + terminal type while the 286 PC running + Procomm will be set to + emulate at VT-100. + + + + + The fourth field specifies if the port should be + enabled. Putting on here will have + the init process start the program + in the second field, getty. If you + put off in this field, there will + be no getty, and hence no logins on + the port. + + + + The final field is used to specify whether the + port is secure. Marking a port as secure means that + you trust it enough to allow the + root account (or any account with + a user ID of 0) to login from that port. Insecure + ports do not allow root logins. + On an insecure port, users must login from + unprivileged accounts and then use &man.su.1; or a + similar mechanism to gain superuser privileges. + + It is highly recommended that you use + insecure + even for terminals that are behind locked doors. It + is quite easy to login and use su + if you need superuser privileges. + + + + + + + Force <command>init</command> to Reread + <filename>/etc/ttys</filename> + + After making the necessary changes to the + /etc/ttys file you should send a SIGHUP + (hangup) signal to the init process to + force it to re-read its configuration file. For example: + + &prompt.root; kill -HUP 1 + + + init is always the first process run + on a system, therefore it will always have PID 1. + + + If everything is set up correctly, all cables are in + place, and the terminals are powered up, then a + getty process should be running on each + terminal and you should see login prompts on your terminals + at this point. + + + + + Troubleshooting Your Connection + + Even with the most meticulous attention to detail, something could + still go wrong while setting up a terminal. Here is a list of + symptoms and some suggested fixes. + + + No Login Prompt Appears + + Make sure the terminal is plugged in and powered up. If it + is a personal computer acting as a terminal, make sure it is + running terminal emulation software on the correct serial + port. + + Make sure the cable is connected firmly to both the terminal + and the FreeBSD computer. Make sure it is the right kind of + cable. + + Make sure the terminal and FreeBSD agree on the bps rate and + parity settings. If you have a video display terminal, make + sure the contrast and brightness controls are turned up. If it + is a printing terminal, make sure paper and ink are in good + supply. + + Make sure that a getty process is running + and serving the terminal. For example, to get a list of + running getty processes with + ps, type: + + &prompt.root; ps -axww|grep getty + + You should see an entry for the terminal. For + example, the following display shows that a + getty is running on the second serial + port ttyd1 and is using the + std.38400 entry in + /etc/gettytab: + + 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1 + + If no getty process is running, make sure + you have enabled the port in /etc/ttys. + Also remember to run kill -HUP 1 + after modifying the ttys file. + + If the getty process is running + but the terminal still does not display a login prompt, + or if it displays a prompt but will not allow you to + type, your terminal or cable may not support hardware + handshaking. Try changing the entry in + /etc/ttys from + std.38400 to + 3wire.38400 remember to run + kill -HUP 1 after modifying + /etc/ttys). The + 3wire entry is similar to + std, but ignores hardware + handshaking. You may need to reduce the baud rate or + enable software flow control when using + 3wire to prevent buffer + overflows. + + + + + If Garbage Appears Instead of a Login Prompt + + Make sure the terminal and FreeBSD agree on the bps rate and + parity settings. Check the getty processes + to make sure the + correct getty type is in use. If + not, edit /etc/ttys and run kill + -HUP 1. + + + + + Characters Appear Doubled; the Password Appears When Typed + + Switch the terminal (or the terminal emulation software) + from half duplex or local echo to + full duplex. + + + + + + + + + + Guy + Helmer + Contributed by + + + + + Sean + Kelly + Additions by + + + + Dial-in Service + dial-in service + + Configuring your FreeBSD system for dial-in service is very + similar to connecting terminals except that you are dealing with + modems instead of terminals. + + + External vs. Internal Modems + + External modems seem to be more convenient for dial-up, because + external modems often can be semi-permanently configured via + parameters stored in non-volatile RAM and they usually provide + lighted indicators that display the state of important RS-232 + signals. Blinking lights impress visitors, but lights are also very + useful to see whether a modem is operating properly. + + Internal modems usually lack non-volatile RAM, so their + configuration may be limited only to setting DIP switches. If your + internal modem has any signal indicator lights, it is probably + difficult to view the lights when the system's cover is in + place. + + + Modems and Cables + modem + + If you are using an external modem, then you will of + course need the proper cable. A standard RS-232C serial + cable should suffice as long as all of the normal signals + are wired: + + + Signal Names + + + + + Acronyms + Names + + + + + + RD + Received Data + + + + TD + Transmitted Data + + + + DTR + Data Terminal Ready + + + + DSR + Data Set Ready + + + + DCD + Data Carrier Detect (RS-232's Received Line + Signal Detector) + + + + SG + Signal Ground + + + + RTS + Request to Send + + + + CTS + Clear to Send + + + +
+ + FreeBSD needs the RTS and + CTS signals for flow control at speeds above + 2400 bps, the CD signal to detect when a call has + been answered or the line has been hung up, and the + DTR signal to reset the modem after a session is + complete. Some cables are wired without all of the needed signals, + so if you have problems, such as a login session not going away when + the line hangs up, you may have a problem with your cable. + + Like other &unix; like operating systems, FreeBSD uses the + hardware signals to find out when a call has been answered + or a line has been hung up and to hangup and reset the modem + after a call. FreeBSD avoids sending commands to the modem + or watching for status reports from the modem. If you are + familiar with connecting modems to PC-based bulletin board + systems, this may seem awkward. + + + + + Serial Interface Considerations + + FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based + EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and + 16450 devices have single-character buffers. The 16550 device + provides a 16-character buffer, which allows for better system + performance. (Bugs in plain 16550's prevent the use of the + 16-character buffer, so use 16550A's if possible). Because + single-character-buffer devices require more work by the operating + system than the 16-character-buffer devices, 16550A-based serial + interface cards are much preferred. If the system has many active + serial ports or will have a heavy load, 16550A-based cards are + better for low-error-rate communications. + + + + Quick Overview + + getty + As with terminals, init spawns a + getty process for each configured serial + port for dial-in connections. For example, if a modem is + attached to /dev/ttyd0, the command + ps ax might show this: + + 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0 + + When a user dials the modem's line and the modems connect, the + CD (Carrier Detect) line is reported by the modem. + The kernel + notices that carrier has been detected and completes + getty's open of the port. getty + sends a login: prompt at the specified initial line + speed. getty watches to see if legitimate + characters are received, and, in a typical configuration, if it finds + junk (probably due to the modem's connection speed being different + than getty's speed), getty tries + adjusting the line speeds until it receives reasonable + characters. + + + /usr/bin/login + + After the user enters his/her login name, + getty executes + /usr/bin/login, which completes the login + by asking for the user's password and then starting the user's + shell. + + + + + Configuration Files + + There are three system configuration files in the + /etc directory that you will probably need to + edit to allow dial-up access to your FreeBSD system. The first, + /etc/gettytab, contains configuration information + for the /usr/libexec/getty daemon. Second, + /etc/ttys holds information that tells + /sbin/init what tty devices + should have getty processes running on them. + Lastly, you can place port initialization commands in the + /etc/rc.d/serial script. + + There are two schools of thought regarding dial-up modems on &unix;. + One group likes to configure their modems and systems so that no matter + at what speed a remote user dials in, the local computer-to-modem + RS-232 interface runs at a locked speed. The benefit of this + configuration is that the remote user always sees a system login + prompt immediately. The downside is that the system does not know + what a user's true data rate is, so full-screen programs like Emacs + will not adjust their screen-painting methods to make their response + better for slower connections. + + The other school configures their modems' RS-232 interface to vary + its speed based on the remote user's connection speed. For example, + V.32bis (14.4 Kbps) connections to the modem might make the modem run + its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the + modem's RS-232 interface run at 2400 bps. Because + getty does not understand any particular modem's + connection speed reporting, getty gives a + login: message at an initial speed and watches the + characters that come back in response. If the user sees junk, it is + assumed that they know they should press the + Enter key until they see a recognizable + prompt. If the data rates do not match, getty sees + anything the user types as junk, tries going to the next + speed and gives the login: prompt again. This + procedure can continue ad nauseam, but normally only takes a keystroke + or two before the user sees a good prompt. Obviously, this login + sequence does not look as clean as the former + locked-speed method, but a user on a low-speed + connection should receive better interactive response from full-screen + programs. + + This section will try to give balanced configuration information, + but is biased towards having the modem's data rate follow the + connection rate. + + + <filename>/etc/gettytab</filename> + + + /etc/gettytab + + /etc/gettytab is a &man.termcap.5;-style + file of configuration information for &man.getty.8;. Please see the + &man.gettytab.5; manual page for complete information on the + format of the file and the list of capabilities. + + + Locked-speed Config + + If you are locking your modem's data communications rate at a + particular speed, you probably will not need to make any changes + to /etc/gettytab. + + + + Matching-speed Config + + You will need to set up an entry in + /etc/gettytab to give + getty information about the speeds you wish to + use for your modem. If you have a 2400 bps modem, you can + probably use the existing D2400 entry. + + # +# Fast dialup terminals, 2400/1200/300 rotary (can start either way) +# +D2400|d2400|Fast-Dial-2400:\ + :nx=D1200:tc=2400-baud: +3|D1200|Fast-Dial-1200:\ + :nx=D300:tc=1200-baud: +5|D300|Fast-Dial-300:\ + :nx=D2400:tc=300-baud: + + If you have a higher speed modem, you will probably need to + add an entry in /etc/gettytab; here is an + entry you could use for a 14.4 Kbps modem with a top interface + speed of 19.2 Kbps: + + # +# Additions for a V.32bis Modem +# +um|V300|High Speed Modem at 300,8-bit:\ + :nx=V19200:tc=std.300: +un|V1200|High Speed Modem at 1200,8-bit:\ + :nx=V300:tc=std.1200: +uo|V2400|High Speed Modem at 2400,8-bit:\ + :nx=V1200:tc=std.2400: +up|V9600|High Speed Modem at 9600,8-bit:\ + :nx=V2400:tc=std.9600: +uq|V19200|High Speed Modem at 19200,8-bit:\ + :nx=V9600:tc=std.19200: + + This will result in 8-bit, no parity connections. + + The example above starts the communications rate at 19.2 Kbps + (for a V.32bis connection), then cycles through 9600 bps (for + V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. + Communications rate cycling is implemented with the + nx= (next table) capability. + Each of the lines uses a tc= (table + continuation) entry to pick up the rest of the + standard settings for a particular data rate. + + If you have a 28.8 Kbps modem and/or you want to take + advantage of compression on a 14.4 Kbps modem, you need to use a + higher communications rate than 19.2 Kbps. Here is an example of + a gettytab entry starting a 57.6 Kbps: + + # +# Additions for a V.32bis or V.34 Modem +# Starting at 57.6 Kbps +# +vm|VH300|Very High Speed Modem at 300,8-bit:\ + :nx=VH57600:tc=std.300: +vn|VH1200|Very High Speed Modem at 1200,8-bit:\ + :nx=VH300:tc=std.1200: +vo|VH2400|Very High Speed Modem at 2400,8-bit:\ + :nx=VH1200:tc=std.2400: +vp|VH9600|Very High Speed Modem at 9600,8-bit:\ + :nx=VH2400:tc=std.9600: +vq|VH57600|Very High Speed Modem at 57600,8-bit:\ + :nx=VH9600:tc=std.57600: + + If you have a slow CPU or a heavily loaded system and do + not have 16550A-based serial ports, you may receive + sio + silo errors at 57.6 Kbps. + + + + + <filename>/etc/ttys</filename> + + /etc/ttys + + + Configuration of the /etc/ttys file + was covered in . + Configuration for modems is similar but we must pass a + different argument to getty and specify a + different terminal type. The general format for both + locked-speed and matching-speed configurations is: + + ttyd0 "/usr/libexec/getty xxx" dialup on + + The first item in the above line is the device special file for + this entry — ttyd0 means + /dev/ttyd0 is the file that this + getty will be watching. The second item, + "/usr/libexec/getty + xxx" + (xxx will be replaced by the initial + gettytab capability) is the process + init will run on the device. The third item, + dialup, is the default terminal type. The fourth + parameter, on, indicates to + init that the line is operational. There can be + a fifth parameter, secure, but it should only be + used for terminals which are physically secure (such as the system + console). + + The default terminal type (dialup in the + example above) may depend on local preferences. + dialup is the traditional default terminal type + on dial-up lines so that users may customize their login scripts to + notice when the terminal is dialup and + automatically adjust their terminal type. However, the author finds + it easier at his site to specify vt102 as the + default terminal type, since the users just use VT102 emulation on + their remote systems. + + After you have made changes to /etc/ttys, + you may send the init process a + HUP signal to re-read the file. You can use the + command + + &prompt.root; kill -HUP 1 + + to send the signal. If this is your first time setting up the + system, you may want to wait until your modem(s) are properly + configured and connected before signaling init. + + + + Locked-speed Config + + For a locked-speed configuration, your + ttys entry needs to have a fixed-speed entry + provided to getty. For a modem whose port + speed is locked at 19.2 Kbps, the ttys entry + might look like this: + + ttyd0 "/usr/libexec/getty std.19200" dialup on + + If your modem is locked at a different data rate, + substitute the appropriate value for + std.speed + instead of std.19200. Make sure that + you use a valid type listed in + /etc/gettytab. + + + + Matching-speed Config + + In a matching-speed configuration, your + ttys entry needs to reference the appropriate + beginning auto-baud (sic) entry in + /etc/gettytab. For example, if you added the + above suggested entry for a matching-speed modem that starts at + 19.2 Kbps (the gettytab entry containing the + V19200 starting point), your + ttys entry might look like this: + + ttyd0 "/usr/libexec/getty V19200" dialup on + + + + + <filename>/etc/rc.d/serial</filename> + + rc files + rc.serial + + + High-speed modems, like V.32, V.32bis, and V.34 modems, + need to use hardware (RTS/CTS) flow + control. You can add stty commands to + /etc/rc.d/serial to set the hardware flow + control flag in the FreeBSD kernel for the modem + ports. + + For example to set the termios flag + crtscts on serial port #1's + (COM2) dial-in and dial-out initialization + devices, the following lines could be added to + /etc/rc.d/serial: + # Serial port initial configuration +stty -f /dev/ttyd1.init crtscts +stty -f /dev/cuad1.init crtscts + + + + + + Modem Settings + + If you have a modem whose parameters may be permanently set in + non-volatile RAM, you will need to use a terminal program (such as + Telix under &ms-dos; or tip under FreeBSD) to set the + parameters. Connect to the modem using the same communications speed + as the initial speed getty will use and configure + the modem's non-volatile RAM to match these requirements: + + + + CD asserted when connected + + + + DTR asserted for operation; dropping DTR + hangs up line and resets modem + + + + CTS transmitted data flow control + + + + Disable XON/XOFF flow control + + + + RTS received data flow control + + + + Quiet mode (no result codes) + + + + No command echo + + + + Please read the documentation for your modem to find out what + commands and/or DIP switch settings you need to give it. + + For example, to set the above parameters on a &usrobotics; + &sportster; 14,400 external modem, one could give these commands to + the modem: + + ATZ +AT&C1&D2&H1&I0&R2&W + + You might also want to take this opportunity to adjust other + settings in the modem, such as whether it will use V.42bis and/or MNP5 + compression. + + The &usrobotics; &sportster; 14,400 external modem also has some DIP switches + that need to be set; for other modems, perhaps you can use these + settings as an example: + + + + Switch 1: UP — DTR Normal + + + + Switch 2: N/A (Verbal Result Codes/Numeric Result + Codes) + + + + Switch 3: UP — Suppress Result Codes + + + + Switch 4: DOWN — No echo, offline commands + + + + Switch 5: UP — Auto Answer + + + + Switch 6: UP — Carrier Detect Normal + + + + Switch 7: UP — Load NVRAM Defaults + + + + Switch 8: N/A (Smart Mode/Dumb Mode) + + + + Result codes should be disabled/suppressed for dial-up modems to + avoid problems that can occur if getty mistakenly + gives a login: prompt to a modem that is in command + mode and the modem echoes the command or returns a result + code. This sequence can result in a extended, silly conversation + between getty and the modem. + + + Locked-speed Config + + For a locked-speed configuration, you will need to configure the + modem to maintain a constant modem-to-computer data rate independent + of the communications rate. On a &usrobotics; &sportster; 14,400 external + modem, these commands will lock the modem-to-computer data rate at + the speed used to issue the commands: + + ATZ +AT&B1&W + + + + Matching-speed Config + + For a variable-speed configuration, you will need to configure + your modem to adjust its serial port data rate to match the incoming + call rate. On a &usrobotics; &sportster; 14,400 external modem, these commands + will lock the modem's error-corrected data rate to the speed used to + issue the commands, but allow the serial port rate to vary for + non-error-corrected connections: + + ATZ +AT&B2&W + + + + Checking the Modem's Configuration + + Most high-speed modems provide commands to view the modem's + current operating parameters in a somewhat human-readable fashion. + On the &usrobotics; &sportster; 14,400 external modems, the command + ATI5 displays the settings that are stored in the + non-volatile RAM. To see the true operating parameters of the modem + (as influenced by the modem's DIP switch settings), use the commands + ATZ and then ATI4. + + If you have a different brand of modem, check your modem's + manual to see how to double-check your modem's configuration + parameters. + + + + + Troubleshooting + + Here are a few steps you can follow to check out the dial-up modem + on your system. + + + Checking Out the FreeBSD System + + Hook up your modem to your FreeBSD system, boot the system, and, + if your modem has status indication lights, watch to see whether the + modem's DTR indicator lights when the + login: prompt appears on the system's console + — if it lights up, that should mean that FreeBSD has started a + getty process on the appropriate communications + port and is waiting for the modem to accept a call. + + If the DTR indicator does not light, login to + the FreeBSD system through the console and issue a ps + ax to see if FreeBSD is trying to run a + getty process on the correct port. You should see + lines like these among the processes displayed: + + 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 + 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1 + + If you see something different, like this: + + 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0 + + and the modem has not accepted a call yet, this means that + getty has completed its open on the + communications port. This could indicate a problem with the cabling + or a mis-configured modem, because getty should + not be able to open the communications port until + CD (carrier detect) has been asserted by the + modem. + + If you do not see any getty processes waiting + to open the desired + ttydN port, + double-check your entries in /etc/ttys to see + if there are any mistakes there. Also, check the log file + /var/log/messages to see if there are any log + messages from init or getty + regarding any problems. If there are any messages, triple-check the + configuration files /etc/ttys and + /etc/gettytab, as well as the appropriate + device special files /dev/ttydN, for any + mistakes, missing entries, or missing device special files. + + + + Try Dialing In + + Try dialing into the system; be sure to use 8 bits, no parity, + and 1 + stop bit on the remote system. If you do not get a prompt right + away, or get garbage, try pressing Enter + about once per second. If you still do not see a + login: prompt after a while, try sending a + BREAK. If you are using a high-speed modem to do + the dialing, try dialing again after locking the dialing modem's + interface speed (via AT&B1 on a &usrobotics; + &sportster; modem, for example). + + If you still cannot get a login: prompt, check + /etc/gettytab again and double-check + that + + + + The initial capability name specified in + /etc/ttys for the line matches a name of a + capability in /etc/gettytab + + + + Each nx= entry matches another + gettytab capability name + + + + Each tc= entry matches another + gettytab capability name + + + + If you dial but the modem on the FreeBSD system will not answer, + make sure that the modem is configured to answer the phone when + DTR is asserted. If the modem seems to be + configured correctly, verify that the DTR line is + asserted by checking the modem's indicator lights (if it has + any). + + If you have gone over everything several times and it still does + not work, take a break and come back to it later. If it still does + not work, perhaps you can send an electronic mail message to the + &a.questions; describing your modem and your problem, and the good + folks on the list will try to help. + + + + + + + Dial-out Service + dial-out service + + The following are tips for getting your host to be able to connect + over the modem to another computer. This is appropriate for + establishing a terminal session with a remote host. + + This is useful to log onto a BBS. + + This kind of connection can be extremely helpful to get a file on + the Internet if you have problems with PPP. If you need to FTP + something and PPP is broken, use the terminal session to FTP it. Then + use zmodem to transfer it to your machine. + + + My Stock Hayes Modem Is Not Supported, What Can I Do? + + Actually, the manual page for tip is out of date. + There is a generic Hayes dialer already built in. Just use + at=hayes in your /etc/remote + file. + + The Hayes driver is not smart enough to recognize some of the + advanced features of newer modems—messages like + BUSY, NO DIALTONE, or + CONNECT 115200 will just confuse it. You should + turn those messages off when you use tip (using + ATX0&W). + + Also, the dial timeout for tip is 60 seconds. + Your modem should use something less, or else tip will think there is + a communication problem. Try ATS7=45&W. + + + As shipped, tip does not yet support + Hayes modems 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? + + + /etc/remote + + Make what is called a direct entry in your + /etc/remote file. For example, if your modem is + hooked up to the first serial port, /dev/cuad0, + then put in the following line: + + cuad0:dv=/dev/cuad0:br#19200:pa=none + + Use the highest bps rate your modem supports in the br capability. + Then, type tip cuad0 and you will be connected to + your modem. + + Or use cu as root with the + following command: + + &prompt.root; cu -lline -sspeed + + line is the serial port + (e.g./dev/cuad0) and + speed is the speed + (e.g.57600). When you are done entering the AT + commands hit ~. to exit. + + + + The <literal>@</literal> Sign for the pn Capability Does Not + Work! + + The @ sign in the phone number capability tells + tip to look in /etc/phones for a phone number. + But the @ sign is also a special character in + capability files like /etc/remote. Escape it + with a backslash: + + pn=\@ + + + + How Can I Dial a Phone Number on the Command Line? + + Put what is called a generic entry in your + /etc/remote file. For example: + + tip115200|Dial any phone number at 115200 bps:\ + :dv=/dev/cuad0:br#115200:at=hayes:pa=none:du: +tip57600|Dial any phone number at 57600 bps:\ + :dv=/dev/cuad0:br#57600:at=hayes:pa=none:du: + + Then you can do things like: + + &prompt.root; tip -115200 5551234 + + If you prefer cu over tip, + use a generic cu entry: + + cu115200|Use cu to dial any number at 115200bps:\ + :dv=/dev/cuad1:br#57600:at=hayes:pa=none:du: + + and type: + + &prompt.root; cu 5551234 -s 115200 + + + + Do I Have to Type in the bps Rate Every Time I Do That? + + Put in an entry for tip1200 or + cu1200, but go ahead and use whatever bps rate is + appropriate with the br capability. tip thinks a + good default is 1200 bps which is why it looks for a + tip1200 entry. You do not have to use 1200 bps, + though. + + + + I Access a Number of Hosts Through a Terminal Server + + Rather than waiting until you are connected and typing + CONNECT <host> each time, use tip's + cm capability. For example, these entries in + /etc/remote: + + pain|pain.deep13.com|Forrester's machine:\ + :cm=CONNECT pain\n:tc=deep13: +muffin|muffin.deep13.com|Frank's machine:\ + :cm=CONNECT muffin\n:tc=deep13: +deep13:Gizmonics Institute terminal server:\ + :dv=/dev/cuad2:br#38400:at=hayes:du:pa=none:pn=5551234: + + will let you type tip pain or tip + muffin to connect to the hosts pain or muffin, and + tip deep13 to get to the terminal server. + + + + Can Tip Try More Than One Line for Each Site? + + This is often a problem where a university has several modem lines + and several thousand students trying to use them. + + Make an entry for your university in + /etc/remote and use @ for the + pn capability: + + big-university:\ + :pn=\@:tc=dialout +dialout:\ + :dv=/dev/cuad3:br#9600:at=courier:du:pa=none: + + Then, list the phone numbers for the university in + /etc/phones: + + big-university 5551111 +big-university 5551112 +big-university 5551113 +big-university 5551114 + + tip will try each one in the listed order, then + give up. If you want to keep retrying, run tip in + a while loop. + + + + Why Do I Have to Hit + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>P</keycap> + </keycombo> + Twice to Send + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>P</keycap> + </keycombo> + Once? + + CtrlP is the default force character, used to tell + tip that the next character is literal data. You + can set the force character to any other character with the + ~s escape, which means set a + variable. + + Type + ~sforce=single-char + followed by a newline. single-char is any + single character. If you leave out + single-char, then the force character is + the nul character, which you can get by typing + + Ctrl2 + + or + + CtrlSpace + . + A pretty good value for single-char is + + Shift + Ctrl + 6 + , which is only used on some terminal + servers. + + You can have the force character be whatever you want by + specifying the following in your $HOME/.tiprc + file: + + force=<single-char> + + + + Suddenly Everything I Type Is in Upper Case?? + + You must have pressed + + Ctrl + A + , tip's + raise character, specially designed for people with + broken caps-lock keys. Use ~s as above and set the + variable raisechar to something reasonable. In + fact, you can set it to the same as the force character, if you never + expect to use either of these features. + + Here is a sample .tiprc file perfect for + Emacs users who need to type + + Ctrl2 + + and + + CtrlA + + a lot: + + force=^^ +raisechar=^^ + + The ^^ is + + ShiftCtrl6 + . + + + + + How Can I Do File Transfers with <command>tip</command>? + + If you are talking to another &unix; system, you can send and + receive files with ~p (put) and + ~t (take). These commands run + cat and echo on the remote + system to accept and send files. The syntax is: + + + ~p + local-file + remote-file + + + + ~t + remote-file + local-file + + + There is no error checking, so you probably should use another + protocol, like zmodem. + + + + How Can I Run zmodem with <command>tip</command>? + + To receive files, start the sending program on the remote end. + Then, type ~C rz to begin receiving them + locally. + + To send files, start the receiving program on the remote end. + Then, type ~C sz files + to send them to the remote system. + + + + + + + + Kazutaka + YOKOTA + Contributed by + + + + + Bill + Paul + Based on a document by + + + + Setting Up the Serial Console + serial console + + + Introduction + + FreeBSD has the ability to boot on a system with only + a dumb terminal on a serial port as a console. Such a configuration + should be useful for two classes of people: system administrators who + wish to install FreeBSD on machines that have no keyboard or monitor + attached, and developers who want to debug the kernel or device + drivers. + + As described in , FreeBSD employs a three stage + bootstrap. The first two stages are in the boot block code which is + stored at the beginning of the FreeBSD slice on the boot disk. The + boot block will then load and run the boot loader + (/boot/loader) as the third stage code. + + In order to set up the serial console you must configure the boot + block code, the boot loader code and the kernel. + + + + + Serial Console Configuration, Terse Version + + This section assumes that you are using the default setup + and just want a fast overview of setting up the serial + console. + + + + + Connect the serial cable to COM1 and the controlling + terminal. + + + + To see all boot messages on the serial console, issue + the following command while logged in as the superuser: + &prompt.root; echo 'console="comconsole"' >> /boot/loader.conf + + + + Edit /etc/ttys and change + off to on and + dialup to vt100 for the + ttyd0 entry. Otherwise a password will not be + required to connect via the serial console, resulting in a + potential security hole. + + + + Reboot the system to see if the changes took effect. + + + + + If a different configuration is required, a more in depth + configuration explanation exists in + . + + + + Serial Console Configuration + + + + Prepare a serial cable. + + null-modem cable + You will need either a null-modem cable or a standard serial + cable and a null-modem adapter. See for + a discussion on serial cables. + + + + Unplug your keyboard. + + Most PC systems probe for the keyboard during the Power-On + Self-Test (POST) and will generate an error if the keyboard is not + detected. Some machines complain loudly about the lack of a + keyboard and will not continue to boot until it is plugged + in. + + If your computer complains about the error, but boots anyway, + then you do not have to do anything special. (Some machines with + Phoenix BIOS installed merely say Keyboard + failed and continue to boot normally.) + + If your computer refuses to boot without a keyboard attached + then you will have to configure the BIOS so that it ignores this + error (if it can). Consult your motherboard's manual for details + on how to do this. + + + Set the keyboard to Not installed in the + BIOS setup. You will still + be able to use your keyboard. All this does is tell the BIOS + not to probe for a keyboard at power-on. Your BIOS should not + complain if the keyboard is absent. You can leave the + keyboard plugged in even with this flag set to Not + installed and the keyboard will still work. + + + + If your system has a &ps2; mouse, chances are very good that + you may have to unplug your mouse as well as your keyboard. + This is because &ps2; mice share some hardware with the keyboard + and leaving the mouse plugged in can fool the keyboard probe + into thinking the keyboard is still there. It is said that a + Gateway 2000 Pentium 90 MHz system with an AMI BIOS that behaves + this way. In general, this is not a problem since the mouse is + not much good without the keyboard anyway. + + + + + Plug a dumb terminal into COM1 + (sio0). + + If you do not have a dumb terminal, you can use an old PC/XT + with a modem program, or the serial port on another &unix; box. If + you do not have a COM1 + (sio0), get one. At this time, there is + no way to select a port other than COM1 + for the boot blocks without recompiling the boot blocks. If you + are already using COM1 for another + device, you will have to temporarily remove that device and + install a new boot block and kernel once you get FreeBSD up and + running. (It is assumed that COM1 will + be available on a file/compute/terminal server anyway; if you + really need COM1 for something else + (and you cannot switch that something else to + COM2 (sio1)), + then you probably should not even be bothering with all this in + the first place.) + + + + Make sure the configuration file of your kernel has + appropriate flags set for COM1 + (sio0). + + Relevant flags are: + + + + 0x10 + + + Enables console support for this unit. The other + console flags are ignored unless this is set. Currently, at + most one unit can have console support; the first one (in + config file order) with this flag set is preferred. This + option alone will not make the serial port the console. Set + the following flag or use the option + described below, together with this flag. + + + + + 0x20 + + + Forces this unit to be the console (unless there is + another higher priority console), regardless of the + option discussed below. + The flag 0x20 must be used + together with the flag. + + + + + 0x40 + + + Reserves this unit (in conjunction with + 0x10) and makes the unit + unavailable for normal access. You should not set + this flag to the serial port unit which you want to + use as the serial console. The only use of this + flag is to designate the unit for kernel remote + debugging. See The + Developer's Handbook for more information on + remote debugging. + + + + + Example: + + device sio0 at isa? port IO_COM1 flags 0x10 irq 4 + + See the &man.sio.4; manual page for more details. + + If the flags were not set, you need to run UserConfig (on a + different console) or recompile the kernel. + + + + Create boot.config in the root directory + of the a partition on the boot drive. + + This file will instruct the boot block code how you would like + to boot the system. In order to activate the serial console, you + need one or more of the following options—if you want + multiple options, include them all on the same line: + + + + + + + Toggles internal and serial consoles. You can use this + to switch console devices. For instance, if you boot from + the internal (video) console, you can use + to direct the boot loader and the kernel + to use the serial port as its console device. Alternatively, + if you boot from the serial port, you can use the + to tell the boot loader and the kernel + to use the video display as the console instead. + + + + + + + + Toggles single and dual console configurations. In the + single configuration the console will be either the internal + console (video display) or the serial port, depending on the + state of the option above. In the dual + console configuration, both the video display and the + serial port will become the console at the same time, + regardless of the state of the option. + However, note that the dual console configuration takes effect + only during the boot block is running. Once the boot loader + gets control, the console specified by the + option becomes the only console. + + + + + + + + Makes the boot block probe the keyboard. If no keyboard + is found, the and + options are automatically set. + + + Due to space constraints in the current version of the + boot blocks, the option is capable of + detecting extended keyboards only. Keyboards with less + than 101 keys (and without F11 and F12 keys) may not be + detected. Keyboards on some laptop computers may not be + properly found because of this limitation. If this is + the case with your system, you have to abandon using + the option. Unfortunately there is no + workaround for this problem. + + + + + + Use either the option to select the + console automatically, or the option to + activate the serial console. + + You may include other options described in &man.boot.8; as + well. + + The options, except for , will be passed to + the boot loader (/boot/loader). The boot + loader will determine which of the internal video or the serial + port should become the console by examining the state of the + option alone. This means that if you specify + the option but not the + option in /boot.config, you can use the + serial port as the console only during the boot block; the boot + loader will use the internal video display as the console. + + + + Boot the machine. + + When you start your FreeBSD box, the boot blocks will echo the + contents of /boot.config to the console. For + example: + + /boot.config: -P +Keyboard: no + + The second line appears only if you put in + /boot.config and indicates presence/absence + of the keyboard. These messages go to either serial or internal + console, or both, depending on the option in + /boot.config. + + + + + + Options + Message goes to + + + + + + none + internal console + + + + + serial console + + + + + serial and internal consoles + + + + + serial and internal consoles + + + + , keyboard present + internal console + + + + , keyboard absent + serial console + + + + + + After the above messages, there will be a small pause before + the boot blocks continue loading the boot loader and before any + further messages printed to the console. Under normal + circumstances, you do not need to interrupt the boot blocks, but + you may want to do so in order to make sure things are set up + correctly. + + Hit any key, other than Enter, at the console to + interrupt the boot process. The boot blocks will then prompt you + for further action. You should now see something like: + + >> FreeBSD/i386 BOOT +Default: 0:ad(0,a)/boot/loader +boot: + + Verify the above message appears on either the serial or + internal console or both, according to the options you put in + /boot.config. If the message appears in the + correct console, hit Enter to continue the boot + process. + + If you want the serial console but you do not see the prompt + on the serial terminal, something is wrong with your settings. In + the meantime, you enter and hit Enter/Return + (if possible) to tell the boot block (and then the boot loader and + the kernel) to choose the serial port for the console. Once the + system is up, go back and check what went wrong. + + + + After the boot loader is loaded and you are in the third stage of + the boot process you can still switch between the internal console and + the serial console by setting appropriate environment variables in the + boot loader. See . + + + + Summary + + Here is the summary of various settings discussed in this section + and the console eventually selected. + + + Case 1: You Set the Flags to 0x10 for + <devicename>sio0</devicename> + + device sio0 at isa? port IO_COM1 flags 0x10 irq 4 + + + + + + Options in /boot.config + Console during boot blocks + Console during boot loader + Console in kernel + + + + + + nothing + internal + internal + internal + + + + + serial + serial + serial + + + + + serial and internal + internal + internal + + + + + serial and internal + serial + serial + + + + , keyboard present + internal + internal + internal + + + + , keyboard absent + serial and internal + serial + serial + + + + + + + + Case 2: You Set the Flags to 0x30 for sio0 + + device sio0 at isa? port IO_COM1 flags 0x30 irq 4 + + + + + + Options in /boot.config + Console during boot blocks + Console during boot loader + Console in kernel + + + + + + nothing + internal + internal + serial + + + + + serial + serial + serial + + + + + serial and internal + internal + serial + + + + + serial and internal + serial + serial + + + + , keyboard present + internal + internal + serial + + + + , keyboard absent + serial and internal + serial + serial + + + + + + + + + Tips for the Serial Console + + + Setting a Faster Serial Port Speed + + By default, the serial port settings are: 9600 baud, 8 + bits, no parity, and 1 stop bit. If you wish to change the speed, you + need to recompile at least the boot blocks. Add the following line + to /etc/make.conf and compile new boot + blocks: + + BOOT_COMCONSOLE_SPEED=19200 + + See for detailed + instructions about building and installing new boot blocks. + + If the serial console is configured in some other way than by + booting with , or if the serial console used by + the kernel is different from the one used by the boot blocks, then + you must also add the following option to the kernel configuration + file and compile a new kernel: + + options CONSPEED=19200 + + + + Using Serial Port Other Than <devicename>sio0</devicename> for + the Console + + Using a port other than sio0 as the + console requires some recompiling. If you want to use another + serial port for whatever reasons, recompile the boot blocks, the + boot loader and the kernel as follows. + + + + Get the kernel source. (See ) + + + + Edit /etc/make.conf and set + BOOT_COMCONSOLE_PORT to the address of the + port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only + sio0 through + sio3 (COM1 + through COM4) can be used; multiport + serial cards will not work. No interrupt setting is + needed. + + + + Create a custom kernel configuration file and add + appropriate flags for the serial port you want to use. For + example, if you want to make sio1 + (COM2) the console: + + device sio1 at isa? port IO_COM2 flags 0x10 irq 3 + + or + + device sio1 at isa? port IO_COM2 flags 0x30 irq 3 + + The console flags for the other serial ports should not be + set. + + + + Recompile and install the boot blocks and the boot loader: + + &prompt.root; cd /sys/boot +&prompt.root; make clean +&prompt.root; make +&prompt.root; make install + + + + Rebuild and install the kernel. + + + + Write the boot blocks to the boot disk with + &man.bsdlabel.8; and boot from the new kernel. + + + + + + Entering the DDB Debugger from the Serial Line + + If you wish to drop into the kernel debugger from the serial + console (useful for remote diagnostics, but also dangerous if you + generate a spurious BREAK on the serial port!) then you should + compile your kernel with the following options: + + options BREAK_TO_DEBUGGER +options DDB + + + + Getting a Login Prompt on the Serial Console + + While this is not required, you may wish to get a + login prompt over the serial line, now that you + can see boot messages and can enter the kernel debugging session + through the serial console. Here is how to do it. + + Open the file /etc/ttys with an editor + and locate the lines: + + ttyd0 "/usr/libexec/getty std.9600" unknown off secure +ttyd1 "/usr/libexec/getty std.9600" unknown off secure +ttyd2 "/usr/libexec/getty std.9600" unknown off secure +ttyd3 "/usr/libexec/getty std.9600" unknown off secure + + ttyd0 through ttyd3 + corresponds to COM1 through + COM4. Change off to + on for the desired port. If you have changed the + speed of the serial port, you need to change + std.9600 to match the current setting, e.g. + std.19200. + + You may also want to change the terminal type from + unknown to the actual type of your serial + terminal. + + After editing the file, you must kill -HUP 1 + to make this change take effect. + + + + + Changing Console from the Boot Loader + + Previous sections described how to set up the serial console by + tweaking the boot block. This section shows that you can specify the + console by entering some commands and environment variables in the + boot loader. As the boot loader is invoked at the third stage of the + boot process, after the boot block, the settings in the boot loader + will override the settings in the boot block. + + + Setting Up the Serial Console + + You can easily specify the boot loader and the kernel to use the + serial console by writing just one line in + /boot/loader.rc: + + set console="comconsole" + + This will take effect regardless of the settings in the boot + block discussed in the previous section. + + You had better put the above line as the first line of + /boot/loader.rc so as to see boot messages on + the serial console as early as possible. + + Likewise, you can specify the internal console as: + + set console="vidconsole" + + If you do not set the boot loader environment variable + console, the boot loader, and subsequently the + kernel, will use whichever console indicated by the + option in the boot block. + + In versions 3.2 or later, you may specify the console in + /boot/loader.conf.local or + /boot/loader.conf, rather than in + /boot/loader.rc. In this method your + /boot/loader.rc should look like: + + include /boot/loader.4th +start + + Then, create /boot/loader.conf.local and + put the following line there. + + console=comconsole + + or + + console=vidconsole + + See &man.loader.conf.5; for more information. + + + At the moment, the boot loader has no option equivalent to the + option in the boot block, and there is no + provision to automatically select the internal console and the + serial console based on the presence of the keyboard. + + + + + Using a Serial Port Other Than <devicename>sio0</devicename> for + the Console + + You need to recompile the boot loader to use a serial port other + than sio0 for the serial console. Follow the + procedure described in . + + + + + Caveats + + The idea here is to allow people to set up dedicated servers that + require no graphics hardware or attached keyboards. Unfortunately, + while most systems will let you boot without a keyboard, there + are quite a few that will not let you boot without a graphics adapter. + Machines with AMI BIOSes can be configured to boot with no graphics + adapter installed simply by changing the graphics adapter setting in + the CMOS configuration to Not installed. + + However, many machines do not support this option and will refuse + to boot if you have no display hardware in the system. With these + machines, you will have to leave some kind of graphics card plugged in, + (even if it is just a junky mono board) although you will not have to + attach a monitor. You might also try installing an AMI + BIOS. + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/txtfiles.ent b/pl_PL.ISO8859-2/books/handbook/txtfiles.ent new file mode 100644 index 0000000000..95f9cd9639 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/txtfiles.ent @@ -0,0 +1,72 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/users/Makefile b/pl_PL.ISO8859-2/books/handbook/users/Makefile new file mode 100644 index 0000000000..dfa2918b7b --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/users/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= users/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/users/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/users/chapter.sgml new file mode 100644 index 0000000000..8b1baf6584 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/users/chapter.sgml @@ -0,0 +1,1040 @@ + + + + + + + Neil + Blakey-Milner + Contributed by + + + + + + Users and Basic Account Management + + + Synopsis + + FreeBSD allows multiple users to use the computer at the same time. + Obviously, only one of those users can be sitting in front of the screen and + keyboard at any one time + + Well, unless you hook up multiple terminals, but we will + save that for . + , but any number of users can log in through the + network to get their work done. To use the system every user must have + an account. + + After reading this chapter, you will know: + + + + The differences between the various user accounts on a FreeBSD + system. + + + + How to add user accounts. + + + + How to remove user accounts. + + + + How to change account details, such as the user's full name, or + preferred shell. + + + + How to set limits on a per-account basis, to control the + resources such as memory and CPU time that accounts and groups of + accounts are allowed to access. + + + + How to use groups to make account management easier. + + + + Before reading this chapter, you should: + + + + Understand the basics of &unix; and FreeBSD (). + + + + + + Introduction + + All access to the system is achieved via accounts, and all + processes are run by users, so user and account management are + of integral importance on FreeBSD systems. + + Every account on a FreeBSD system has certain information associated + with it to identify the account. + + + + User name + + + The user name as it would be typed at the + login: prompt. User names must be unique across + the computer; you may not have two users with the same + user name. There are a number of rules for creating valid user + names, documented in &man.passwd.5;; you would typically use user + names that consist of eight or fewer all lower case + characters. + + + + + Password + + + Each account has a password associated with it. The password + may be blank, in which case no password will be required to access + the system. This is normally a very bad idea; every account + should have a password. + + + + + User ID (UID) + + + The UID is a number, traditionally from 0 to 65535 + It is possible to use UID/GIDs as large as + 4294967295, but such IDs can cause serious problems + with software that makes assumptions about the values + of IDs. + , used to uniquely identify + the user to the system. Internally, FreeBSD uses the UID to + identify users—any FreeBSD commands that allow you to + specify a user name will convert it to the UID before working with + it. This means that you can have several accounts with different + user names but the same UID. As far as FreeBSD is concerned these + accounts are one user. It is unlikely you will ever need to do + this. + + + + + Group ID (GID) + + + The GID is a number, traditionally from 0 to 65535, used to uniquely identify + the primary group that the user belongs to. Groups are a + mechanism for controlling access to resources based on a user's + GID rather than their UID. This can significantly reduce the size + of some configuration files. A user may also be in more than one + group. + + + + + Login class + + + Login classes are an extension to the group mechanism that + provide additional flexibility when tailoring the system to + different users. + + + + + Password change time + + + By default FreeBSD does not force users to change their + passwords periodically. You can enforce this on a per-user basis, + forcing some or all of your users to change their passwords after + a certain amount of time has elapsed. + + + + + Account expiry time + + + By default FreeBSD does not expire accounts. If you are + creating accounts that you know have a limited lifespan, for + example, in a school where you have accounts for the students, + then you can specify when the account expires. After the expiry + time has elapsed the account cannot be used to log in to the + system, although the account's directories and files will + remain. + + + + + User's full name + + + The user name uniquely identifies the account to FreeBSD, but + does not necessarily reflect the user's real name. This + information can be associated with the account. + + + + + Home directory + + + The home directory is the full path to a directory on the + system in which the user will start when logging on to the + system. A common convention is to put all user home directories + under + /home/username + or /usr/home/username. + The user would store their personal files in their home directory, + and any directories they may create in there. + + + + + User shell + + + The shell provides the default environment users use to + interact with the system. There are many different kinds of + shells, and experienced users will have their own preferences, + which can be reflected in their account settings. + + + + + There are three main types of accounts: the Superuser, system users, and user accounts. The Superuser + account, usually called root, is used to + manage the system with no limitations on privileges. System + users run services. Finally, user accounts are used by real + people, who log on, read mail, and so forth. + + + + The Superuser Account + + + accounts + superuser (root) + + The superuser account, usually called + root, comes preconfigured to facilitate + system administration, and should not be used for day-to-day + tasks like sending and receiving mail, general exploration of + the system, or programming. + + This is because the superuser, unlike normal user accounts, + can operate without limits, and misuse of the superuser account + may result in spectacular disasters. User accounts are unable + to destroy the system by mistake, so it is generally best to use + normal user accounts whenever possible, unless you especially + need the extra privilege. + + You should always double and triple-check commands you issue + as the superuser, since an extra space or missing character can + mean irreparable data loss. + + So, the first thing you should do after reading this + chapter is to create an unprivileged user account for yourself + for general usage if you have not already. This applies equally + whether you are running a multi-user or single-user machine. + Later in this chapter, we discuss how to create additional + accounts, and how to change between the normal user and + superuser. + + + + System Accounts + + + accounts + system + + System users are those used to run services such as DNS, + mail, web servers, and so forth. The reason for this is + security; if all services ran as the superuser, they could + act without restriction. + + + accounts + daemon + + + accounts + operator + + Examples of system users are daemon, + operator, bind (for + the Domain Name Service), news, and + www. + + + accounts + nobody + + nobody is the generic unprivileged + system user. However, it is important to keep in mind that the + more services that use nobody, the more + files and processes that user will become associated with, and + hence the more privileged that user becomes. + + + + User Accounts + + + accounts + user + + User accounts are the primary means of access for real + people to the system, and these accounts insulate the user and + the environment, preventing the users from damaging the system + or other users, and allowing users to customize their + environment without affecting others. + + Every person accessing your system should have a unique user + account. This allows you to find out who is doing what, prevent + people from clobbering each others' settings or reading each + others' mail, and so forth. + + Each user can set up their own environment to accommodate + their use of the system, by using alternate shells, editors, key + bindings, and language. + + + + Modifying Accounts + + + accounts + modifying + + + There are a variety of different commands available in the + &unix; environment to manipulate user accounts. The most common + commands are summarized below, followed by more detailed + examples of their usage. + + + + + + + + + Command + Summary + + + + + &man.adduser.8; + The recommended command-line application for adding + new users. + + + &man.rmuser.8; + The recommended command-line application for + removing users. + + + &man.chpass.1; + A flexible tool to change user database information. + + + &man.passwd.1; + The simple command-line tool to change user + passwords. + + + &man.pw.8; + A powerful and flexible tool to modify all aspects + of user accounts. + + + + + + + <command>adduser</command> + + + accounts + adding + + + adduser + + + /usr/share/skel + + skeleton directory + &man.adduser.8; is a simple program for + adding new users. It creates entries in the system + passwd and group + files. It will also create a home directory for the new user, + copy in the default configuration files (dotfiles) from + /usr/share/skel, and can optionally mail + the new user a welcome message. + + + The password you type in is not echoed, nor are asterisks + displayed. Make sure that you do not mistype the password. + + + + + Just use &man.adduser.8; without arguments + from now on, and you will not have to go through changing the + defaults. If the program asks you to change the defaults, + exit the program, and try the + option. + + + + Adding a user on &os; + + &prompt.root; adduser +Username: jru +Full name: J. Random User +Uid (Leave empty for default): +Login group [jru]: +Login group is jru. Invite jru into other groups? []: wheel +Login class [default]: +Shell (sh csh tcsh zsh nologin) [sh]: zsh +Home directory [/home/jru]: +Use password-based authentication? [yes]: +Use an empty password? (yes/no) [no]: +Use a random password? (yes/no) [no]: +Enter password: +Enter password again: +Lock out the account after creation? [no]: +Username : jru +Password : **** +Full Name : J. Random User +Uid : 1001 +Class : +Groups : jru wheel +Home : /home/jru +Shell : /usr/local/bin/zsh +Locked : no +OK? (yes/no): yes +adduser: INFO: Successfully added (jru) to the user database. +Add another user? (yes/no): no +Goodbye! +&prompt.root; + + + + + <command>rmuser</command> + + rmuser + + accounts + removing + + + You can use &man.rmuser.8; to + completely remove a user from the system. + &man.rmuser.8; performs the following + steps: + + + + Removes the user's &man.crontab.1; entry (if + any). + + + Removes any &man.at.1; jobs belonging to the + user. + + + Kills all processes owned by the user. + + + Removes the user from the system's local password + file. + + + Removes the user's home directory (if it is owned by + the user). + + + Removes the incoming mail files belonging to the user + from /var/mail. + + + Removes all files owned by the user from temporary + file storage areas such as /tmp. + + + Finally, removes the username from all groups to which + it belongs in /etc/group. + + + If a group becomes empty and the group name is the + same as the username, the group is removed; this + complements the per-user unique groups created by + &man.adduser.8;. + + + + + + &man.rmuser.8; cannot be used to remove + superuser accounts, since that is almost always an indication + of massive destruction. + + By default, an interactive mode is used, which attempts to + make sure you know what you are doing. + + + <command>rmuser</command> Interactive Account Removal + + &prompt.root; rmuser jru +Matching password entry: +jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh +Is this the entry you wish to remove? y +Remove user's home directory (/home/jru)? y +Updating password file, updating databases, done. +Updating group file: trusted (removing group jru -- personal group is empty) done. +Removing user's incoming mail file /var/mail/jru: done. +Removing files belonging to jru from /tmp: done. +Removing files belonging to jru from /var/tmp: done. +Removing files belonging to jru from /var/tmp/vi.recover: done. +&prompt.root; + + + + + <command>chpass</command> + + chpass + &man.chpass.1; changes user database + information such as passwords, shells, and personal + information. + + Only system administrators, as the superuser, may change + other users' information and passwords with + &man.chpass.1;. + + When passed no options, aside from an optional username, + &man.chpass.1; displays an editor + containing user information. When the user exists from the + editor, the user database is updated with the new + information. + + + You will be asked for your password + after exiting the editor if you are not the superuser. + + + + Interactive <command>chpass</command> by Superuser + + #Changing user database information for jru. +Login: jru +Password: * +Uid [#]: 1001 +Gid [# or name]: 1001 +Change [month day year]: +Expire [month day year]: +Class: +Home directory: /home/jru +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information: + + + The normal user can change only a small subset of this + information, and only for themselves. + + + Interactive <command>chpass</command> by Normal User + + #Changing user database information for jru. +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information: + + + + &man.chfn.1; and &man.chsh.1; are + just links to &man.chpass.1;, as + are &man.ypchpass.1;, + &man.ypchfn.1;, and + &man.ypchsh.1;. NIS support is automatic, so + specifying the yp before the command is + not necessary. If this is confusing to you, do not worry, NIS will + be covered in . + + + + <command>passwd</command> + + passwd + + accounts + changing password + + &man.passwd.1; is the usual way to + change your own password as a user, or another user's password + as the superuser. + + + To prevent accidental or unauthorized changes, the original + password must be entered before a new password can be set. + + + + Changing Your Password + + &prompt.user; passwd +Changing local password for jru. +Old password: +New password: +Retype new password: +passwd: updating the database... +passwd: done + + + + Changing Another User's Password as the Superuser + + &prompt.root; passwd jru +Changing local password for jru. +New password: +Retype new password: +passwd: updating the database... +passwd: done + + + + As with &man.chpass.1;, + &man.yppasswd.1; is just a link to + &man.passwd.1;, so NIS works with either + command. + + + + + + <command>pw</command> + pw + + &man.pw.8; is a command line utility to create, remove, + modify, and display users and groups. It functions as a front + end to the system user and group files. &man.pw.8; + has a very powerful set of command line options that make it + suitable for use in shell scripts, but new users may find it + more complicated than the other commands presented + here. + + + + + + + Limiting Users + + limiting users + + accounts + limiting + + If you have users, the ability to limit their system use may + have come to mind. FreeBSD provides + several ways an administrator can limit the amount of system + resources an individual may use. These limits are + divided into two sections: disk quotas, and other resource + limits. + + quotas + + limiting users + quotas + + disk quotas + Disk quotas limit disk usage to users, and + they + provide a way to quickly check that usage without + calculating it every time. Quotas are discussed in . + + The other resource limits include ways to limit the amount of + CPU, memory, and other resources a user may consume. These are + defined using login classes and are discussed here. + + + /etc/login.conf + + Login classes are defined in + /etc/login.conf. The precise semantics are + beyond the scope of this section, but are described in detail in the + &man.login.conf.5; manual page. It is sufficient to say that each + user is assigned to a login class (default by + default), and that each login class has a set of login capabilities + associated with it. A login capability is a + name=value + pair, where name is a well-known + identifier and value is an arbitrary + string processed accordingly depending on the name. Setting up login + classes and capabilities is rather straight-forward and is also + described in &man.login.conf.5;. + + + The system does not normally read the configuration in + /etc/login.conf directly, but reads the database + file /etc/login.conf.db which provides + faster lookups. + To generate /etc/login.conf.db from + /etc/login.conf, execute the following + command: + + &prompt.root; cap_mkdb /etc/login.conf + + + Resource limits are different from plain vanilla login + capabilities in two ways. First, for every limit, there is a soft + (current) and hard limit. A soft limit may be adjusted by the user + or application, but may be no higher than the hard limit. The latter + may be lowered by the user, but never raised. Second, most resource + limits apply per process to a specific user, not the user as a whole. + Note, however, that these differences are mandated by the specific + handling of the limits, not by the implementation of the login + capability framework (i.e., they are not really + a special case of login capabilities). + + And so, without further ado, below are the most commonly used + resource limits (the rest, along with all the other login + capabilities, may be found in &man.login.conf.5;). + + + + coredumpsize + + + coredumpsize + + limiting users + coredumpsize + + The limit on the size of a core file generated by a program + is, for obvious reasons, subordinate to other limits on disk + usage (e.g., filesize, or disk quotas). + Nevertheless, it is often used as a less-severe method of + controlling disk space consumption: since users do not generate + core files themselves, and often do not delete them, setting this + may save them from running out of disk space should a large + program (e.g., emacs) crash. + + + + + cputime + + + cputime + + limiting users + cputime + + This is the maximum amount of CPU time a user's process may + consume. Offending processes will be killed by the kernel. + + + This is a limit on CPU time + consumed, not percentage of the CPU as displayed in some + fields by &man.top.1; and &man.ps.1;. A limit on the + latter is, at the time of this writing, not possible, and + would be rather useless: a compiler—probably a + legitimate task—can easily use almost 100% of a CPU + for some time. + + + + + + + filesize + + + filesize + + limiting users + filesize + + This is the maximum size of a file the user may possess. + Unlike disk quotas, this limit is + enforced on individual files, not the set of all files a user + owns. + + + + + maxproc + + + maxproc + + limiting users + maxproc + + This is the maximum number of processes a user may be + running. This includes foreground and background processes + alike. For obvious reasons, this may not be larger than the + system limit specified by the kern.maxproc + &man.sysctl.8;. Also note that setting this + too small may hinder a + user's productivity: it is often useful to be logged in + multiple times or execute pipelines. Some tasks, such as + compiling a large program, also spawn multiple processes (e.g., + &man.make.1;, &man.cc.1;, and other intermediate + preprocessors). + + + + + memorylocked + + + memorylocked + + limiting users + memorylocked + + This is the maximum amount a memory a process may have + requested to be locked into main memory (e.g., see + &man.mlock.2;). Some system-critical programs, such as + &man.amd.8;, lock into main memory such that in the event + of being swapped out, they do not contribute to + a system's trashing in time of trouble. + + + + + memoryuse + + + memoryuse + + limiting users + memoryuse + + This is the maximum amount of memory a process may consume + at any given time. It includes both core memory and swap + usage. This is not a catch-all limit for restricting memory + consumption, but it is a good start. + + + + + openfiles + + + openfiles + + limiting users + openfiles + + This is the maximum amount of files a process may have + open. In FreeBSD, files are also used to represent sockets and + IPC channels; thus, be careful not to set this too low. The + system-wide limit for this is defined by the + kern.maxfiles &man.sysctl.8;. + + + + + sbsize + + + sbsize + + limiting users + sbsize + + This is the limit on the amount of network memory, and thus + mbufs, a user may consume. This originated as a response to an + old DoS attack by creating a lot of sockets, but can be + generally used to limit network communications. + + + + + stacksize + + + stacksize + + limiting users + stacksize + + This is the maximum size a process' stack may grow to. + This alone is not sufficient to limit the amount of memory a + program may use; consequently, it should be used in conjunction + with other limits. + + + + + There are a few other things to remember when setting resource + limits. Following are some general tips, suggestions, and + miscellaneous comments. + + + + Processes started at system startup by + /etc/rc are assigned to the + daemon login class. + + + + Although the /etc/login.conf that comes + with the system is a good source of reasonable values for most + limits, only you, the administrator, can know what is appropriate + for your system. Setting a limit too high may open your system + up to abuse, while setting it too low may put a strain on + productivity. + + + + Users of the X Window System (X11) should probably be granted + more resources than other users. X11 by itself takes a lot of + resources, but it also encourages users to run more programs + simultaneously. + + + + Remember that many limits apply to individual processes, not + the user as a whole. For example, setting + openfiles to 50 means + that each process the user runs may open up to 50 files. Thus, + the gross amount of files a user may open is the value of + openfiles multiplied by the value of + maxproc. This also applies to memory + consumption. + + + + For further information on resource limits and login classes and + capabilities in general, please consult the relevant manual pages: + &man.cap.mkdb.1;, &man.getrlimit.2;, &man.login.conf.5;. + + + + Groups + + groups + + /etc/groups + + + accounts + groups + + A group is simply a list of users. Groups are identified by + their group name and GID (Group ID). In FreeBSD (and most other &unix; like + systems), the two factors the kernel uses to decide whether a process + is allowed to do something is its user ID and list of groups it + belongs to. Unlike a user ID, a process has a list of groups + associated with it. You may hear some things refer to the group ID + of a user or process; most of the time, this just means the first + group in the list. + + The group name to group ID map is in + /etc/group. This is a plain text file with four + colon-delimited fields. The first field is the group name, the + second is the encrypted password, the third the group ID, and the + fourth the comma-delimited list of members. It can safely be edited + by hand (assuming, of course, that you do not make any syntax + errors!). For a more complete description of the syntax, see the + &man.group.5; manual page. + + If you do not want to edit /etc/group + manually, you can use the &man.pw.8; command to add and edit groups. + For example, to add a group called teamtwo and + then confirm that it exists you can use: + + + Adding a Group Using &man.pw.8; + + &prompt.root; pw groupadd teamtwo +&prompt.root; pw groupshow teamtwo +teamtwo:*:1100: + + + The number 1100 above is the group ID of the + group teamtwo. Right now, + teamtwo has no members, and is thus rather + useless. Let's change that by inviting jru to + the teamtwo group. + + + Adding Somebody to a Group Using &man.pw.8; + + &prompt.root; pw groupmod teamtwo -M jru +&prompt.root; pw groupshow teamtwo +teamtwo:*:1100:jru + + + The argument to the option is a + comma-delimited list of users who are members of the group. From the + preceding sections, we know that the password file also contains a + group for each user. The latter (the user) is automatically added to + the group list by the system; the user will not show up as a member + when using the command to &man.pw.8;, + but will show up when the information is queried via &man.id.1; or + similar tool. In other words, &man.pw.8; only manipulates the + /etc/group file; it will never attempt to read + additionally data from /etc/passwd. + + + Using &man.id.1; to Determine Group Membership + + &prompt.user; id jru +uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo) + + + As you can see, jru is a member of the + groups jru and + teamtwo. + + For more information about &man.pw.8;, see its manual page, and + for more information on the format of + /etc/group, consult the &man.group.5; manual + page. + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/vinum/Makefile b/pl_PL.ISO8859-2/books/handbook/vinum/Makefile new file mode 100644 index 0000000000..eca585a9aa --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/vinum/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= vinum/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/vinum/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/vinum/chapter.sgml new file mode 100644 index 0000000000..c3224799c8 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/vinum/chapter.sgml @@ -0,0 +1,1449 @@ + + + + + + + Greg + Lehey + Originally written by + + + + + The Vinum Volume Manager + + + Synopsis + + +No matter what disks you have, there are always potential problems: + + + They can be too small. + + + + They can be too slow. + + + + They can be too unreliable. + + + +One way some users safeguard themselves against such issues is +through the use of multiple, and sometimes redundant, disks. + +In addition to supporting various cards and controllers for hardware +RAID systems, the base FreeBSD system includes the Vinum Volume Manager, +a block device driver that implements virtual disk drives. + +Vinum provides more flexibility, performance, and reliability than +traditional disk storage, and implements RAID-0, RAID-1, and RAID-5 +models both individually and in combination. + +This chapter provides an overview of potential problems with traditional +disk storage, and an introduction to the Vinum Volume Manager. + + Starting with FreeBSD 5, Vinum has been rewritten in + order to fit into the GEOM architecture (), + retaining the original ideas, terminology, and on-disk metadata. + This rewrite is called gvinum (for + GEOM vinum). The following text usually refers to + Vinum as an abstract name, regardless of the + implementation variant. Any command invocations should now be + done using the gvinum command, and the name of + the kernel module has been changed from + vinum.ko to + geom_vinum.ko, and all device nodes reside + under /dev/gvinum instead of + /dev/vinum. As of FreeBSD 6, the old Vinum + implementation is no longer available in the code + base. + + + + + Disks Are Too Small + + Vinum + RAID + software + + Vinum is a so-called Volume + Manager, a virtual disk driver that addresses these + three problems. Let us look at them in more detail. Various + solutions to these problems have been proposed and + implemented: + + + Disks are getting bigger, but so are data storage + requirements. Often you will find you want a file system that + is bigger than the disks you have available. Admittedly, this + problem is not as acute as it was ten years ago, but it still + exists. Some systems have solved this by creating an abstract + device which stores its data on a number of disks. + + + + Access Bottlenecks + + Modern systems frequently need to access data in a highly + concurrent manner. For example, large FTP or HTTP servers can + maintain thousands of concurrent sessions and have multiple + 100 Mbit/s connections to the outside world, well beyond + the sustained transfer rate of most disks. + + Current disk drives can transfer data sequentially at up to + 70 MB/s, but this value is of little importance in an + environment where many independent processes access a drive, + where they may achieve only a fraction of these values. In such + cases it is more interesting to view the problem from the + viewpoint of the disk subsystem: the important parameter is the + load that a transfer places on the subsystem, in other words the + time for which a transfer occupies the drives involved in the + transfer. + + In any disk transfer, the drive must first position the + heads, wait for the first sector to pass under the read head, + and then perform the transfer. These actions can be considered + to be atomic: it does not make any sense to interrupt + them. + + Consider a typical transfer of + about 10 kB: the current generation of high-performance + disks can position the heads in an average of 3.5 ms. The + fastest drives spin at 15,000 rpm, so the average + rotational latency (half a revolution) is 2 ms. At + 70 MB/s, the transfer itself takes about 150 μs, + almost nothing compared to the positioning time. In such a + case, the effective transfer rate drops to a little over + 1 MB/s and is clearly highly dependent on the transfer + size. + + The traditional and obvious solution to this bottleneck is + more spindles: rather than using one large disk, + it uses several smaller disks with the same aggregate storage + space. Each disk is capable of positioning and transferring + independently, so the effective throughput increases by a factor + close to the number of disks used. + + + The exact throughput improvement is, of course, smaller than + the number of disks involved: although each drive is capable of + transferring in parallel, there is no way to ensure that the + requests are evenly distributed across the drives. Inevitably + the load on one drive will be higher than on another. + + + disk concatenation + + + Vinum + concatenation + + + The evenness of the load on the disks is strongly dependent + on the way the data is shared across the drives. In the + following discussion, it is convenient to think of the disk + storage as a large number of data sectors which are addressable + by number, rather like the pages in a book. The most obvious + method is to divide the virtual disk into groups of consecutive + sectors the size of the individual physical disks and store them + in this manner, rather like taking a large book and tearing it + into smaller sections. This method is called + concatenation and has the advantage that + the disks are not required to have any specific size + relationships. It works well when the access to the virtual + disk is spread evenly about its address space. When access is + concentrated on a smaller area, the improvement is less marked. + illustrates the sequence in which + storage units are allocated in a concatenated + organization. + + +
+ Concatenated Organization + +
+ + + + disk striping + + + Vinum + striping + + + RAID + + + An alternative mapping is to divide the address space into + smaller, equal-sized components and store them sequentially on + different devices. For example, the first 256 sectors may be + stored on the first disk, the next 256 sectors on the next disk + and so on. After filling the last disk, the process repeats + until the disks are full. This mapping is called + striping or RAID-0 + + + RAID stands for Redundant + Array of Inexpensive Disks and offers various forms + of fault tolerance, though the latter term is somewhat + misleading: it provides no redundancy. . + + Striping requires somewhat more effort to locate the data, and it + can cause additional I/O load where a transfer is spread over + multiple disks, but it can also provide a more constant load + across the disks. illustrates the + sequence in which storage units are allocated in a striped + organization. + + +
+ Striped Organization + +
+ + + + + Data Integrity + + The final problem with current disks is that they are + unreliable. Although disk drive reliability has increased + tremendously over the last few years, they are still the most + likely core component of a server to fail. When they do, the + results can be catastrophic: replacing a failed disk drive and + restoring data to it can take days. + + + disk mirroring + + + Vinum + mirroring + + + RAID-1 + + + The traditional way to approach this problem has been + mirroring, keeping two copies of the data + on different physical hardware. Since the advent of the + RAID levels, this technique has also been + called RAID level 1 or + RAID-1. Any write to the volume writes to + both locations; a read can be satisfied from either, so if one + drive fails, the data is still available on the other + drive. + + Mirroring has two problems: + + + + The price. It requires twice as much disk storage as + a non-redundant solution. + + + + The performance impact. Writes must be performed to + both drives, so they take up twice the bandwidth of a + non-mirrored volume. Reads do not suffer from a + performance penalty: it even looks as if they are + faster. + + + + RAID-5An + alternative solution is parity, + implemented in the RAID levels 2, 3, 4 and + 5. Of these, RAID-5 is the most + interesting. As implemented in Vinum, it is a variant on a + striped organization which dedicates one block of each stripe + to parity of the other blocks. As implemented by Vinum, a + RAID-5 plex is similar to a striped plex, + except that it implements RAID-5 by + including a parity block in each stripe. As required by + RAID-5, the location of this parity block + changes from one stripe to the next. The numbers in the data + blocks indicate the relative block numbers. + + +
+ RAID-5 Organization + +
+ + + Compared to mirroring, RAID-5 has the + advantage of requiring significantly less storage space. Read + access is similar to that of striped organizations, but write + access is significantly slower, approximately 25% of the read + performance. If one drive fails, the array can continue to + operate in degraded mode: a read from one of the remaining + accessible drives continues normally, but a read from the + failed drive is recalculated from the corresponding block from + all the remaining drives. + + + + + Vinum Objects + In order to address these problems, Vinum implements a four-level + hierarchy of objects: + + + + The most visible object is the virtual disk, called a + volume. Volumes have essentially the same + properties as a &unix; disk drive, though there are some minor + differences. They have no size limitations. + + + + Volumes are composed of plexes, + each of which represent the total address space of a + volume. This level in the hierarchy thus provides + redundancy. Think of plexes as individual disks in a + mirrored array, each containing the same data. + + + + Since Vinum exists within the &unix; disk storage + framework, it would be possible to use &unix; + partitions as the building block for multi-disk plexes, + but in fact this turns out to be too inflexible: + &unix; disks can have only a limited number of + partitions. Instead, Vinum subdivides a single + &unix; partition (the drive) + into contiguous areas called + subdisks, which it uses as building + blocks for plexes. + + + + Subdisks reside on Vinum drives, + currently &unix; partitions. Vinum drives can + contain any number of subdisks. With the exception of a + small area at the beginning of the drive, which is used + for storing configuration and state information, the + entire drive is available for data storage. + + + + The following sections describe the way these objects provide the + functionality required of Vinum. + + + Volume Size Considerations + + Plexes can include multiple subdisks spread over all + drives in the Vinum configuration. As a result, the size of + an individual drive does not limit the size of a plex, and + thus of a volume. + + + + Redundant Data Storage + Vinum implements mirroring by attaching multiple plexes to + a volume. Each plex is a representation of the data in a + volume. A volume may contain between one and eight + plexes. + + Although a plex represents the complete data of a volume, + it is possible for parts of the representation to be + physically missing, either by design (by not defining a + subdisk for parts of the plex) or by accident (as a result of + the failure of a drive). As long as at least one plex can + provide the data for the complete address range of the volume, + the volume is fully functional. + + + + Performance Issues + + Vinum implements both concatenation and striping at the + plex level: + + + + A concatenated plex uses the + address space of each subdisk in turn. + + + + A striped plex stripes the data + across each subdisk. The subdisks must all have the same + size, and there must be at least two subdisks in order to + distinguish it from a concatenated plex. + + + + + + Which Plex Organization? + The version of Vinum supplied with FreeBSD &rel.current; implements + two kinds of plex: + + + + Concatenated plexes are the most flexible: they can + contain any number of subdisks, and the subdisks may be of + different length. The plex may be extended by adding + additional subdisks. They require less + CPU time than striped plexes, though + the difference in CPU overhead is not + measurable. On the other hand, they are most susceptible + to hot spots, where one disk is very active and others are + idle. + + + + The greatest advantage of striped + (RAID-0) plexes is that they reduce hot + spots: by choosing an optimum sized stripe (about + 256 kB), you can even out the load on the component + drives. The disadvantages of this approach are + (fractionally) more complex code and restrictions on + subdisks: they must be all the same size, and extending a + plex by adding new subdisks is so complicated that Vinum + currently does not implement it. Vinum imposes an + additional, trivial restriction: a striped plex must have + at least two subdisks, since otherwise it is + indistinguishable from a concatenated plex. + + + + summarizes the advantages + and disadvantages of each plex organization. + + + Vinum Plex Organizations + + + + Plex type + Minimum subdisks + Can add subdisks + Must be equal size + Application + + + + + + concatenated + 1 + yes + no + Large data storage with maximum placement flexibility + and moderate performance + + + + striped + 2 + no + yes + High performance in combination with highly concurrent + access + + + +
+ + + + + Some Examples + + Vinum maintains a configuration + database which describes the objects known to an + individual system. Initially, the user creates the + configuration database from one or more configuration files with + the aid of the &man.gvinum.8; utility program. Vinum stores a + copy of its configuration database on each disk slice (which + Vinum calls a device) under its control. + This database is updated on each state change, so that a restart + accurately restores the state of each Vinum object. + + + The Configuration File + The configuration file describes individual Vinum objects. The + definition of a simple volume might be: + + + drive a device /dev/da3h + volume myvol + plex org concat + sd length 512m drive a + + This file describes four Vinum objects: + + + + The drive line describes a disk + partition (drive) and its location + relative to the underlying hardware. It is given the + symbolic name a. This separation of + the symbolic names from the device names allows disks to + be moved from one location to another without + confusion. + + + + The volume line describes a volume. + The only required attribute is the name, in this case + myvol. + + + + The plex line defines a plex. + The only required parameter is the organization, in this + case concat. No name is necessary: + the system automatically generates a name from the volume + name by adding the suffix + .px, where + x is the number of the plex in the + volume. Thus this plex will be called + myvol.p0. + + + + The sd line describes a subdisk. + The minimum specifications are the name of a drive on + which to store it, and the length of the subdisk. As with + plexes, no name is necessary: the system automatically + assigns names derived from the plex name by adding the + suffix .sx, + where x is the number of the subdisk + in the plex. Thus Vinum gives this subdisk the name + myvol.p0.s0. + + + + After processing this file, &man.gvinum.8; produces the following + output: + + + &prompt.root; gvinum -> create config1 + Configuration summary + Drives: 1 (4 configured) + Volumes: 1 (4 configured) + Plexes: 1 (8 configured) + Subdisks: 1 (16 configured) + + D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%) + + V myvol State: up Plexes: 1 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + + This output shows the brief listing format of &man.gvinum.8;. It + is represented graphically in . + + +
+ A Simple Vinum Volume + +
+ + + This figure, and the ones which follow, represent a + volume, which contains the plexes, which in turn contain the + subdisks. In this trivial example, the volume contains one + plex, and the plex contains one subdisk. + + This particular volume has no specific advantage over a + conventional disk partition. It contains a single plex, so it + is not redundant. The plex contains a single subdisk, so + there is no difference in storage allocation from a + conventional disk partition. The following sections + illustrate various more interesting configuration + methods. + + + + Increased Resilience: Mirroring + + The resilience of a volume can be increased by mirroring. + When laying out a mirrored volume, it is important to ensure + that the subdisks of each plex are on different drives, so + that a drive failure will not take down both plexes. The + following configuration mirrors a volume: + + + drive b device /dev/da4h + volume mirror + plex org concat + sd length 512m drive a + plex org concat + sd length 512m drive b + + In this example, it was not necessary to specify a + definition of drive a again, since Vinum + keeps track of all objects in its configuration database. + After processing this definition, the configuration looks + like: + + + + Drives: 2 (4 configured) + Volumes: 2 (4 configured) + Plexes: 3 (8 configured) + Subdisks: 3 (16 configured) + + D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%) + D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%) + + V myvol State: up Plexes: 1 Size: 512 MB + V mirror State: up Plexes: 2 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB + + shows the structure + graphically. + + +
+ A Mirrored Vinum Volume + +
+ + + In this example, each plex contains the full 512 MB + of address space. As in the previous example, each plex + contains only a single subdisk. + + + + Optimizing Performance + + The mirrored volume in the previous example is more + resistant to failure than an unmirrored volume, but its + performance is less: each write to the volume requires a write + to both drives, using up a greater proportion of the total + disk bandwidth. Performance considerations demand a different + approach: instead of mirroring, the data is striped across as + many disk drives as possible. The following configuration + shows a volume with a plex striped across four disk + drives: + + + drive c device /dev/da5h + drive d device /dev/da6h + volume stripe + plex org striped 512k + sd length 128m drive a + sd length 128m drive b + sd length 128m drive c + sd length 128m drive d + + As before, it is not necessary to define the drives which are + already known to Vinum. After processing this definition, the + configuration looks like: + + + Drives: 4 (4 configured) + Volumes: 3 (4 configured) + Plexes: 4 (8 configured) + Subdisks: 7 (16 configured) + + D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%) + D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%) + D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%) + D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%) + + V myvol State: up Plexes: 1 Size: 512 MB + V mirror State: up Plexes: 2 Size: 512 MB + V striped State: up Plexes: 1 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB + P striped.p1 State: up Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB + S striped.p0.s0 State: up PO: 0 B Size: 128 MB + S striped.p0.s1 State: up PO: 512 kB Size: 128 MB + S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB + S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB + + +
+ A Striped Vinum Volume + +
+ + + This volume is represented in + . The darkness of the stripes + indicates the position within the plex address space: the lightest stripes + come first, the darkest last. + + + + Resilience and Performance + + With sufficient hardware, it + is possible to build volumes which show both increased + resilience and increased performance compared to standard + &unix; partitions. A typical configuration file might + be: + + + volume raid10 + plex org striped 512k + sd length 102480k drive a + sd length 102480k drive b + sd length 102480k drive c + sd length 102480k drive d + sd length 102480k drive e + plex org striped 512k + sd length 102480k drive c + sd length 102480k drive d + sd length 102480k drive e + sd length 102480k drive a + sd length 102480k drive b + + The subdisks of the second plex are offset by two drives from those + of the first plex: this helps ensure that writes do not go to the same + subdisks even if a transfer goes over two drives. + + represents the structure + of this volume. + + +
+ A Mirrored, Striped Vinum Volume + +
+ + + + + + Object Naming + + As described above, Vinum assigns default names to plexes + and subdisks, although they may be overridden. Overriding the + default names is not recommended: experience with the VERITAS + volume manager, which allows arbitrary naming of objects, has + shown that this flexibility does not bring a significant + advantage, and it can cause confusion. + + Names may contain any non-blank character, but it is + recommended to restrict them to letters, digits and the + underscore characters. The names of volumes, plexes and + subdisks may be up to 64 characters long, and the names of + drives may be up to 32 characters long. + + Vinum objects are assigned device nodes in the hierarchy + /dev/gvinum. The configuration shown above + would cause Vinum to create the following device nodes: + + + + This only applies to the historic Vinum + implemenation. + + The control devices + /dev/vinum/control and + /dev/vinum/controld, which are used + by &man.gvinum.8; and the Vinum daemon respectively. + + + + Device entries for each volume. + These are the main devices used by Vinum. Thus the configuration + above would include the devices + /dev/gvinum/myvol, + /dev/gvinum/mirror, + /dev/gvinum/striped, + /dev/gvinum/raid5 and + /dev/gvinum/raid10. + + + + This only applies to the historic Vinum + implemenation. + + A directory /dev/vinum/drive + with entries for each drive. These entries are in fact + symbolic links to the corresponding disk nodes. + + + + All volumes get direct entries under + /dev/gvinum/. + + + + The directories + /dev/gvinum/plex, and + /dev/gvinum/sd, which contain + device nodes for each plex and for each subdisk, + respectively. + + + + For example, consider the following configuration file: + + drive drive1 device /dev/sd1h + drive drive2 device /dev/sd2h + drive drive3 device /dev/sd3h + drive drive4 device /dev/sd4h + volume s64 setupstate + plex org striped 64k + sd length 100m drive drive1 + sd length 100m drive drive2 + sd length 100m drive drive3 + sd length 100m drive drive4 + + After processing this file, &man.gvinum.8; creates the following + structure in /dev/gvinum: + + + drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex + crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64 + drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd + + /dev/vinum/plex: + total 0 + crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 + + /dev/vinum/sd: + total 0 + crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0 + crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1 + crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2 + crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3 + + Although it is recommended that plexes and subdisks should + not be allocated specific names, Vinum drives must be named. + This makes it possible to move a drive to a different location + and still recognize it automatically. Drive names may be up to + 32 characters long. + + + Creating File Systems + + Volumes appear to the system to be identical to disks, + with one exception. Unlike &unix; drives, Vinum does + not partition volumes, which thus do not contain a partition + table. This has required modification to some disk + utilities, notably &man.newfs.8;, which previously tried to + interpret the last letter of a Vinum volume name as a + partition identifier. For example, a disk drive may have a + name like /dev/ad0a or + /dev/da2h. These names represent + the first partition (a) on the + first (0) IDE disk (ad) and the + eighth partition (h) on the third + (2) SCSI disk (da) respectively. + By contrast, a Vinum volume might be called + /dev/gvinum/concat, a name which has + no relationship with a partition name. + + Normally, &man.newfs.8; interprets the name of the disk and + complains if it cannot understand it. For example: + + &prompt.root; newfs /dev/gvinum/concat +newfs: /dev/gvinum/concat: can't figure out file system partition + + In order to create a file system on this volume, use + &man.newfs.8;: + + &prompt.root; newfs /dev/gvinum/concat + + On &os; versions prior to 5.0 &man.newfs.8; requires + an additional -v flag and the old device naming + scheme: + + &prompt.root; newfs -v /dev/vinum/concat + + + + + + Configuring Vinum + + The GENERIC kernel does not contain + Vinum. It is possible to build a special kernel which includes + Vinum, but this is not recommended. The standard way to start + Vinum is as a kernel module (kld). You do + not even need to use &man.kldload.8; for Vinum: when you start + &man.gvinum.8;, it checks whether the module has been loaded, and + if it is not, it loads it automatically. + + + + Startup + + Vinum stores configuration information on the disk slices + in essentially the same form as in the configuration files. + When reading from the configuration database, Vinum recognizes + a number of keywords which are not allowed in the + configuration files. For example, a disk configuration might + contain the following text: + + volume myvol state up +volume bigraid state down +plex name myvol.p0 state up org concat vol myvol +plex name myvol.p1 state up org concat vol myvol +plex name myvol.p2 state init org striped 512b vol myvol +plex name bigraid.p0 state initializing org raid5 512b vol bigraid +sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b +sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b +sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b +sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b +sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b +sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b +sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b +sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b +sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b +sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b +sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b +sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b +sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b + + The obvious differences here are the presence of + explicit location information and naming (both of which are + also allowed, but discouraged, for use by the user) and the + information on the states (which are not available to the + user). Vinum does not store information about drives in the + configuration information: it finds the drives by scanning + the configured disk drives for partitions with a Vinum + label. This enables Vinum to identify drives correctly even + if they have been assigned different &unix; drive + IDs. + + + Automatic Startup + + This information only relates to the historic + Vinum implementation. Gvinum always + features an automatic startup once the kernel module is + loaded. + + In order to start Vinum automatically when you boot the + system, ensure that you have the following line in your + /etc/rc.conf: + + start_vinum="YES" # set to YES to start vinum + + If you do not have a file + /etc/rc.conf, create one with this + content. This will cause the system to load the Vinum + kld at startup, and to start any objects + mentioned in the configuration. This is done before + mounting file systems, so it is possible to automatically + &man.fsck.8; and mount file systems on Vinum volumes. + + When you start Vinum with the vinum + start command, Vinum reads the configuration + database from one of the Vinum drives. Under normal + circumstances, each drive contains an identical copy of the + configuration database, so it does not matter which drive is + read. After a crash, however, Vinum must determine which + drive was updated most recently and read the configuration + from this drive. It then updates the configuration if + necessary from progressively older drives. + + + + + + + Using Vinum for the Root Filesystem + + For a machine that has fully-mirrored filesystems using + Vinum, it is desirable to also mirror the root filesystem. + Setting up such a configuration is less trivial than mirroring + an arbitrary filesystem because: + + + + The root filesystem must be available very early during + the boot process, so the Vinum infrastructure must already be + available at this time. + + + The volume containing the root filesystem also contains + the system bootstrap and the kernel, which must be read + using the host system's native utilities (e. g. the BIOS on + PC-class machines) which often cannot be taught about the + details of Vinum. + + + + In the following sections, the term root + volume is generally used to describe the Vinum volume + that contains the root filesystem. It is probably a good idea + to use the name "root" for this volume, but + this is not technically required in any way. All command + examples in the following sections assume this name though. + + + Starting up Vinum Early Enough for the Root + Filesystem + + There are several measures to take for this to + happen: + + + + Vinum must be available in the kernel at boot-time. + Thus, the method to start Vinum automatically described in + is not applicable to + accomplish this task, and the + start_vinum parameter must actually + not be set when the following setup + is being arranged. The first option would be to compile + Vinum statically into the kernel, so it is available all + the time, but this is usually not desirable. There is + another option as well, to have + /boot/loader () load the vinum kernel module + early, before starting the kernel. This can be + accomplished by putting the line: + + geom_vinum_load="YES" + + into the file + /boot/loader.conf. + + + + For Gvinum, all startup + is done automatically once the kernel module has been + loaded, so the procedure described above is all that is + needed. The following text documents the behaviour of + the historic Vinum system, for the sake of older + setups. + + Vinum must be initialized early since it needs to + supply the volume for the root filesystem. By default, + the Vinum kernel part is not looking for drives that might + contain Vinum volume information until the administrator + (or one of the startup scripts) issues a vinum + start command. + + The following paragraphs are outlining the steps + needed for FreeBSD 5.X and above. The setup required for + FreeBSD 4.X differs, and is described below in . + + By placing the line: + + vinum.autostart="YES" + + into /boot/loader.conf, Vinum is + instructed to automatically scan all drives for Vinum + information as part of the kernel startup. + + Note that it is not necessary to instruct the kernel + where to look for the root filesystem. + /boot/loader looks up the name of the + root device in /etc/fstab, and passes + this information on to the kernel. When it comes to mount + the root filesystem, the kernel figures out from the + device name provided which driver to ask to translate this + into the internal device ID (major/minor number). + + + + + + Making a Vinum-based Root Volume Accessible to the + Bootstrap + + Since the current FreeBSD bootstrap is only 7.5 KB of + code, and already has the burden of reading files (like + /boot/loader) from the UFS filesystem, it + is sheer impossible to also teach it about internal Vinum + structures so it could parse the Vinum configuration data, and + figure out about the elements of a boot volume itself. Thus, + some tricks are necessary to provide the bootstrap code with + the illusion of a standard "a" partition + that contains the root filesystem. + + For this to be possible at all, the following requirements + must be met for the root volume: + + + + The root volume must not be striped or RAID-5. + + + + The root volume must not contain more than one + concatenated subdisk per plex. + + + + Note that it is desirable and possible that there are + multiple plexes, each containing one replica of the root + filesystem. The bootstrap process will, however, only use one + of these replica for finding the bootstrap and all the files, + until the kernel will eventually mount the root filesystem + itself. Each single subdisk within these plexes will then + need its own "a" partition illusion, for + the respective device to become bootable. It is not strictly + needed that each of these faked "a" + partitions is located at the same offset within its device, + compared with other devices containing plexes of the root + volume. However, it is probably a good idea to create the + Vinum volumes that way so the resulting mirrored devices are + symmetric, to avoid confusion. + + In order to set up these "a" partitions, + for each device containing part of the root volume, the + following needs to be done: + + + + The location (offset from the beginning of the device) + and size of this device's subdisk that is part of the root + volume need to be examined, using the command: + + &prompt.root; gvinum l -rv root + + Note that Vinum offsets and sizes are measured in + bytes. They must be divided by 512 in order to obtain the + block numbers that are to be used in the + bsdlabel command. + + + + Run the command: + + &prompt.root; bsdlabel -e devname + + for each device that participates in the root volume. + devname must be either the name + of the disk (like da0) for disks + without a slice (aka. fdisk) table, or the name of the + slice (like ad0s1). + + If there is already an "a" + partition on the device (presumably, containing a + pre-Vinum root filesystem), it should be renamed to + something else, so it remains accessible (just in case), + but will no longer be used by default to bootstrap the + system. Note that active partitions (like a root + filesystem currently mounted) cannot be renamed, so this + must be executed either when being booted from a + Fixit medium, or in a two-step process, + where (in a mirrored situation) the disk that has not been + currently booted is being manipulated first. + + Then, the offset the Vinum partition on this + device (if any) must be added to the offset of the + respective root volume subdisk on this device. The + resulting value will become the + "offset" value for the new + "a" partition. The + "size" value for this partition can be + taken verbatim from the calculation above. The + "fstype" should be + 4.2BSD. The + "fsize", "bsize", + and "cpg" values should best be chosen + to match the actual filesystem, though they are fairly + unimportant within this context. + + That way, a new "a" partition will + be established that overlaps the Vinum partition on this + device. Note that the bsdlabel will + only allow for this overlap if the Vinum partition has + properly been marked using the "vinum" + fstype. + + + + That's all! A faked "a" partition + does exist now on each device that has one replica of the + root volume. It is highly recommendable to verify the + result again, using a command like: + + &prompt.root; fsck -n /dev/devnamea + + + + It should be remembered that all files containing control + information must be relative to the root filesystem in the + Vinum volume which, when setting up a new Vinum root volume, + might not match the root filesystem that is currently active. + So in particular, the files /etc/fstab + and /boot/loader.conf need to be taken + care of. + + At next reboot, the bootstrap should figure out the + appropriate control information from the new Vinum-based root + filesystem, and act accordingly. At the end of the kernel + initialization process, after all devices have been announced, + the prominent notice that shows the success of this setup is a + message like: + + Mounting root from ufs:/dev/gvinum/root + + + + Example of a Vinum-based Root Setup + + After the Vinum root volume has been set up, the output of + gvinum l -rv root could look like: + + +... +Subdisk root.p0.s0: + Size: 125829120 bytes (120 MB) + State: up + Plex root.p0 at offset 0 (0 B) + Drive disk0 (/dev/da0h) at offset 135680 (132 kB) + +Subdisk root.p1.s0: + Size: 125829120 bytes (120 MB) + State: up + Plex root.p1 at offset 0 (0 B) + Drive disk1 (/dev/da1h) at offset 135680 (132 kB) + + + The values to note are 135680 for the + offset (relative to partition + /dev/da0h). This translates to 265 + 512-byte disk blocks in bsdlabel's terms. + Likewise, the size of this root volume is 245760 512-byte + blocks. /dev/da1h, containing the + second replica of this root volume, has a symmetric + setup. + + The bsdlabel for these devices might look like: + + +... +8 partitions: +# size offset fstype [fsize bsize bps/cpg] + a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*) + c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*) + h: 71771672 16 vinum # (Cyl. 0*- 4467*) + + + It can be observed that the "size" + parameter for the faked "a" partition + matches the value outlined above, while the + "offset" parameter is the sum of the offset + within the Vinum partition "h", and the + offset of this partition within the device (or slice). This + is a typical setup that is necessary to avoid the problem + described in . It can also + be seen that the entire "a" partition is + completely within the "h" partition + containing all the Vinum data for this device. + + Note that in the above example, the entire device is + dedicated to Vinum, and there is no leftover pre-Vinum root + partition, since this has been a newly set-up disk that was + only meant to be part of a Vinum configuration, ever. + + + + Troubleshooting + + If something goes wrong, a way is needed to recover from + the situation. The following list contains few known pitfalls + and solutions. + + + System Bootstrap Loads, but System Does Not Boot + + If for any reason the system does not continue to boot, + the bootstrap can be interrupted with by pressing the + space key at the 10-seconds warning. The + loader variables (like vinum.autostart) + can be examined using the show, and + manipulated using set or + unset commands. + + If the only problem was that the Vinum kernel module was + not yet in the list of modules to load automatically, a + simple load geom_vinum will help. + + When ready, the boot process can be continued with a + boot -as. The options + will request the kernel to ask for the + root filesystem to mount (), and make the + boot process stop in single-user mode (), + where the root filesystem is mounted read-only. That way, + even if only one plex of a multi-plex volume has been + mounted, no data inconsistency between plexes is being + risked. + + At the prompt asking for a root filesystem to mount, any + device that contains a valid root filesystem can be entered. + If /etc/fstab had been set up + correctly, the default should be something like + ufs:/dev/gvinum/root. A typical alternate + choice would be something like + ufs:da0d which could be a + hypothetical partition that contains the pre-Vinum root + filesystem. Care should be taken if one of the alias + "a" partitions are entered here that are + actually reference to the subdisks of the Vinum root device, + because in a mirrored setup, this would only mount one piece + of a mirrored root device. If this filesystem is to be + mounted read-write later on, it is necessary to remove the + other plex(es) of the Vinum root volume since these plexes + would otherwise carry inconsistent data. + + + + Only Primary Bootstrap Loads + + If /boot/loader fails to load, but + the primary bootstrap still loads (visible by a single dash + in the left column of the screen right after the boot + process starts), an attempt can be made to interrupt the + primary bootstrap at this point, using the + space key. This will make the bootstrap + stop in stage two, see . An + attempt can be made here to boot off an alternate partition, + like the partition containing the previous root filesystem + that has been moved away from "a" + above. + + + + Nothing Boots, the Bootstrap + Panics + + This situation will happen if the bootstrap had been + destroyed by the Vinum installation. Unfortunately, Vinum + accidentally currently leaves only 4 KB at the beginning of + its partition free before starting to write its Vinum header + information. However, the stage one and two bootstraps plus + the bsdlabel embedded between them currently require 8 KB. + So if a Vinum partition was started at offset 0 within a + slice or disk that was meant to be bootable, the Vinum setup + will trash the bootstrap. + + Similarly, if the above situation has been recovered, + for example by booting from a Fixit medium, + and the bootstrap has been re-installed using + bsdlabel -B as described in , the bootstrap will trash the Vinum + header, and Vinum will no longer find its disk(s). Though + no actual Vinum configuration data or data in Vinum volumes + will be trashed by this, and it would be possible to recover + all the data by entering exact the same Vinum configuration + data again, the situation is hard to fix at all. It would + be necessary to move the entire Vinum partition by at least + 4 KB off, in order to have the Vinum header and the system + bootstrap no longer collide. + + + + + Differences for FreeBSD 4.X + + Under FreeBSD 4.X, some internal functions required to + make Vinum automatically scan all disks are missing, and the + code that figures out the internal ID of the root device is + not smart enough to handle a name like + /dev/vinum/root automatically. + Therefore, things are a little different here. + + Vinum must explicitly be told which disks to scan, using a + line like the following one in + /boot/loader.conf: + + vinum.drives="/dev/da0 /dev/da1" + + It is important that all drives are mentioned that could + possibly contain Vinum data. It does not harm if + more drives are listed, nor is it + necessary to add each slice and/or partition explicitly, since + Vinum will scan all slices and partitions of the named drives + for valid Vinum headers. + + Since the routines used to parse the name of the root + filesystem, and derive the device ID (major/minor number) are + only prepared to handle classical device names + like /dev/ad0s1a, they cannot make + any sense out of a root volume name like + /dev/vinum/root. For that reason, + Vinum itself needs to pre-setup the internal kernel parameter + that holds the ID of the root device during its own + initialization. This is requested by passing the name of the + root volume in the loader variable + vinum.root. The entry in + /boot/loader.conf to accomplish this + looks like: + + vinum.root="root" + + Now, when the kernel initialization tries to find out the + root device to mount, it sees whether some kernel module has + already pre-initialized the kernel parameter for it. If that + is the case, and the device claiming the + root device matches the major number of the driver as figured + out from the name of the root device string being passed (that + is, "vinum" in our case), it will use the + pre-allocated device ID, instead of trying to figure out one + itself. That way, during the usual automatic startup, it can + continue to mount the Vinum root volume for the root + filesystem. + + However, when boot -a has been + requesting to ask for entering the name of the root device + manually, it must be noted that this routine still cannot + actually parse a name entered there that refers to a Vinum + volume. If any device name is entered that does not refer to + a Vinum device, the mismatch between the major numbers of the + pre-allocated root parameter and the driver as figured out + from the given name will make this routine enter its normal + parser, so entering a string like + ufs:da0d will work as expected. Note + that if this fails, it is however no longer possible to + re-enter a string like ufs:vinum/root + again, since it cannot be parsed. The only way out is to + reboot again, and start over then. (At the + askroot prompt, the initial + /dev/ can always be omitted.) + + + + + diff --git a/pl_PL.ISO8859-2/books/handbook/x11/Makefile b/pl_PL.ISO8859-2/books/handbook/x11/Makefile new file mode 100644 index 0000000000..06b452cd33 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/x11/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= x11/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/pl_PL.ISO8859-2/books/handbook/x11/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/x11/chapter.sgml new file mode 100644 index 0000000000..319dc29131 --- /dev/null +++ b/pl_PL.ISO8859-2/books/handbook/x11/chapter.sgml @@ -0,0 +1,1680 @@ + + + + + + + Ken + Tom + Updated for X.Org's X11 server by + + + Marc + Fonvieille + + + + + The X Window System + + + Synopsis + + FreeBSD uses X11 to provide users with + a powerful graphical user interface. X11 + is an open-source implementation of the X Window System that + includes both &xorg; and + &xfree86;. &os; versions up to and + including &os; 5.2.1-RELEASE + will find the default installation to be + &xfree86;, the X11 server released by + The &xfree86; Project, Inc. As of &os; 5.3-RELEASE, the + default and official flavor of X11 was changed to + &xorg;, the X11 server developed by + the X.Org Foundation. + + This chapter will cover the installation and configuration + of X11 with emphasis on + &xorg;. + + For more information on the video hardware that X11 + supports, check either the &xorg; or &xfree86; web + sites. + + After reading this chapter, you will know: + + + + The various components of the X Window System, and how they + interoperate. + + + + How to install and configure X11. + + + + How to install and use different window managers. + + + + How to use &truetype; fonts in X11. + + + + How to set up your system for graphical logins + (XDM). + + + + Before reading this chapter, you should: + + + Know how to install additional third-party + software (). + + + + This chapter covers the installation and the configuration + of both &xorg; and + &xfree86; X11 servers. For the most + part, configuration files, commands and syntaxes are identical. + In the case where there are differences, both + &xorg; and + &xfree86; syntaxes will be + shown. + + + + + Understanding X + + Using X for the first time can be somewhat of a shock to someone + familiar with other graphical environments, such as µsoft.windows; or + &macos;. + + While it is not necessary to understand all of the details of various + X components and how they interact, some basic knowledge makes + it possible to take advantage of X's strengths. + + + Why X? + + X is not the first window system written for &unix;, but it is the + most popular of them. X's original development team had worked on another + window system prior to writing X. That system's name was + W (for Window). X was just the next + letter in the Roman alphabet. + + X can be called X, X Window System, + X11, and a number of other terms. You may find + that using the term X Windows to describe X11 + can be offensive to some people; for a bit more insight on + this, see &man.X.7;. + + + + The X Client/Server Model + + X was designed from the beginning to be network-centric, and + adopts a client-server model. + + In the X model, the + X server runs on the computer that has the keyboard, + monitor, and mouse attached. The server's responsibility includes tasks such as managing + the display, handling input from the keyboard and mouse, and so on. + Each X application (such as XTerm, or + &netscape;) is a client. A + client sends messages to the server such as Please draw a + window at these coordinates, and the server sends back + messages such as The user just clicked on the OK + button. + + In a home or small + office environment, the X server and the X clients commonly run on + the same computer. However, it is perfectly possible to run the X + server on a less powerful desktop computer, and run X applications + (the clients) on, say, the powerful and expensive machine that serves + the office. In this scenario the communication between the X client + and server takes place over the network. + + This confuses some people, because the X terminology is + exactly backward to what they expect. They expect the X + server to be the big powerful machine down the hall, and + the X client to be the machine on their desk. + + It is important to remember that the X server is the machine with the monitor and + keyboard, and the X clients are the programs that display the + windows. + + There is nothing in the protocol that forces the client and + server machines to be running the same operating system, or even to + be running on the same type of computer. It is certainly possible to + run an X server on µsoft.windows; or Apple's &macos;, and there are + various free and commercial applications available that do exactly + that. + + Starting with &os; 5.3-RELEASE, the X server that + installs with &os; is &xorg;, + and is available for free, under a + license very similar to the FreeBSD license. Commercial X servers for + FreeBSD are also available. + + + + The Window Manager + + The X design philosophy is much like the &unix; design philosophy, + tools, not policy. This means that X does not try to + dictate how a task is to be accomplished. Instead, tools are provided + to the user, and it is the user's responsibility to decide how to use + those tools. + + This philosophy extends to X not dictating what windows should + look like on screen, how to move them around with the mouse, what + keystrokes should be used to move between windows (i.e., + + Alt + Tab + , in the case of µsoft.windows;), what the title bars + on each window should look like, whether or not they have close + buttons on them, and so on. + + Instead, X delegates this responsibility to an application called + a Window Manager. There are dozens of window + managers available for X: AfterStep, + Blackbox, ctwm, + Enlightenment, + fvwm, Sawfish, + twm, + Window Maker, and more. Each of these + window managers provides a different look and feel; some of them + support virtual desktops; some of them allow customized + keystrokes to manage the desktop; some have a Start + button or similar device; some are themeable, allowing + a complete change of look-and-feel by applying a new theme. These + window managers, and many more, are available in the + x11-wm category of the Ports Collection. + + In addition, the KDE and + GNOME desktop environments both have their + own window managers which integrate with the desktop. + + Each window manager also has a different configuration mechanism; + some expect configuration file written by hand, others feature + GUI tools for most of the configuration tasks; at least one + (Sawfish) has a configuration file written + in a dialect of the Lisp language. + + + Focus Policy + + Another feature the window manager is responsible for is the + mouse focus policy. Every windowing system + needs some means of choosing a window to be actively receiving + keystrokes, and should visibly indicate which window is active as + well. + + A familiar focus policy is called click-to-focus. + This is the model utilized by µsoft.windows;, in which a window + becomes active upon receiving a mouse click. + + X does not support any particular focus policy. Instead, the + window manager controls which window has the focus at any one time. + Different window managers will support different focus methods. All + of them support click to focus, and the majority of them support + several others. + + The most popular focus policies are: + + + + focus-follows-mouse + + + The window that is under the mouse pointer is the + window that has the focus. This may not necessarily be + the window that is on top of all the other windows. + The focus is changed by pointing at another window, there + is no need to click in it as well. + + + + + sloppy-focus + + + This policy is a small extension to focus-follows-mouse. + With focus-follows-mouse, if the mouse is moved over the + root window (or background) then no window has the focus, + and keystrokes are simply lost. With sloppy-focus, focus is + only changed when the cursor enters a new window, and not + when exiting the current window. + + + + + click-to-focus + + + The active window is selected by mouse click. The + window may then be raised, and appear in + front of all other windows. All keystrokes will now be + directed to this window, even if the cursor is moved to + another window. + + + + + Many window managers support other policies, as well as + variations on these. Be sure to consult the documentation for + the window manager itself. + + + + + Widgets + + The X approach of providing tools and not policy extends to the + widgets seen on screen in each application. + + Widget is a term for all the items in the user + interface that can be clicked or manipulated in some way; buttons, + check boxes, radio buttons, icons, lists, and so on. µsoft.windows; + calls these controls. + + µsoft.windows; and Apple's &macos; both have a very rigid widget + policy. Application developers are supposed to ensure that their + applications share a common look and feel. With X, it was not + considered sensible to mandate a particular graphical style, or set + of widgets to adhere to. + + As a result, do not expect X applications to have a common + look and feel. There are several popular widget sets and + variations, including the original Athena widget set from MIT, + &motif; (on which the widget set in + µsoft.windows; was modeled, all bevelled edges and three shades of + grey), OpenLook, and others. + + Most newer X applications today will use a modern-looking widget + set, either Qt, used by KDE, or + GTK+, used by the + GNOME + project. In this respect, there is some convergence in + look-and-feel of the &unix; desktop, which certainly makes things + easier for the novice user. + + + + + Installing X11 + + &xorg; or + &xfree86; may be installed on &os;. + Beginning with &os; 5.3-RELEASE, + &xorg; is the default X11 + implementation for &os;. &xorg; is + the X server of the open source X Window System implementation released by the X.Org + Foundation. &xorg; is based on the code of + &xfree86 4.4RC2 and X11R6.6. + The X.Org Foundation released X11R6.7 in April 2004 and + X11R6.8.2 in February 2005, this latter is the version + currently available in the &os; Ports Collection. + + To build and install &xorg; from the + Ports Collection: + + &prompt.root; cd /usr/ports/x11/xorg +&prompt.root; make install clean + + + To build &xorg; in its + entirety, be sure to have at least 4 GB of free space + available. + + + To build and install &xfree86; + from the Ports Collection: + + &prompt.root; cd /usr/ports/x11/XFree86-4 +&prompt.root; make install clean + + Alternatively, X11 + can be installed directly from packages. + Binary packages to use with &man.pkg.add.1; tool are also available for + X11. When the remote fetching + feature of &man.pkg.add.1; is used, the version number of the + package must be removed. &man.pkg.add.1; will automatically fetch + the latest version of the application. + + So to fetch and install the package of + &xorg;, simply type: + + &prompt.root; pkg_add -r xorg + + The &xfree86; 4.X package can be + installed by typing: + + &prompt.root; pkg_add -r XFree86 + + The examples above will install the complete + X11 distribution including the + servers, clients, fonts etc. Separate packages and ports of X11 + are also + available. + + The rest of this chapter will explain how to configure + X11, and how to set up a productive desktop + environment. + + + Moving from <application>&xfree86;</application> to + <application>&xorg;</application> + + As with any port, you should check the + /usr/ports/UPDATING file for changes. + Included in this file are instructions for converting your + system from &xfree86; to + &xorg;. + + Use CVSup to update your ports + tree prior to attempting any conversion. You will also need + to install sysutils/portupgrade prior to + converting your X11 installation. + + In your /etc/make.conf you will need + to add the variable X_WINDOW_SYSTEM=xorg. + This ensures that your system knows which X11 is being used. + The older XFREE86_VERSION variable has been + deprecated and has been replaced with the + X_WINDOW_SYSTEM variable. + + Then, use the following commands: + + &prompt.root; pkg_delete -f /var/db/pkg/imake-4* /var/db/pkg/XFree86-* +&prompt.root; cd /usr/ports/x11/xorg +&prompt.root; make install clean +&prompt.root; pkgdb -F + + The &man.pkgdb.1; command is part of the + portupgrade software and will + update various package dependencies. + + + To build &xorg; in its + entirety, be sure to have at least 4 GB of free space + available. + + + + + + + + + Christopher + Shumway + Contributed by + + + + + X11 Configuration + + + &xfree86; 4.X + &xfree86; + &xorg; + X11 + + + Before Starting + + Before configuration of X11 + the following information about the target system is needed: + + + Monitor specifications + Video Adapter chipset + Video Adapter memory + + + horizontal scan rate + vertical scan rate + + The specifications for the monitor are used by + X11 to determine the resolution and + refresh rate to run at. These specifications can usually be + obtained from the documentation that came with the monitor or from + the manufacturer's website. There are two ranges of numbers that + are needed, the horizontal scan rate and the vertical synchronization + rate. + + The video adapter's chipset defines what driver module + X11 uses to talk to the graphics + hardware. With most chipsets, this can be automatically + determined, but it is still useful to know in case the automatic + detection does not work correctly. + + Video memory on the graphic adapter determines the + resolution and color depth which the system can run at. This is + important to know so the user knows the limitations of the + system. + + + + + Configuring X11 + + Configuration of X11 is + a multi-step process. The first step is to build an initial + configuration file. + As the super user, simply + run: + + &prompt.root; Xorg -configure + + In the case of &xfree86; + type: + + &prompt.root; XFree86 -configure + + This will generate an + X11 configuration skeleton file in the + /root directory called + xorg.conf.new (whether you &man.su.1; or + do a direct login affects the inherited supervisor + $HOME directory variable). + For &xfree86;, this configuration + file is called XF86Config.new. The + X11 program will attempt to probe + the graphics hardware on the system and write a + configuration file to load the proper drivers for the detected + hardware on the target system. + + The next step is to test the existing + configuration to verify that &xorg; + can work with the graphics + hardware on the target system. To perform this task, + type: + + &prompt.root; Xorg -config xorg.conf.new + + &xfree86; users will type: + + &prompt.root; XFree86 -xf86config XF86Config.new + + If a black and grey grid and an X mouse cursor appear, + the configuration was successful. To exit the test, just press + + Ctrl + Alt + Backspace + simultaneously. + + If the mouse does not work, you will need to first + configure it before proceeding. See + in the &os; install chapter. + + X11 tuning + + Next, tune the xorg.conf.new (or XF86Config.new if you are running &xfree86;) + configuration file to taste. Open the file in a text editor such + as &man.emacs.1; or &man.ee.1;. First, add the + frequencies for the target system's monitor. These are usually + expressed as a horizontal and vertical synchronization rate. These + values are added to the xorg.conf.new file + under the "Monitor" section: + + Section "Monitor" + Identifier "Monitor0" + VendorName "Monitor Vendor" + ModelName "Monitor Model" + HorizSync 30-107 + VertRefresh 48-120 +EndSection + + The HorizSync and + VertRefresh keywords may be missing in the + configuration file. If they are, they need to be added, with + the correct horizontal synchronization rate placed after the + HorizSync keyword and the vertical + synchronization rate after the VertRefresh + keyword. In the example above the target monitor's rates were + entered. + + X allows DPMS (Energy Star) features to be used with capable + monitors. The &man.xset.1; program controls the time-outs and can force + standby, suspend, or off modes. If you wish to enable DPMS features + for your monitor, you must add the following line to the monitor + section: + + + Option "DPMS" + + + xorg.conf + + + XF86Config + + + While the xorg.conf.new (or XF86Config.new) + configuration file is still open in an editor, select + the default resolution and color depth desired. This is + defined in the "Screen" section: + + Section "Screen" + Identifier "Screen0" + Device "Card0" + Monitor "Monitor0" + DefaultDepth 24 + SubSection "Display" + Viewport 0 0 + Depth 24 + Modes "1024x768" + EndSubSection +EndSection + + The DefaultDepth keyword describes + the color depth to run at by default. This can be overridden + with the command line switch to + &man.Xorg.1; (or &man.XFree86.1;). + The Modes keyword + describes the resolution to run at for the given color depth. + Note that only VESA standard modes are supported as defined by + the target system's graphics hardware. + In the example above, the default color depth is twenty-four + bits per pixel. At this color depth, the accepted resolution is + 1024 by 768 + pixels. + + Finally, write the configuration file and test it using + the test mode given above. + + + One of the tools available to assist you during + troubleshooting process are the X11 log files, which contain + information on each device that the X11 server attaches to. + &xorg; log file names are in the format + of /var/log/Xorg.0.log + (&xfree86; log file names follow the + format of XFree86.0.log). The exact name + of the log can vary from Xorg.0.log to + Xorg.8.log and so forth. + + + If all is well, the configuration + file needs to be installed in a common location where + &man.Xorg.1; (or &man.XFree86.1;) + can find it. + This is typically /etc/X11/xorg.conf or + /usr/X11R6/etc/X11/xorg.conf (for + &xfree86; it is called + /etc/X11/XF86Config or + /usr/X11R6/etc/X11/XF86Config). + + &prompt.root; cp xorg.conf.new /etc/X11/xorg.conf + + For &xfree86;: + + &prompt.root; cp XF86Config.new /etc/X11/XF86Config + + The X11 configuration process is now + complete. In order to start + &xfree86; 4.X with &man.startx.1;, + install the x11/wrapper port. + &xorg; already includes the wrapper + code and does not require the installation of the wrapper port. + The X11 server may also be started with the use of + &man.xdm.1;. + + There is also a graphical configuration tool, + &man.xorgcfg.1; (&man.xf86cfg.1; for &xfree86;), that comes with the + X11 distribution. It + allows you to interactively define your configuration by choosing + the appropriate drivers and settings. This program can be invoked from the console, by typing the command xorgcfg -textmode. For more details, + refer to the &man.xorgcfg.1; and &man.xf86cfg.1; manual pages. + + Alternatively, there is also a tool called &man.xorgconfig.1; + (&man.xf86config.1; for &xfree86;), + this program is a console utility that is less user friendly, + but it may work in situations where the other tools do + not. + + + + + Advanced Configuration Topics + + + Configuration with &intel; i810 Graphics Chipsets + + Intel i810 graphic chipset + + Configuration with &intel; i810 integrated chipsets + requires the agpgart + AGP programming interface for X11 + to drive the card. See the &man.agp.4; driver manual page + for more information. + + This will allow configuration of the hardware as any other + graphics board. Note on systems without the &man.agp.4; + driver compiled in the kernel, trying to load the module + with &man.kldload.8; will not work. This driver has to be + in the kernel at boot time through being compiled in or + using /boot/loader.conf. + + If you are using &xfree86; 4.1.0 (or + later) and messages about unresolved symbols like + fbPictureInit appear, try adding the + following line after Driver "i810" in the + X11 configuration file: + Option "NoDDC" + + + + + + + + + Murray + Stokely + Contributed by + + + + Using Fonts in X11 + + + Type1 Fonts + The default fonts that ship with + X11 are less than ideal for typical + desktop publishing applications. Large presentation fonts show up + jagged and unprofessional looking, and small fonts in + &netscape; are almost completely unintelligible. + However, there are several free, high quality Type1 (&postscript;) fonts + available which can be readily used + with X11. For instance, the URW font collection + (x11-fonts/urwfonts) includes + high quality versions of standard type1 fonts (Times Roman, + Helvetica, Palatino and others). The Freefonts collection + (x11-fonts/freefonts) includes + many more fonts, but most of them are intended for use in + graphics software such as the Gimp, and are not + complete enough to serve as screen fonts. In addition, + X11 can be configured to use + &truetype; fonts with a minimum of effort. For more details on + this, see the &man.X.7; manual page or the + section on &truetype; fonts. + + To install the above Type1 font collections from the ports + collection, run the following commands: + + &prompt.root; cd /usr/ports/x11-fonts/urwfonts +&prompt.root; make install clean + + And likewise with the freefont or other collections. To have the X + server detect these fonts, add an appropriate line to the + X server configuration file in /etc/X11/ + (xorg.conf for + &xorg; and + XF86Config for + &xfree86;), which reads: + + FontPath "/usr/X11R6/lib/X11/fonts/URW/" + + Alternatively, at the command line in the X session + run: + + &prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/URW +&prompt.user; xset fp rehash + + This will work but will be lost when the X session is closed, + unless it is added to the startup file (~/.xinitrc + for a normal startx session, + or ~/.xsession when logging in through a + graphical login manager like XDM). + A third way is to use the new + /usr/X11R6/etc/fonts/local.conf file: see the + section on anti-aliasing. + + + + + &truetype; Fonts + + TrueType Fonts + fonts + TrueType + + + Both &xfree86; 4.X and &xorg; have built in support + for rendering &truetype; fonts. There are two different modules + that can enable this functionality. The freetype module is used + in this example because it is more consistent with the other font + rendering back-ends. To enable the freetype module just add the + following line to the "Module" section of the + /etc/X11/xorg.conf or + /etc/X11/XF86Config file. + + Load "freetype" + + For &xfree86; 3.3.X, a separate + &truetype; font server is needed. + Xfstt is commonly used for + this purpose. To install Xfstt, + simply install the port + x11-servers/Xfstt. + + Now make a directory for the &truetype; fonts (for example, + /usr/X11R6/lib/X11/fonts/TrueType) + and copy all of the &truetype; fonts into this directory. Keep in + mind that &truetype; fonts cannot be directly taken from a + &macintosh;; they must be in &unix;/&ms-dos;/&windows; format for use by + X11. Once the files have been + copied into this directory, use + ttmkfdir to create a + fonts.dir file, so that the X font renderer + knows that these new files have been installed. + ttmkfdir is available from the FreeBSD + Ports Collection as + x11-fonts/ttmkfdir. + + &prompt.root; cd /usr/X11R6/lib/X11/fonts/TrueType +&prompt.root; ttmkfdir > fonts.dir + + Now add the &truetype; directory to the font + path. This is just the same as described above for Type1 fonts, that is, use + + &prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/TrueType +&prompt.user; xset fp rehash + + or add a FontPath line to the + xorg.conf (or XF86Config) file. + + That's it. Now &netscape;, + Gimp, + &staroffice;, and all of the other X + applications should now recognize the installed &truetype; + fonts. Extremely small fonts (as with text in a high resolution + display on a web page) and extremely large fonts (within + &staroffice;) will look much better + now. + + + + + + + Joe Marcus + Clarke + Updated by + + + + + Anti-Aliased Fonts + + anti-aliased fonts + fonts + anti-aliased + + Anti-aliasing has been available in X11 since + &xfree86; 4.0.2. However, font + configuration was cumbersome before the introduction of + &xfree86; 4.3.0. + Beginning with + &xfree86; 4.3.0, all fonts in X11 + that are found + in /usr/X11R6/lib/X11/fonts/ and + ~/.fonts/ are automatically + made available for anti-aliasing to Xft-aware applications. Not + all applications are Xft-aware, but many have received Xft support. + Examples of Xft-aware applications include Qt 2.3 and higher (the + toolkit for the KDE desktop), + GTK+ 2.0 and higher (the toolkit for the + GNOME desktop), and + Mozilla 1.2 and higher. + + + In order to control which fonts are anti-aliased, or to + configure anti-aliasing properties, create (or edit, if it + already exists) the file + /usr/X11R6/etc/fonts/local.conf. Several + advanced features of the Xft font system can be tuned using + this file; this section describes only some simple + possibilities. For more details, please see + &man.fonts-conf.5;. + + XML + + This file must be in XML format. Pay careful attention to + case, and make sure all tags are properly closed. The file + begins with the usual XML header followed by a DOCTYPE + definition, and then the <fontconfig> tag: + + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig> + + + As previously stated, all fonts in + /usr/X11R6/lib/X11/fonts/ as well as + ~/.fonts/ are already made available to + Xft-aware applications. If you wish to add another directory + outside of these two directory trees, add a line similar to the + following to + /usr/X11R6/etc/fonts/local.conf: + + <dir>/path/to/my/fonts</dir> + + After adding new fonts, and especially new font directories, + you should run the following command to rebuild the font + caches: + + &prompt.root; fc-cache -f + + Anti-aliasing makes borders slightly fuzzy, which makes very + small text more readable and removes staircases from + large text, but can cause eyestrain if applied to normal text. To + exclude font sizes smaller than 14 point from anti-aliasing, include + these lines: + + <match target="font"> + <test name="size" compare="less"> + <double>14</double> + </test> + <edit name="antialias" mode="assign"> + <bool>false</bool> + </edit> + </match> + <match target="font"> + <test name="pixelsize" compare="less" qual="any"> + <double>14</double> + </test> + <edit mode="assign" name="antialias"> + <bool>false</bool> + </edit> + </match> + + fonts + spacing + + Spacing for some monospaced fonts may also be inappropriate + with anti-aliasing. This seems to be an issue with + KDE, in particular. One possible fix for + this is to force the spacing for such fonts to be 100. Add the + following lines: + + <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>fixed</string> + </test> + <edit name="family" mode="assign"> + <string>mono</string> + </edit> + </match> + <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>console</string> + </test> + <edit name="family" mode="assign"> + <string>mono</string> + </edit> + </match> + + (this aliases the other common names for fixed fonts as + "mono"), and then add: + + <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="spacing" mode="assign"> + <int>100</int> + </edit> + </match> + + Certain fonts, such as Helvetica, may have a problem when + anti-aliased. Usually this manifests itself as a font that + seems cut in half vertically. At worst, it may cause + applications such as Mozilla to + crash. To avoid this, consider adding the following to + local.conf: + + <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>Helvetica</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + Once you have finished editing + local.conf make sure you end the file + with the </fontconfig> tag. Not doing this will cause + your changes to be ignored. + + The default font set that comes with + X11 is not very + desirable when it comes to anti-aliasing. A much better + set of default fonts can be found in the + x11-fonts/bitstream-vera + port. This port will install a + /usr/X11R6/etc/fonts/local.conf file + if one does not exist already. If the file does exist, + the port will create a /usr/X11R6/etc/fonts/local.conf-vera + file. Merge the contents of this file into + /usr/X11R6/etc/fonts/local.conf, and the + Bitstream fonts will automatically replace the default + X11 Serif, Sans Serif, and Monospaced + fonts. + + Finally, users can add their own settings via their personal + .fonts.conf files. To do this, each user should + simply create a ~/.fonts.conf. This file must + also be in XML format. + + LCD screen + Fonts + LCD screen + + One last point: with an LCD screen, sub-pixel sampling may be + desired. This basically treats the (horizontally separated) + red, green and blue components separately to improve the horizontal + resolution; the results can be dramatic. To enable this, add the + line somewhere in the local.conf file: + + + <match target="font"> + <test qual="all" name="rgba"> + <const>unknown</const> + </test> + <edit name="rgba" mode="assign"> + <const>rgb</const> + </edit> + </match> + + + Depending on the sort of display, + rgb may need to be changed to bgr, + vrgb or vbgr: experiment and + see which works best. + + + Mozilla + disabling anti-aliased fonts + + + Anti-aliasing should be enabled the next time the X + server is started. However, programs must know how to take + advantage of it. At present, the Qt toolkit does, + so the entire KDE environment can + use anti-aliased fonts. + GTK+ and + GNOME can also be made to use + anti-aliasing via the Font capplet (see for details). By default, + Mozilla 1.2 and greater will + automatically use anti-aliasing. To disable this, rebuild + Mozilla with the + -DWITHOUT_XFT flag. + + + + + + + + Seth + Kingsley + Contributed by + + + + The X Display Manager + + Overview + + X Display Manager + The X Display Manager (XDM) is + an optional part of the X Window System that is used for login + session management. This is useful for several types of + situations, including minimal X Terminals, + desktops, and large network display + servers. Since the X Window System is network and protocol + independent, there are a wide variety of possible configurations + for running X clients and servers on different machines + connected by a network. XDM provides + a graphical interface for choosing which display server to + connect to, and entering authorization information such as a + login and password combination. + + Think of XDM as + providing the same functionality to the user as the + &man.getty.8; utility (see for + details). That is, it performs system logins to the display + being connected to and then runs a session manager on behalf of + the user (usually an X window + manager). XDM then waits for this + program to exit, signaling that the user is done and should be + logged out of the display. At this point, + XDM can display the login and display + chooser screens for the next user to login. + + + + Using XDM + + The XDM daemon program is + located in /usr/X11R6/bin/xdm. This program + can be run at any time as root and it will + start managing the X display on the local machine. If + XDM is to be run every + time the machine boots up, a convenient way to do this is by + adding an entry to /etc/ttys. For more + information about the format and usage of this file, see . There is a line in the default + /etc/ttys file for running the + XDM daemon on a virtual terminal: + + ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure + + By default this entry is disabled; in order to enable it + change field 5 from off to + on and restart &man.init.8; using the + directions in . The first field, the + name of the terminal this program will manage, is + ttyv8. This means that + XDM will start running on the 9th + virtual terminal. + + + + Configuring XDM + + The XDM configuration directory + is located in /usr/X11R6/lib/X11/xdm. In + this directory there are several files used to change the + behavior and appearance of + XDM. Typically these files will + be found: + + + + + + File + Description + + + + + + Xaccess + Client authorization ruleset. + + + + Xresources + Default X resource values. + + + + Xservers + List of remote and local displays to manage. + + + + Xsession + Default session script for logins. + + + + Xsetup_* + Script to launch applications before the login + interface. + + + + xdm-config + Global configuration for all displays running on + this machine. + + + + xdm-errors + Errors generated by the server program. + + + + xdm-pid + The process ID of the currently running XDM. + + + + + + Also in this directory are a few scripts and programs used + to set up the desktop when XDM is + running. The purpose of each of these files will be briefly + described. The exact syntax and usage of all of these files is + described in &man.xdm.1;. + + The default configuration is a simple rectangular login + window with the hostname of the machine displayed at the top in + a large font and Login: and + Password: prompts below. This is a good starting + point for changing the look and feel of + XDM screens. + + + Xaccess + + The protocol for connecting to + XDM controlled displays is called + the X Display Manager Connection Protocol (XDMCP). This file + is a ruleset for controlling XDMCP connections from remote + machines. It is ignored unless the xdm-config + is changed to listen for remote connections. By default, it does + not allow any clients to connect. + + + + Xresources + This is an application-defaults file for the display + chooser and the login screens. This is where the appearance + of the login program can be modified. The format is identical + to the app-defaults file described in the + X11 documentation. + + + + Xservers + This is a list of the remote displays the chooser should + provide as choices. + + + + Xsession + This is the default session script for + XDM to run after a user has logged + in. Normally each user will have a customized session script + in ~/.xsession that overrides this + script. + + + + Xsetup_* + These will be run automatically before displaying the + chooser or login interfaces. There is a script for each + display being used, named Xsetup_ followed + by the local display number (for instance + Xsetup_0). Typically these scripts will + run one or two programs in the background such as + xconsole. + + + + xdm-config + This contains settings in the form of app-defaults + that are applicable to every display that this installation + manages. + + + + xdm-errors + This contains the output of the X servers that + XDM is trying to run. If a display + that XDM is trying to start hangs + for some reason, this is a good place to look for error + messages. These messages are also written to the user's + ~/.xsession-errors file on a per-session + basis. + + + + + Running a Network Display Server + + In order for other clients to connect to the display + server, edit the access control rules, and enable the connection + listener. By default these are set to conservative values. + To make XDM listen for connections, + first comment out a line in the xdm-config + file: + + ! SECURITY: do not listen for XDMCP or Chooser requests +! Comment out this line if you want to manage X terminals with xdm +DisplayManager.requestPort: 0 + + and then restart XDM. Remember that + comments in app-defaults files begin with a ! + character, not the usual #. More strict + access controls may be desired. Look at the example + entries in Xaccess, and refer to the + &man.xdm.1; manual page. + + + + Replacements for XDM + + Several replacements for the default + XDM program exist. One of them, + kdm (bundled with + KDE) is described later in this + chapter. The kdm display manager offers many visual + improvements and cosmetic frills, as well as the + functionality to allow users to choose their window manager + of choice at login time. + + + + + + + + Valentino + Vaschetto + Contributed by + + + + + + Desktop Environments + + This section describes the different desktop environments + available for X on FreeBSD. A desktop environment + can mean anything ranging from a simple window manager to a + complete suite of desktop applications, such as + KDE or GNOME. + + + + GNOME + + + About GNOME + + GNOME + GNOME is a user-friendly + desktop environment that enables users to easily use and + configure their computers. GNOME + includes a panel (for starting applications and displaying + status), a desktop (where data and applications can be + placed), a set of standard desktop tools and applications, and + a set of conventions that make it easy for applications to + cooperate and be consistent with each other. Users of other + operating systems or environments should feel right at home + using the powerful graphics-driven environment that + GNOME provides. More + information regarding GNOME on + FreeBSD can be found on the FreeBSD GNOME + Project's web site. The web site also contains fairly + comprehensive FAQs about installing, configuring, and managing + GNOME. + + + + Installing GNOME + + The easiest way to install + GNOME is through the + Desktop Configuration menu during the FreeBSD + installation process as described in of Chapter 2. It can also + be easily installed from a package or the ports + collection: + + To install the GNOME package + from the network, simply type: + + &prompt.root; pkg_add -r gnome2 + + To build GNOME from source, use + the ports tree: + + &prompt.root; cd /usr/ports/x11/gnome2 +&prompt.root; make install clean + + Once GNOME is installed, + the X server must be told to start + GNOME instead of a default window + manager. + + The easiest way to start + GNOME is with + GDM, the GNOME Display Manager. + GDM, which is installed as a part + of the GNOME desktop (but is + disabled by default), can be enabled by adding + gdm_enable="YES" to + /etc/rc.conf. Once you have rebooted, + GNOME will start automatically + once you log in — no further configuration is + necessary. + + GNOME may also be started + from the command-line by properly configuring a file named + .xinitrc. + If a custom .xinitrc is already in + place, simply replace the line that starts the current window + manager with one that starts + /usr/X11R6/bin/gnome-session instead. + If nothing special has been done to the configuration file, + then it is enough simply to type: + + &prompt.user; echo "/usr/X11R6/bin/gnome-session" > ~/.xinitrc + + Next, type startx, and the + GNOME desktop environment will be + started. + + If an older display manager, like + XDM, is being used, this will not work. + Instead, create an executable .xsession + file with the same command in it. To do this, edit the file + and replace the existing window manager command with + /usr/X11R6/bin/gnome-session: + + + &prompt.user; echo "#!/bin/sh" > ~/.xsession +&prompt.user; echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession +&prompt.user; chmod +x ~/.xsession + + Yet another option is to configure the display manager to + allow choosing the window manager at login time; the section on + KDE details + explains how to do this for kdm, the + display manager of KDE. + + + + Anti-aliased Fonts with GNOME + + GNOME + anti-aliased fonts + X11 + supports anti-aliasing via its RENDER extension. + GTK+ 2.0 and greater (the toolkit used by + GNOME) can make use of this + functionality. Configuring anti-aliasing is described in + . So, with up-to-date software, + anti-aliasing is possible within the + GNOME desktop. Just go to + + Applications + Desktop Preferences + Font, and select either + Best shapes, + Best contrast, or + Subpixel smoothing (LCDs). For a + GTK+ application that is not part of the + GNOME desktop, set the + environment variable GDK_USE_XFT to + 1 before launching the program. + + + + + KDE + + KDE + + About KDE + + KDE is an easy to use + contemporary desktop environment. Some of the things that + KDE brings to the user are: + + + + A beautiful contemporary desktop + + + + A desktop exhibiting complete network transparency + + + + An integrated help system allowing for convenient, + consistent access to help on the use of the + KDE desktop and its + applications + + + + Consistent look and feel of all + KDE applications + + + + Standardized menu and toolbars, keybindings, color-schemes, + etc. + + + + Internationalization: KDE + is available in more than 40 languages + + + + Centralized consisted dialog driven desktop + configuration + + + + A great number of useful + KDE applications + + + + KDE comes with a web browser called + Konqueror, which represents + a solid competitor to other existing web browsers on &unix; + systems. More information on KDE + can be found on the KDE + website. For FreeBSD specific information and + resources on KDE, consult + the FreeBSD-KDE + team's website. + + + + Installing KDE + + Just as with GNOME or any + other desktop environment, the easiest way to install + KDE is through the Desktop + Configuration menu during the FreeBSD installation + process as described in of Chapter + 2. Once again, the software can be easily installed from a package + or from the Ports Collection: + + To install the KDE package + from the network, simply type: + + &prompt.root; pkg_add -r kde + + &man.pkg.add.1; will automatically fetch the latest version + of the application. + + To build KDE from source, + use the ports tree: + + &prompt.root; cd /usr/ports/x11/kde3 +&prompt.root; make install clean + + After KDE has been installed, + the X server must be told to launch this application + instead of the default window manager. This is accomplished + by editing the .xinitrc file: + + &prompt.user; echo "exec startkde" > ~/.xinitrc + + Now, whenever the X Window System is invoked with + startx, + KDE will be the desktop. + + If a display manager such as + XDM is being used, the + configuration is slightly different. Edit the + .xsession file instead. Instructions + for kdm are described later in + this chapter. + + + + + More Details on KDE + + Now that KDE is installed on + the system, most things can be discovered through the + help pages, or just by pointing and clicking at various menus. + &windows; or &mac; users will feel quite at home. + + The best reference for KDE is + the on-line documentation. KDE + comes with its own web browser, + Konqueror, dozens of useful + applications, and extensive documentation. The remainder of + this section discusses the technical items that are + difficult to learn by random exploration. + + + The KDE Display Manager + + KDE + display manager + An administrator of a multi-user system may wish to have + a graphical login screen to welcome users. + XDM can be + used, as described earlier. However, + KDE includes an + alternative, kdm, which is designed + to look more attractive and include more login-time options. + In particular, users can easily choose (via a menu) which + desktop environment (KDE, + GNOME, or something else) to run + after logging on. + + To enable kdm, the + ttyv8 entry in /etc/ttys + has to be adapted. The line should look as follows: + + ttyv8 "/usr/local/bin/kdm -nodaemon" xterm on secure + + + + + + XFce + + About XFce + + XFce is a desktop environment + based on the GTK+ + toolkit used by GNOME, but is much + more lightweight and meant for those who want a simple, + efficient desktop which is nevertheless easy to use and + configure. Visually, it looks very much like + CDE, found on commercial &unix; + systems. Some of XFce's features + are: + + + + A simple, easy-to-handle desktop + + + + Fully configurable via mouse, with drag and + drop, etc + + + + Main panel similar to CDE, with + menus, applets and applications launchers + + + + Integrated window manager, file manager, sound manager, + GNOME compliance module, and other + things + + + + Themeable (since it uses GTK+) + + + + Fast, light and efficient: ideal for older/slower machines + or machines with memory limitations + + + + More information on XFce + can be found on the XFce + website. + + + + Installing XFce + + A binary package for XFce + exists (at the time of writing). To install, simply type: + + &prompt.root; pkg_add -r xfce4 + + Alternatively, to build from source, use the ports + collection: + + &prompt.root; cd /usr/ports/x11-wm/xfce4 +&prompt.root; make install clean + + Now, tell the X server to launch + XFce the next time X is started. + Simply type this: + + &prompt.user; echo "/usr/X11R6/bin/startxfce4" > ~/.xinitrc + + The next time X is started, + XFce will be the desktop. + As before, if a display manager like + XDM is being used, create an + .xsession, as described in the + section on GNOME, but + with the /usr/X11R6/bin/startxfce4 + command; or, configure the display manager to allow + choosing a desktop at login time, as explained in + the section on kdm. + + + + + + +