diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index b01f4b1b35..baeeb71f44 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,3859 +1,3859 @@
Advanced NetworkingSynopsisThe following chapter will cover some of the more frequently
used network services on UNIX systems. This, of course, will
pertain to configuring said services on your FreeBSD system.Gateways and RoutesContributed by &a.gryphon;. 6 October
1995.routeroutinggatewaysubnetFor one machine to be able to find another, there must be a
mechanism in place to describe how to get from one to the other. This is
called Routing. A route is a defined pair of addresses: a
destination and a gateway. The pair
indicates that if you are trying to get to this
destination, send along through this
gateway. There are three types of destinations:
individual hosts, subnets, and default. The
default route is used if none of the other routes apply.
We will talk a little bit more about default routes later on. There are
also three types of gateways: individual hosts, interfaces (also called
links), and ethernet hardware addresses.An exampleTo illustrate different aspects of routing, we will use the
following example which is the output of the command netstat
-r:Destination Gateway Flags Refs Use Netif Expire
default outside-gw UGSc 37 418 ppp0
localhost localhost UH 0 181 lo0
test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
10.20.30.255 link#1 UHLW 1 2421
foobar.com link#1 UC 0 0
host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
host2.foobar.com link#1 UC 0 0
224 link#1 UC 0 0default routeThe first two lines specify the default route (which we will cover
in the next section) and the localhost route.loopback deviceThe interface (Netif column) that it specifies
to use for localhost is
lo0, also known as the loopback device. This
says to keep all traffic for this destination internal, rather than
sending it out over the LAN, since it will only end up back where it
started anyway.EthernetMAC addressThe next thing that stands out are the 0:e0:... addresses. These are ethernet hardware
addresses. FreeBSD will automatically identify any hosts
(test0 in the example) on the local ethernet and add
a route for that host, directly to it over the ethernet interface,
ed0. There is also a timeout
(Expire column) associated with this type of route,
which is used if we fail to hear from the host in a specific amount of
time. In this case the route will be automatically deleted. These
hosts are identified using a mechanism known as RIP (Routing
Information Protocol), which figures out routes to local hosts based
upon a shortest path determination.subnetFreeBSD will also add subnet routes for the local subnet (10.20.30.255 is the broadcast address for the
subnet 10.20.30, and foobar.com is the domain name associated
with that subnet). The designation link#1 refers
to the first ethernet card in the machine. You will notice no
additional interface is specified for those.Both of these groups (local network hosts and local subnets) have
their routes automatically configured by a daemon called
routed. If this is not run, then only routes which
are statically defined (ie. entered explicitly) will exist.The host1 line refers to our host, which it
knows by ethernet address. Since we are the sending host, FreeBSD
knows to use the loopback interface (lo0)
rather than sending it out over the ethernet interface.The two host2 lines are an example of what
happens when we use an ifconfig alias (see the section of ethernet for
reasons why we would do this). The => symbol
after the lo0 interface says that not only
are we using the loopback (since this is address also refers to the
local host), but specifically it is an alias. Such routes only show
up on the host that supports the alias; all other hosts on the local
network will simply have a link#1 line for
such.The final line (destination subnet 224) deals
with MultiCasting, which will be covered in a another section.The other column that we should talk about are the
Flags. Each route has different attributes that
are described in the column. Below is a short table of some of these
flags and their meanings:UUp: The route is active.HHost: The route destination is a single host.GGateway: Send anything for this destination on to this
remote system, which will figure out from there where to send
it.SStatic: This route was configured manually, not
automatically generated by the system.CClone: Generates a new route based upon this route for
machines we connect to. This type of route is normally used
for local networks.WWasCloned: Indicated a route that was auto-configured
based upon a local area network (Clone) route.LLink: Route involves references to ethernet
hardware.Default routesdefault routeWhen the local system needs to make a connection to remote host,
it checks the routing table to determine if a known path exists. If
the remote host falls into a subnet that we know how to reach (Cloned
routes), then the system checks to see if it can connect along that
interface.If all known paths fail, the system has one last option: the
default route. This route is a special type of gateway
route (usually the only one present in the system), and is always
marked with a c in the flags field. For hosts on a
local area network, this gateway is set to whatever machine has a
direct connection to the outside world (whether via PPP link, or your
hardware device attached to a dedicated data line).If you are configuring the default route for a machine which
itself is functioning as the gateway to the outside world, then the
default route will be the gateway machine at your Internet Service
Provider's (ISP) site.Let us look at an example of default routes. This is a common
configuration:
[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
The hosts Local1 and Local2 are
at your site, with the formed being your PPP connection to your ISP's
Terminal Server. Your ISP has a local network at their site, which
has, among other things, the server where you connect and a hardware
device (T1-GW) attached to the ISP's Internet feed.The default routes for each of your machines will be:hostdefault gatewayinterfaceLocal2Local1ethernetLocal1T1-GWPPPA common question is Why (or how) would we set the T1-GW to
be the default gateway for Local1, rather than the ISP server it is
connected to?.Remember, since the PPP interface is using an address on the ISP's
local network for your side of the connection, routes for any other
machines on the ISP's local network will be automatically generated.
Hence, you will already know how to reach the T1-GW machine, so there
is no need for the intermediate step of sending traffic to the ISP
server.As a final note, it is common to use the address ...1 as the gateway address for your local
network. So (using the same example), if your local class-C address
space was 10.20.30 and your ISP was
using 10.9.9 then the default routes
would be:
Local2 (10.20.30.2) --> Local1 (10.20.30.1)
Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1)
Dual homed hostsdual homed hostsThere is one other type of configuration that we should cover, and
that is a host that sits on two different networks. Technically, any
machine functioning as a gateway (in the example above, using a PPP
connection) counts as a dual-homed host. But the term is really only
used to refer to a machine that sits on two local-area
networks.In one case, the machine as two ethernet cards, each having an
address on the separate subnets. Alternately, the machine may only
have one ethernet card, and be using ifconfig aliasing. The former is
used if two physically separate ethernet networks are in use, the
latter if there is one physical network segment, but two logically
separate subnets.Either way, routing tables are set up so that each subnet knows
that this machine is the defined gateway (inbound route) to the other
subnet. This configuration, with the machine acting as a Bridge
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.Routing propagationrouting propogationWe 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.TroubleshootingtracerouteSometimes, there is a problem with routing propagation, and some
sites are unable to connect to you. Perhaps the most useful command
for trying to figure out where a routing is breaking down is the
&man.traceroute.8; command. It is equally useful if you cannot seem
to make a connection to a remote machine (i.e. &man.ping.8;
fails).The &man.traceroute.8; command is run with the name of the remote
host you are trying to connect to. It will show the gateway hosts
along the path of the attempt, eventually either reaching the target
host, or terminating because of a lack of connection.For more information, see the manual page for
&man.traceroute.8;.BridgingWritten by Steve Peterson
steve@zpfe.com.IntroductionIP subnetbridgeIt is sometimes useful to divide one physical network (i.e., 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. and a FreeBSD system with two network
interface cards can act as a bridge.The bridge works by learning the MAC layer addresses (i.e.,
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 appropriateThere are two common situations in which a bridge is used
today.High traffic on a segmentSituation one is where your physical network segment is
overloaded with traffic, but you don't want for whatever reason to
subnet the network and interconnect the subnets with a
router.Let's 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 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 firewallfirewallIP MasqueradingThe second common situation is where firewall functionality is
needed without IP Masquerading (NAT).An example is a small company that is connected via DSL or ISDN
to their ISP. They have a 13 address global IP allocation for their
ISP and have 10 PCs on their network. In this situation, using a
router-based firewall is difficult because of subnetting
issues.routerDSLISDNA 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 bridgeNetwork interface card selectionA bridge requires at least two network cards to function.
Unfortunately, not all network interface cards as of FreeBSD 4.0
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 changeskernel configurationkernel configurationoptions BRIDGETo enable kernel support for bridging, add theoptions BRIDGEstatement to your kernel configuration file, and rebuild your
kernel.Firewall supportfirewallIf 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 an undocumented 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 supportIf 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 bridgeAdd the linenet.link.ether.bridge=1to /etc/sysctl.conf to enable the bridge at
runtime. If you want the bridged packets to be filtered by ipfw, you
should also addnet.link.ether.bridge_ipfw=1as well.PerformanceMy bridge/firewall is a Pentium 90 with one 3Com 3C900B and one
3C905B. The protected side of the network runs at 10mbps half duplex
and the connection between the bridge and my router (a Cisco 675) runs
at 100mbps full duplex. With no filtering enabled, I've found that
the bridge adds about 0.4 milliseconds of latency to pings from the
protected 10mbps network to the Cisco 675.Other informationIf you want to be able to telnet into the bridge from the network,
it is OK 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.NFSWritten by &a.unfurl;, 4 March 2000.NFSAmong the many different file systems that FreeBSD supports is
a very unique type, the Network File System or NFS. NFS allows you
to share directories and files on one machine with one or more other
machines via the network they are attached to. Using NFS, users and
programs can access files on remote systems as if they were local
files.NFS has several benefits:Local workstations don't need as much disk space because
commonly used data can be stored on a single machine and still
remain accessible to everyone on the network.There is no need for users to have unique home directories
on every machine on your network. Once they have an established
directory that is available via NFS it can be accessed from
anywhere.
- Storage devices such as floppies and CD-ROM drives can be
+ Storage devices such as floppies and CDROM drives can be
used by other machines on the network eliminating the need for
extra hardware.How It WorksNFS is composed of two sides – a client side and a
server side. Think of it as a want/have relationship. The client
wants the data that the server side
has. The server shares its data with the
client. In order for this system to function properly a few
processes have to be configured and running properly.The server has to be running the following daemons:NFSserverportmapmountdnfsdnfsd - The NFS Daemon which services
requests from NFS clients.mountd - The NFS Mount Daemon which
actually carries out requests that nfsd passes on to
it.portmap - The portmapper daemon which
allows NFS clients to find out which port the NFS server is
using.The client side only needs to run a single daemon:NFSclientnfsiodnfsiod - The NFS async I/O Daemon which
services requests from its NFS server.Configuring NFSNFSconfigurationLuckily for us, on a FreeBSD system this setup is a snap. The
processes that need to be running can all be run at boot time with
a few modifications to your /etc/rc.conf
file.On the NFS server make sure you have:portmap_enable="YES"
nfs_server_enable="YES"
nfs_server_flags="-u -t -n 4"
mountd_flags="-r"mountd is automatically run whenever the
NFS server is enabled. The and
flags to nfsd tell it to
serve UDP and TCP clients. The flag tells
nfsd to start 4 copies of itself.On the client, make sure you have:nfs_client_enable="YES"
nfs_client_flags="-n 4"Like nfsd, the tells
nfsiod to start 4 copies of itself.The last configuration step requires that you create a file
called /etc/exports. The exports file
specifies which file systems on your server will be shared
(a.k.a., exported) and with what clients they will
be shared. Each line in the file specifies a file system to be
shared. There are a handful of options that can be used in this
file but only a few will be mentioned here. You can find out
about the rest in the &man.exports.5; man page.Here are a few example /etc/exports
entries:NFSexporting filesystemsThe following line exports /cdrom to
three silly 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 shared file system read-only. With this flag, the
remote system will not be able to make any changes to the
shared file system./cdrom -ro moe larry curlyThe following line exports /home to three
hosts by IP address. This is a useful setup if you have a
private network but do not have DNS running. The
flag allows all the directories below
the specified file system to be exported as well./home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4The following line exports /a to two
machines that have different domain names than the server. The
flag allows
the root user on the remote system to write to the shared
file system as root. Without the -maproot=0 flag even if
someone has root access on the remote system they won't
be able to modify files on the shared file system./a -maproot=0 host.domain.com box.example.comIn order for a client to share an exported file system it must
have permission to do so. Make sure your client is listed in your
/etc/exports file.It's important to remember that you must restart mountd
whenever you modify /etc/exports so that
your changes take effect. This can be accomplished by sending
the hangup signal to the mountd process :&prompt.root; kill -HUP `cat /var/run/mountd.pid`Now that you have made all these changes you can just reboot
and let FreeBSD start everything for you at boot time or you can
run the following commands as root:On the NFS server:&prompt.root; portmap
&prompt.root; nfsd -u -t -n 4
&prompt.root; mountd -rOn the NFS client:&prompt.root; nfsiod -n 4Now you should be ready to actually mount a remote file
system. This can be done one of two ways. In these examples the
server's name will be server and the client's
name will be client. If you just want to
temporarily mount a remote file system or just want to test out
your config you can run a command like this as root on the
client:NFSmounting filesystems&prompt.root; mount server:/home /mntThis will mount /home on the server on
/mnt on the client. If everything is setup
correctly you should be able to go into /mnt on the client and see
all the files that are on the server.If you want to permanently (each time you reboot) mount a
remote file system you need to add it to your
/etc/fstab file. Here is an example
line:server:/home /mnt nfs rw 0 0Read the &man.fstab.5; man page for more options.Practical UsesThere are many very cool uses for NFS. Some of the more common
ones are listed below.NFSuses
- Have several machines on a network and share a CD-ROM or
+ Have several machines on a network and share a CDROM or
floppy drive among them. This is cheaper and often more
convenient.With so many machines on a network, it gets old having your
personal files strewn all over the place. You can have a
central NFS server that houses all user home directories and
shares them with the rest of the machines on the LAN, so no
matter where you log in you will have the same home
directory.When you get to reinstalling FreeBSD on one of your
machines, NFS is the way to go! Just pop your distribution
- CD-ROM into your file server and away you go!
+ CDROM into your file server and away you go!
Have a common /usr/ports/distfiles
directory that all your machines share. That way, when you go
to install a port that you've already installed on a different
machine, you do not have to download the source all over
again!Problems integrating with other systemsContributed by &a.jlind;.Certain Ethernet adapters for ISA PC systems have limitations
which can lead to serious network problems, particularly with NFS.
This difficulty is not specific to FreeBSD, but FreeBSD systems
are affected by it.The problem nearly always occurs when (FreeBSD) PC systems are
networked with high-performance workstations, such as those made
by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS
mount will work fine, and some operations may succeed, but
suddenly the server will seem to become unresponsive to the
client, even though requests to and from other systems continue to
be processed. This happens to the client system, whether the
client is the FreeBSD system or the workstation. On many systems,
there is no way to shut down the client gracefully once this
problem has manifested itself. The only solution is often to
reset the client, because the NFS situation cannot be
resolved.Though the correct solution is to get a higher
performance and capacity Ethernet adapter for the FreeBSD system,
there is a simple workaround that will allow satisfactory
operation. If the FreeBSD system is the
server, include the option
on the mount from the client. If the
FreeBSD system is the client, then mount the
NFS file system with the option . These
options may be specified using the fourth field of the
fstab entry on the client for automatic
mounts, or by using the parameter of the mount
command for manual mounts.It should be noted that there is a different problem,
sometimes mistaken for this one, when the NFS servers and clients
are on different networks. If that is the case, make
certain that your routers are routing the
necessary UDP information, or you will not get anywhere, no matter
what else you are doing.In the following examples, fastws is the host
(interface) name of a high-performance workstation, and
freebox is the host (interface) name of a FreeBSD
system with a lower-performance Ethernet adapter. Also,
/sharedfs will be the exported NFS
filesystem (see man exports), and
/project will be the mount point on the
client for the exported file system. In all cases, note that
additional options, such as or
and may be desirable in
your application.Examples for the FreeBSD system (freebox) as
the client: in /etc/fstab on freebox:fastws:/sharedfs /project nfs rw,-r=1024 0 0As a manual mount command on freebox:&prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /projectExamples for the FreeBSD system as the server: in
/etc/fstab on fastws:freebox:/sharedfs /project nfs rw,-w=1024 0 0As a manual mount command on fastws:&prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /projectNearly any 16-bit Ethernet adapter will allow operation
without the above restrictions on the read or write size.For anyone who cares, here is what happens when the failure
occurs, which also explains why it is unrecoverable. NFS
typically works with a block size of 8k (though it
may do fragments of smaller sizes). Since the maximum Ethernet
packet is around 1500 bytes, the NFS block gets
split into multiple Ethernet packets, even though it is still a
single unit to the upper-level code, and must be received,
assembled, and acknowledged as a unit. The
high-performance workstations can pump out the packets which
comprise the NFS unit one right after the other, just as close
together as the standard allows. On the smaller, lower capacity
cards, the later packets overrun the earlier packets of the same
unit before they can be transferred to the host and the unit as a
whole cannot be reconstructed or acknowledged. As a result, the
workstation will time out and try again, but it will try again
with the entire 8K unit, and the process will be repeated, ad
infinitum.By keeping the unit size below the Ethernet packet size
limitation, we ensure that any complete Ethernet packet received
can be acknowledged individually, avoiding the deadlock
situation.Overruns may still occur when a high-performance workstations
is slamming data out to a PC system, but with the better cards,
such overruns are not guaranteed on NFS units. When
an overrun occurs, the units affected will be retransmitted, and
there will be a fair chance that they will be received, assembled,
and acknowledged.Diskless OperationContributed by &a.martin;.diskless workstationnetboot.com/netboot.rom
allow you to boot your FreeBSD machine over the network and run FreeBSD
without having a disk on your client. Under 2.0 it is now possible to
have local swap. Swapping over NFS is also still supported.Supported Ethernet cards include: Western Digital/SMC 8003, 8013,
8216 and compatibles; NE1000/NE2000 and compatibles (requires
recompile)Setup InstructionsFind a machine that will be your server. This machine will
require enough disk space to hold the FreeBSD 2.0 binaries and
have bootp, tftp and NFS services available. Tested
machines:HP-UXHP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
work)SolarisSun/Solaris 2.3. (you may need to get bootp)Set up a bootp server to provide the client with IP, gateway,
netmask.diskless:\
:ht=ether:\
:ha=0000c01f848a:\
:sm=255.255.255.0:\
:hn:\
:ds=192.1.2.3:\
:ip=192.1.2.4:\
:gw=192.1.2.5:\
:vm=rfc1048:TFTPbootpSet up a TFTP server (on same machine as bootp server) to
provide booting information to client. The name of this file is
cfg.X.X.X.X (or
/tftpboot/cfg.X.X.X.X,
it will try both) where X.X.X.X is the
IP address of the client. The contents of this file can be any
valid netboot commands. Under 2.0, netboot has the following
commands:helpprint help listip
print/set client's IP addressserver
print/set bootp/tftp server addressnetmask
print/set netmaskhostname nameprint/set hostnamekernel
print/set kernel namerootfs
print/set root filesystemswapfs
print/set swap filesystemswapsize
set diskless swapsize in KBytesdiskbootboot from diskautobootcontinue boot processtrans
|turn transceiver on|offflags
set boot flagsA typical completely diskless cfg file might contain:rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomainA cfg file for a machine with local swap might contain:rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomainEnsure that your NFS server has exported the root (and swap if
applicable) filesystems to your client, and that the client has
root access to these filesystems A typical
/etc/exports file on FreeBSD might look
like:/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomainAnd on HP-UX:/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomainNFSswapping overIf you are swapping over NFS (completely diskless
configuration) create a swap file for your client using
dd. If your swapfs command
has the arguments /swapfs and the size 20000
as in the example above, the swapfile for myclient will be called
/swapfs/swap.X.X.X.X
where X.X.X.X is the client's IP addr,
e.g.:&prompt.root; dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000Also, the client's swap space might contain sensitive
information once swapping starts, so make sure to restrict read
and write access to this file to prevent unauthorized
access:&prompt.root; chmod 0600 /swapfs/swap.192.1.2.4Unpack the root filesystem in the directory the client will
use for its root filesystem (/rootfs/myclient
in the example above).On HP-UX systems: The server should be running HP-UX 9.04
or later for HP9000/800 series machines. Prior versions do not
allow the creation of device files over NFS.When extracting /dev in
/rootfs/myclient, beware that some
systems (HPUX) will not create device files that FreeBSD is
happy with. You may have to go to single user mode on the
first bootup (press control-c during the bootup phase), cd
/dev and do a sh ./MAKEDEV
all from the client to fix this.Run netboot.com on the client or make an
EPROM from the netboot.rom fileUsing Shared / and /usr
filesystemsAlthough this is not an officially sanctioned or supported way
of doing this, some people report that it works quite well. If
anyone has any suggestions on how to do this cleanly, please tell
&a.doc;.Compiling netboot for specific setupsNetboot can be compiled to support NE1000/2000 cards by changing
the configuration in
/sys/i386/boot/netboot/Makefile. See the
comments at the top of this file.ISDNA 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.ISDN CardsContributed by &a.hm;.ISDNcardsThis section is really only relevant to ISDN users in countries
where the DSS1/Q.931 ISDN standard is supported.Some growing number of PC ISDN cards are supported under FreeBSD
2.2.x and up by the isdn4bsd driver package. It is still under
development but the reports show that it is successfully used all over
Europe.isdn4bsdThe latest isdn4bsd version is available from ftp://isdn4bsd@ftp.consol.de/pub/,
the main isdn4bsd ftp site (you have to log in as user
isdn4bsd , give your mail address as the password
and change to the pub directory. Anonymous ftp
as user ftp or anonymous
will not give the desired result).Isdn4bsd allows you to connect to other ISDN routers using either
IP over raw HDLC or by using synchronous PPP. A telephone answering
machine application is also available.Many ISDN PC cards are supported, mostly the ones with a Siemens
ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola,
Cologne Chip Designs) is currently under development. For an
up-to-date list of supported cards, please have a look at the README
file.In case you are interested in adding support for a different ISDN
protocol, a currently unsupported ISDN PC card or otherwise enhancing
isdn4bsd, please get in touch with hm@kts.org.A majordomo maintained mailing list is available. To join the
list, send mail to &a.majordomo; and
specify:subscribe freebsd-isdnin the body of your message.ISDN Terminal AdaptersTerminal adapters(TA), are to ISDN what modems are to regular
phone lines.modemMost 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.PPPThe 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 setup. However, at the same time any problems you
experienced with the PPP program and are going to persist.If you want maximum stability, use the kernel PPP option, not the user-land iijPPP.The following TA's are know to work with FreeBSD.Motorola BitSurfer and Bitsurfer ProAdtranMost other TA's will probably work as well, TA vendors try to make
sure their product can accept most of the standard modem AT command
set.The real problem with external TA's is like modems you need a good
serial card in your computer.You should read the 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.2Kbs, even though you have a 128Kbs connection. To fully
utilize the 128Kbs that ISDN is capable of, you must move the TA to a
synchronous serial card.Do not be fooled into buying an internal TA and thinking you have
avoided the synchronous/asynchronous issue. Internal TA's simply have
a standard PC serial port chip built into them. All this will do, is
save you having to buy another serial cable, and find another empty
electrical socket.A synchronous card with a TA is at least as fast as a stand-alone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.The choice of sync/TA v.s. stand-alone router is largely a
religious issue. There has been some discussion of this in
the mailing lists. I suggest you search the archives for
the complete discussion.Stand-alone ISDN Bridges/RoutersISDNstand-alone bridges/routersISDN bridges or routers are not at all specific to FreeBSD
or any other operating system. For a more complete
description of routing and bridging technology, please refer
to a Networking reference book.In the context of this page, 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(or card), and manages its own connection to
the other bridge/router. It has all the software to do PPP
and other protocols built in.A router will allow you much faster throughput that a
standard TA, since it will be using a full synchronous ISDN
connection.The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem.
If you are planning to connect to an Internet provider, you
should discuss your needs with them.If you are planning to connect two LAN segments together,
ie: home LAN to the office LAN, this is the simplest lowest
maintenance solution. Since you are buying the equipment for
both sides of the connection you can be assured that the link
will work.For example to connect a home computer or branch office
network to a head office network the following setup could be
used.Branch office or Home network10 base 2Network 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 (Do not admit to owning it)
|
Stand-alone router
|
ISDN BRI line10 Base 2 EthernetIf 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 LAN10 base TNetwork 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 lineISDN Network DiagramOne large advantage of most routers/bridges is that they allow you
to have 2 separate independent PPP connections to
2 separate sites at the same time. This is not
supported on most TA's, except for specific(expensive) models that
have two serial ports. Do not confuse this with channel bonding, MPP
etc.This can be very useful feature, for example if you have an
dedicated ISDN connection at your office and would like to
tap into it, but don't want to get another ISDN line at work. A router
at the office location can manage a dedicated B channel connection
(64Kbs) to the internet, as well as a use the other B channel for a
separate data connection. The second B channel can be used for
dial-in, dial-out or dynamically bond(MPP etc.) with the first B channel
for more bandwidth.IPX/SPXAn 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.NIS/YPWritten by &a.unfurl;, 21 January 2000, enhanced
with parts and comments from Eric Ogren
eogren@earthlink.net and Udo Erdelhoff
ue@nathan.ruhr.de in June 2000.What is it?NISSolarisHP-UXAIXLinuxNetBSDOpenBSDNIS, 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 Unices (Solaris, HP-UX, AIX, Linux,
NetBSD, OpenBSD, FreeBSD, etc) support NIS.yellow pages (see NIS)NIS was formerly known as Yellow Pages (or yp), but due to
copyright violations, Sun was forced to change the name.NISdomainsIt 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 NTIt is similar to Windows NT's domain system; although the
internal implementation of the two aren't at all similar,
the basic functionality can be compared.Terms/processes you should knowThere 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 an NIS client:The NIS domainname. An NIS master
server and all of its clients (including its slave servers) have
a NIS domainname. Similar to an NT domain name, the NIS
domainname does not have anything to do with DNS.portmapportmap. portmap
must be running in order to enable RPC (Remote Procedure Call, a
network protocol used by NIS). If portmap is
not running, it will be impossible to run an NIS server, or to
act as an NIS client.ypbind. 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. ypserv,
which should only be running on NIS servers, is the NIS server
process itself. If ypserv 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 don't 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.
rpc.yppasswdd, another process that should
only be running on NIS master servers, 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
server it is bound to, to get this information.Machine typesNISmaster serverA NIS master server.
This server, analogous to a Windows
NT 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.NISslave serverNIS slave servers.
Similar to NT's 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.NISclientNIS clients. NIS clients, like most
NT workstations, authenticate against the NIS server (or the NT
domain controller in the NT Workstation case) to log on.Using NIS/YPThis 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.PlanningLet's 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 nameIP addressMachine roleellington10.0.0.2NIS mastercoltrane10.0.0.3NIS slavebasie10.0.0.4Faculty workstationbird10.0.0.5Client machinecli[1-11]10.0.0.[6-17]Other client machinesIf 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 NameNISdomainnameThis 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.SunOSHowever, 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 RequirementsThere 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 won't 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 serverNISserver configurationSetting 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.Now, all you have to do is to run the command
/etc/netstart as superuser. It will
setup everything for you, using the values you defined in
/etc/rc.conf.Initializing the NIS mapsNIS mapsThe 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 don't 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.passwdYou should remove all entries regarding system accounts
(bin, tty, kmem, games, etc), as well as any accounts that you
don't 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 UnixWhen you have finished, it's time to initialize the NIS
maps! FreeBSD includes a script named
ypinit to do this for you
(see its man page for more information). Note that this
script is available on most UNIX OSs, 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/MakefileYou should comment out the line that says `NOPUSH =
"True"' (if it is not commented out already).Setting up a NIS slave serverNISconfiguring a slave serverSetting 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.byuidThese two lines force the slave to sync its maps with
the maps on the master server. Although this is
not mandatory, because the master server
tries to make sure any changes to its NIS maps are
communicated to its slaves, the password
information is so vital to systems that depend on the server,
that 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 an NIS clientNISclient configurationSetting 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, add this line to your
/etc/master.passwd file, using
vipw:+:::::::::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
part below for more information.
For more detailed reading see O'Reilly's book on
Managing NFS and NIS.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 SecurityIn general, any remote user can issue an RPC to ypserv and
retrieve the contents of your NIS maps, provided the remote user
knows your domainname. To prevent such unauthorized transactions,
ypserv supports a feature called securenets which can be used to
restrict access to a given set of hosts. At startup, ypserv 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.0If ypserv 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
tcpwrapper package. This allows the
administrator to use the tcpwrapper 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.tcpwrapperThe use of the tcpwrapper
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 onIn our lab, there is a machine basie that is
supposed to be a faculty only workstation. We don't 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;Using netgroupsnetgroupsThe netgroups part was contributed by
Udo Erdelhoff ue@nathan.ruhr.de in July
2000.The method shown in the previous chapter 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 chapter 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)Descriptionalpha, betaNormal employees of the IT departmentcharlie, deltaThe new apprentices of the IT departmentecho, foxtrott, golf, ...Ordinary employeesable, baker, ...The current internsMachine Name(s)Descriptionwar, death, famine, pollutionYour most important servers. Only the IT
employees are allowed to log onto these
machines.pride, greed, envy, wrath, lust, slothLess 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.trashcanA 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 ypinit 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 typeellington&prompt.root; vi /var/yp/netgroupand 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 unlucky fellows with more than one NIS
domain.Each of these fields can contain wildcards. See
&man.netgroup.5; for details.netgroupsNetgroup 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 BIGGRP3You 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; makeThis 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.byuserThe 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/nologinThe corresponding lines for the normal workstations
could be:+@IT_EMP:::::::::
+@USERS:::::::::
+:::::::::/sbin/nologinAnd 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 config 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 USERSThis 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/nologinOnce 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
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 rememberThere 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-domainYou could also run adduser jsmith instead
of pw useradd jsmith.Keep the administration accounts out of the NIS
maps. You don't want to be propagating administrative
accounts and passwords to machines that will have users that
shouldn't 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, and it is probably the most important weakness. 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 can not 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 on 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.libscrypt v.s. libdescryptNIScrypto libraryOne of the most common issues that people run into when trying
to implement NIS is crypt library compatibility. If your NIS
server is using the DES crypt libraries, it will only support
clients that are using DES as well. To check which one your server
and clients are using look at the symlinks in
/usr/lib. If the machine is configured to
use the DES libraries, it will look something like this:&prompt.user; ls -l /usr/lib/*crypt*
lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libdescrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a
-r--r--r-- 1 root wheel 13018 Nov 8 14:27 /usr/lib/libdescrypt.a
lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2
-r--r--r-- 1 root wheel 12965 Nov 8 14:27 /usr/lib/libdescrypt.so.2
-r--r--r-- 1 root wheel 14750 Nov 8 14:27 /usr/lib/libdescrypt_p.aIf the machine is configured to use the standard FreeBSD MD5
crypt libraries they will look something like this:&prompt.user; ls -l /usr/lib/*crypt*
lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libscrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a
-r--r--r-- 1 root wheel 6194 Nov 8 14:27 /usr/lib/libscrypt.a
lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2
-r--r--r-- 1 root wheel 7579 Nov 8 14:27 /usr/lib/libscrypt.so.2
-r--r--r-- 1 root wheel 6684 Nov 8 14:27 /usr/lib/libscrypt_p.aIf you have trouble authenticating on an NIS client, this
is a pretty good place to start looking for possible problems.
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.DHCPWritten by &a.gsutter;, March 2000.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
uses the ISC (Internet Software Consortium) DHCP implementation, so
all implementation-specific information here is for use with the ISC
distribution.What This Section CoversThis handbook section attempts to describe only the parts
of the DHCP system that are integrated with FreeBSD;
consequently, the server portions are not described. The DHCP
manual pages, in addition to the references below, are useful
resources.How it WorksUDPWhen 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 IntegrationFreeBSD fully integrates the ISC DHCP client,
dhclient. 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.sysinstallDHCP is supported by sysinstall.
When configuring a network interface within sysinstall,
the first question asked is, "Do you want to try dhcp
configuration of this 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:DHCPrequirementsMake sure that the bpf
device is compiled into your kernel. To do this, add
pseudo-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 don't have a custom
kernel, you shouldn't 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). bpfis required to use DHCP, but if
you are very sensitive about security, you probably
shouldn't 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.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=""DHCPserverThe DHCP server, dhcpd, is included
as part of the isc-dhcp2 port in the ports
collection. This port contains the full ISC DHCP distribution,
consisting of client, server, relay agent and documentation.
FilesDHCPconfiguration files/etc/dhclient.confdhclient 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;
man page./sbin/dhclientdhclient is statically linked and
resides in /sbin. The &man.dhclient.8;
manual page gives more information about
dhclient./sbin/dhclient-scriptdhclient-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.leasesThe 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 ReadingThe DHCP protocol is fully described in
RFC 2131.
An informational resource has also been set up at
dhcp.org.DNSContributed by &a.chern;, April 12, 2001.
OverviewBINDFreeBSD 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
IPs, and vice versa. For example, a query for www.freebsd.org
will send back a reply for the IP address of The FreeBSD Project's
webpage, whereas, a query for ftp.freebsd.org will return the IP
of the corresponding ftp machine. Likewise, the opposite can
happen. A query for an IP address can resolve its hostname.
DNSDNS is coordinated across the Internet through a somewhat
complex system of authoritative root name servers, and other
smaller-scale nameservers who host and relay individual domain
information.
This document refers to BIND 8.x, as it is the most current,
stable version used in FreeBSD.
RFC1034 and RFC1035 dictates the DNS protocol.
Currently, BIND is maintained by the
Internet Software Consortium (www.isc.org)Terminologyzoneszone - Each individual domain, subdomain,
or 'area' dictated by DNS is considered a zone.
Examples of zones:
. is the root zoneorg. is a zone under the root zonefoobardomain.org is a zone under the org. zonefoo.foobardomain.org. is a subdomain, a zone under the
foobardomain.org. zone
1.2.3.in-addr.arpa is a zone referencing all ips which fall
under the 3.2.1.* ip space.
named, bind, name server - these are all
common names for the BIND name server package within FreeBSD.
resolverresolver - a network process by which a
system queries a nameserver for answers
root zoneroot zone - literally, a '.', refers to
the root, or beginning zone. All zones fall under this, as do all
files in fall under the root directory. It is the beginning of the
Internet zone hierarchy
origin - refers to the point of start for
the particular zone
forward dns - mapping of hostnames to ip
addresses
reverse DNSreverse dns - the opposite, mapping of ip
addresses to hostnames
Reasons to run a name server
You need your machine to host DNS information to the world
An authoritative nameserver replies exclusively
to requests.
For example, you register foobardomain.org and wish
to assign hostnames to the proper IP addresses.
A slave nameserver, which replies to queries for a
domain when the primary is down or inaccessible.
The above two can also be done with in-addr.arpa, IP
to hostname entries
You wish your machine to act as a local relay of DNS
information
DNS traffic has been measured to be about 5% or more
of the total Internet traffic.
A local DNS server may have some added benefit by
providing a local cache of DNS information.
For example, when one queries for www.freebsd.org,
their resolver goes out to (usually) your ISP's name
server, and retrieves the query.
With a local, caching DNS server, the query only has to
be made once to the outside world. Every additional
query will not have to go outside of the local network,
since the information is cached.
How it works
A DNS server in FreeBSD relies on the BIND daemon. This daemon is
called 'named' for obvious reasons.
named - the bind daemonndc - name daemon control program/etc/namedb - directory where all the bind
information resides
/etc/namedb/named.conf - daemon configuration
file
zone files are usually contained within the
/etc/namedb
directory, and contain the information (query answers from
your site) served by your name server.
Starting BINDBINDstarting
Since bind is installed by default, configuring it all is
relatively simple.
To ensure the named daemon is started at boot, put the following
modifications in your /etc/rc.confnamed_enable="YES"To start the daemon manually (after configuring it)&prompt.root; ndc startConfiguration filesBINDconfiguration filesmake-localhostBe sure to
&prompt.root; cd /etc/namedb
&prompt.root; sh make-localhostto properly create your local reverse dns zone file in
/etc/namedb/localhost.rev.
/etc/namedb/named.conf
- // $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.51 2001/07/06 13:02:58 dd Exp $
+ // $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.52 2001/07/13 22:44:03 murray Exp $
//
// Refer to the named(8) man page for details. If you are ever going
// to setup a primary server, make sure you've understood the hairy
// details of how DNS is working. Even with simple mistakes, you can
// break connectivity for affected parties, or cause huge amount of
// useless Internet traffic.
options {
directory "/etc/namedb";
// 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, if you want to benefit from your
uplink's cache, you can enable this section of the config file.
Normally, your nameserver will recursively query different
nameservers until it finds the answer it is looking for. Having
this enabled will have it automatically see if your
uplink's (or whatever provided) ns has the requested query.
If your uplink has a heavily trafficked, fast nameserver,
enabling this properly could work to your advantage.
127.0.0.1 will *NOT* work here; change this to the IP of a
nameserver 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 8.1 uses an unprivileged
* port by default.
*/
// query-source address * port 53;
/*
* If running in a sandbox, you may have to specify a different
* location for the dumpfile.
*/
// dump-file "s/named_dump.db";
};
// Note: the following will be supported in a future release.
/*
host { any; } {
topology {
127.0.0.0/8;
};
};
*/
// Setting up secondaries is way easier and the rough picture for this
// is explained below.
//
// If you enable a local name server, don't forget to enter 127.0.0.1
// into your /etc/resolv.conf so this server will be queried first.
// 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 "localhost.rev";
};
zone
"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.INT" {
type master;
file "localhost.rev";
};
// NB: Do not use the IP addresses below, they are faked, and only
// serve demonstration/documentation purposes!
//
// Example secondary config entries. It can be convenient to become
// a secondary at least for the zone where 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 the first bytes of the respective IP address, in reverse
// order, with ".IN-ADDR.ARPA" appended.)
//
// Before starting to setup a primary zone, better make sure you fully
// understand how DNS and BIND works, however. There are sometimes
// unobvious pitfalls. Setting up a secondary is comparably simpler.
//
// NB: Don't blindly enable the examples below. :-) Use actual names
// and addresses instead.
//
// NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
// The directory containing the secondary zones must be write accessible
// to bind. The following sequence is suggested:
//
// mkdir /etc/namedb/s
// chown bind:bind /etc/namedb/s
// chmod 750 /etc/namedb/s
/*
zone "domain.com" {
type slave;
file "s/domain.com.bak";
masters {
192.168.1.1;
};
};
zone "0.168.192.in-addr.arpa" {
type slave;
file "s/0.168.192.in-addr.arpa.bak";
masters {
192.168.1.1;
};
};
*/
These are example slave entries, read below to see more.
For each new domain added to your nameserver, you must add one
of these entries to your named.conf
The simplest zone entry, can look like
zone "foobardomain.org" {
type master;
file "foorbardomain.org";
};For a master entry with the zone information within
foobardomain.org, or
zone "foobardomain.org" {
type slave;
file "foobardomain.org";
};
for a slave. Note that slave zones automatically query the
listed master (authoritative) name servers for the zone file.
Zone files
An example master 'foobardomain.org' (existing within
/etc/namedb/foobardomain.org) is as follows:
$TTL 3600
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ) ; Minimum TTL
; DNS Servers
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
; Machine Names
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
; Aliases
www IN CNAME @
; MX Record
@ IN MX 10 mail.foobardomain.org.
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 foobardomain.org, so www would be www.foobardomain.org.
The format of this file follows:
recordname IN recordtype valueDNSrecords
The most commonly used DNS records:
SOA - start of zone authorityNS - an authoritative nameserverA - A host addressCNAME - the canonical name for an
aliasMX - mail exchangePTR - a domain name pointer (used in
reverse dns)
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh after 3 hours
3600 ; Retry after 1 hour
604800 ; Expire after 1 week
86400 ) ; Minimum TTL of 1 day
foobardomain.org. - the domain name, also
the origin for this zone file.
ns1.foobardomain.org. - the
primary/authoritative nameserver for this zone
admin.foobardomain.org. - the
responsible person for this zone, e-mail address with @
replaced. (admin@foobardomain.org becomes admin.foobardomain.org)
5 - 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.
2001041002 would mean last modified 04/10/2001, the latter 02 being
the second time the zone file has been modified this day. The
serial number is important as it alerts slave nameservers for a zone
when it is updated.
@ IN NS ns1.foobardomain.org.
This is an NS entry. Every nameserver that is going to reply
authoritatively for the zone must have one of these entries.
The @ as seen here could have been 'foobardomain.org.' The @
translates to the origin.
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
The A record indicates machine names. As seen above,
ns1.foobardomain.org would resolve to 3.2.1.2. Again, the
origin symbol, @, is used here, thus meaning foobardomain.org would
resolve to 3.2.1.30.
www IN CNAME @
The canonical name record is usually used for giving aliases
to a machine. In the example, www is aliased to the machine
addressed to the origin, or foobardomain.org (3.2.1.30).
CNAMEs can be used to provide alias hostnames, or round
robin one hostname among multiple machines.
@ IN MX 10 mail.foobardomain.org.
The MX record indicates which mail servers are responsible
for handling incoming mail for the zone.
mail.foobardomain.org is the hostname of the mail server,
and 10 being the priority of that mailserver.
One can have several mailservers, with priorities of 3, 2,
1. A mail server attempting to deliver to foobardomain.org
would first try the highest priority MX, 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.2.3.in-addr.arpa. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
2 IN PTR ns1.foobardomain.org.
3 IN PTR ns2.foobardomain.org.
10 IN PTR mail.foobardomain.org.
30 IN PTR foobardomain.org.
This file gives the proper IP to hostname mappings of our above
fictitious domain.
Caching Name ServerBINDcaching name server
A caching nameserver is simply a nameserver 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.
Running named in a SandboxBINDrunning in a sandboxContributed by Mike Makonnen
mike_makonnen@yahoo.com, May 1, 2001chrootFor added security you may want to run &man.named.8; in a
sandbox. This will reduce the potential damage should it be
compromised. If you include a sandbox directory in its command
line, named will &man.chroot.8;
into that directory immediately upon finishing processing its
command line. It is also a good idea to have named run as a
non-privileged user in the sandbox. The default FreeBSD install
contains a user bind with group bind. If we wanted the sandbox in
the /etc/namedb/sandbox directory the command
line for named would look like this:
&prompt.root; /usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf> The following steps should be taken in order to
successfully run named in a sandbox. Throughout the following
discussion we will assume the path to your sandbox is
/etc/namedb/sandboxCreate the sandbox directory:
/etc/namedb/sandboxCreate other necessary directories off of the sandbox
directory: etc and
var/runcopy /etc/localtime to
sandbox/etcmake bind:bind the owner of all files and directories in
the sandbox:
&prompt.root; chown -R bind:bind /etc/namedb/sandbox&prompt.root; chmod -R 750 /etc/namedb/sandboxThere are some issues you need to be aware of when running
named in a sandbox.Your &man.named.conf.5; file and all your zone files must
be in the sandbox
sandbox/etc/localtime is needed
in order to have the correct time for your time zone in
log messages. &man.named.8; will write its process id to a file in
sandbox/var/runThe Unix socket used for communication by the &man.ndc.8;
utility will be created in
sandbox/var/runWhen using the ndc utility you need to specify the
location of the Unix socket created in the sandbox, by
&man.named.8;, by using the -c switch:
&prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndcIf you enable logging to file, the log files must be
in the sandbox&man.named.8; can be started in a sandbox properly, if the
following is in /etc/rc.confnamed_flags="-u bind -g bind -t /etc/namedb/sandbox"How to use the nameserverIf setup properly, the nameserver should be accessible through
the network and locally. /etc/resolv.conf must
contain a nameserver entry with the local ip so it will query the
local name server first.
To access it over the network, the machine must have the
nameserver's IP address set properly in its own nameserver
configuration options.
SecurityAlthough BIND is the most common implementation of DNS,
there is always the issue of security. Possible and
exploitable security holes are sometimes found.
It is a good idea to subscribe to CERT and
freebsd-announce
to stay up to date with the current Internet and FreeBSD security
issues.
If a problem arises, keeping your sources up to date and having a
fresh build of named can't hurt.
Further Reading
&man.ndc.8; &man.named.8; &man.named.conf.5;
Official ISC BIND Page
http://www.isc.org/products/BIND/
BIND FAQ
http://www.nominum.com/resources/faqs/bind-faqs.htmlO'Reilly DNS and BIND 4th EditionRFC1034 - Domain Names -
Concepts and FacilitiesRFC1035 - Domain Names -
Implementation and SpecificationNetwork Address Translation daemon (natd)Contributed by &a.chern;, June 2001.
OverviewnatdFreeBSD'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. natd does this by changing
the source ip 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 requestor.Internet connection sharingIP masqueradingThe most common use of NAT is to perform what is commonly known as
Internet Connection Sharing.SetupDue 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
in more and more need of an Internet Connection Sharing solution. The
ability to connect several computers online through one connection and
ip makes &man.natd.8; a reasonable choice.Most commonly, a user has a machine connected to a cable or DSL
line with one ip 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. _______ __________ ________
| | | | | |
| Hub |-----| Client B |-----| Router |----- Internet
|_______| |__________| |________|
|
____|_____
| |
| Client A |
|__________|Network LayoutWith this setup, the machine without Internet access can use
the machine with access as a gateway to access the outside
world.kernelconfigurationConfigurationThe following options must be in the kernel configuration
file:options IPFIREWALL
options IPDIVERTAdditionally, at choice, the following may also be suitable:options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSEThe following must be in /etc/rc.conf:gateway_enable="YES"
firewall_enable="YES"
firewall_type="OPEN"
natd_enable="YES"
natd_interface="fxp0"
natd_flags=""gateway_enable="YES"Sets up the machine to act as a gateway. Running
sysctl -w net.inet.ip.forwarding=1
would have the same effect.firewall_enable="YES"Enables the firewall rules in
/etc/rc.firewall at boot.firewall_type="OPEN"This specifies a predefined firewall ruleset that
allows anything in. See
/etc/rc.firewall for additional
types.natd_interface="fxp0"Indicates which interface to forward packets through.
(the interface connected to the Internet)natd_flags=""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.Each machine and interface behind the LAN should be assigned ip
numbers in the private network space as defined by
RFC 1918
and have a default gateway of the natd machine's internal ip.For example, client a and b behind the LAN have ips of 192.168.0.2
and 192.168.0.3, while the natd machine's LAN interface has an ip 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 natd
to work.Port RedirectionThe drawback with natd 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 -redirect_port 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 -redirect_port 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; or placed within the
natd_flags="" option in
/etc/rc.conf.For further configuration options, consult &man.natd.8;Address Redirectionaddress redirectionAddress redirection is useful if several ips are available, yet
they must be on one machine. With this, &man.natd.8; can assign each
LAN client its own external ip. &man.natd.8; then rewrites outgoing
packets from the LAN clients with the proper external ip and redirects
all traffic incoming on that particular ip back to the specific LAN
client. This is also known as static NAT. For example, the ips
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 -redirect_address syntax is as follows: -redirect_address localIP publicIPlocalIPThe internal ip of the LAN client.publicIPThe external ip 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.3Like -redirect_port, these arguments are also placed within
natd_flags of /etc/rc.conf. With address
redirection, there is no need for port redirection since all data
received on a particular ip address is redirected.The external ips on the natd machine must be active and aliased
to the external interface. Look at &man.rc.conf.5; to do so.
diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index 8a87fb7dfa..7fd6b5a4b6 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1,2048 +1,2048 @@
Installing FreeBSDRestructured, updated, and parts rewritten by &a.jim;,
January 2000.SynopsisinstallationThe following chapter will attempt to guide you through the
installation of FreeBSD on your system. It can be installed through a
variety of methods, including anonymous FTP (assuming you have
network connectivity via modem or local network), CDROM, floppy
disk, tape, an MS-DOS partition, or even NFS.No matter which method you choose, you will need to get started
by creating the installation disks as described
in the next section.
Booting into the FreeBSD installer, even if you are not planning on
installing FreeBSD right away, will provide important information
about compatibility with your hardware. This information may
dictate which installation options are even possible for you. It
can also provide clues early-on in the process to potential problems
you may come across later.installationnetworkanonymous FTPIf you plan to install FreeBSD via anonymous FTP, the only
things you will need are the installation floppies. The
installation program itself will handle anything else that is
required.For more information about obtaining FreeBSD, see the Obtaining FreeBSD section of the
Appendix.By now, you are probably wondering what exactly it is you need
to do. Continue on to the installation guide.Installation GuideThe following sections will guide you through preparing for and
actually installing FreeBSD. If you find something missing, please
let us know about it by sending email to the &a.doc;.Preparing for the InstallationThere are various things you should do in preparation for the
installation. The following describes what needs to be done prior to
each type of installation.The first thing to do is to make sure your hardware is
supported by FreeBSD. The list of supported hardware should
come in handy here. ;-) It would also be a good idea to make a
list of any special cards you have installed,
such as SCSI controllers, ethernet cards, sound cards, etc..
The list should include their IRQs and IO port addresses.Creating the Installation Floppiesinstallationboot floppiesinstallationCDROMYou may need to prepare some floppy disks. These disks will
be used to boot your computer in to the FreeBSD install process.
This step is not necessary if you are
- installing from CD-ROM, and your computer
- supports booting from the CD-ROM. If you do not meet these
+ installing from CDROM, and your computer
+ supports booting from the CDROM. If you do not meet these
requirements then you will need to create some floppies to boot
from.If you are not sure whether your computer can boot from the
- CD-ROM it does not hurt to try. Just insert the CD-ROM as
+ CDROM it does not hurt to try. Just insert the CDROM as
normal and restart your computer. You might need to adjust some
options in your BIOS so that your computer will try and boot
- from the CD-ROM drive before the hard disk.
+ from the CDROM drive before the hard disk.
- Even if you have the CD-ROM it might make sense for you to
+ Even if you have the CDROM it might make sense for you to
download the files. There have been occasions where bugs in the
FreeBSD installer have been discovered after the CDs have been
released. When this happens the copies of the images on the FTP
site will be fixed as soon as possible. Obviously, it is not
possible to update the CDs after they have been pressed.Acquire the boot floppy imagesThese are files with a .flp
- extension. If you have a CD-ROM release of FreeBSD then you
+ extension. If you have a CDROM release of FreeBSD then you
will find the files in the floppies
subdirectory. Alternatively, you can download the images from
the floppies directory of the FreeBSD FTP site or your local mirror.The names of the files you will need varies between
FreeBSD releases (sometimes) and the architecture you will be
installing on. The installation
boot image information on the FTP site provides
up-to-the-minute information about the specific files you will
need.Prepare the floppy disksYou 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.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 some other disks, and try
again.Write the image files to the floppy disks.The image files, such as kern.flp,
are not regular files you copy to the
disk. Instead, they are images of the complete contents of
the disk.This means that you can not use
commands like DOS' copy to write the
files. Instead, you must use specific tools to write the
images directly to the disk.DOSIf you are creating the floppies on a computer running DOS
then we provide a tool to do this called
fdimage.
- If you are using the floppies from the CD-ROM, and your
- CD-ROM is the E: drive then you would
+ 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. Adjust the command
line as necessary, depending on where you have placed the
.flp files. If you do not have the
- CD-ROM then fdimage can be downloaded from
+ 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/fd0On FreeBSD /dev/fd0 refers to the
first floppy disk (the A: drive).
/dev/rfd1 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.Before Installing from CDROMIf your CDROM is of an unsupported type, please skip ahead
to the MS-DOS Preparation
section.There is not a whole lot of preparation needed if you are
installing from one of BSDi's
FreeBSD CDROMs (other CDROM distributions may work as well,
though we cannot say for certain as we have no hand or say in
how they created). You can either boot into the CD installation
directly from DOS using the install.bat or
you can make floppies with the makeflp.bat
command.If the CD has El Torito boot support and your system
supports booting directly from the CDROM drive (many older
systems do NOT), simply insert the first
CD of the set into the drive and reboot your system. You
will be put into the installation menu directly from the CD.DOSIf you are installing from an MS-DOS partition and have
the proper drivers to access your CD, run the
install.bat script provided on the CDROM.
This will attempt to boot the FreeBSD installation directly
from DOS.You must do this from actual DOS (i.e., boot in DOS
mode) and not from a DOS window under Windows.For the easiest interface of all (from DOS), type
view. This will bring up a DOS menu utility
that leads you through all of the available options.UNIXIf you are creating the boot floppies from a UNIX machine,
see the Creating the Boot
Floppies section of this guide for examples.Once you have booted from DOS or floppy, you should then be
able to select CDROM as the media type during the install
process and load the entire distribution from CDROM. No other
types of installation media should be required.After your system is fully installed and you have rebooted
(from the hard disk), you can mount the CDROM at any time by
typing:&prompt.root; mount /cdromBefore removing the CD from the drive again, you must first
unmount it. This is done with the following command:&prompt.root; umount /cdromDo not just remove it from the drive!Before invoking the installation, be sure that the CDROM
is in the drive so that the install probe can find it. This
is also true if you wish the CDROM to be added to the default
system configuration automatically during the installation (whether
or not you actually use it as the installation media).installationnetworkFTPFinally, if you would like people to be able to FTP install
FreeBSD directly from the CDROM in your machine, you will find
it quite easy. After the machine is fully installed, you simply
need to add the following line to the password file (using the
vipw command):ftp:*:99:99::0:0:FTP:/cdrom:/nonexistentAnyone 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 you choose to enable anonymous FTP during the
installation of your system, the installation program will do
the above for you.Before installing from FloppiesinstallationfloppiesIf 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.44MB or 1.2MB 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
disklabel and newfs
commands to put a UFS filesystem on them instead, as the
following sequence of commands (for a 3.5" 1.44MB floppy)
illustrates:&prompt.root; fdformat -f 1440 fd0.1440
&prompt.root; disklabel -w -r fd0.1440 floppy3
&prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0Use fd0.1200 and
floppy5 for 5.25" 1.2MB 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 5 of them will fit on a conventional
1.44MB floppy. Go through all your floppies, packing as many
files as will fit on each one, until you have 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.Before Installing from MS-DOSinstallationfrom MS-DOSTo prepare for an installation from an MS-DOS partition,
copy the files from the distribution into a directory named,
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:\FreeBSDC:\>xcopy e:\bin c:\FreeBSD\bin\ /sC:\>xcopy e:\manpages c:\FreeBSD\manpages\ /sAssuming 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 bin distribution can be
found in the &rel.current;/bin 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.Before Installing from QIC/SCSI Tapeinstallationfrom
QIC/SCSI TapeInstalling 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, so
after getting all of the distribution files you are interested
in, simply tar them onto the tape like so:&prompt.root; cd /freebsd/distdir
&prompt.root; tar cvf /dev/rwt0 dist1 ... dist2When you go to do the installation, you should also make
sure that you leave enough room in some temporary directory
(which you will be allowed to choose) to accommodate the
full contents of the tape you have created.
Due to the non-random access nature of tapes, this method of
installation requires quite a bit of temporary storage. You
should expect to require as much temporary storage as you have
stuff written on tape.When 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 Networkinstallationnetworkserial
(SLIP or PPP)installationnetworkparallel (PLIP)installationnetworkEthernetThere are three types of network installations you can do.
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 50kbytes/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 Supported Hardware list. 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 (see below), 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 NFSinstallationnetworkNFSThe NFS installation is fairly straight-forward. Simply
copy the FreeBSD distribution files you want onto a server
somewhere and then point the NFS media selection at it.If this server supports only privileged port
(as is generally the default for Sun workstations), you will
need to set this option in the Options menu before
installation can proceed.If you have a poor quality ethernet card which suffers
from very slow transfer rates, you may also wish to toggle the
appropriate Options flag.In order for NFS installation to work, the server must
support subdir mounts, e.g., if your FreeBSD 3.4 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 . 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.Before Installing via FTPinstallationnetworkFTPFTP installation may be done from any FreeBSD mirror site
containing a reasonably up-to-date version of FreeBSD. A full
list of FTP mirrors located all over the world is provided
during the install process.If you are installing from an FTP site not listed in this
menu, or are having trouble getting your name server
configured properly, you can also specify a URL to use by
selecting the choice labeled Other in that menu.
You can also use the IP address of a machine you wish to
install from, so the following would work in the absence of a
name server:ftp://209.55.82.20/pub/FreeBSD/&rel.current;-RELEASEThere are three FTP installation modes you can choose from:
active or passive FTP or via a HTTP proxy.FTP ActiveThis 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 PassiveFTPPassive modeThis option instructs FreeBSD to use
Passive mode for all FTP operations.
This allows the user to pass through firewalls
that do not allow incoming connections on random port
addresses.FTP via a HTTP proxyFTPvia a HTTP
proxyThis option instructs FreeBSD 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.There is another type of FTP proxy other tha HTTP
proxies. This type is very uncommon, though. If you
are not absolutely certain, you can assume that you
have a HTTP proxy as described above.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.bar.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.bar.com:1234/pub/FreeBSD.Since /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.bar.com, you are able to install from
that machine (which will fetch the files
from ftp.FreeBSD.org as your
installation requests them.Check your BIOS drive numberingIf you have used features in your BIOS to renumber your disk
drives without re-cabling them then you should read first to avoid confusion.Installing FreeBSDOnce you have completed the pre-installation step relevant to
your situation, you are ready to install FreeBSD!Although you should not experience any difficulty, there is
always the chance that you may, no matter how slight it is. If this
is the case in your situation, then you may wish to go back and
re-read the relevant preparation section or sections. Perhaps you
will come across something you missed the first time. If you are
having hardware problems, or FreeBSD refuses to boot at all, read
the Hardware Guide for a
list of possible solutions.sysinstallThe FreeBSD boot floppies contain all of the online
documentation you should need to be able to navigate through an
installation. If it does not, please let us know what you found
to be the most confusing or most lacking. Send your comments to
the &a.doc;. It is the objective of the installation program
(sysinstall) to be self-documenting enough that painful
step-by-step guides are no longer necessary. It may
take us a little while to reach that objective, but nonetheless,
it is still our objective :-)Meanwhile, you may also find the following typical
installation sequence to be helpful:Boot the kern.flp floppy and when
asked, remove it and insert the
mfsroot.flp and hit return. After a
boot sequence which can take anywhere from 30 seconds to 3
minutes, depending on your hardware, you should be presented
with a menu of initial choices. If the
kern.flp floppy does not boot at all or
the boot hangs at some stage, read the Q&A section of the
Hardware Guide for
possible causes.Press F1. You should see some basic usage instructions on
the menu screen and general navigation. If you have not used
this menu system before then please read
this thoroughly.Select the Options item and set any special preferences
you may have.installationstandardinstallationexpressinstallationcustomSelect a Standard, Express, or Custom install, depending on
whether or not you would like the installation to help you
through a typical installation, give you a high degree of
control over each step, or simply whiz through it (using
reasonable defaults when possible) as fast as possible. If
you have never used FreeBSD before, the Standard installation
method is most recommended.The final configuration menu choice allows you to further
configure your FreeBSD installation by giving you menu-driven
access to various system defaults. Some items, like
networking, may be especially important if you did a CDROM,
tape, or floppy install and have not yet configured your
network interfaces (assuming you have any). Properly
configuring such interfaces here will allow FreeBSD to come up
on the network when you first reboot from the hard
disk.Supported HardwarehardwareFreeBSD currently runs on a wide variety of ISA, VLB, EISA, and
PCI bus based PCs, ranging from the 386SX to Pentium class machines
(though the 386SX is not recommended). Support for generic IDE or
ESDI drive configurations, various SCSI controllers, and network and
serial cards is also provided. FreeBSD also supports IBM's
microchannel (MCA) bus.In order to run FreeBSD, a recommended minimum of eight
megabytes of RAM is suggested. Sixteen megabytes is the preferred
amount of RAM as you may have some trouble with anything less than
sixteen depending on your hardware.What follows is a list of hardware currently known to work with
FreeBSD. There may be other hardware that works as well, but we
have simply not received any confirmation of it.Disk Controllersdisk controllersWD1003 (any generic MFM/RLL)WD1007 (any generic IDE/ESDI)IDEATAAdaptec 1535 ISA SCSI controllersAdaptec 154X series ISA SCSI controllersAdaptec 174X series EISA SCSI controllers in standard and
enhanced modeAdaptec 274X/284X/2920C/294X/2950/3940/3950
(Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllersAdaptec AIC-7850, AIC-7860, AIC-7880, AIC-789X on-board SCSI
controllersAdaptec 1510 series ISA SCSI controllers (not for bootable
devices)Adaptec 152X series ISA SCSI controllersAdaptec AIC-6260 and AIC-6360 based boards, which include
the AHA-152X and SoundBlaster SCSI cardsAdvanSys SCSI controllers (all models)BusLogic MultiMaster W Series Host Adapters
including BT-948, BT-958, BT-9580BusLogic MultiMaster C Series Host Adapters
including BT-946C, BT-956C, BT-956CD, BT-445C, BT-747C,
BT-757C, BT-757CD, BT-545C, BT-540CFBusLogic MultiMaster S Series Host Adapters
including BT-445S, BT-747S, BT-747D, BT-757S, BT-757D,
BT-545S, BT-542D, BT-742A, BT-542BBusLogic MultiMaster A Series Host Adapters
including BT-742A, BT-542BAMI FastDisk controllers that are true BusLogic
MultiMaster clones are also supported.BusLogic/Mylex Flashpoint adapters are NOT
yet supported.DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III,
SmartCACHE IV, and SmartRAID IV SCSI/RAID are supported. The
DPT SmartRAID/CACHE V is not yet supported. The DPT PM3754U2-16M
SCSI RAID Controller is also supported.Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES,
SMART, SMART-2/E, Smart-2/P, SMART-2SL, Integrated Array, and
Smart Arrays 3200, 3100ES, 221, 4200, 4200, 4250ES.SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820,
53C825a, 53C860, 53C875, 53C875j, 53C885, and 53C896 PCI SCSI
controllers including ASUS SC-200, Data Technology DTC3130
(all variants), Diamond FirePort (all), NCR cards (all),
SymBios cards (all), Tekram DC390W, 390U, and 390F, and Tyan
S1365QLogic 1020, 1040, 1040B, and 2100 SCSI and Fibre
Channel AdaptersDTC 3290 EISA SCSI controller in 1542 evaluation
modeWith all supported SCSI controllers, full support is provided
for SCSI-I and SCSI-II peripherals, including hard disks, optical
disks, tape drives (including DAT and 8mm Exabyte), medium
changers, processor target devices, and CDROM drives. WORM
devices that support CDROM commands are supported for read-only
access by the CDROM driver. WORM/CD-R/CD-RW writing support is
provided by cdrecord, which is in the ports tree.
- The following CD-ROM type systems are supported at this
+ The following CDROM type systems are supported at this
time:cd - SCSI interface (includes
ProAudio Spectrum and SoundBlaster SCSI)matcd - Matsushita/Panasonic
(Creative SoundBlaster) proprietary interface (562/563
models)scd - Sony proprietary interface
(all models)acd - ATAPI IDE interfaceThe following drivers were supported under the old SCSI
subsystem, but are NOT YET supported under the new CAM SCSI
subsystem:NCR5380/NCR53400 (ProAudio Spectrum) SCSI
controllerUltraStor 14F, 24F, and 34F SCSI controllersSeagate ST01/02 SCSI controllersFuture Domain 8XX/950 series SCSI controllersWD7000 SCSI controllerThere is work-in-progress to port the UltraStor driver
to the new CAM framework, but no estimates on when or if it
will be completed.Unmaintained drivers, which might or might not work for your
hardware:Floppy tape interface (Colorado/Mountain/Insight)
- mcd - Mitsumi proprietary CD-ROM
+ mcd - Mitsumi proprietary CDROM
interface (all models)Network Cardsnetwork cardsAdaptec Duralink PCI fast ethernet adapters based on the
Adaptec AIC-6195 fast ethernet controller chip, including the
following:ANA-62011 64-bit single port 10/100baseTX
adapterANA-62022 64-bit dual port 10/100baseTX adapterANA-62044 64-bit quad port 10/100baseTX adapterANA-69011 32-bit single port 10/100baseTX
adapterANA-62020 64-bit single port 100baseFX adapterAllied-Telesyn AT1700 and RE2000 cardsAlteon Networks PCI gigabit ethernet NICs based on the
Tigon 1 and Tigon 2 chipsets including the Alteon AceNIC
(Tigon 1 and 2), 3Com 3c985-SX (Tigon 1 and 2), Netgear GA620
(Tigon 2), Silicon Graphics Gigabit Ethernet, DEC/Compaq
EtherWORKS 1000, NEC Gigabit EthernetAMD PCnet/PCI (79c970 and 53c974 or 79c974)RealTek 8129/8139 fast ethernet NICs including the
following:Allied-Telesyn AT2550Allied-Telesyn AT2500TXGenius GF100TXR (RTL8139)NDC Communications NE100TX-EOvisLink LEF-8129TXOvisLink LEF-8139TXNetronix Inc. EA-1210 NetEther 10/100KTX-9130TX 10/100 Fast EthernetAccton Cheetah EN1207D (MPX 5030/5038;
RealTek 8139 clone)SMC EZ Card 10/100 PCI 1211-TXLite-On 98713, 98713A, 98715, and 98725 fast ethernet
NICs, including the LinkSys EtherFast LNE100TX, NetGear
FA310-TX Rev. D1, Matrox FastNIC 10/100, Kingston
KNE110TXMacronix 98713, 98713A, 98715, 98715A, and 98725 fast
ethernet NICs including the NDC Communications SFA100A
(98713A), CNet Pro120A (98713 or 98713A), CNet Pro120B
(98715), SVEC PN102TX (98713)Macronix/Lite-On PNIC II LC82C115 fast ethernet NICs
including the LinkSys EtherFast LNE100TX version 2Winbond W89C840F fast ethernet NICs including the
Trendware TE100-PCIEVIA Technologies VT3043 Rhine I and
VT86C100A Rhine II fast ethernet NICs including
the Hawking Technologies PN102TX and D-Link DFE-530TXSilicon Integrated Systems SiS 900 and SiS 7016 PCI fast
ethernet NICsSundance Technologies ST201 PCI fast ethernet NICs
including the D-Link DFE-550TXSysKonnect SK-984x PCI gigabit ethernet cards including
the SK-9841 1000baseLX (single mode fiber, single port),
the SK-9842 1000baseSX (multimode fiber, single port), the
SK-9843 1000baseLX (single mode fiber, dual port), and the
SK-9844 1000baseSX (multimode fiber, dual port).Texas Instruments ThunderLAN PCI NICs, including the
Compaq Netelligent 10, 10/100, 10/100 Proliant, 10/100
Dual-Port, 10/100 TX Embedded UTP, 10 T PCI UTP/Coax, and
10/100 TX UTP, the Compaq NetFlex 3P, 3P Integrated, and 3P
w/BNC, the Olicom OC-2135/2138, OC-2325, OC-2326 10/100 TX
UTP, and the Racore 8165 10/100baseTX and 8148
10baseT/100baseTX/100baseFX multi-personality cardsADMtek AL981-based and AN985-based PCI fast ethernet
NICsASIX Electronics AX88140A PCI NICs including the Alfa Inc.
GFC2204 and CNet Pro110BDEC EtherWORKS III NICs (DE203, DE204, and DE205)DEC EtherWORKS II NICs (DE200, DE201, DE202, and
DE422)DEC DC21040, DC21041, or DC21140 based NICs (SMC
Etherpower 8432T, DE245, etc.)DEC FDDI (DEFPA/DEFEA) NICsEfficient ENI-155p ATM PCIFORE PCA-200E ATM PCIFujitsu MB86960A/MB86965AHP PC Lan+ cards (model numbers: 27247B and 27252A)Intel EtherExpress ISA (not recommended due to driver
instability)Intel EtherExpress Pro/10Intel EtherExpress Pro/100B PCI Fast EthernetIsolan AT 4141-0 (16 bit)Isolink 4110 (8 bit)Novell NE1000, NE2000, and NE2100 Ethernet
interfacesPCI network cards emulating the NE2000, including the
RealTek 8029, NetVin 5000, Winbond W89C940, Surecom NE-34, VIA
VT86C9263Com 3C501, 3C503 Etherlink II, 3C505 Etherlink/+, 3C507
Etherlink 16/TP, 3C509, 3C579, 3C589 (PCMCIA),
3C590/592/595/900/905/905B/905C PCI and EISA (Fast) Etherlink
III / (Fast) Etherlink XL, 3C980/3C980B Fast Etherlink XL
server adapter, 3CSOHO100-TX OfficeConnect adapterToshiba ethernet cardsPCMCIA ethernet cards from IBM and National Semiconductor
are also supportedUSB PeripheralsUSB PeripheralsA wide range of USB peripherals are supported. Owing to the
generic nature of most USB devices, with some exceptions any
device of a given class will be supported even if not explicitly
listed here.USB keyboardsUSB miceUSB printers and USB to parallel printer conversion
cablesUSB hubsMotherboard chipsets:ALi Aladdin-VIntel 82371SB (PIIX3) and 82371AB and EB (PIIX4)
chipsetsNEC uPD 9210 Host ControllerVIA 83C572 USB Host Controllerand any other UHCI or OHCI compliant motherboard chipset
(no exceptions known).PCI plug-in USB host controllersADS Electronics PCI plug-in card (2 ports)Entrega PCI plug-in card (4 ports)Specific USB devices reported to be working:Agiler Mouse 29UOAndromeda hubApple iMac mouse and keyboardATen parallel printer adapterBelkin F4U002 parallel printer adapter and Belkin
mouseBTC BTC7935 keyboard with mouse portCherry G81-3504Chic mouseCypress mouseEntrega USB-to-parallel printer adapterGenius Niche mouseIomega USB Zip 100 MBKensington Mouse-in-a-BoxLogitech M2452 keyboardLogitech wheel mouse (3 buttons)Logitech PS/2 / USB mouse (3 buttons)MacAlly mouse (3 buttons)MacAlly self-powered hub (4 ports)Microsoft Intellimouse (3 buttons)Microsoft keyboardNEC hubTrust Ami Mouse (3 buttons)ISDN (European DSS1 [Q.921/Q.931] protocol)ISDNAsuscom I-IN100-ST-DV (experimental, may work)Asuscom ISDNlink 128KAVM A1AVM Fritz!Card classicAVM Fritz!Card PCIAVM Fritz!Card PCMCIA (currently FreeBSD 3.x only)AVM Fritz!Card PnP (currently FreeBSD 3.x only)Creatix ISDN-S0/8Creatix ISDN-S0/16Creatix ISDN-S0 PnPDr.Neuhaus Niccy 1008Dr.Neuhaus Niccy 1016Dr.Neuhaus Niccy GO@ (ISA PnP)Dynalink IS64PH (no longer maintained)ELSA 1000pro ISAELSA 1000pro PCIELSA PCC-16ITK ix1 micro (currently FreeBSD 3.x only)ITK ix1 micro V.3 (currently FreeBSD 3.x only)Sagem Cybermod (ISA PnP, may work)Sedlbauer Win SpeedSiemens I-Surf 2.0Stollman Tina-pp (under development)Teles S0/8Teles S0/16Teles S0/16.3 (the c Versions - like 16.3c
- are unsupported!)Teles S0 PnP (experimental, may work)3Com/USRobotics Sportster ISDN TA intern (non-PnP
version)Sound DevicesThe following soundcards or codecs are supported (devices marked
'experimental' are only supported in FreeBSD-CURRENT and might
work only unstably):sound cards16550 UART (Midi) (experimental, needs a trick in the hints
file)Advance Asound 100, 110 and Logic ALS120Aureal Vortex1/Vortex2 and Vortex Advantage based soundcards
by a
third
party driverCreative Labs SB16, SB32, SB AWE64 (including Gold),
Vibra16, SB PCI (experimental), SB Live! (experimental)
and most SoundBlaster compatible cardsCreative Labs SB Midi Port (experimental), SB OPL3
Synthesizer (experimental)Crystal Semiconductor CS461x/462x Audio Accelerator,
the support for the CS461x Midi port is experimentalCrystal Semiconductor CS428x Audio ControllerCS4237, CS4236, CS4232, CS4231 (ISA)ENSONIQ AudioPCI ES1370/1371ESS ES1868, ES1869, ES1879, ES1888Gravis UltraSound PnP, MAXNeoMagic 256AV/ZX (PCI)OPTi931 (ISA)OSS-compatible sequencer (Midi) (experimental)Trident 4DWave DX/NX (PCI)Yahama OPL-SAx (ISA)Miscellaneous DevicesAST 4 port serial card using shared IRQARNET 8 port serial card using shared IRQARNET (now Digiboard) Sync 570/i high-speed serialBoca BB1004 4-Port serial card (Modems NOT
supported)Boca IOAT66 6-Port serial card (Modems supported)Boca BB1008 8-Port serial card (Modems NOT
supported)Boca BB2016 16-Port serial card (Modems supported)Cyclades Cyclom-y Serial BoardMoxa SmartIO CI-104J 4-Port serial cardSTB 4 port card using shared IRQSDL Communications RISCom/8 Serial BoardSDL Communications RISCom/N2 and N2pci high-speed sync
serial boardsSpecialix SI/XIO/SX multiport serial cards, with both the
older SIHOST2.x and the new enhanced
(transputer based, aka JET) host cards; ISA, EISA and PCI are
supportedStallion multiport serial boards: EasyIO, EasyConnection
8/32 & 8/64, ONboard 4/16 and BrumbyAdlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum,
Gravis UltraSound, and Roland MPU-401 sound cardsConnectix QuickCamMatrox Meteor Video frame grabberCreative Labs Video Spigot frame grabberCortex1 frame grabberVarious frame grabbers based on the Brooktree Bt848
and Bt878 chipHP4020, HP6020, Philips CDD2000/CDD2660 and Plasmon CD-R
drivesBus micePS/2 miceStandard PC JoystickX-10 power controllersGPIB and Transputer drivesGenius and Mustek hand scannersFloppy tape drives (some rather old models only, driver is
rather stale)Lucent Technologies WaveLAN/IEEE 802.11 PCMCIA and ISA
standard speed (2Mbps) and turbo speed (6Mbps) wireless
network adapters and workalikes (NCR WaveLAN/IEEE 802.11,
Cabletron RoamAbout 802.11 DS)The ISA versions of these adapters are actually PCMCIA
cards combined with an ISA to PCMCIA bridge card, so both
kinds of devices work with the same driver.TroubleshootinginstallationtroubleshootingThe 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 supported
hardware list 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.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.Change 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.MS-DOS User's Questions and AnswersDOSMany users wish to install FreeBSD on PCs inhabited by MS-DOS.
Here are some commonly asked questions about installing FreeBSD on
such systems.Help, I have no space! Do I need to delete everything
first?If your machine is already running MS-DOS and has little
or no free space available for the FreeBSD installation, all
hope is not lost! You may find the FIPS utility, provided
in the tools directory on the FreeBSD
CDROM or various FreeBSD FTP sites to be quite
useful.FIPSFIPS allows you to split an existing MS-DOS partition
into two pieces, preserving the original partition and
allowing you to install onto the second free piece. You
first defragment your MS-DOS partition using the Windows
DEFRAG utility (go into Explorer, right-click on the
hard drive, and choose to defrag your
hard drive), or Norton Disk Tools. You then must run FIPS. It
will prompt you for the rest of the information it needs.
Afterwards, you can reboot and install FreeBSD on the new
free slice. See the Distributions menu
for an estimate of how much free space you will need for the
kind of installation you want.Partition MagicThere is also a very useful
product from PowerQuest
called Partition Magic. This
application has far more functionality than FIPS, and is
highly recommended if you plan to often add/remove
operating systems (like me). However, it does cost
money, and if you plan to install FreeBSD once and then
leave it there, FIPS will probably be fine for you.Can I use compressed MS-DOS filesystems from
FreeBSD?No. If you are using a utility such as Stacker(tm) or
DoubleSpace(tm), FreeBSD will only be able to use whatever
portion of the filesystem you leave uncompressed. The rest
of the filesystem will show up as one large file (the
stacked/double spaced file!). Do not remove that
file or you will probably regret it
greatly!It is probably better to create another uncompressed
primary MS-DOS partition and use this for communications
between MS-DOS and FreeBSD.Can I mount my extended MS-DOS partition?partitionsslicesYes. DOS extended partitions are mapped in at the end
of the other slices in FreeBSD, e.g., your
D: drive might be
/dev/da0s5, your
E: drive,
/dev/da0s6, and so on. This example
assumes, of course, that your extended partition is on SCSI
drive 0. For IDE drives, substitute ad
for da appropriately if installing
4.0-RELEASE or later, and substitute
wd for da if you
are installing a version of FreeBSD prior to 4.0. You otherwise
mount extended partitions exactly like you would any other
DOS drive, for example:&prompt.root; mount -t msdos /dev/ad0s5 /dos_dAdvanced Installation GuideWritten by &a.logo;, May 2001.This section describes how to install FreeBSD in exceptional
cases.Installing FreeBSD on a system without a monitor or
keyboardinstallationheadless
(serial console)serial consoleThis type of installation is called a "headless install",
because the machine that you are trying to install FreeBSD on
either doesnt have a monitor attached to it, or doesnt 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 these steps:Fetch the right boot floppy imagesFirst you will need to get the right disk images so
that you can boot into the install program. The secret
with using a serial console is that you tell the boot
loader to send I/O through a serial port instead of
displaying console output to the VGA device and trying to
read input from a local keyboard. Enough of that now,
let's get back to getting these disk images.You will need to get kern.flp and
mfsroot.flp from the
floppies directory.Write the image files to the floppy disks.The image files, such as
kern.flp, are
not regular files that you copy to
the disk. Instead, they are images of the complete
contents of the disk.This means that you can not use
commands like DOS' copy to write the
files. Instead, you must use specific tools to write the
images directly to the disk.fdimageIf you are creating the floppies on a computer running
DOS then we provide a tool to do this called
fdimage.
- If you are using the floppies from the CD-ROM, and
- your CD-ROM is the E: drive then
+ 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. Adjust the
command line as necessary, depending on where you have
placed the .flp files. If you do not
- have the CD-ROM then fdimage can be
+ 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/fd0On FreeBSD /dev/fd0 refers to
the first floppy disk (the A:
drive). /dev/rfd1 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.Enabling the boot floppies to boot into a serial
consoleDo not try to mount the floppy if it is write-protectedmountIf 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 /mntNow that you have the floppy mounted, you must
change into the floppy directory&prompt.root; cd /mntHere 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.configNow that you have your floppy configured correctly,
you must unmount the floppy using the &man.umount.8;
command&prompt.root; cd /
&prompt.root; umount /mntNow you can remove the floppy from the floppy
driveConnecting your null modem cablenull modem cableYou 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 installIt's now time to go ahead and start the install. Put
the kern.flp floppy in the floppy
drive of the machine you're doing the headless install
on, and power on the machine.Connecting to your headless machinecuNow you have to connect to that machine with
&man.cu.1;:&prompt.root; cu -l /dev/cuaa0That's it! You should be able to control the headless
machine through your cu session now. 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. Just
select the FreeBSD color console and proceed with your
install!
diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index 0723bd83b7..40b65ee30b 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -1,2247 +1,2247 @@
Linux Binary CompatibilityRestructured and parts updated by &a.jim;, 22 March
2000. Originally contributed by &a.handy; and
&a.rich;SynopsisLinux binary compatibilitybinary compatibilityLinuxThe following chapter will cover FreeBSD's Linux binary
compatibility features, how to install it, and how it works.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 Star Office, the Linux version of
Netscape, Adobe Acrobat, RealPlayer 5 and 7, 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.Linux/proc filesystemThere 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 the Linux
/proc filesystem (which is different from
FreeBSD's /proc filesystem), or i386-specific
calls, such as enabling virtual 8086 mode.For information on installing the Linux binary compatibility
mode, see the next section.InstallationWith the advent of 3.0-RELEASE, it is no longer necessary to
specify options LINUX or
options COMPAT_LINUX in your kernel
configuration.KLD (kernel loadable object)The Linux binary compatibility is now done via a KLD object
(Kernel LoaDable object), so it can be installed
on-the-fly without having to reboot. You will,
however, need to have the following in
/etc/rc.conf:linux_enable=YESThis, in turn, triggers the following action in
/etc/rc.i386:# Start the Linux binary compatibility if requested.
#
case ${linux_enable} in
[Yy][Ee][Ss])
echo -n ' linux'; linux > /dev/null 2>&1
;;
esacIf you wish to verify that the KLD is loaded,
kldstat will do that:&prompt.user; kldstat
Id Refs Address Size Name
1 2 0xc0100000 16bdb8 kernel
7 1 0xc24db000 d000 linux.kokernel optionsLINUXIf for some reason you do not want to or cannot load the KLD,
then you may statically link the binary compatibility in the kernel
by adding options LINUX to your kernel
configuration file. Then install your new kernel as described in
the kernel configuration section
of this handbook.Installing Linux Runtime LibrariesLinuxinstalling Linux librariesThis can be done one of two ways, either by using the
linux_base port, or
by installing them manually.Installing using the linux_base portports collectionThis 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
&prompt.root; make install distcleanYou 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.Installing libraries manuallyIf 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 librariesshared librariesWhat 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.29symbolic linksYou 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.27and 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.29If 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 binariesLinuxELF binariesELF 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
AbortTo 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-binaryGNU toolchainThe GNU toolchain now places the appropriate branding
information into ELF binaries automatically, so you this step
should become increasingly more rare in the future.Configuring the host name resolverIf DNS does not work or you get this message:resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keywordYou will need to configure a
/compat/linux/etc/host.conf file
containing:order hosts, bind
multi onThe 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.Installing MathematicaUpdated for Mathematica version 4.x by &a.murray
and merged with work by Bojan Bistrovic
bojanb@physics.odu.edu.applicationsMathematicaThis document describes the process of installing the Linux
version of Mathematica 4.X onto a FreeBSD system.The Linux version of Mathematica runs perfectly under FreeBSD
however the binaries shipped by Wolfram need to be branded so that
FreeBSD knows to use the Linux ABI to execute them.The Linux version of Mathematica or Mathematica for Students can
be ordered directly from Wolfram at http://www.wolfram.com/.Branding the Linux binariesThe Linux binaries are located in the Unix
directory of the Mathematica CDROM distributed by Wolfram. You
need to copy this directory tree to your local hard drive so that
you can brand the Linux binaries with &man.brandelf.1; before
running the installer:&prompt.root; mount /cdrom
&prompt.root; cp -rp /cdrom/Unix/ /localdir/
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm
&prompt.root; cd /localdir/Installers/Linux/
&prompt.root; ./MathInstallerAlternatively, you can simply set the default ELF brand
to Linux for all unbranded binaries with the command:&prompt.root; sysctl -w kern.fallback_elf_brand=3This will make FreeBSD assume that unbranded ELF binaries
use the Linux ABI and so you should be able to run the
installer straight from the CDROM.Obtaining your Mathematica PasswordBefore you can run Mathematica you will have to obtain a
password from Wolfram that corresponds to your machine
ID.EthernetMAC addressOnce you have installed the Linux compatibility runtime
libraries and unpacked Mathematica you can obtain the
machine ID by running the program
mathinfo in the Install directory. This
machine ID is based solely on the MAC address of your first
ethernet card.&prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux
&prompt.root; mathinfo
disco.example.com 7115-70839-20412When you register with Wolfram, either by email, phone or fax,
you will give them the machine ID and they will
respond with a corresponding password consisting of groups of
numbers. You can then enter this information when you attempt to
run Mathematica for the first time exactly as you would for any
other Mathematica platform.Running the Mathematica front end over a networkMathematica 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 mkfontdir 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; mkfontdirNow 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 rehashIf you are using the XFree86 server, you can have these font
directories loaded automatically by adding them to your
XF86Config file.fontsIf 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.Installing OracleContributed by Marcel Moolenaar
marcel@cup.hp.comapplicationsOraclePrefaceThis document describes the process of installing Oracle 8.0.5 and
Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD
machineInstalling the Linux environmentMake sure you have both linux_base and
linux_devtools from the ports collection
installed. These ports are added to the collection after the release
of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for
that matter, update your ports collection. You may want to consider
updating your FreeBSD version too. If you run into difficulties with
linux_base-6.1 or
linux_devtools-6.1 you may have to use version
5.2 of these packages.If you want to run the intelligent agent, you'll
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 is :&prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm packageInstallation of the package should not generate any errors.Creating the Oracle environmentBefore 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 Tuningkernel tuningAs described in the Oracle installation guide, you need to set
the maximum size of shared memory. Don't 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=61Set these options to suit your intended use of Oracle.Also, make sure you have the following options in your kernel
config-file:options SYSVSHM #SysV shared memory
options SYSVSEM #SysV semaphores
options SYSVMSG #SysV interprocess communicationOracle accountCreate 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.EnvironmentBesides the normal Oracle variables, such as
ORACLE_HOME and ORACLE_SID you must
set the following environment variables:VariableValueLD_LIBRARY_PATH$ORACLE_HOME/libCLASSPATH$ORACLE_HOME/jdbc/lib/classes111.zipPATH/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/binIt 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:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:$ORACLE_HOME/bin
export PATHInstalling OracleDue to a slight inconsistency in the Linux emulator, you need to
create a directory named .oracle in
/var/tmp before you start the installer. Either
make it world writable or let it be owner 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 installDon't forget to run root.sh again!Patching root.shWhen installing Oracle, some actions, which need to be performed
as root, are recorded in a shell script called
root.sh. root.sh 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 scriptWhen you don't 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 genclntshThe 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.lstRunning OracleWhen you have followed the instructions, you should be able to run
Oracle as if it was run on Linux itself.Installing SAP R/3 (4.6B - IDES)Contributed by Holger Kippholger.kipp@alogis.comConverted to SGML by &a.logo;applicationsSAP R/3PrefaceThis document describes a possible way of installing a SAP
R/3 4.6B IDES-System with Oracle 8.0.5 for Linux onto a
FreeBSD 4.3 machine, including the installation of FreeBSD 4.3
stable and Oracle 8.0.5.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 R/3 installation guides.Please see the documentation that comes with the SAP R/3
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
+ The following CDROMs have been used for
SAP-installation:NameNumberDescriptionKERNEL51009113SAP Kernel Oracle /
Installation / AIX, Linux, SolarisRDBMS51007558Oracle / RDBMS 8.0.5.X /
LinuxEXPORT151010208IDES / DB-Export / Disc
1 of 6EXPORT251010209IDES / DB-Export / Disc
2 of 6EXPORT351010210IDES / DB-Export /
Disc3 of 6EXPORT451010211IDES / DB-Export /
Disc4 of 6EXPORT551010212IDES / DB-Export /
Disc5 of 6EXPORT651010213IDES / DB-Export /
Disc6 of 6Additionally, I 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
of course FreeBSD 4.3 stable (it was only a few days past 4.3
RELEASE).SAP-NotesThe following notes should be read before installing
SAP R/3 or proved to be useful
during installation:NumberTitle0171356SAP Software auf Linux: grundlegenden
Anmerkungen0201147INST: 4.6C R/3 Inst. on UNIX -
Oracle0373203Update / Migration Oracle 8.0.5 -->
8.0.6/8.1.6 LINUX0072984Release of Digital UNIX 4.0B for
Oracle0130581R3SETUP step DIPGNTAB terminates0144978Your system has not been installed
correctly0162266Questions and tips for R3SETUP on Windows
NT / W2KHardware-RequirementsThe following equipment is sufficient for a
SAP R/3 System (4.6B):Component4.6B4.6CProcessor2 x 800MHz Pentium III2 x 800MHz Pentium IIIMemory1GB ECC2GB ECCHard Disc Space50-60GB (IDES)50-60GB (IDES)For use in production, Xeon-Processors with large cache,
high-speed disc access (SCSI, RAID hardware controller), USV
and ECC-RAM is recommended. The large amount of Hard disc
space is due to the preconfigured IDES System, which creates
27 GB of database files during installation. Usually after
installation it is then necessary to extend some
tablespaces.I used a dual processor board with 2 800MHz Pentium III
processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing
- a 40/80 GB DLT tape drive and CD-ROM), Mylex AcelleRAID (2
+ a 40/80 GB DLT tape drive and CDROM), Mylex AcelleRAID (2
channels, firmware 6.00-1-00 with 32MB RAM). To the Mylex
Raid-controller are attached two 17GB hard discs (mirrored)
and four 36GB hard discs (RAID level 5).Installation of FreeBSD 4.3 stableFirst I installed FreeBSD 4.3 stable. I did the
default-installation via ftp.Installation via FTPGet the diskimages
kern.flp and mfsroot.flp and put them on floppy disks (I got
mine from ftp7.de.freebsd.org. Please choose the appropriate
mirror).&prompt.root; dd if=kern.flp of=/dev/fd0
&prompt.root; dd if=mfsroot.flp of=/dev/fd0Don't forget to use different disks for the two images
:-), then boot from the floppy with the kern.flp-image on it
and follow instructions. I used the following disk
layout:FilesystemSize (1k-blocks)Size (GB)Mounted on/dev/da0s1a1.016.3031//dev/da0s1b6<swap>/dev/da0s1e2.032.6232/var/dev/da0s1f8.205.3398/usr/dev/da1s1e45.734.36145/compat/linux/oracle/dev/da1s1f2.032.6232/compat/linux/sapmnt/dev/da1s1g2.032.6232/compat/linux/usr/sapI had to configure and initialise the two logical drives
with the Mylex software beforehand. It is located on the
board itself and can be started during the boot phase of the
pc. Please note that this disk layout differs slightly from
the SAP recommendations, as SAP suggests mounting the
oracle-subdirectories (and some others) separately - I
decided to just create them as real subdirectories for
simplicity.Get the latest stable-sourcesFor FreeBSD 4.3 stable onwards, it is quite easy to get
the latest stable sources. With the older versions of
FreeBSD, I had my own script located in /etc/cvsup. Setting
up cvsup for FreeBSD 4.3 is quite easy. As user
root do the following:&prompt.root; cp /etc/defaults/make.conf /etc/make.conf
&prompt.root; vi /etc/make.confThe file /etc/make.conf requires the
following entries to be active:SUP_UPDATE= yes
SUP= /usr/local/bin/cvsup
SUPFLAGS= -g -L 2
SUPHOST= cvsup8.FreeBSD.org
SUPFILE= /usr/share/examples/cvsup/stable-supfile
PORTSSUPFILE= /usr/share/examples/cvsup/ports-supfile
DOCSUPFILE= /usr/share/examples/cvsup/doc-supfileChange the SUPHOST-value
appropriately. The supfiles in
/usr/share/examples/cvsup should be
fine. If you don't want to load all the docfiles, leave the
corresponding DOCSUPFILE-entry
inactive. Starting cvsup to get the latest stable-sources
is then very easy:&prompt.root; cd /usr/src
&prompt.root; make updateMake world and a new kernelThe first thing to do is to install the sources.
As user root, do the following:&prompt.root; cd /usr/src
&prompt.root; make worldIf this goes through, one can then continue creating and
configuring the new kernel. Usually this is where to
customize the kernel configuration file. As the computer is
named troubadix, the natural name for the config file also
is troubadix:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; cp GENERIC TROUBADIX
&prompt.root; vi TROUBADIXAt this stage one can define the drivers to use and not
to use, etc. See the appropriate documentation or have a
look at file LINT for some additional
explanations.One can then also include the parameters as described
below Creating the new kernel then requires:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; config TROUBADIX
&prompt.root; cd /usr/src/sys/compile/TROUBADIX
&prompt.root; make depend
&prompt.root; make
&prompt.root; make installAfter make install finished
successfully, one should reboot the computer to have the new
kernel available.Installing the Linux environmentI had some trouble downloading the required RPM-files (for
4.3 stable, 2nd May 2001), so you might try one of the
following locations (if all the others fail and the following
aren't out of date):ftp7.de.freebsd.org/pub/FreeBSD/distfiles/rpmftp.redhat.com/pub/redhat/linux/6.1/en/os/i386/RedHat/RPMSInstalling Linux base-systemFirst the linux base-system needs to be installed (as root):
&prompt.root; cd /usr/ports/emulators/linux_base
&prompt.root; make packageInstalling Linux developmentNext, the linux development is needed:&prompt.root; cd /usr/ports/devel/linux_devtools
&prompt.root; make packageInstalling necessary RPMsRPMsTo start the R3SETUP-Program, pam support is needed. As
this also requires some other packages, I ended up
installing several packages. After that, pam still
complained about a missing package, so I forced the
installation and it worked. I wonder if the other packages
are really needed or if it would have been sufficient to
install the pam-package.Anyway, here is the list of packages I installed:cracklib-2.7-5.i386.rpmcracklib-dicts-2.7-5.i386.rpmpwdb-0.60-1.i386.rpmpam-0.68-7.i386.rpmI installed these packages with the following
command:&prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <package_name>except for the pam package, which I forced with&prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm pam-0.68-7.i386.rpmFor Oracle to run the
intelligent agent, I also had to install the following
RedHat TCL package (as is stated in the FreeBSD Handbook):
tcl-8.0.5-30.i386.rpm (otherwise the
relinking during Oracle install
won't work). There are some other issues regarding
relinking of Oracle, but that is
a Oracle-Linux issue, not FreeBSD specific as far as I
understand it.Creating the SAP/R3 environmentCreating the necessary filesystems and mountpointsFor a simple installation, it is sufficient to create the
following filesystems:mountpointsize in GB/compat/linux/oracle45 GB/compat/linux/sapmnt2 GB/compat/linux/usr/sap2 GBI also created some links, so FreeBSD will also find the
correct path:&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/sapCreating users and directoriesSAP R/3 needs two users and three groups. The usernames
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 I used IDS. We have
therefore the following groups (group ids might differ,
these are just the values I used with my installation):group idgroup namedescription100dbaData Base Administrator101sapsysSAP System102operData Base OperatorFor 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 idusernamegeneric namegroupadditional groupsdescription1000idsadm<sid>admsapsysoperSAP Administrator1002oraidsora<sid>dbaoperDB AdministratorAdding the users with adduser
requires the following (please note shell and home
directory) entries for SAP-Administrator:Name: idsadm <sid>adm
Password: ******
Fullname: SAP IDES Administrator
Uid: 1000
Gid: 101 (sapsys)
Class:
Groups: sapsys dba
HOME: /home/idsadm /home/<sid>adm
Shell: /bin/shand for Database-Administrator:Name: oraids ora<sid>
Password: ******
Fullname: Oracle IDES Administrator
Uid: 1002
Gid: 100 (dba)
Class:
Groups: dba
HOME: /oracle/IDS /oracle/<sid>
Shell: /bin/shThis should also include group
oper in case you are using both
groups dba and
oper.Creating directoriesThese directories are usually created as separate
filesystems. This depends entirely on your requirements. I
choose to create them as simple directories, as they are all
located on the same RAID 5 anyway:First we'll set owners and right 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 idsadm:sapsys /compat/linux/usr/sap
&prompt.root; chmow 775 /compat/linux/usr/sapSecond we'll create directories as user ora<sid>. These
will all be subdirectories of /oracle/IDS:&prompt.root; su - oraids
&prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB
&prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6
&prompt.root; mkdir saparch sapreorg
&prompt.root; exitIn the third step we create directories as user idsadm
(<sid>adm):&prompt.root; su - idsadm
&prompt.root; cd /usr/sap
&prompt.root; mkdir IDS
&prompt.root; mkdir trans
&prompt.root; exitEntries in /etc/servicesSAP R/3 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'll do no harm adding all
entries from 00 to
99 for dp,
gw, sp and
ms);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
sapmsIDS 3600/tcp # SAP Message Server. 3600 + Instance-NumberNecessary localeslocaleSAP requires at least two locales that aren't 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 I wouldn't 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-1If they are not present, there will be some problems
during the installation. If these are then subsequently
ignored (eg 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 Tuningkernel tuningSAP R/3 Systems need a lot of resources. I therefore
added the following parameters to my kernel config-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 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 indentifiers
options SEMUME=100 #number of UNDO keysThe 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.
Installing SAP R/3
- Preparing SAP CD-ROMs
+ Preparing SAP CDROMs
- There are lots of CD-ROMs to mount and unmount during
- installation. Assuming you have enough CD-ROM-drives, you
- can just mount them all. I decided to copy the CD-ROM
+ There are lots of CDROMs to mount and unmount during
+ installation. Assuming you have enough CDROM-drives, you
+ can just mount them all. I decided to copy the CDROM
contents to corresponding directories:/oracle/IDS/sapreorg/<cd-name>where <cd-name> was one of KERNEL, RDBMS, EXPORT1,
EXPORT2, EXPORT3, EXPORT4, EXPORT5 and EXPORT6. All the
filenames should be in capital letters, otherwise use the -g
option for mounting. So use the following commands:&prompt.root; mount_cd9660 -g /dev/cd0a /mnt
&prompt.root; cp -R /mnt/* /oracle/IDS/sapreorg/<cd-name>
&prompt.root; umount /mntRunning the install-scriptFirst we need to prepare an install-directory:&prompt.root; cd /oracle/IDS/sapreorg
&prompt.root; mkdir install
&prompt.root; cd installThen the install-script is started, which will copy nearly
all the relevant files into the install-directory:/oracle/IDS/sapreorg/KERNEL/UNIX/INSTTOOL.SHAs this is an IDES-Installation with a fully customized
SAP R/3 Demo-System, we have six instead of just three
EXPORT-CDs. At this point the installation template
CENTRDB.R3S is for installing a standard central instance
(R/3 and Database), not an IDES central instance, so copy
the corresponding CENTRDB.R3S from the EXPORT1 directory,
otherwise R3SETUP will only ask for three EXPORT-CDs.Start R3SETUPMake sure LD_LIBRARY_PATH is set correctly:&prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/libStart R3SETUP as user root from installation
directory:&prompt.root; cd /oracle/IDS/sapreorg/install
&prompt.root; ./R3SETUP -f CENTRDB.R3SThe script then asks some questions (defaults in brackets,
followed by actual input):QuestionDefaultInputEnter SAP System ID[C11]IDS<ret>Enter SAP Instance Number[00]<ret>Enter SAPMOUNT Directory[/sapmnt]<ret>Enter name of SAP central host[troubadix.domain.de]<ret>Enter name of SAP db host[troubadix]<ret>Select character set[1] (WE8DEC)<ret>Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.61<ret>Extract Oracle Client archive[1] (Yes, extract)<ret>Enter path to KERNEL CD[/sapcd]/oracle/IDS/sapreorg/KERNELEnter path to RDBMS CD[/sapcd]/oracle/IDS/sapreorg/RDBMSEnter path to EXPORT1 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT1Directory to copy EXPORT1 CD[/oracle/IDS/sapreorg/CD4_DIR]<ret>Enter path to EXPORT2 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT2Directory to copy EXPORT2 CD[/oracle/IDS/sapreorg/CD5_DIR]<ret>Enter path to EXPORT3 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT3Directory to copy EXPORT3 CD[/oracle/IDS/sapreorg/CD6_DIR]<ret>Enter path to EXPORT4 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT4Directory to copy EXPORT4 CD[/oracle/IDS/sapreorg/CD7_DIR]<ret>Enter path to EXPORT5 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT5Directory to copy EXPORT5 CD[/oracle/IDS/sapreorg/CD8_DIR]<ret>Enter path to EXPORT6 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT6Directory to copy EXPORT6 CD[/oracle/IDS/sapreorg/CD9_DIR]<ret>Enter amount of RAM for SAP + DB850<ret> (in Megabytes)Service Entry Message Server[3600]<ret>Enter Group-ID of sapsys[101]<ret>Enter Group-ID of oper[102]<ret>Enter Group-ID of dba[100]<ret>Enter User-ID of <sid>adm[1000]<ret>Enter User-ID of ora<sid>[1002]<ret>Number of parallel procs[2]<ret>If I had not copied the CDs to the different locations,
then the SAP-Installer can't find the CD needed (identified
by the LABEL.ASC-File on CD) and would
then ask you to insert / mount the CD and confirm or enter
the mountpath.The CENTRDB.R3S might not be
error-free. In my case, it requested EXPORT4 again (but
indicated the correct key (6_LOCATI ON, then 7_LOCATION
etc.), so one can just continue with entering the correct
values. Don't get irritated.Apart from some problems mentioned below, everything
should go straight throught up to the point where the Oracle
database software needs to be installed.Installing Oracle 8.0.5Please see the corresponding SAP-Notes and Oracle Readmes
regarding Linux and Oracle DB for possible problems. Most if
not all problems stem from incompatible librariesFor more information on installing Oracle, refer to the Installing Oracle
chapter.Installing the Oracle 8.0.5 with orainstIf 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.rpmcompat-glibc-5.2-2.0.7.2.i386.rpmcompat-egcs-5.2-1.0.3a.1.i386.rpmcompat-egcs-c++-5.2-1.0.3a.1.i386.rpmcompat-binutils-5.2-2.9.1.0.23.1.i386.rpmSee the corresponding SAP-Notes or Oracle Readmes for
further information. If this is no option (at the time of
installation I didn't 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 can't 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; ./orainstConfirm 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 I 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 / 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. I did not
delete the remains of my previous RDBMS-installation tries,
though.Afterwards, Oracle Database could be started with no
problems.Continue with SAP R/3 installationFirst check the environment settings of users idsamd
(<sid>adm) and oraids (ora<sid>). 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 loadAfterwards, R3SETUP can either be restarted or continued
(depending on whether exit was chosen or not). R3SETUP then
creates the tablespaces and loads the data from EXPORT1 to
EXPORT6 (remember, it is an IDES system, otherwise it would
only be EXPORT1 to EXPORT3) 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!):QuestionInputEnter Password for sapr3sap<ret>Confirum Password for sapr3sap<ret>Enter Password for syschange_on_install<ret>Confirm Password for syschange_on_install<ret>Enter Password for systemmanager<ret>Confirm Password for systemmanager<ret>At this point I had a few problems with dipgntab.ListenerStart the Oracle-Listener as user oraids (ora<sid>) as
follows:umask 0; lsnrctl startOtherwise you might get ORA-12546 as the sockets won't
have the correct permissions. See SAP note 072984.Post-installation stepsRequest SAP R/3 license keyThis is needed, as the temporary license is only valid for
four weeks. Don't forget to enter the correct Operating System:
(X) Other: FreeBSD 4.3 Stable. First get
the hardware key. Log on as user idsadm and
call saplicense:&prompt.root; /sapmnt/IDS/exe/saplicense -getCalling saplicense without options
gives a list of options. Upon receiving the license key, it can
be installed using&prompt.root; /sapmnt/IDS/exe/saplicense -installYou 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 UsersCreate 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 username, I 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:TaskTransactionConfigure Transport System, eg as Stand-Alone
Transport Domain EntitySTMSCreate / Edit Profile for SystemRZ10Maintain Operation Modes and InstancesRZ04These and all the other post-installation steps are
thoroughly described in SAP installation guides.Edit init<sid>.sap (initIDS.sap)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, I 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/sa0Explanations:compress The tape I use is a HP DLT1
which does hardware compression.archive_function This defines the
default behaviour 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 one needs to
recover the database, and one of the archive-tapes has gone
bad.cpio_flags Default is to use -B which
sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at
least 32K blocksize, so I used --block-size=128 for
64K. --format=newc is needed I have inode numbers greater than
65535. The last option --quiet 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 reckognized
automagically.tape_size This usually gives the raw
storage capability of the tape. For security reason (we use
hardware compression), thevalue 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.Problems during installationOSUSERSIDADM_IND_ORA during R3SETUPIf R3SETUP complains at this stage, edit file
CENTRDB.R3S. Locate [OSUSERSIDADM_IND_ORA] and edit the
following values:HOME=/home/idsadm (was empty)
STATUS=OK (had status ERROR)
Then you can restart R3SETUP with:&prompt.root; ./R3SETUP -f CENTRDB.R3SOSUSERDBSID_IND_ORA during R3SETUPPossibly R3SETUP also complains at this stage. Just edit
CENTRDB.R3S. Locate [OSUSERDBSID_IND_ORA] and edit the
following value in that section:STATUS=OKThen just restart R3SETUP again:&prompt.root; ./R3SETUP -f CENTRDB.R3Soraview.vrf FILE NOT FOUND during Oracle installationYou haven't 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.TEXTENV_INVALID during R3SETUP, RFC or SAPGUI startIf this error is encountered, the correct locale is
missing. SAP note 0171356 lists the necessary RPMs that
need be installed (eg 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]
SpeicherzugriffsfehlerThis behaviour is due to SAP R/3 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 one 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.ORA-12546. Start Listener with correct permissionsStart the Oracle Listener as user
oraids with the following commands:&prompt.root; umask 0; lsnrctl startOtherwise one might get ORA-12546 as the sockets won't
have the correct permissions. See SAP note 0072984.[DIPGNTAB_IND_IND] during R3SETUPIn general, see SAP note 0130581 (R3SETUP step DIPGNTAB
terminates). During this specific installation, for some
reasons the installation process was not using the proper
SAP system name "IDS", but the empty string "" instead. This
lead 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/DVMGS00the following path were used:/usr/sap//SYS/...
/usr/sap/D00iTo continue with the installation, I 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 I also found SAP notes (0029227 and 0008401) describing
this behaviour.[RFCRSWBOINI_IND_IND] during R3SETUPSet 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 R3SETUPSet 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. See SAP note 0162266 for further
information.Advanced TopicsIf 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 loaderFreeBSD 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.ELFFor 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).SolarisThe 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 fileWhen this is done, the ELF loader will see the
Linux brand on the file.ELFbrandingWhen 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 flagged for special handling of
the trap vector for the signal trampoline code, and sever 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
union option to FS mounts
(not the unionfs!) does. First, an attempt
is made to lookup the file in the
/compat/linux/original-path
directory, then only if that fails, the
lookup is done in the
/original-path
directory. This makes sure that binaries that require other
binaries can run (e.g., the Linux toolchain can all run under
Linux ABI support). It also means that the Linux binaries can
load and exec FreeBSD binaries, if there are no corresponding
Linux binaries present, and that you could place a &man.uname.1;
command in the /compat/linux directory tree
to ensure that the Linux binaries could not tell they were not
running on Linux.In effect, there is a Linux kernel in the FreeBSD kernel; the
various underlying functions that implement all of the services
provided by the kernel are identical to both the FreeBSD system
call table entries, and the Linux system call table entries: file
system operations, virtual memory operations, signal delivery,
System V IPC, etc… The only difference is that FreeBSD
binaries get the FreeBSD glue functions, and
Linux binaries get the Linux glue functions
(most older OS's only had their own glue
functions: addresses of functions in a static global
sysent[] structure array, instead of addresses
of functions dereferenced off a dynamically initialized pointer in
the proc structure of the process making the
call).Which one is the native FreeBSD ABI? It does not matter.
Basically the only difference is that (currently; this could
easily be changed in a future release, and probably will be after
this) the FreeBSD glue functions are
statically linked into the kernel, and the Linux glue functions
can be statically linked, or they can be accessed via a kernel
module.Yeah, but is this really emulation? No. It is an ABI
implementation, not an emulation. There is no emulator (or
simulator, to cut off the next question) involved.So why is it sometimes called Linux emulation?
To make it hard to sell FreeBSD! 8-). Really, it
is because the historical implementation was done at a time when
there was really no word other than that to describe what was
going on; saying that FreeBSD ran Linux binaries was not true, if
you did not compile the code in or load a module, and there needed
to be a word to describe what was being loaded—hence
the Linux emulator.
diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index 09b5192394..1e44de0950 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -1,1256 +1,1256 @@
Installing Applications: Packages and PortsSynopsisThere is only so much you can do with FreeBSD. If you are an
operating systems developer then the base system likely contains
everything you need. If that is not what you are planning to do with
FreeBSD then you will probably want to install additional
software—perhaps a web server, or a mail reader, or a graphical
environment such as KDE or GNOME.If you have used a Unix system before you will know that the typical
procedure for installing third party software goes something like
this:Download the software, which might be distributed in source code
format, or as a binary.Unpack the software from its distribution format (typically a
tarball compressed with either &man.compress.1; or &man.gzip.1;).Locate the documentation (perhaps a README
file, or some files in a doc/ subdirectory) and
read up on how to install the software.If the software was distributed in source format, compile it.
This may involve editing a Makefile, or
running a configure script, and other work.Test and install the software.And that is only if everything goes well. If you are installing a
software package that was not deliberately ported to FreeBSD you may
even have to go in and edit the code to make it work properly.Should you want to, you can continue to install software the
traditional way with FreeBSD. However, FreeBSD provides
two technologies which can save you a lot of effort; packages and
ports. At the time of writing, over 4,000 third party applications have
been made available in this way.For any given application, the FreeBSD package for that application
is a single file which you must download. The package contains
pre-compiled copies of all the commands for the application, as well as
any configuration files or documentation. A downloaded package file can
be manipulated with FreeBSD pkg_* commands, such as
&man.pkg.add.1; &man.pkg.delete.1;, &man.pkg.info.1;, and so on.Installing a new application can be carried out with a single
command.A FreeBSD port for an application is a collection of files designed
to automate the process of compiling an application from source
code.Remember that there are a number of steps you would normally carry
out if you compiled a program yourself (unpacking, patching, compiling,
installing). The files that make up a port contain all the necessary
information to alllow the system to do this for you. You run a handful
of simple commands and the source code for the application is
automatically downloaded, extracted, patched, compiled, and installed
for you.In fact, the ports system can also be used to generate packages
which can later be manipulated with the pkg_*
commands.Both packages and ports understand
dependencies. Suppose you want to install an
application that depends on a specific library being installed. Both
the application and the library have been made available as FreeBSD
ports and packages. If you use the pkg_add command
or the ports system to add the application, both will notice that the
library has not been installed, and the commands will install the
library first.Given that the two technologies are quite similar, you might be
wondering why FreeBSD bothers with both. Packages and ports both have
their own strengths, and which one you use will depend on your own
preference.Package benefitsA compressed package tarball is typically smaller than the
compressed tarball containing the source code for the application.Packages do not require any additional compilation. For large
applications, such as Mozilla,
KDE, or GNOME
this can be important, particularly if you are on a slow system.Packages do not require you to understand any of the process
involved in compiling software on FreeBSD.Ports benefitsPackages are normally compiled with conservative options,
because they have to run on the maximum number of systems. By
installing from the port, you can tweak the compilation options to
(for example) generate code that is specific to a 686 processor.Some packages have compile time options relating to what they
can and can't do. For example, Apache
can be configured with a wide variety of different builtin options.
By building from the port you do not have to accept the default
options, and can set them yourself.In some cases, multiple packages will exist for the same
application to specify certain settings. For example,
Ghostscript is available as a
ghostscript package and a
ghostscript-nox11 package, depending on whether
or not you have installed an X11 server. This sort of rough
tweaking is possible with packages, but rapidly becomes impossible
if an application has more than one or two different compile time
options.The licensing conditions of some software distributions forbid
binary distribution. They must be distributed as source
code.Some people do not trust binary distributions. At least with
source code, you can (in theory) read through it and look for
potential problems yourself.If you have local patches, you will need the source in order to
apply them.Some people like having code around, so they can read it if they
get bored, hack it, borrow from it (license permitting, of course),
and so on.To keep track of updated ports, subscribe to
freebsd-ports.The remainder of this chapter will explain how to use packages and
ports to install and manage third party software on FreeBSD.Finding your applicationBefore you can install any applications you need to know what you
want, and what the application is called.FreeBSD's list of available applications is growing all the time.
Currently there are over 4,000 applications available as packages or
ports. There are a number of ways to find what you want.The FreeBSD web site maintains an up-to-date searchable list of
all the available applications, at
http://www.FreeBSD.org/ports/.
The name space is divided in to categories, and you may either
search for an application by name (if you know it), or you can list
all the applications available in a category.Dan Langille maintains FreshPorts, at
http://www.freshports.org/.
FreshPorts tracks changes to the applications in the ports tree as
they happen, and allows you to watch one or more
ports, and will send you an e-mail when they are updated.If you do not know the name of the application you want, try
using a site like FreshMeat
(http://www.freshmeat.net/)
or AppWatch
(http://www.appwatch.com/)
to find an application, then check back at the FreeBSD site to see
if the application has been ported yet.Using the Packages SystemContributed by &a.chern;, April 30, 2001.Installing a PackageYou can use the &man.pkg.add.1; utility to install a
FreeBSD software package from a local file or from a server on
the network.Downloading a package and then installing it locally&prompt.root; ftp 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/irc
250 CWD command successful.
ftp> get xchat-1.7.1.tgz
local: xchat-1.7.1.tgz remote: xchat-1.7.1.tgz
150 Opening BINARY mode data connection for 'xchat-1.7.1.tgz' (471488 bytes).
100% |**************************************************| 460 KB 00:00 ETA
226 Transfer complete.
471488 bytes received in 5.37 seconds (85.70 KB/s)
ftp> exit
&prompt.root; pkg_add xchat-1.7.1.tgz
&prompt.root;If you don't have a source of local packages (such as a
- FreeBSD CD-ROM set) then it will probably be easier to use the
+ FreeBSD CDROM set) then it will probably be easier to use the
-r option to &man.pkg.add.1;. This will cause the utility to
automatically determine the correct object format and release
and then to fetch and install the package from an FTP site.
&prompt.root; pkg_add -r xchat-1.7.1This would download the correct package and add it without
any further user intervention.Package files are distributed in .tgz format. You can
find them at ftp://ftp.freebsd.org/ports/packages,
- or on the FreeBSD CD-ROM distribution. Every CD on the
+ or on the FreeBSD CDROM distribution. Every CD on the
FreeBSD 4-CD set (and PowerPak, etc) contains packages in
the /packages directory. The layout of
the packages is similar to that of the
/usr/ports tree. Each category has its
own directory, and every package can be found within the
All directory.
The directory structure of the package system is homologous
to that of the ports; they work with each other to form the entire
package/port system.
Deleting a Package&prompt.root pkg_delete xchat-1.7.1
&prompt.root&man.pkg.delete.1; is the utility for removing
previously installed software package distributions.
Managing packages&man.pkg.info.1; a utility that lists and describes
the various packages installed.
&prompt.root pkg_info
cvsup-bin-16.1 A general network file distribution system optimized for CV
docbook-1.2 Meta-port for the different versions of the DocBook DTD
...&man.pkg.version.1; a utility that summarizes the
versions of all installed packages. It compares the package
version to the current version found in the ports tree.
&prompt.root pkg_version
cvsup-bin =
docbook =
...The symbols in the second column indicate the relative age
of the installed version and the version available in the local
ports tree.SymbolMeaning=The version of the
installed package matches that of the one found in the
local ports tree.<The installed version is older then the one available
in the ports tree.>The installed version is newer
than the one found in the local ports tree. (local ports
tree is probably out of date)?The installed package cannot be
found in the ports index.*There are multiple versions of the
package.Miscellaneous&man.pkg.add.1; &man.pkg.delete.1; &man.pkg.info.1;
&man.pkg.version.1; &man.pkg.create.1;
All package information is stored within the
/var/db/pkg directory. The listing
of contents and descriptions of each package can be found within
files in this directory.
Using the Ports CollectionThe following sections provide basic instructions on using the
ports collection to install or remove programs from your
system.Installing PortsThe first thing that should be explained
when it comes to the Ports collection is what is actually meant
by a skeleton. In a nutshell, a port skeleton is a
minimal set of files that are needed for a program to compile and
install cleanly on FreeBSD. Each port skeleton includes:A Makefile. The
Makefile contains various statements that
specify how the application should be compiled and where it
should be installed on your systemA distinfo file. This file contains
information about the files that must be downloaded to build the
port, and checksums, to ensure that those files have not been
corrupted during the download.A files directory. This directory
contains patches to make the program compile and install on
your FreeBSD system. Patches are basically small files that
specify changes to particular files. They are in plain text
format, and basically say Remove line 10 or
Change line 26 to this .... Patches are also
known as diffs because they are generated by the
diff program.This directory may also contain other files used in building
the port.A pkg-comment file. This is a one-line
description of the program.A pkg-descr file. This is a more
detailed, often multiple-line, description of the program.A pkg-plist file. This is a list of all
the files that will be installed by the port. It also tells the
ports system what files to remove upon deinstallation.Now that you have enough background information to know what
the Ports collection is used for, you are ready to install your
first port. There are two ways this can be done, and each is
explained below.Before we get into that however, you will need to choose a
port to install. There are a few ways to do this, with the
easiest method being the ports listing on the FreeBSD
web site. You can browse through the ports listed there
or use the search function on the site. Each port also includes
a description so you can read a bit about each port before
deciding to install it.Another method is to use the whereis
command. To use whereis, simply type
whereis <program you want to
install> at the prompt, and if it is found on
your system, you will be told where it is, like so:&prompt.root; whereis xchat
xchat: /usr/ports/irc/xchat
&prompt.root;This tells us that xchat (an irc client) can be found in the
/usr/ports/irc/xchat directory.Yet another way of finding a particular port is by using the
Ports collection's built-in search mechanism. To use the search
feature, you will need to be in the
/usr/ports directory. Once in that
directory, run make search key=program-name
where program-name is the name of the program you
want to find. For example, if you were looking for xchat:&prompt.root; cd /usr/ports
&prompt.root; make search key=xchat
Port: xchat-1.3.8
Path: /usr/ports/irc/xchat
Info: An X11 IRC client using the GTK+ toolkit, and optionally, GNOME
Maint: jim@FreeBSD.org
Index: irc
B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6
imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1
R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b
png-1.0.3 tiff-3.5.1The part of the output you want to pay particular attention
to is the Path: line, since that tells you where to
find it. The other information provided is not needed in order
to install the port directly, so it will not be covered
here.You must be the root user to install
ports.Now that you have found a port you would like to install, you
are ready to do the actual installation.Installing ports from a CDROMAs you may have guessed from the title, everything
described in this section assumes you have a FreeBSD CDROM set.
If you do not, you can order one from the FreeBSD Mall.Assuming that your FreeBSD CDROM is in the drive and is
mounted on /cdrom (and the mount point
must be /cdrom),
you are ready to install the port. To begin, change directories
to the directory where the port you want to install lives:&prompt.root; cd /usr/ports/irc/xchatOnce inside the xchat directory, you will see the port
skeleton. The next step is to compile (also called build) the
port. This is done by simply typing make at
the prompt. Once you have done so, you should see something
like this:&prompt.root; make
>> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
>> Attempting to fetch from file:/cdrom/ports/distfiles/.
===> Extracting for xchat-1.3.8
>> Checksum OK for xchat-1.3.8.tar.bz2.
===> xchat-1.3.8 depends on executable: bzip2 - found
===> xchat-1.3.8 depends on executable: gmake - found
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
===> Patching for xchat-1.3.8
===> Applying FreeBSD patches for xchat-1.3.8
===> Configuring for xchat-1.3.8
...
[configure output snipped]
...
===> Building for xchat-1.3.8
...
[compilation snipped]
...
&prompt.root;Take notice that once the compile is complete you are
returned to your prompt. The next step is to install the
port. In order to install it, you simply need to tack one word
onto the make command, and that word is
install:&prompt.root; make install
===> Installing for xchat-1.3.8
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
...
[install routines snipped]
...
===> Generating temporary packing list
===> Installing xchat docs in /usr/X11R6/share/doc/xchat
===> Registering installation for xchat-1.3.8
&prompt.root;Once you are returned to your prompt, you should be able to
run the application you just installed.You can save an extra step by just running make
install instead of make and
make install as two separate steps.Please be aware that the licenses of a few ports do not
allow for inclusion on the CDROM. This could be for various
reasons, including things such as registration form needs
to be filled out before downloading, if redistribution is not
allowed, and so on. If you wish to install a port not
included on the CDROM, you will need to be online in order to
do so (see the next
section).Installing ports from the InternetAs with the last section, this section makes an assumption
that you have a working Internet connection. If you do not,
you will need to do the CDROM
installation.Installing a port from the Internet is done exactly the same
way as it would be if you were installing from a CDROM. The
only difference between the two is that the program's source
code is downloaded from the Internet instead of pulled from the
CDROM.The steps involved are identical:&prompt.root; make install
>> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
>> Attempting to fetch from http://xchat.org/files/v1.3/.
Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100%
305543 bytes transferred in 2.9 seconds (102.81 Kbytes/s)
===> Extracting for xchat-1.3.8
>> Checksum OK for xchat-1.3.8.tar.bz2.
===> xchat-1.3.8 depends on executable: bzip2 - found
===> xchat-1.3.8 depends on executable: gmake - found
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
===> Patching for xchat-1.3.8
===> Applying FreeBSD patches for xchat-1.3.8
===> Configuring for xchat-1.3.8
...
[configure output snipped]
...
===> Building for xchat-1.3.8
...
[compilation snipped]
...
===> Installing for xchat-1.3.8
===> xchat-1.3.8 depends on shared library: gtk12.2 - found
===> xchat-1.3.8 depends on shared library: Imlib.5 - found
===> xchat-1.3.8 depends on shared library: X11.6 - found
...
[install routines snipped]
...
===> Generating temporary packing list
===> Installing xchat docs in /usr/X11R6/share/doc/xchat
===> Registering installation for xchat-1.3.8
&prompt.root;As you can see, the only difference is the line that tells
you where the system is fetching the port from.That about does it for installing ports onto your system.
In the section you will learn how to remove a port from your
system.Removing Installed PortsNow that you know how to install ports, you are probably
wondering how to remove them, just in case you install one and
later on you decide that you installed the wrong port. The next
few paragraphs will cover just that.Now we will remove our previous example (which was xchat for
those of you not paying attention). As with installing ports,
the first thing you must do is change to the port directory,
which if you remember was
/usr/ports/irc/xchat. After you change
directories, you are ready to uninstall xchat. This is done with
the make deinstall command (makes sense
right?):&prompt.root; cd /usr/ports/irc/xchat
&prompt.root; make deinstall
===> Deinstalling for xchat-1.3.8
&prompt.root;That was easy enough. You have now managed to remove xchat
from your system. If you would like to reinstall it, you can do
so by running make reinstall from the
/usr/ports/irc/xchat directory.TroubleshootingThe following sections cover some of the more frequently asked
questions about the Ports collection and some basic troubleshooting
techniques, and what do to if a port is broken.Some Questions and AnswersI thought this was going to be a discussion about
modems??!Ah, you must be thinking of the serial ports on the back
of your computer. We are using port here to
mean the result of porting a program from one
version of UNIX to another.What is a patch?A patch is a small file that specifies how to go from
one version of a file to another. It contains plain text,
and basically says things like delete line 23,
add these two lines after line 468, or
change line 197 to this. They are also known
as diffs because they are generated by the
diff program.What is all this about
tarballs?It is a file ending in .tar, or
with variations such as .tar.gz,
.tar.Z, .tar.bz2,
and even .tgz.Basically, it is a directory tree that has been archived
into a single file (.tar) and
optionally compressed (.gz). This
technique was originally used for Tape
ARchives (hence the name
tar), but it is a widely used way of
distributing program source code around the Internet.You can see what files are in them, or even extract them
yourself by using the standard UNIX tar program, which comes
with the base FreeBSD system, like this:&prompt.user; tar tvzf foobar.tar.gz
&prompt.user; tar xzvf foobar.tar.gz
&prompt.user; tar tvf foobar.tar
&prompt.user; tar xvf foobar.tarAnd a checksum?It is a number generated by adding up all the data in
the file you want to check. If any of the characters
change, the checksum will no longer be equal to the total,
so a simple comparison will allow you to spot the
difference.I did what you said for compiling ports from a CDROM and
it worked great until I tried to install the kermit
port.&prompt.root; make install
>> cku190.tar.gz doesn't seem to exist on this system.
>> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.Why can it not be found? Have I got a dud CDROM?As was explained in the compiling ports from CDROM
section, some ports cannot be put on the CDROM set
due to licensing restrictions. Kermit is an example of
that. The licensing terms for kermit do not allow us to put
the tarball for it on the CDROM, so you will have to fetch
it by hand—sorry!The reason why you got all those error messages was
because you were not connected to the Internet at the time.
Once you have downloaded it from any of the MASTER_SITES
(listed in the Makefile), you can restart the install
process.I did that, but when I tried to put it into
/usr/ports/distfiles I got some error
about not having permission.The ports mechanism looks for the tarball in
/usr/ports/distfiles, but you will not
be able to copy anything there because it is symlinked to
the CDROM, which is read-only. You can tell it to look
somewhere else by doing:&prompt.root; make DISTDIR=/where/you/put/it installDoes the ports scheme only work if you have everything
in /usr/ports? My system administrator
says I must put everything under
/u/people/guests/wurzburger, but it
does not seem to work.You can use the PORTSDIR and
PREFIX variables to tell the ports
mechanism to use different directories. For
instance,&prompt.root; make PORTSDIR=/u/people/guests/wurzburger/ports installwill compile the port in
/u/people/guests/wurzburger/ports and
install everything under
/usr/local.&prompt.root; make PREFIX=/u/people/guests/wurzburger/local installwill compile it in /usr/ports and
install it in
/u/people/guests/wurzburger/local.And of course,&prompt.root; make PORTSDIR=../ports PREFIX=../local installwill combine the two (it is too long to write fully on
the page, but it should give you the general idea).Some ports that use &man.imake.1; (a part of the X Windows
System) don't work well with PREFIX, and will insist on
installing under /usr/X11R6. Similarly, some Perl ports
ignore PREFIX and install in the Perl tree. Making these
ports respect PREFIX is a difficult or impossible
job.If you do not fancy typing all that in every time you
install a port, it is a good idea to put these variables
into your environment. Read the man page for your shell for
instructions on doing so.I do not have a FreeBSD CDROM, but I would like to have
all the tarballs handy on my system so I do not have to wait
for a download every time I install a port. Is there any
way to get them all at once?To get every single tarball for the Ports collection,
do:&prompt.root; cd /usr/ports
&prompt.root; make fetchFor all the tarballs for a single ports directory,
do:&prompt.root; cd /usr/ports/directory
&prompt.root; make fetchand for just one port—well, you have probably
guessed already.I know it is probably faster to fetch the tarballs from
one of the FreeBSD mirror sites close by. Is there any way
to tell the port to fetch them from servers other than the
ones listed in the MASTER_SITES?Yes. If you know, for example, that ftp.FreeBSD.org is much closer to you
than the sites listed in MASTER_SITES,
do as follows:&prompt.root; cd /usr/ports/directory
&prompt.root; make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetchI want to know what files make is
going to need before it tries to pull them down.make fetch-list will display a list
of the files needed for a port.Is there any way to stop the port from compiling? I
want to do some hacking on the source before I install it,
but it is a bit tiresome to watch it and hit control-C every
time.Doing make extract will stop it
after it has fetched and extracted the source code.I am trying to make my own port and I want to be able
to stop it compiling until I have had a chance to see if my
patches worked properly. Is there something like
make extract, but for patches?Yep, make patch is what you want.
You will probably find the PATCH_DEBUG
option useful as well. And by the way, thank you for your
efforts!I have heard that some compiler options can cause bugs.
Is this true? How can I make sure that I compile ports
with the right settings?Yes, with version 2.6.3 of gcc (the
version shipped with FreeBSD 2.1.0 and 2.1.5), the
option could result in buggy code
unless you used the
option as well. (Most of the ports do not use
). You should be
able to specify the compiler options used by something
like:&prompt.root; make CFLAGS='-O2 -fno-strength-reduce' installor by editing /etc/make.conf, but
unfortunately not all ports respect this. The surest way
is to do make configure, then go into
the source directory and inspect the Makefiles by hand, but
this can get tedious if the source has lots of
sub-directories, each with their own Makefiles.The default FreeBSD compiler options are quite conservative,
so if you have not changed them you should not have any
problems.There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are
available?Look in the INDEX file in
/usr/ports. If you would like to
search the ports collection for a keyword, you can do that
too. For example, you can find ports relevant to the LISP
programming language using:&prompt.user; cd /usr/ports
&prompt.user; make search key=lispI went to install the foo port but
the system suddenly stopped compiling it and starting
compiling the bar port. What is going
on?The foo port needs something that is
supplied with bar — for instance,
if foo uses graphics,
bar might have a library with useful
graphics processing routines. Or bar
might be a tool that is needed to compile the
foo port. I installed the
grizzle program from the ports and
frankly it is a complete waste of disk space. I want to
delete it but I do not know where it put all the files.
Any clues?No problem, just do:&prompt.root; pkg_delete grizzle-6.5Alternatively, you can do:&prompt.root; cd /usr/ports/somewhere/grizzle
&prompt.root; make deinstallHang on a minute, you have to know the version number
to use that command. You do not seriously expect me to
remember that, do you??Not at all, you can find it out by doing:&prompt.root; pkg_info -I 'grizzle*'
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.Talking of disk space, the ports directory seems to be
taking up an awful lot of room. Is it safe to go in there
and delete things?Yes, if you have installed the program and are fairly
certain you will not need the source again, there is no
point in keeping it hanging around. The best way to do
this is:&prompt.root; cd /usr/ports
&prompt.root; make cleanwhich will go through all the ports subdirectories and
delete everything except the skeletons for each
port.I tried that and it still left all those tarballs or
whatever you called them in the
distfiles directory. Can I delete
those as well?Yes, if you are sure you have finished with them,
those can go as well. They can be removed manually, or by
using make distclean.I like having lots and lots of programs to play with.
Is there any way of installing all the ports in one
go?Just do:&prompt.root; cd /usr/ports
&prompt.root; make installBe careful, as some ports may install files with the same
name. If you install two graphics ports and they both install
/usr/local/bin/plot then you will obviously
have problems.OK, I tried that, but I thought it would take a very
long time so I went to bed and left it to get on with it.
When I looked at the computer this morning, it had only
done three and a half ports. Did something go
wrong?No, the problem is that some of the ports need to ask
you questions that we cannot answer for you (e.g., Do
you want to print on A4 or US letter sized paper?)
and they need to have someone on hand to answer
them.I really do not want to spend all day staring at the
monitor. Any better ideas?OK, do this before you go to bed/work/the local
park:&prompt.root cd /usr/ports
&prompt.root; make -DBATCH installThis will install every port that does
not require user input. Then, when
you come back, do:&prompt.root; cd /usr/ports
&prompt.root; make -DINTERACTIVE installto finish the job.At work, we are using frobble, which
is in your Ports collection, but we have altered it quite a
bit to get it to do what we need. Is there any way of making
our own packages, so we can distribute it more easily around
our sites?No problem, assuming you know how to make patches for
your changes:&prompt.root; cd /usr/ports/somewhere/frobble
&prompt.root; make extract
&prompt.root; cd work/frobble-2.8
[Apply your patches]
&prompt.root; cd ../..
&prompt.root; make packageThis ports stuff is really clever. I am desperate to
find out how you did it. What is the secret?Nothing secret about it at all, just look at the
bsd.port.mk and
bsd.port.subdir.mk files in your
makefiles
directory.(Readers with an aversion to intricate shell-scripts are
advised not to follow this link...)Help! This port is broken!If you come across a port that doesn't work for you, there are
a few things you can do, including:Fix it! The how to make a
port section should help you do this.Gripe—by email only! Send
email to the maintainer of the port first. Type make
maintainer or read the Makefile
to find the maintainer's email address. Remember to include
the name and version of the port (send the
$FreeBSD: line from the
Makefile) and the output leading up to the
error when you email the maintainer. If you do not get a
response from the maintainer, you can use
send-pr to submit a bug report.Forget about it. This is the easiest route—very
few ports can be classified as essential. There's
also a good chance any problems will be fixed in the next
version when the port is updated.Grab the package from an ftp site near you. The
master package collection is on ftp.FreeBSD.org in the packages
directory, but be sure to check your local mirror
first! These are more likely to work
than trying to compile from source and are a lot faster as
well. Use the &man.pkg.add.1; program to install the package
on your system.Advanced TopicsThe documentation that was here has been moved to its own Porter's Handbook for ease of
reference. Please go there if you wish to create and submit your own
ports.