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 6cf8ef8022..dc9ef5ec8f 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,5639 +1,5639 @@
Advanced NetworkingSynopsisThis chapter will cover a number of advanced networking
topics.After reading this chapter, you will know:The basics of gateways and routes.How to set up IEEE 802.11 and &bluetooth; devices.How to make FreeBSD act as a bridge.How to set up network booting on a diskless machine.How to set up network address translation.How to connect two computers via PLIP.How to set up IPv6 on a FreeBSD machine.How to configure ATM.How to enable and utilize the features of CARP, the
Common Access Redundancy Protocol in &os;Before reading this chapter, you should:Understand the basics of the /etc/rc scripts.Be familiar with basic network terminology.Know how to configure and install a new FreeBSD kernel
().Know how to install additional third-party
software ().CoranthGryphonContributed by Gateways and RoutesroutinggatewaysubnetFor one machine to be able to find another over a network,
there must be a mechanism in place to describe how to get from
one to the other. This is called
routing. A route is a
defined pair of addresses: a destination and a
gateway. The pair indicates that if you are
trying to get to this destination,
communicate through this gateway. There
are three types of destinations: individual hosts, subnets, and
default. The default route is
used if none of the other routes apply. We will talk a little
bit more about default routes later on. There are also three
types of gateways: individual hosts, interfaces (also called
links), and Ethernet hardware addresses (MAC
addresses).
An ExampleTo illustrate different aspects of routing, we will use the
following example from netstat:&prompt.user; netstat -r
Routing tables
Destination Gateway Flags Refs Use Netif Expire
default outside-gw UGSc 37 418 ppp0
localhost localhost UH 0 181 lo0
test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
10.20.30.255 link#1 UHLW 1 2421
example.com link#1 UC 0 0
host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
host2.example.com link#1 UC 0 0
224 link#1 UC 0 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 this
routing table specifies to use for
localhost is lo0,
also known as the loopback device. This says to keep all
traffic for this destination internal, rather than sending it
out over the LAN, since it will only end up back where it
started.EthernetMAC addressThe next thing that stands out are the addresses beginning
with 0:e0:. These are Ethernet
hardware addresses, which are also known as MAC addresses.
FreeBSD will automatically identify any hosts
(test0 in the example) on the local Ethernet
and add a route for that host, directly to it over the
Ethernet interface, ed0. There is
also a timeout (Expire column) associated
with this type of route, which is used if we fail to hear from
the host in a specific amount of time. When this happens, the
route to this host will be automatically deleted. These hosts
are identified using a mechanism known as RIP (Routing
Information Protocol), which figures out routes to local hosts
based upon a shortest path determination.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 example.com is the domain name associated
with that subnet). The designation link#1 refers
to the first Ethernet card in the machine. You will notice no
additional interface is specified for those.Both of these groups (local network hosts and local subnets) have
their routes automatically configured by a daemon called
routed. If this is not run, then only
routes which are statically defined (i.e. entered explicitly) will
exist.The host1 line refers to our host, which it
knows by Ethernet address. Since we are the sending host, FreeBSD
knows to use the loopback interface (lo0)
rather than sending it out over the Ethernet interface.The two host2 lines are an example of
what happens when we use an &man.ifconfig.8; alias (see the
section on Ethernet for reasons why we would do this). The
=> symbol after the
lo0 interface says that not only are
we using the loopback (since this address also refers to the
local host), but specifically it is an alias. Such routes
only show up on the host that supports the alias; all other
hosts on the local network will simply have a
link#1 line for such routes.The final line (destination subnet 224) deals
with multicasting, which will be covered in another section.Finally, various attributes of each route can be seen in
the Flags column. Below is a short table
of some of these flags and their meanings: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 a remote host,
it checks the routing table to determine if a known path exists. If
the remote host falls into a subnet that we know how to reach (Cloned
routes), then the system checks to see if it can connect along that
interface.If all known paths fail, the system has one last option: the
default route. This route is a special type of gateway
route (usually the only one present in the system), and is always
marked with a c in the flags field. For hosts on a
local area network, this gateway is set to whatever machine has a
direct connection to the outside world (whether via PPP link,
DSL, cable modem, T1, or another network interface).If you are configuring the default route for a machine which
itself is functioning as the gateway to the outside world, then the
default route will be the gateway machine at your Internet Service
Provider's (ISP) site.Let us look at an example of default routes. This is a common
configuration:
[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
The hosts Local1 and
Local2 are at your site.
Local1 is connected to an ISP via a dial up
PPP connection. This PPP server computer is connected through
a local area network to another gateway computer through an
external interface to the ISPs Internet feed.The default routes for each of your machines will be: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.It is common to use the address X.X.X.1 as the gateway address for your local
network. So (using the same example), if your local class-C address
space was 10.20.30 and your ISP was
using 10.9.9 then the default routes
would be:HostDefault RouteLocal2 (10.20.30.2)Local1 (10.20.30.1)Local1 (10.20.30.1, 10.9.9.30)T1-GW (10.9.9.1)You can easily define the default route via the
/etc/rc.conf file. In our example, on the
Local2 machine, we added the following line
in /etc/rc.conf:defaultrouter="10.20.30.1"It is also possible to do it directly from the command
line with the &man.route.8; command:&prompt.root; route add default 10.20.30.1For more information on manual manipulation of network
routing tables, consult &man.route.8; manual page.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 has two Ethernet cards, each
having an address on the separate subnets. Alternately, the
machine may only have one Ethernet card, and be using
&man.ifconfig.8; aliasing. The former is used if two
physically separate Ethernet networks are in use, the latter
if there is one physical network segment, but two logically
separate subnets.Either way, routing tables are set up so that each subnet knows
that this machine is the defined gateway (inbound route) to the other
subnet. This configuration, with the machine acting as a router
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.If you want this machine to actually forward packets
between the two interfaces, you need to tell FreeBSD to enable
this ability. See the next section for more details on how
to do this.Building a RouterrouterA network router is simply a system that forwards packets
from one interface to another. Internet standards and good
engineering practice prevent the FreeBSD Project from enabling
this by default in FreeBSD. You can enable this feature by
changing the following variable to YES in
&man.rc.conf.5;:gateway_enable=YES # Set to YES if this host will be a gatewayThis option will set the &man.sysctl.8; variable
net.inet.ip.forwarding to
1. If you should need to stop routing
temporarily, you can reset this to 0 temporarily.BGPRIPOSPFYour new router will need routes to know where to send the
traffic. If your network is simple enough you can use static
routes. FreeBSD also comes with the standard BSD routing
daemon &man.routed.8;, which speaks RIP (both version 1 and
version 2) and IRDP. Support for BGP v4, OSPF v2, and other
sophisticated routing protocols is available with the
net/zebra package.
Commercial products such as &gated; are also available for more
complex network routing solutions.AlHoangContributed by Setting Up Static RoutesManual ConfigurationLet us assume we have a network as follows:
INTERNET
| (10.0.0.1/24) Default Router to Internet
|
|Interface xl0
|10.0.0.10/24
+------+
| | RouterA
| | (FreeBSD gateway)
+------+
| Interface xl1
| 192.168.1.1/24
|
+--------------------------------+
Internal Net 1 | 192.168.1.2/24
|
+------+
| | RouterB
| |
+------+
| 192.168.2.1/24
|
Internal Net 2
In this scenario, RouterA is our &os;
machine that is acting as a router to the rest of the
Internet. It has a default route set to 10.0.0.1 which allows it to connect
with the outside world. We will assume that
RouterB is already configured properly and
knows how to get wherever it needs to go. (This is simple
in this picture. Just add a default route on
RouterB using 192.168.1.1 as the gateway.)If we look at the routing table for
RouterA we would see something like the
following:&prompt.user; netstat -nr
Routing tables
Internet:
Destination Gateway Flags Refs Use Netif Expire
default 10.0.0.1 UGS 0 49378 xl0
127.0.0.1 127.0.0.1 UH 0 6 lo0
10.0.0/24 link#1 UC 0 0 xl0
192.168.1/24 link#2 UC 0 0 xl1With the current routing table RouterA
will not be able to reach our Internal Net 2. It does not
have a route for 192.168.2.0/24. One way to alleviate
this is to manually add the route. The following command
would add the Internal Net 2 network to
RouterA's routing table using 192.168.1.2 as the next hop:&prompt.root; route add -net 192.168.2.0/24 192.168.1.2Now RouterA can reach any hosts on the
192.168.2.0/24
network.Persistent ConfigurationThe above example is perfect for configuring a static
route on a running system. However, one problem is that the
routing information will not persist if you reboot your &os;
machine. The way to handle the addition of a static route
is to put it in your /etc/rc.conf
file:# Add Internal Net 2 as a static route
static_routes="internalnet2"
route_internalnet2="-net 192.168.2.0/24 192.168.1.2"The static_routes configuration
variable is a list of strings separated by a space. Each
string references to a route name. In our above example we
only have one string in static_routes.
This string is internalnet2. We
then add a configuration variable called
route_internalnet2
where we put all of the configuration parameters we would
give to the &man.route.8; command. For our example above we
would have used the command:&prompt.root; route add -net 192.168.2.0/24 192.168.1.2so we need "-net 192.168.2.0/24 192.168.1.2".As said above, we can have more than one string in
static_routes. This allows us to
create multiple static routes. The following lines shows
an example of adding static routes for the 192.168.0.0/24 and 192.168.1.0/24 networks on an imaginary
router:static_routes="net1 net2"
route_net1="-net 192.168.0.0/24 192.168.0.1"
route_net2="-net 192.168.1.0/24 192.168.1.1"Routing Propagationrouting propagationWe 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 routing is breaking down is the
&man.traceroute.8; command. It is equally useful if you cannot seem
to make a connection to a remote machine (i.e. &man.ping.8;
fails).The &man.traceroute.8; command is run with the name of the remote
host you are trying to connect to. It will show the gateway hosts
along the path of the attempt, eventually either reaching the target
host, or terminating because of a lack of connection.For more information, see the manual page for
&man.traceroute.8;.Multicast Routingmulticast routingkernel optionsMROUTINGFreeBSD supports both multicast applications and multicast
routing natively. Multicast applications do not require any
special configuration of FreeBSD; applications will generally
run out of the box. Multicast routing
requires that support be compiled into the kernel:options MROUTINGIn addition, the multicast routing daemon, &man.mrouted.8;
must be configured to set up tunnels and DVMRP via
/etc/mrouted.conf. More details on
multicast configuration may be found in the manual page for
&man.mrouted.8;.As of &os; 7.0 the &man.mrouted.8; multicast routing daemon
has been removed from the base system. It implements the
DVMRP multicast routing protocol, which has
largely been replaced by &man.pim.4; in many multicast
installations. The related &man.map-mbone.8; and
&man.mrinfo.8; utilities have also been removed. These programs
are now available in the &os; Ports Collection as
net/mrouted.LoaderMarcFonvieilleMurrayStokelyWireless Networkingwireless networking802.11wireless networkingWireless Networking BasicsMost wireless networks are based on the IEEE 802.11
standards. A basic wireless network consists of multiple
stations communicating with radios that broadcast in either
the 2.4GHz or 5GHz band (though this varies according to the
locale and is also changing to enable communication in the
2.3GHz and 4.9GHz ranges).802.11 networks are organized in two ways: in
infrastructure mode one station acts as a
master with all the other stations associating to it; the
network is known as a BSS and the master station is termed an
access point (AP). In a BSS all communication passes through
the AP; even when one station wants to communicate with
another wireless station messages must go through the AP. In
the second form of network there is no master and stations
communicate directly. This form of network is termed an IBSS
and is commonly known as an ad-hoc
network.802.11 networks were first deployed in the 2.4GHz band
using protocols defined by the IEEE 802.11 and 802.11b
standard. These specifications include the operating
frequencies, MAC layer characteristics including framing and
transmission rates (communication can be done at various
rates). Later the 802.11a standard defined operation in the
5GHz band, including different signalling mechanisms and
higher transmission rates. Still later the 802.11g standard
was defined to enable use of 802.11a signalling and
transmission mechanisms in the 2.4GHz band in such a way as to
be backwards compatible with 802.11b networks.Separate from the underlying transmission techniques
802.11 networks have a variety of security mechanisms. The
original 802.11 specifications defined a simple security
protocol called WEP. This protocol uses a fixed pre-shared key
and the RC4 cryptographic cipher to encode data transmitted on
a network. Stations must all agree on the fixed key in order
to communicate. This scheme was shown to be easily broken and
is now rarely used except to discourage transient users from
joining networks. Current security practice is given by the
IEEE 802.11i specification that defines new cryptographic
ciphers and an additional protocol to authenticate stations to
an access point and exchange keys for doing data
communication. Further, cryptographic keys are periodically
refreshed and there are mechanisms for detecting intrusion
attempts (and for countering intrusion attempts). Another
security protocol specification commonly used in wireless
networks is termed WPA. This was a precursor to 802.11i
defined by an industry group as an interim measure while
waiting for 802.11i to be ratified. WPA specifies a subset of
the requirements found in 802.11i and is designed for
implementation on legacy hardware. Specifically WPA requires
only the TKIP cipher that is derived from the original WEP
cipher. 802.11i permits use of TKIP but also requires support
for a stronger cipher, AES-CCM, for encrypting data. (The AES
cipher was not required in WPA because it was deemed too
computationally costly to be implemented on legacy
hardware.)Other than the above protocol standards the other
important standard to be aware of is 802.11e. This defines
protocols for deploying multi-media applications such as
streaming video and voice over IP (VoIP) in an 802.11 network.
Like 802.11i, 802.11e also has a precursor specification
termed WME (later renamed WMM) that has been defined by an
industry group as a subset of 802.11e that can be deployed now
to enable multi-media applications while waiting for the final
ratification of 802.11e. The most important thing to know
about 802.11e and WME/WMM is that it enables prioritized
traffic use of a wireless network through Quality of Service
(QoS) protocols and enhanced media access protocols. Proper
implementation of these protocols enable high speed bursting
of data and prioritized traffic flow.Since the 6.0 version, &os; supports networks that operate
using 802.11a, 802.11b, and 802.11g. The WPA and 802.11i
security protocols are likewise supported (in conjunction with
any of 11a, 11b, and 11g) and QoS and traffic prioritization
required by the WME/WMM protocols are supported for a limited
set of wireless devices.Basic SetupKernel ConfigurationTo use wireless networking you need a wireless
networking card and to configure the kernel with the
appropriate wireless networking support. The latter is
separated into multiple modules so that you only need to
configure the software you are actually going to use.The first thing you need is a wireless device. The most
commonly used devices are those that use parts made by
Atheros. These devices are supported by the &man.ath.4;
driver and require the following line to be added to the
/boot/loader.conf file:if_ath_load="YES"The Atheros driver is split up into three separate
pieces: the driver proper (&man.ath.4;), the hardware
support layer that handles chip-specific functions
(&man.ath.hal.4;), and an algorithm for selecting which of
several possible rates for transmitting frames
(ath_rate_sample here). When you load this support as
modules these dependencies are automatically handled for
you. If instead of an Atheros device you had another device
you would select the module for that device; e.g.:if_wi_load="YES"for devices based on the Intersil Prism parts
(&man.wi.4; driver).In the rest of this document, we will use an
&man.ath.4; device, the device name in the examples must
be changed according to your configuration. A list of
available wireless drivers can be found at the beginning
of the &man.wlan.4; manual page. If a native &os; driver
for your wireless device does not exist, it may be
possible to directly use the &windows; driver with the
help of the NDIS driver
wrapper.With a device driver configured you need to also bring
in the 802.11 networking support required by the driver.
For the &man.ath.4; driver these are at least the &man.wlan.4;,
wlan_scan_ap and
wlan_scan_sta
modules; the &man.wlan.4; module is automatically loaded with the
wireless device driver, the remaining modules must be loaded
at boot time via the /boot/loader.conf
file:wlan_scan_ap_load="YES"
wlan_scan_sta_load="YES"With that you will need the modules
that implement cryptographic support for the security
protocols you intend to use. These are intended to be
dynamically loaded on demand by the &man.wlan.4; module but
for now they must be manually configured. The following
modules are available: &man.wlan.wep.4;, &man.wlan.ccmp.4;
and &man.wlan.tkip.4;. Both &man.wlan.ccmp.4; and
&man.wlan.tkip.4; drivers are only needed if you intend to
use the WPA and/or 802.11i security protocols. If your
network is to run totally open (i.e., with no encryption)
then you do not even need the &man.wlan.wep.4; support. To
load these modules at boot time, add the following lines to
/boot/loader.conf:wlan_wep_load="YES"
wlan_ccmp_load="YES"
wlan_tkip_load="YES"With this information in the system bootstrap
configuration file (i.e.,
/boot/loader.conf), you have to reboot
your &os; box. If you do not want to reboot your machine
for the moment, you can just load the modules by hand using
&man.kldload.8;.If you do not want to use modules, it is possible to
compile these drivers into the kernel by adding the
following lines to your kernel configuration file:device ath # Atheros IEEE 802.11 wireless network driver
device ath_hal # Atheros Hardware Access Layer
device ath_rate_sample # John Bicket's SampleRate control algorithm.
device wlan # 802.11 support (Required)
device wlan_scan_ap # 802.11 AP mode scanning
device wlan_scan_sta # 802.11 STA mode scanning
device wlan_wep # WEP crypto support for 802.11 devices
device wlan_ccmp # AES-CCMP crypto support for 802.11 devices
device wlan_tkip # TKIP and Michael crypto support for 802.11 devicesWith this information in the kernel configuration
file, recompile the kernel and reboot your &os;
machine.When the system is up, we could find some information
about the wireless device in the boot messages, like
this:ath0: <Atheros 5212> mem 0xff9f0000-0xff9fffff irq 17 at device 2.0 on pci2
ath0: Ethernet address: 00:11:95:d5:43:62
ath0: mac 7.9 phy 4.5 radio 5.6Infrastructure ModeThe infrastructure mode or BSS mode is the mode that is
typically used. In this mode, a number of wireless access
points are connected to a wired network. Each wireless
network has its own name, this name is called the SSID of the
network. Wireless clients connect to the wireless access
points.&os; ClientsHow to Find Access PointsTo scan for networks, use the
ifconfig command. This request may
take a few moments to complete as it requires that the
system switches to each available wireless frequency and
probes for available access points. Only the super-user
can initiate such a scan:&prompt.root; ifconfig ath0 up scan
SSID BSSID CHAN RATE S:N INT CAPS
dlinkap 00:13:46:49:41:76 6 54M 29:3 100 EPS WPA WME
freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS WPAYou must mark the interface
before you can scan. Subsequent scan requests do not
require you to mark the interface up again.The output of a scan request lists each BSS/IBSS
network found. Beside the name of the network,
SSID, we find the
BSSID which is the MAC address of the
access point. The CAPS field
identifies the type of each network and the capabilities
of the stations operating there:EExtended Service Set (ESS). Indicates that the
station is part of an infrastructure network (in
contrast to an IBSS/ad-hoc network).IIBSS/ad-hoc network. Indicates that the station
is part of an ad-hoc network (in contrast to an ESS
network).PPrivacy. Data confidentiality is required for
all data frames exchanged within the BSS. This means
that this BSS requires the station to use
cryptographic means such as WEP, TKIP or AES-CCMP to
encrypt/decrypt data frames being exchanged with
others.SShort Preamble. Indicates that the network is
using short preambles (defined in 802.11b High
Rate/DSSS PHY, short preamble utilizes a 56 bit sync
field in contrast to a 128 bit field used in long
preamble mode).sShort slot time. Indicates that the 802.11g
network is using a short slot time because there are
no legacy (802.11b) stations present.One can also display the current list of known
networks with:&prompt.root; ifconfig ath0 list scanThis information may be updated automatically by the
adapter or manually with a request.
Old data is automatically removed from the cache, so over
time this list may shrink unless more scans are
done.Basic SettingsThis section provides a simple example of how to make
the wireless network adapter work in &os; without
encryption. After you are familiar with these concepts,
we strongly recommend using WPA to set up your
wireless network.There are three basic steps to configure a wireless
network: selecting an access point, authenticating your
station, and configuring an IP address. The following
sections discuss each step.Selecting an Access PointMost of time it is sufficient to let the system
choose an access point using the builtin heuristics.
This is the default behaviour when you mark an interface
up or otherwise configure an interface by listing it in
/etc/rc.conf, e.g.:ifconfig_ath0="DHCP"If there are multiple access points and you want to
select a specific one, you can select it by its
SSID:ifconfig_ath0="ssid your_ssid_here DHCP"In an environment where there are multiple access
points with the same SSID (often done to simplify
roaming) it may be necessary to associate to one
specific device. In this case you can also specify the
BSSID of the access point (you can also leave off the
SSID):ifconfig_ath0="ssid your_ssid_here bssid xx:xx:xx:xx:xx:xx DHCP"There are other ways to constrain the choice of an
access point such as limiting the set of frequencies the
system will scan on. This may be useful if you have a
multi-band wireless card as scanning all the possible
channels can be time-consuming. To limit operation to a
specific band you can use the
parameter; e.g.:ifconfig_ath0="mode 11g ssid your_ssid_here DHCP"will force the card to operate in 802.11g which is
defined only for 2.4GHz frequencies so any 5GHz channels
will not be considered. Other ways to do this are the
parameter, to lock operation to
one specific frequency, and the
parameter, to specify a list
of channels for scanning. More information about these
parameters can be found in the &man.ifconfig.8; manual
page.AuthenticationOnce you have selected an access point your station
needs to authenticate before it can pass data.
Authentication can happen in several ways. The most
common scheme used is termed open authentication and
allows any station to join the network and communicate.
This is the authentication you should use for test
purpose the first time you set up a wireless network.
Other schemes require cryptographic handshakes be
completed before data traffic can flow; either using
pre-shared keys or secrets, or more complex schemes that
involve backend services such as RADIUS. Most users
will use open authentication which is the default
setting. Next most common setup is WPA-PSK, also known
as WPA Personal, which is described below.If you have an &apple; &airport; Extreme base
station for an access point you may need to configure
shared-key authentication together with a WEP key.
This can be done in the
/etc/rc.conf file or using the
&man.wpa.supplicant.8; program. If you have a single
&airport; base station you can setup access with
something like:ifconfig_ath0="authmode shared wepmode on weptxkey 1 wepkey 01234567 DHCP"In general shared key authentication is to be
avoided because it uses the WEP key material in a
highly-constrained manner making it even easier to
crack the key. If WEP must be used (e.g., for
compatibility with legacy devices) it is better to use
WEP with open authentication. More
information regarding WEP can be found in the .Getting an IP Address with DHCPOnce you have selected an access point and set the
authentication parameters, you will have to get an IP
address to communicate. Most of time you will obtain
your wireless IP address via DHCP. To achieve that,
simply edit /etc/rc.conf and add
DHCP to the configuration for your
device as shown in various examples above:ifconfig_ath0="DHCP"At this point, you are ready to bring up the
wireless interface:&prompt.root; /etc/rc.d/netif startOnce the interface is running, use
ifconfig to see the status of the
interface ath0:&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps)
status: associated
ssid dlinkap channel 6 bssid 00:13:46:49:41:76
authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100The status: associated means you
are connected to the wireless network (to the
dlinkap network in our case). The
bssid 00:13:46:49:41:76 part is the
MAC address of your access point; the
authmode line informs you that the
communication is not encrypted
(OPEN).Static IP AddressIn the case you cannot obtain an IP address from a
DHCP server, you can set a fixed IP address. Replace
the DHCP keyword shown above with the
address information. Be sure to retain any other
parameters you have set up for selecting an access
point:ifconfig_ath0="ssid your_ssid_here inet 192.168.1.100 netmask 255.255.255.0"WPAWPA (Wi-Fi Protected Access) is a security protocol
used together with 802.11 networks to address the lack of
proper authentication and the weakness of WEP. WPA leverages
the 802.1X authentication protocol and uses one of several
ciphers instead of WEP for data integrity. The only
cipher required by WPA is TKIP (Temporary Key Integrity
Protocol) which is a cipher that extends the basic RC4
cipher used by WEP by adding integrity checking, tamper
detection, and measures for responding to any detected
intrusions. TKIP is designed to work on legacy hardware
with only software modification; it represents a
compromise that improves security but is still not
entirely immune to attack. WPA also specifies the
AES-CCMP cipher as an alternative to TKIP and that is
preferred when possible; for this specification the term
WPA2 (or RSN) is commonly used.WPA defines authentication and encryption protocols.
Authentication is most commonly done using one of two
techniques: by 802.1X and a backend authentication service
such as RADIUS, or by a minimal handshake between the
station and the access point using a pre-shared secret.
The former is commonly termed WPA Enterprise with the
latter known as WPA Personal. Since most people will not
set up a RADIUS backend server for wireless network,
WPA-PSK is by far the most commonly encountered
configuration for WPA.The control of the wireless connection and the
authentication (key negotiation or authentication with a
server) is done with the &man.wpa.supplicant.8; utility.
This program requires a configuration file,
/etc/wpa_supplicant.conf, to run.
More information regarding this file can be found in the
&man.wpa.supplicant.conf.5; manual page.WPA-PSKWPA-PSK also known as WPA-Personal is based on a
pre-shared key (PSK) generated from a given password and
that will be used as the master key in the wireless
network. This means every wireless user will share the
same key. WPA-PSK is intended for small networks where
the use of an authentication server is not possible or
desired.Always use strong passwords that are
sufficiently long and made from a rich alphabet so
they will not be guessed and/or attacked.The first step is the configuration of the
/etc/wpa_supplicant.conf file with
the SSID and the pre-shared key of your network:network={
ssid="freebsdap"
psk="freebsdmall"
}Then, in /etc/rc.conf, we
indicate that the wireless device configuration will be
done with WPA and the IP address will be obtained with
DHCP:ifconfig_ath0="WPA DHCP"Then, we can bring up the interface:&prompt.root; /etc/rc.d/netif start
Starting wpa_supplicant.
DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 5
DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 6
DHCPOFFER from 192.168.0.1
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.1
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
protmode CTS roaming MANUAL bintval 100Or you can try to configure it manually using the
same /etc/wpa_supplicant.conf above, and
run:&prompt.root; wpa_supplicant -i ath0 -c /etc/wpa_supplicant.conf
Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz)
Associated with 00:11:95:c3:0d:ac
WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=TKIP GTK=TKIP]The next operation is the launch of the
dhclient command to get the IP
address from the DHCP server:&prompt.root; dhclient ath0
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.1
bound to 192.168.0.254 -- renewal in 300 seconds.
&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/48Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
protmode CTS roaming MANUAL bintval 100If the /etc/rc.conf is set up
with the line ifconfig_ath0="DHCP"
then it is no need to run the
dhclient command manually,
dhclient will be launched after
wpa_supplicant plumbs the
keys.In the case where the use of DHCP is not possible,
you can set a static IP address after
wpa_supplicant has authenticated the
station:&prompt.root; ifconfig ath0 inet 192.168.0.100 netmask 255.255.255.0
&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
protmode CTS roaming MANUAL bintval 100When DHCP is not used, you also have to manually set
up the default gateway and the nameserver:&prompt.root; route add default your_default_router
&prompt.root; echo "nameserver your_DNS_server" >> /etc/resolv.confWPA with EAP-TLSThe second way to use WPA is with an 802.1X backend
authentication server, in this case WPA is called
WPA-Enterprise to make difference with the less secure
WPA-Personal with its pre-shared key. The
authentication in WPA-Enterprise is based on EAP
(Extensible Authentication Protocol).EAP does not come with an encryption method, it was
decided to embed EAP inside an encrypted tunnel. Many
types of EAP authentication methods have been designed,
the most common methods are EAP-TLS, EAP-TTLS and
EAP-PEAP.EAP-TLS (EAP with Transport Layer Security) is a
very well-supported authentication protocol in the
wireless world since it was the first EAP method to be
certified by the Wi-Fi alliance.
EAP-TLS will require three certificates to run: the CA
certificate (installed on all machines), the server
certificate for your authentication server, and one
client certificate for each wireless client. In this
EAP method, both authentication server and wireless
client authenticate each other in presenting their
respective certificates, and they verify that these
certificates were signed by your organization's
certificate authority (CA).As previously, the configuration is done via
/etc/wpa_supplicant.conf:network={
ssid="freebsdap"
proto=RSN
key_mgmt=WPA-EAP
eap=TLS
identity="loader"
ca_cert="/etc/certs/cacert.pem"
client_cert="/etc/certs/clientcert.pem"
private_key="/etc/certs/clientkey.pem"
private_key_passwd="freebsdmallclient"
}This field indicates the network name
(SSID).Here, we use RSN (IEEE 802.11i) protocol, i.e.,
WPA2.The key_mgmt line refers to
the key management protocol we use. In our case it
is WPA using EAP authentication:
WPA-EAP.In this field, we mention the EAP method for our
connection.The identity field contains
the identity string for EAP.The ca_cert field indicates
the pathname of the CA certificate file. This file
is needed to verify the server certificate.The client_cert line gives
the pathname to the client certificate file. This
certificate is unique to each wireless client of the
network.The private_key field is the
pathname to the client certificate private key
file.The private_key_passwd field
contains the passphrase for the private key.Then add the following line to
/etc/rc.conf:ifconfig_ath0="WPA DHCP"The next step is to bring up the interface with the
help of the rc.d facility:&prompt.root; /etc/rc.d/netif start
Starting wpa_supplicant.
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
txpowmax 36 protmode CTS roaming MANUAL bintval 100As previously shown, it is also possible to bring up
the interface manually with both
wpa_supplicant and
ifconfig commands.WPA with EAP-TTLSWith EAP-TLS both the authentication server and the
client need a certificate, with EAP-TTLS (EAP-Tunneled
Transport Layer Security) a client certificate is
optional. This method is close to what some secure web
sites do , where the web server can create a secure SSL
tunnel even if the visitors do not have client-side
certificates. EAP-TTLS will use the encrypted TLS
tunnel for safe transport of the authentication
data.The configuration is done via the
/etc/wpa_supplicant.conf
file:network={
ssid="freebsdap"
proto=RSN
key_mgmt=WPA-EAP
eap=TTLS
identity="test"
password="test"
ca_cert="/etc/certs/cacert.pem"
phase2="auth=MD5"
}In this field, we mention the EAP method for our
connection.The identity field contains
the identity string for EAP authentication inside
the encrypted TLS tunnel.The password field contains
the passphrase for the EAP authentication.The ca_cert field indicates
the pathname of the CA certificate file. This file
is needed to verify the server certificat.In this field, we mention the authentication
method used in the encrypted TLS tunnel. In our
case, EAP with MD5-Challenge has been used. The
inner authentication phase is often
called phase2.You also have to add the following line to
/etc/rc.conf:ifconfig_ath0="WPA DHCP"The next step is to bring up the interface:&prompt.root; /etc/rc.d/netif start
Starting wpa_supplicant.
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
txpowmax 36 protmode CTS roaming MANUAL bintval 100WPA with EAP-PEAPPEAP (Protected EAP) has been designed as an
alternative to EAP-TTLS. There are two types of PEAP
methods, the most common one is PEAPv0/EAP-MSCHAPv2. In
the rest of this document, we will use the PEAP term to
refer to that EAP method. PEAP is the most used EAP
standard after EAP-TLS, in other words if you have a
network with mixed OSes, PEAP should be the most
supported standard after EAP-TLS.PEAP is similar to EAP-TTLS: it uses a server-side
certificate to authenticate clients by creating an
encrypted TLS tunnel between the client and the
authentication server, which protects the ensuing
exchange of authentication information. In term of
security the difference between EAP-TTLS and PEAP is
that PEAP authentication broadcasts the username in
clear, only the password is sent in the encrypted TLS
tunnel. EAP-TTLS will use the TLS tunnel for both
username and password.We have to edit the
/etc/wpa_supplicant.conf file and
add the EAP-PEAP related settings:network={
ssid="freebsdap"
proto=RSN
key_mgmt=WPA-EAP
eap=PEAP
identity="test"
password="test"
ca_cert="/etc/certs/cacert.pem"
phase1="peaplabel=0"
phase2="auth=MSCHAPV2"
}In this field, we mention the EAP method for our
connection.The identity field contains
the identity string for EAP authentication inside
the encrypted TLS tunnel.The password field contains
the passphrase for the EAP authentication.The ca_cert field indicates
the pathname of the CA certificate file. This file
is needed to verify the server certificat.This field contains the parameters for the
first phase of the authentication (the TLS
tunnel). According to the authentication server
used, you will have to specify a specific label
for the authentication. Most of time, the label
will be client EAP encryption which
is set by using peaplabel=0.
More information can be found in the
&man.wpa.supplicant.conf.5; manual page.In this field, we mention the authentication
protocol used in the encrypted TLS tunnel. In the
case of PEAP, it is
auth=MSCHAPV2.The following must be added to
/etc/rc.conf:ifconfig_ath0="WPA DHCP"Then, we can bring up the interface:&prompt.root; /etc/rc.d/netif start
Starting wpa_supplicant.
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
txpowmax 36 protmode CTS roaming MANUAL bintval 100WEPWEP (Wired Equivalent Privacy) is part of the original
802.11 standard. There is no authentication mechanism,
only a weak form of access control, and it is easily to be
cracked.WEP can be set up with
ifconfig:&prompt.root; ifconfig ath0 ssid my_net wepmode on weptxkey 3 wepkey 3:0x3456789012 \
inet 192.168.1.100 netmask 255.255.255.0The weptxkey means which WEP
key will be used in the transmission. Here we used the
third key. This must match the setting in the access
point. If you do not have any idea of what is the key
used by the access point, you should try to use
1 (i.e., the first key) for this
value.The wepkey means setting the
selected WEP key. It should in the format
index:key, if the index is
not given, key 1 is set. That is
to say we need to set the index if we use keys other
than the first key.You must replace
the 0x3456789012 with the key
configured for use on the access point.You are encouraged to read &man.ifconfig.8; manual
page for further information.The wpa_supplicant facility also
can be used to configure your wireless interface with WEP.
The example above can be set up by adding the following
lines to
/etc/wpa_supplicant.conf:network={
ssid="my_net"
key_mgmt=NONE
wep_key3=3456789012
wep_tx_keyidx=3
}Then:&prompt.root; wpa_supplicant -i ath0 -c /etc/wpa_supplicant.conf
Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz)
Associated with 00:13:46:49:41:76Ad-hoc ModeIBSS mode, also called ad-hoc mode, is designed for point
to point connections. For example, to establish an ad-hoc
network between the machine A and the machine
- B we will just need to choose two IP adresses
+ B we will just need to choose two IP addresses
and a SSID.On the box A:&prompt.root; ifconfig ath0 ssid freebsdap mediaopt adhoc inet 192.168.0.1 netmask 255.255.255.0
&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
ether 00:11:95:c3:0d:ac
media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>)
status: associated
ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac
authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100The adhoc parameter indicates the
interface is running in the IBSS mode.On B, we should be able to detect
A:&prompt.root; ifconfig ath0 up scan
SSID BSSID CHAN RATE S:N INT CAPS
freebsdap 02:11:95:c3:0d:ac 2 54M 19:3 100 ISThe I in the output confirms the
machine A is in ad-hoc mode. We just have to
configure B with a different IP
address:&prompt.root; ifconfig ath0 ssid freebsdap mediaopt adhoc inet 192.168.0.2 netmask 255.255.255.0
&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>)
status: associated
ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac
authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100Both A and B are now
ready to exchange informations.&os; Host Access Points&os; can act as an Access Point (AP) which eliminates the
need to buy a hardware AP or run an ad-hoc network. This can be
particularly useful when your &os; machine is acting as a
gateway to another network (e.g., the Internet).Basic SettingsBefore configuring your &os; machine as an AP, the
kernel must be configured with the appropriate wireless
networking support for your wireless card. You also have to
add the support for the security protocols you intend to
use. For more details, see .The use of the NDIS driver wrapper and the &windows;
drivers do not allow currently the AP operation. Only
native &os; wireless drivers support AP mode.Once the wireless networking support is loaded, you can
check if your wireless device supports the host-based access
point mode (also know as hostap mode):&prompt.root; ifconfig ath0 list caps
ath0=783ed0f<WEP,TKIP,AES,AES_CCM,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,TKIPMIC,WPA1,WPA2,BURST,WME>This output displays the card capabilities; the
HOSTAP word confirms this wireless card
can act as an Access Point. Various supported ciphers are
also mentioned: WEP, TKIP, WPA2, etc., these informations
are important to know what security protocols could be set
on the Access Point.The wireless device can now be put into hostap mode and
configured with the correct SSID and IP address:&prompt.root; ifconfig ath0 ssid freebsdap mode 11g mediaopt hostap inet 192.168.0.1 netmask 255.255.255.0Use again ifconfig to see the status
of the ath0 interface:&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
ether 00:11:95:c3:0d:ac
media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode OPEN privacy OFF txpowmax 38 bmiss 7 protmode CTS burst dtimperiod 1 bintval 100The hostap parameter indicates the
interface is running in the host-based access point
mode.The interface configuration can be done automatically at
boot time by adding the following line to
/etc/rc.conf:ifconfig_ath0="ssid freebsdap mode 11g mediaopt hostap inet 192.168.0.1 netmask 255.255.255.0"Host-based Access Point without Authentication or
EncryptionAlthough it is not recommended to run an AP without any
authentication or encryption, this is a simple way to check
if your AP is working. This configuration is also important
for debugging client issues.Once the AP configured as previously shown, it is
possible from another wireless machine to initiate a scan to
find the AP:&prompt.root; ifconfig ath0 up scan
SSID BSSID CHAN RATE S:N INT CAPS
freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 ESThe client machine found the Access Point and can be
associated with it:&prompt.root; ifconfig ath0 ssid freebsdap inet 192.168.0.2 netmask 255.255.255.0
&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
ether 00:11:95:d5:43:62
media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps)
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100WPA Host-based Access PointThis section will focus on setting up &os; Access Point
using the WPA security protocol. More details regarding WPA
and the configuration of WPA-based wireless clients can be
found in the .The hostapd daemon is used to
deal with client authentication and keys management on the
WPA enabled Access Point.In the following, all the configuration operations will
be performed on the &os; machine acting as AP. Once the
AP is correctly working, hostapd
should be automatically enabled at boot with the following
line in /etc/rc.conf:hostapd_enable="YES"Before trying to configure
hostapd, be sure you have done
the basic settings introduced in the .WPA-PSKWPA-PSK is intended for small networks where the use
of an backend authentication server is not possible or
desired.The configuration is done in the
/etc/hostapd.conf file:interface=ath0
debug=1
ctrl_interface=/var/run/hostapd
ctrl_interface_group=wheel
ssid=freebsdap
wpa=1
wpa_passphrase=freebsdmall
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP TKIP This field indicates the wireless interface used
for the Access Point.This field sets the level of verbosity during the
execution of hostapd. A
value of 1 represents the minimal
level.The ctrl_interface field gives
the pathname of the directory used by
hostapd to stores its
domain socket files for the communication with
external programs such as &man.hostapd.cli.8;. The
default value is used here.The ctrl_interface_group line
sets the group (here, it is the
wheel group) allowed to access
to the control interface files.This field sets the network name.The wpa field enables WPA and
specifies which WPA authentication protocol will be
required. A value of 1 configures the
AP for WPA-PSK.The wpa_passphrase field
contains the ASCII passphrase for the WPA
authentication.Always use strong passwords that are
sufficiently long and made from a rich alphabet so
they will not be guessed and/or attacked.The wpa_key_mgmt line refers to
the key management protocol we use. In our case it is
WPA-PSK.The wpa_pairwise field
indicates the set of accepted encryption algorithms by
the Access Point. Here both TKIP (WPA) and CCMP
(WPA2) ciphers are accepted. CCMP cipher is an
alternative to TKIP and that is strongly preferred
when possible; TKIP should be used solely for stations
incapable of doing CCMP.The next step is to start
hostapd:&prompt.root /etc/rc.d/hostapd forcestart&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 2290
inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
ether 00:11:95:c3:0d:ac
media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100The Access Point is running, the clients can now be
associated with it, see for more details. It is
possible to see the stations associated with the AP using
the ifconfig ath0 list
sta command.WEP Host-based Access PointIt is not recommended to use WEP for setting up an
Access Point since there is no authentication mechanism and
it is easily to be cracked. Some legacy wireless cards only
support WEP as security protocol, these cards will only
allow to set up AP without authentication or encryption or
using the WEP protocol.The wireless device can now be put into hostap mode and
configured with the correct SSID and IP address:&prompt.root; ifconfig ath0 ssid freebsdap wepmode on weptxkey 3 wepkey 3:0x3456789012 mode 11g mediaopt hostap \
inet 192.168.0.1 netmask 255.255.255.0The weptxkey means which WEP
key will be used in the transmission. Here we used the
third key (note that the key numbering starts with
1). This parameter must be specified
to really encrypt the data.The wepkey means setting the
selected WEP key. It should in the format
index:key, if the index is
not given, key 1 is set. That is
to say we need to set the index if we use keys other
than the first key.Use again ifconfig to see the status
of the ath0 interface:&prompt.root; ifconfig ath0
ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
ether 00:11:95:c3:0d:ac
media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap>
status: associated
ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100From another wireless machine, it is possible to initiate
a scan to find the AP:&prompt.root; ifconfig ath0 up scan
SSID BSSID CHAN RATE S:N INT CAPS
freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPSThe client machine found the Access Point and can be
associated with it using the correct parameters (key, etc.),
see for more
details.TroubleshootingIf you are having trouble with wireless networking, there
are a number of steps you can take to help troubleshoot the
problem.If you do not see the access point listed when
scanning be sure you have not configured your wireless
device to a limited set of channels.If you cannot associate to an access point verify the
configuration of your station matches the one of the
access point. This includes the authentication scheme and
any security protocols. Simplify your configuration as
much as possible. If you are using a security protocol
such as WPA or WEP configure the access point for open
authentication and no security to see if you can get
traffic to pass.Once you can associate to the access point diagnose
any security configuration using simple tools like
&man.ping.8;.The wpa_supplicant has much
debugging support; try running it manually with the
option and look at the system
logs.There are also many lower-level debugging tools. You
can enable debugging messages in the 802.11 protocol
support layer using the wlandebug
program found in
/usr/src/tools/tools/net80211. For
example:&prompt.root; wlandebug -i ath0 +scan+auth+debug+assoc
net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan>can be used to enable console messages related to
scanning for access points and doing the 802.11 protocol
handshakes required to arrange communication.There are also many useful statistics maintained by
the 802.11 layer; the wlanstats tool
will dump these informations. These statistics should
identify all errors identified by the 802.11 layer.
Beware however that some errors are identified in the
device drivers that lie below the 802.11 layer so they may
not show up. To diagnose device-specific problems you
need to refer to the drivers' documentation.If the above information does not help to clarify the
problem, please submit a problem report and include output
from the above tools.PavLucistnikWritten by pav@FreeBSD.orgBluetoothBluetoothIntroductionBluetooth is a wireless technology for creating personal networks
operating in the 2.4 GHz unlicensed band, with a range of 10 meters.
Networks are usually formed ad-hoc from portable devices such as
cellular phones, handhelds and laptops. Unlike the other popular
wireless technology, Wi-Fi, Bluetooth offers higher level service
profiles, e.g. FTP-like file servers, file pushing, voice transport,
serial line emulation, and more.The Bluetooth stack in &os; is implemented using the Netgraph
framework (see &man.netgraph.4;). A broad variety of Bluetooth USB
dongles is supported by the &man.ng.ubt.4; driver. The Broadcom BCM2033
chip based Bluetooth devices are supported via the &man.ubtbcmfw.4; and
&man.ng.ubt.4; drivers. The 3Com Bluetooth PC Card 3CRWB60-A is
supported by the &man.ng.bt3c.4; driver. Serial and UART based
Bluetooth devices are supported via &man.sio.4;, &man.ng.h4.4;
and &man.hcseriald.8;. This section describes the use of the USB
Bluetooth dongle.Plugging in the DeviceBy default Bluetooth device drivers are available as kernel modules.
Before attaching a device, you will need to load the driver into the
kernel:&prompt.root; kldload ng_ubtIf the Bluetooth device is present in the system during system
startup, load the module from
/boot/loader.conf:ng_ubt_load="YES"Plug in your USB dongle. The output similar to the following will
appear on the console (or in syslog):ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
wMaxPacketSize=49, nframes=6, buffer size=294The /etc/rc.d/bluetooth script
is used to start and stop the Bluetooth stack. It is a good
idea to stop the stack before unplugging the device, but it is not
(usually) fatal. When starting the stack, you will receive output similar
to the following:&prompt.root; /etc/rc.d/bluetooth start ubt0
BD_ADDR: 00:02:72:00:d4:1a
Features: 0xff 0xff 0xf 00 00 00 00 00
<3-Slot> <5-Slot> <Encryption> <Slot offset>
<Timing accuracy> <Switch> <Hold mode> <Sniff mode>
<Park mode> <RSSI> <Channel quality> <SCO link>
<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD>
<Paging scheme> <Power control> <Transparent SCO data>
Max. ACL packet size: 192 bytes
Number of ACL packets: 8
Max. SCO packet size: 64 bytes
Number of SCO packets: 8HCIHost Controller Interface (HCI)Host Controller Interface (HCI) provides a command interface to the
baseband controller and link manager, and access to hardware status and
control registers. This interface provides a uniform method of accessing
the Bluetooth baseband capabilities. HCI layer on the Host exchanges
data and commands with the HCI firmware on the Bluetooth hardware.
The Host Controller Transport Layer (i.e. physical bus) driver provides
both HCI layers with the ability to exchange information with each
other.A single Netgraph node of type hci is
created for a single Bluetooth device. The HCI node is normally
connected to the Bluetooth device driver node (downstream) and
the L2CAP node (upstream). All HCI operations must be performed
on the HCI node and not on the device driver node. Default name
for the HCI node is devicehci.
For more details refer to the &man.ng.hci.4; manual page.One of the most common tasks is discovery of Bluetooth devices in
RF proximity. This operation is called inquiry.
Inquiry and other HCI related operations are done with the
&man.hccontrol.8; utility. The example below shows how to find out
which Bluetooth devices are in range. You should receive the list of
devices in a few seconds. Note that a remote device will only answer
the inquiry if it put into discoverable
mode.&prompt.user; hccontrol -n ubt0hci inquiry
Inquiry result, num_responses=1
Inquiry result #0
BD_ADDR: 00:80:37:29:19:a4
Page Scan Rep. Mode: 0x1
Page Scan Period Mode: 00
Page Scan Mode: 00
Class: 52:02:04
Clock offset: 0x78ef
Inquiry complete. Status: No error [00]BD_ADDR is unique address of a Bluetooth
device, similar to MAC addresses of a network card. This address
is needed for further communication with a device. It is possible
to assign human readable name to a BD_ADDR.
The /etc/bluetooth/hosts file contains information
regarding the known Bluetooth hosts. The following example shows how
to obtain human readable name that was assigned to the remote
device:&prompt.user; hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4
BD_ADDR: 00:80:37:29:19:a4
Name: Pav's T39If you perform an inquiry on a remote Bluetooth device, it will
find your computer as your.host.name (ubt0). The name
assigned to the local device can be changed at any time.The Bluetooth system provides a point-to-point connection (only two
Bluetooth units involved), or a point-to-multipoint connection. In the
point-to-multipoint connection the connection is shared among several
Bluetooth devices. The following example shows how to obtain the list
of active baseband connections for the local device:&prompt.user; hccontrol -n ubt0hci read_connection_list
Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPENA connection handle is useful when termination
of the baseband connection is required. Note, that it is normally not
required to do it by hand. The stack will automatically terminate
inactive baseband connections.&prompt.root; hccontrol -n ubt0hci disconnect 41
Connection handle: 41
Reason: Connection terminated by local host [0x16]Refer to hccontrol help for a complete listing
of available HCI commands. Most of the HCI commands do not require
superuser privileges.L2CAPLogical Link Control and Adaptation Protocol (L2CAP)Logical Link Control and Adaptation Protocol (L2CAP) provides
connection-oriented and connectionless data services to upper layer
protocols with protocol multiplexing capability and segmentation and
reassembly operation. L2CAP permits higher level protocols and
applications to transmit and receive L2CAP data packets up to 64
kilobytes in length.L2CAP is based around the concept of channels.
Channel is a logical connection on top of baseband connection. Each
channel is bound to a single protocol in a many-to-one fashion. Multiple
channels can be bound to the same protocol, but a channel cannot be
bound to multiple protocols. Each L2CAP packet received on a channel is
directed to the appropriate higher level protocol. Multiple channels
can share the same baseband connection.A single Netgraph node of type l2cap is
created for a single Bluetooth device. The L2CAP node is normally
connected to the Bluetooth HCI node (downstream) and Bluetooth sockets
nodes (upstream). Default name for the L2CAP node is
devicel2cap. For more details refer to the
&man.ng.l2cap.4; manual page.A useful command is &man.l2ping.8;, which can be used to ping
other devices. Some Bluetooth implementations might not return all of
the data sent to them, so 0 bytes in the following
example is normal.&prompt.root; l2ping -a 00:80:37:29:19:a4
0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0The &man.l2control.8; utility is used to perform various operations
on L2CAP nodes. This example shows how to obtain the list of logical
connections (channels) and the list of baseband connections for the
local device:&prompt.user; l2control -a 00:02:72:00:d4:1a read_channel_list
L2CAP channels:
Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State
00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN
&prompt.user; l2control -a 00:02:72:00:d4:1a read_connection_list
L2CAP connections:
Remote BD_ADDR Handle Flags Pending State
00:07:e0:00:0b:ca 41 O 0 OPENAnother diagnostic tool is &man.btsockstat.1;. It does a job
similar to as &man.netstat.1; does, but for Bluetooth network-related
data structures. The example below shows the same logical connection as
&man.l2control.8; above.&prompt.user; btsockstat
Active L2CAP sockets
PCB Recv-Q Send-Q Local address/PSM Foreign address CID State
c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN
Active RFCOMM sessions
L2PCB PCB Flag MTU Out-Q DLCs State
c2afe900 c2b53380 1 127 0 Yes OPEN
Active RFCOMM sockets
PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State
c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPENRFCOMMRFCOMM ProtocolThe RFCOMM protocol provides emulation of serial ports over the
L2CAP protocol. The protocol is based on the ETSI standard TS 07.10.
RFCOMM is a simple transport protocol, with additional provisions for
emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The
RFCOMM protocol supports up to 60 simultaneous connections (RFCOMM
channels) between two Bluetooth devices.For the purposes of RFCOMM, a complete communication path involves
two applications running on different devices (the communication
endpoints) with a communication segment between them. RFCOMM is intended
to cover applications that make use of the serial ports of the devices
in which they reside. The communication segment is a Bluetooth link from
one device to another (direct connect).RFCOMM is only concerned with the connection between the devices in
the direct connect case, or between the device and a modem in the
network case. RFCOMM can support other configurations, such as modules
that communicate via Bluetooth wireless technology on one side and
provide a wired interface on the other side.In &os; the RFCOMM protocol is implemented at the Bluetooth sockets
layer.pairingPairing of DevicesBy default, Bluetooth communication is not authenticated, and any
device can talk to any other device. A Bluetooth device (for example,
cellular phone) may choose to require authentication to provide a
particular service (for example, Dial-Up service). Bluetooth
authentication is normally done with PIN codes.
A PIN code is an ASCII string up to 16 characters in length. User is
required to enter the same PIN code on both devices. Once user has
entered the PIN code, both devices will generate a
link key. After that the link key can be stored
either in the devices themselves or in a persistent storage. Next time
both devices will use previously generated link key. The described
above procedure is called pairing. Note that if
the link key is lost by any device then pairing must be repeated.The &man.hcsecd.8; daemon is responsible for handling of all
Bluetooth authentication requests. The default configuration file is
/etc/bluetooth/hcsecd.conf. An example section for
a cellular phone with the PIN code arbitrarily set to
1234 is shown below:device {
bdaddr 00:80:37:29:19:a4;
name "Pav's T39";
key nokey;
pin "1234";
}There is no limitation on PIN codes (except length). Some devices
(for example Bluetooth headsets) may have a fixed PIN code built in.
The switch forces the &man.hcsecd.8; daemon to stay
in the foreground, so it is easy to see what is happening. Set the
remote device to receive pairing and initiate the Bluetooth connection
to the remote device. The remote device should say that pairing was
accepted, and request the PIN code. Enter the same PIN code as you
have in hcsecd.conf. Now your PC and the remote
device are paired. Alternatively, you can initiate pairing on the remote
device.On &os; 5.5, 6.1 and newer, the following line can be added to the
/etc/rc.conf file to have
hcsecd started automatically on system
start:hcsecd_enable="YES"The following is a sample of the
hcsecd daemon output:hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4SDPService Discovery Protocol (SDP)The Service Discovery Protocol (SDP) provides the means for client
applications to discover the existence of services provided by server
applications as well as the attributes of those services. The attributes
of a service include the type or class of service offered and the
mechanism or protocol information needed to utilize the service.SDP involves communication between a SDP server and a SDP client.
The server maintains a list of service records that describe the
characteristics of services associated with the server. Each service
record contains information about a single service. A client may
retrieve information from a service record maintained by the SDP server
by issuing a SDP request. If the client, or an application associated
with the client, decides to use a service, it must open a separate
connection to the service provider in order to utilize the service.
SDP provides a mechanism for discovering services and their attributes,
but it does not provide a mechanism for utilizing those services.Normally, a SDP client searches for services based on some desired
characteristics of the services. However, there are times when it is
desirable to discover which types of services are described by an SDP
server's service records without any a priori information about the
services. This process of looking for any offered services is called
browsing.The Bluetooth SDP server &man.sdpd.8; and command line client
&man.sdpcontrol.8; are included in the standard &os; installation.
The following example shows how to perform a SDP browse query.&prompt.user; sdpcontrol -a 00:01:03:fc:6e:ec browse
Record Handle: 00000000
Service Class ID List:
Service Discovery Server (0x1000)
Protocol Descriptor List:
L2CAP (0x0100)
Protocol specific parameter #1: u/int/uuid16 1
Protocol specific parameter #2: u/int/uuid16 1
Record Handle: 0x00000001
Service Class ID List:
Browse Group Descriptor (0x1001)
Record Handle: 0x00000002
Service Class ID List:
LAN Access Using PPP (0x1102)
Protocol Descriptor List:
L2CAP (0x0100)
RFCOMM (0x0003)
Protocol specific parameter #1: u/int8/bool 1
Bluetooth Profile Descriptor List:
LAN Access Using PPP (0x1102) ver. 1.0
... and so on. Note that each service has a list of attributes
(RFCOMM channel for example). Depending on the service you might need to
make a note of some of the attributes. Some Bluetooth implementations do
not support service browsing and may return an empty list. In this case
it is possible to search for the specific service. The example below
shows how to search for the OBEX Object Push (OPUSH) service:&prompt.user; sdpcontrol -a 00:01:03:fc:6e:ec search OPUSHOffering services on &os; to Bluetooth clients is done with the
&man.sdpd.8; server. On &os; 5.5, 6.1 and newer, the following line can
be added to the /etc/rc.conf file:sdpd_enable="YES"Then the sdpd daemon can be started with:&prompt.root; /etc/rc.d/sdpd startThe local server application that wants to provide Bluetooth
service to the remote clients will register service with the local
SDP daemon. The example of such application is &man.rfcomm.pppd.8;.
Once started it will register Bluetooth LAN service with the local
SDP daemon.The list of services registered with the local SDP server can be
obtained by issuing SDP browse query via local control channel:&prompt.root; sdpcontrol -l browseDial-Up Networking (DUN) and Network Access with PPP (LAN)
ProfilesThe Dial-Up Networking (DUN) profile is mostly used with modems
and cellular phones. The scenarios covered by this profile are the
following:use of a cellular phone or modem by a computer as
a wireless modem for connecting to a dial-up Internet access server,
or using other dial-up services;use of a cellular phone or modem by a computer to
receive data calls.Network Access with PPP (LAN) profile can be used in the following
situations:LAN access for a single Bluetooth device;
LAN access for multiple Bluetooth devices;
PC to PC (using PPP networking over serial cable
emulation).In &os; both profiles are implemented with &man.ppp.8; and
&man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth
connection into something PPP can operate with. Before any profile
can be used, a new PPP label in the /etc/ppp/ppp.conf
must be created. Consult &man.rfcomm.pppd.8; manual page for examples.
In the following example &man.rfcomm.pppd.8; will be used to open
RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on
DUN RFCOMM channel. The actual RFCOMM channel number will be obtained
from the remote device via SDP. It is possible to specify RFCOMM channel
by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP
query. Use &man.sdpcontrol.8; to find out RFCOMM
channel on the remote device.&prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialupIn order to provide Network Access with PPP (LAN) service the
&man.sdpd.8; server must be running. A new entry for LAN clients must
be created in the /etc/ppp/ppp.conf file. Consult
&man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP
server on valid RFCOMM channel number. The RFCOMM PPP server will
automatically register Bluetooth LAN service with the local SDP daemon.
The example below shows how to start RFCOMM PPP server.&prompt.root; rfcomm_pppd -s -C 7 -l rfcomm-serverOBEXOBEX Object Push (OPUSH) ProfileOBEX is a widely used protocol for simple file transfers between
mobile devices. Its main use is in infrared communication, where it is
used for generic file transfers between notebooks or PDAs,
and for sending business cards or calendar entries between cellular
phones and other devices with PIM applications.The OBEX server and client are implemented as a third-party package
obexapp, which is available as
comms/obexapp port.OBEX client is used to push and/or pull objects from the OBEX server.
An object can, for example, be a business card or an appointment.
The OBEX client can obtain RFCOMM channel number from the remote device
via SDP. This can be done by specifying service name instead of RFCOMM
channel number. Supported service names are: IrMC, FTRN and OPUSH.
It is possible to specify RFCOMM channel as a number. Below is an
example of an OBEX session, where device information object is pulled
from the cellular phone, and a new object (business card) is pushed
into the phone's directory.&prompt.user; obexapp -a 00:80:37:29:19:a4 -C IrMC
obex> get telecom/devinfo.txt devinfo-t39.txt
Success, response: OK, Success (0x20)
obex> put new.vcf
Success, response: OK, Success (0x20)
obex> di
Success, response: OK, Success (0x20)In order to provide OBEX Object Push service,
&man.sdpd.8; server must be running. A root folder, where all incoming
objects will be stored, must be created. The default path to the root
folder is /var/spool/obex. Finally, start OBEX
server on valid RFCOMM channel number. The OBEX server will
automatically register OBEX Object Push service with the local SDP
daemon. The example below shows how to start OBEX server.&prompt.root; obexapp -s -C 10Serial Port Profile (SPP)The Serial Port Profile (SPP) allows Bluetooth devices to perform
RS232 (or similar) serial cable emulation. The scenario covered by this
profile deals with legacy applications using Bluetooth as a cable
replacement, through a virtual serial port abstraction.The &man.rfcomm.sppd.1; utility implements the Serial Port profile.
A pseudo tty is used as a virtual serial port abstraction. The example
below shows how to connect to a remote device Serial Port service.
Note that you do not have to specify a RFCOMM channel -
&man.rfcomm.sppd.1; can obtain it from the remote device via SDP.
If you would like to override this, specify a RFCOMM channel on the
command line.&prompt.root; rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6
rfcomm_sppd[94692]: Starting on /dev/ttyp6...Once connected, the pseudo tty can be used as serial port:&prompt.root; cu -l ttyp6TroubleshootingA remote device cannot connectSome older Bluetooth devices do not support role switching.
By default, when &os; is accepting a new connection, it tries to
perform a role switch and become master. Devices, which do not
support this will not be able to connect. Note that role switching is
performed when a new connection is being established, so it is not
possible to ask the remote device if it does support role switching.
There is a HCI option to disable role switching on the local
side:&prompt.root; hccontrol -n ubt0hci write_node_role_switch 0Something is going wrong, can I see what exactly is happening?Yes, you can. Use the third-party package
hcidump, which is available as
comms/hcidump port.
The hcidump utility is similar to
&man.tcpdump.1;. It can be used to display the content of the Bluetooth
packets on the terminal and to dump the Bluetooth packets to a
file.AndrewThompsonWritten by BridgingIntroductionIP subnetbridgeIt is sometimes useful to divide one physical network
(such as an Ethernet segment) into two separate network
segments without having to create IP subnets and use a router
to connect the segments together. A device that connects two
networks together in this fashion is called a
bridge. A FreeBSD system with two network
interface cards can act as a bridge.The bridge works by learning the MAC layer addresses
(Ethernet addresses) of the devices on each of its network interfaces.
It forwards traffic between two networks only when its source and
destination are on different networks.In many respects, a bridge is like an Ethernet switch with very
few ports.Situations Where Bridging Is AppropriateThere are many common situations in which a bridge is used
today.Connecting NetworksThe basic operation of a bridge is to join two or more
network segments together. There are many reasons to use a
host based bridge over plain networking equipment such as
cabling constraints, firewalling or connecting pseudo
networks such as a Virtual Machine interface. A bridge can
also connect a wireless interface running in hostap mode to
a wired network and act as an access point.Filtering/Traffic Shaping FirewallfirewallNATA common situation is where firewall functionality is
needed without routing or network address translation (NAT).An example is a small company that is connected via DSL
or ISDN to their ISP. They have a 13 globally-accessible IP
addresses from their ISP and have 10 PCs on their network.
In this situation, using a router-based firewall is
difficult because of subnetting issues.routerDSLISDNA bridge-based firewall can be configured and dropped into the
path just downstream of their DSL/ISDN router without any IP
numbering issues.Network TapA bridge can join two network segments and be used to
inspect all Ethernet frames that pass between them. This can
either be from using &man.bpf.4;/&man.tcpdump.1; on the
bridge interface or by sending a copy of all frames out an
additional interface (span port).Layer 2 VPNTwo Ethernet networks can be joined across an IP link by
bridging the networks to an EtherIP tunnel or a &man.tap.4;
based solution such as OpenVPN.Layer 2 RedundancyA network can be connected together with multiple links
and use the Spanning Tree Protocol to block redundant paths.
For an Ethernet network to function properly only one active
path can exist between two devices, Spanning Tree will
detect loops and put the redundant links into a blocked
state. Should one of the active links fail then the
protocol will calculate a different tree and reenable one of
the blocked paths to restore connectivity to all points in
the network.Kernel ConfigurationThis section covers &man.if.bridge.4; bridge
implementation, a netgraph bridging driver is also available,
for more information see &man.ng.bridge.4; manual page.The bridge driver is a kernel module and will be
automatically loaded by &man.ifconfig.8; when creating a
bridge interface. It is possible to compile the bridge in to
the kernel by adding device if_bridge to
your kernel configuration file.Packet filtering can be used with any firewall package
that hooks in via the &man.pfil.9; framework. The firewall
can be loaded as a module or compiled into the kernel.The bridge can be used as a traffic shaper with
&man.altq.4; or &man.dummynet.4;.Enabling the BridgeThe bridge is created using interface cloning. To create
a bridge use &man.ifconfig.8;, if the bridge driver is not
present in the kernel then it will be loaded
automatically.&prompt.root; ifconfig bridge create
bridge0
&prompt.root; ifconfig bridge0
bridge0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500
ether 96:3d:4b:f1:79:7a
id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15
maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0A bridge interface is created and is automatically
assigned a randomly generated Ethernet address. The
maxaddr and timeout
parameters control how many MAC addresses the bridge will keep
in its forwarding table and how many seconds before each entry
is removed after it is last seen. The other parameters
control how Spanning Tree operates.Add the member network interfaces to the bridge. For the
bridge to forward packets all member interfaces and the bridge
need to be up:&prompt.root; ifconfig bridge0 addm fxp0 addm fxp1 up
&prompt.root; ifconfig fxp0 up
&prompt.root; ifconfig fxp1 upThe bridge is now forwarding Ethernet frames between
fxp0 and
fxp1. The equivalent configuration
in /etc/rc.conf so the bridge is created
at startup is:cloned_interfaces="bridge0"
ifconfig_bridge0="addm fxp0 addm fxp1 up"
ifconfig_fxp0="up"
ifconfig_fxp1="up"If the bridge host needs an IP address then the correct
place to set this is on the bridge interface itself rather
than one of the member interfaces. This can be set statically
or via DHCP:&prompt.root; ifconfig bridge0 inet 192.168.0.1/24It is also possible to assign an IPv6 address to a bridge
interface.FirewallingfirewallWhen packet filtering is enabled, bridged packets will
pass through the filter inbound on the originating interface,
on the bridge interface and outbound on the appropriate
interfaces. Either stage can be disabled. When direction of
the packet flow is important it is best to firewall on the
member interfaces rather than the bridge itself.The bridge has several configurable settings for passing
non-IP and ARP packets, and layer2 firewalling with IPFW. See
&man.if.bridge.4; for more information.Spanning TreeThe bridge driver implements the Rapid Spanning Tree
Protocol (RSTP or 802.1w) with backwards compatibility with
the legacy Spanning Tree Protocol (STP). Spanning Tree is
used to detect and remove loops in a network topology. RSTP
provides faster Spanning Tree convergence than legacy STP, the
protocol will exchange information with neighbouring switches
to quickly transition to forwarding without creating
loops.The following table shows the supported operating
modes:OS VersionSTP ModesDefault Mode&os; 5.4—&os; 6.2STPSTP&os; 6.3+RSTP or STPSTP&os; 7.0+RSTP or STPRSTPSpanning Tree can be enabled on member interfaces using
the stp command. For a bridge with
fxp0 and
fxp1 as the current interfaces,
enable STP with the following:&prompt.root; ifconfig bridge0 stp fxp0 stp fxp1
bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
ether d6:cf:d5:a0:94:6d
id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15
maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0
member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
port 3 priority 128 path cost 200000 proto rstp
role designated state forwarding
member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
port 4 priority 128 path cost 200000 proto rstp
role designated state forwardingThis bridge has a spanning tree ID of
00:01:02:4b:d4:50 and a priority of
32768. As the root id
is the same it indicates that this is the root bridge for the
tree.Another bridge on the network also has spanning tree
enabled:bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
ether 96:3d:4b:f1:79:7a
id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15
maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4
member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
port 4 priority 128 path cost 200000 proto rstp
role root state forwarding
member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP>
port 5 priority 128 path cost 200000 proto rstp
role designated state forwardingThe line root id 00:01:02:4b:d4:50 priority 32768
ifcost 400000 port 4 shows that the root bridge is
00:01:02:4b:d4:50 as above and has a path
cost of 400000 from this bridge, the path
to the root bridge is via port 4 which is
fxp0.Advanced BridgingReconstruct Traffic FlowsThe bridge supports monitor mode, where the packets are
discarded after &man.bpf.4; processing, and are not
processed or forwarded further. This can be used to
multiplex the input of two or more interfaces into a single
&man.bpf.4; stream. This is useful for reconstructing the
traffic for network taps that transmit the RX/TX signals out
through two separate interfaces.To read the input from four network interfaces as one
stream:&prompt.root; ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up
&prompt.root; tcpdump -i bridge0Span PortsA copy of every Ethernet frame received by the bridge
will be transmitted out a designated span port. The number
of span ports configured on a bridge is unlimited, if an
interface is designated as a span port then it may not also
be used as a regular bridge port. This is most useful for
snooping a bridged network passively on another host
connected to one of the span ports of the bridge.To send a copy of all frames out the interface named
fxp4:&prompt.root; ifconfig bridge0 span fxp4Private InterfacesA private interface does not forward any traffic to any
other port that is also a private interface. The traffic is
blocked unconditionally so no Ethernet frames will be
forwarded, including ARP. If traffic needs to be
selectively blocked then a firewall should be used
instead.Sticky InterfacesIf a bridge member interface is marked as sticky then
dynamically learned address entries are treated at static once
entered into the forwarding cache. Sticky entries are never
aged out of the cache or replaced, even if the address is seen
on a different interface. This gives the benefit of static
address entries without the need to pre-populate the
forwarding table, clients learnt on a particular segment of
the bridge can not roam to another segment.Another example of using sticky addresses would be to
combine the bridge with VLANs to create a router where
customer networks are isolated without wasting IP address
space. Consider that CustomerA is on
vlan100 and CustomerB is on
vlan101. The bridge has the address
192.168.0.1 and is also an
internet router.&prompt.root; ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101
&prompt.root; ifconfig bridge0 inet 192.168.0.1/24Both clients see 192.168.0.1 as their default gateway
and since the bridge cache is sticky they can not spoof the
MAC address of the other customer to intercept their
traffic.Any communication between the VLANs can be blocked using
private interfaces (or a firewall):&prompt.root; ifconfig bridge0 private vlan100 private vlan101The customers are completely isolated from each other,
the full /24 address range
can be allocated without subnetting.Address limitsThe number of unique source MAC addresses behind an
interface can be limited. Once the limit is reached packets
with unknown source addresses are dropped until an
existing host cache entry expires or is removed.The following example sets the maximum number of Ethernet
devices for CustomerA on
vlan100 to 10.&prompt.root; ifconfig bridge0 ifmaxaddr vlan100 10SNMP MonitoringThe bridge interface and STP parameters can be monitored
via the SNMP daemon which is included in the &os; base
system. The exported bridge MIBs conform to the IETF
standards so any SNMP client or monitoring package can be
used to retrieve the data.On the bridge machine uncomment the
begemotSnmpdModulePath."bridge" =
"/usr/lib/snmp_bridge.so" line from
/etc/snmp.config and start the
bsnmpd daemon. Other
configuration such as community names and access lists may
need to be modified. See &man.bsnmpd.1; and
&man.snmp.bridge.3; for more information.The following examples use the
Net-SNMP software (net-mgmt/net-snmp) to query a
bridge, the net-mgmt/bsnmptools port can also
be used. From the SNMP client host add to
$HOME/.snmp/snmp.conf the following
lines to import the bridge MIB definitions in to
Net-SNMP:mibdirs +/usr/share/snmp/mibs
mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIBTo monitor a single bridge via the IETF BRIDGE-MIB
(RFC4188) do&prompt.user; snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge
BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44
BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports
BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds
BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2
BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50
...
BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5)
BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1)
BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000
BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0
BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80
BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1
RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)The dot1dStpTopChanges.0 value is two
which means that the STP bridge topology has changed twice,
a topology change means that one or more links in the
network have changed or failed and a new tree has been
calculated. The
dot1dStpTimeSinceTopologyChange.0 value
will show when this happened.To monitor multiple bridge interfaces one may use the
private BEGEMOT-BRIDGE-MIB:&prompt.user; snmpwalk -v 2c -c public bridge1.example.com
enterprises.fokus.begemot.begemotBridge
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1
...
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1
BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31
BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9To change the bridge interface being monitored via the
mib-2.dot1dBridge subtree do:&prompt.user; snmpset -v 2c -c private bridge1.example.com
BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2AndrewThompsonWritten by Link Aggregation and FailoverlaggfailoverfeclacploadbalanceroundrobinIntroductionThe &man.lagg.4; interface allows aggregation of multiple network
interfaces as one virtual interface for the purpose of providing
fault-tolerance and high-speed links.Operating ModesfailoverSends and receives traffic only through the master port. If the
master port becomes unavailable, the next active port is used. The
first interface added is the master port; any interfaces added after
that are used as failover devices.fecSupports Cisco EtherChannel. This is a static setup and does not
negotiate aggregation with the peer or exchange frames to monitor the
link, if the switch supports LACP then that should be used
instead.Balances outgoing traffic across the active ports based on hashed
protocol header information and accepts incoming traffic from any
active port. The hash includes the Ethernet source and destination
address, and, if available, the VLAN tag, and the IPv4/IPv6 source
and destination address.lacpSupports the IEEE 802.3ad Link Aggregation Control Protocol
(LACP) and the Marker Protocol. LACP will negotiate a set of
aggregable links with the peer in to one or more Link Aggregated
Groups. Each LAG is composed of ports of the same speed, set to
full-duplex operation. The traffic will be balanced across the ports
in the LAG with the greatest total speed, in most cases there will
only be one LAG which contains all ports. In the event of changes in
physical connectivity, Link Aggregation will quickly converge to a
new configuration.Balances outgoing traffic across the active ports based on hashed
protocol header information and accepts incoming traffic from any
active port. The hash includes the Ethernet source and destination
address, and, if available, the VLAN tag, and the IPv4/IPv6 source
and destination address.loadbalanceThis is an alias of fec mode.roundrobinDistributes outgoing traffic using a round-robin scheduler
through all active ports and accepts incoming traffic from any active
port. This mode will violate Ethernet frame ordering and should be
used with caution.ExamplesLACP aggregation with a Cisco switchThis example connects two interfaces on a &os; machine to the
switch as a single load balanced and fault tolerant link. More interfaces
can be added to increase throughput and fault tolerance. Since frame
ordering is mandatory on Ethernet links then any traffic between two
stations always flows over the same physical link limiting the maximum
speed to that of one interface. The transmit algorithm attempts to use as
much information as it can to distinguish different traffic flows and
balance across the available interfaces.On the Cisco switch add the interfaces to the channel group.interface FastEthernet0/1
channel-group 1 mode active
channel-protocol lacp
!
interface FastEthernet0/2
channel-group 1 mode active
channel-protocol lacp
!On the &os; machine create the lagg interface.&prompt.root; ifconfig lagg0 create
&prompt.root; ifconfig lagg0 up laggproto lacp laggport fxp0 laggport fxp1View the interface status from ifconfig; ports marked as
ACTIVE are part of the active aggregation group
that has been negotiated with the remote switch and traffic will be
transmitted and received. Use the verbose output of &man.ifconfig.8;
to view the LAG identifiers.lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
options=8<VLAN_MTU>
ether 00:05:5d:71:8d:b8
media: Ethernet autoselect
status: active
laggproto lacp
laggport: fxp1 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING>
laggport: fxp0 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING>The switch will show which ports are active. For more detail use
show lacp neighbor detail.switch# show lacp neighbor
Flags: S - Device is requesting Slow LACPDUs
F - Device is requesting Fast LACPDUs
A - Device is in Active mode P - Device is in Passive mode
Channel group 1 neighbors
Partner's information:
LACP port Oper Port Port
Port Flags Priority Dev ID Age Key Number State
Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D
Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3DFailover modeFailover mode can be used to switch over to another interface if
the link is lost on the master.&prompt.root; ifconfig lagg0 create
&prompt.root; ifconfig lagg0 up laggproto failover laggport fxp0 laggport fxp1lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
options=8<VLAN_MTU>
ether 00:05:5d:71:8d:b8
media: Ethernet autoselect
status: active
laggproto failover
laggport: fxp1 flags=0<>
laggport: fxp0 flags=5<MASTER,ACTIVE>Traffic will be transmitted and received on
fxp0. If the link is lost on
fxp0 then fxp1 will
become the active link. If the link is restored on the master
interface then it will once again become the active link.Jean-FrançoisDockèsUpdated by AlexDupreReorganized and enhanced by Diskless Operationdiskless workstationdiskless operationA FreeBSD machine can boot over the network and operate without a
local disk, using file systems mounted from an NFS server. No system
modification is necessary, beyond standard configuration files.
Such a system is relatively easy to set up because all the necessary elements
are readily available:There are at least two possible methods to load the kernel over
the network:PXE: The &intel; Preboot eXecution
Environment system is a form of smart boot ROM built into some
networking cards or motherboards. See &man.pxeboot.8; for more
details.The Etherboot
port (net/etherboot) produces
ROM-able code to boot kernels over the network. The
code can be either burnt into a boot PROM on a network
card, or loaded from a local floppy (or hard) disk
drive, or from a running &ms-dos; system. Many network
cards are supported.A sample script
(/usr/share/examples/diskless/clone_root) eases
the creation and maintenance of the workstation's root file system
on the server. The script will probably require a little
customization but it will get you started very quickly.Standard system startup files exist in /etc
to detect and support a diskless system startup.Swapping, if needed, can be done either to an NFS file or to
a local disk.There are many ways to set up diskless workstations. Many
elements are involved, and most can be customized to suit local
taste. The following will describe variations on the setup of a complete system,
emphasizing simplicity and compatibility with the
standard FreeBSD startup scripts. The system described has the
following characteristics:The diskless workstations use a shared
read-only / file system, and a shared
read-only /usr.The root file system is a copy of a
standard FreeBSD root (typically the server's), with some
configuration files overridden by ones specific to diskless
operation or, possibly, to the workstation they belong to.The parts of the root which have to be
writable are overlaid with &man.md.4; file systems. Any changes
will be lost when the system reboots.The kernel is transferred and loaded either with
Etherboot or PXE
as some situations may mandate the use of either method.As described, this system is insecure. It should
live in a protected area of a network, and be untrusted by
other hosts.All the information in this section has been tested
using &os; 5.2.1-RELEASE.Background InformationSetting up diskless workstations is both relatively
straightforward and prone to errors. These are sometimes
difficult to diagnose for a number of reasons. For example:Compile time options may determine different behaviors at
runtime.Error messages are often cryptic or totally absent.In this context, having some knowledge of the background
mechanisms involved is very useful to solve the problems that
may arise.Several operations need to be performed for a successful
bootstrap:The machine needs to obtain initial parameters such as its IP
address, executable filename, server name, root path. This is
done using the DHCP or BOOTP protocols.
DHCP is a compatible extension of BOOTP, and
uses the same port numbers and basic packet format.It is possible to configure a system to use only BOOTP.
The &man.bootpd.8; server program is included in the base &os;
system.However, DHCP has a number of advantages
over BOOTP (nicer configuration files, possibility of using
PXE, plus many others not directly related to
diskless operation), and we will describe mainly a
DHCP configuration, with equivalent examples
using &man.bootpd.8; when possible. The sample configuration will
use the ISC DHCP software package
(release 3.0.1.r12 was installed on the test server).The machine needs to transfer one or several programs to local
memory. Either TFTP or NFS
are used. The choice between TFTP and
NFS is a compile time option in several places.
A common source of error is to specify filenames for the wrong
protocol: TFTP typically transfers all files from
a single directory on the server, and would expect filenames
relative to this directory. NFS needs absolute
file paths.The possible intermediate bootstrap programs and the kernel
need to be initialized and executed. There are several important
variations in this area:PXE will load &man.pxeboot.8;, which is
a modified version of the &os; third stage loader. The
&man.loader.8; will obtain most parameters necessary to system
startup, and leave them in the kernel environment before
transferring control. It is possible to use a
GENERIC kernel in this case.Etherboot, will directly
load the kernel, with less preparation. You will need to
build a kernel with specific options.PXE and Etherboot
work equally well; however, because kernels
normally let the &man.loader.8; do more work for them,
PXE is the preferred method.If your BIOS and network cards support
PXE, you should probably use it.Finally, the machine needs to access its file systems.
NFS is used in all cases.See also &man.diskless.8; manual page.Setup InstructionsConfiguration Using ISC DHCPDHCPdiskless operationThe ISC DHCP server can answer
both BOOTP and DHCP requests.ISC DHCP
3.0 is not part of the base
system. You will first need to install the
net/isc-dhcp3-server port or the
corresponding package.Once ISC DHCP is installed, it
needs a configuration file to run (normally named
/usr/local/etc/dhcpd.conf). Here follows
a commented example, where host margaux
uses Etherboot and host
corbieres uses PXE:
default-lease-time 600;
max-lease-time 7200;
authoritative;
option domain-name "example.com";
option domain-name-servers 192.168.4.1;
option routers 192.168.4.1;
subnet 192.168.4.0 netmask 255.255.255.0 {
use-host-decl-names on;
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.4.255;
host margaux {
hardware ethernet 01:23:45:67:89:ab;
fixed-address margaux.example.com;
next-server 192.168.4.4;
filename "/data/misc/kernel.diskless";
option root-path "192.168.4.4:/data/misc/diskless";
}
host corbieres {
hardware ethernet 00:02:b3:27:62:df;
fixed-address corbieres.example.com;
next-server 192.168.4.4;
filename "pxeboot";
option root-path "192.168.4.4:/data/misc/diskless";
}
}
This option tells
dhcpd to send the value in the
host declarations as the hostname for the
diskless host. An alternate way would be to add an
option host-name
margaux inside the
host declarations.The
next-server directive designates
the TFTP or NFS server to
use for loading loader or kernel file (the default is to use
the same host as the
DHCP server).The
filename directive defines the file that
Etherboot or PXE
will load for the next execution step. It must be specified
according to the transfer method used.
Etherboot can be compiled to use
NFS or TFTP. The &os;
port configures NFS by default.
PXE uses TFTP, which is
why a relative filename is used here (this may depend on the
TFTP server configuration, but would be
fairly typical). Also, PXE loads
pxeboot, not the kernel. There are other
interesting possibilities, like loading
pxeboot from a &os; CD-ROM
/boot directory (as
&man.pxeboot.8; can load a GENERIC kernel,
this makes it possible to use PXE to boot
from a remote CD-ROM).The
root-path option defines the path to
the root file system, in usual NFS notation.
When using PXE, it is possible to leave off
the host's IP as long as you do not enable the kernel option
BOOTP. The NFS server will then be
the same as the TFTP one.Configuration Using BOOTPBOOTPdiskless operationHere follows an equivalent bootpd
configuration (reduced to one client). This would be found in
/etc/bootptab.Please note that Etherboot
must be compiled with the non-default option
NO_DHCP_SUPPORT in order to use BOOTP,
and that PXE needs DHCP. The only
obvious advantage of bootpd is
that it exists in the base system.
.def100:\
:hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
:sm=255.255.255.0:\
:ds=192.168.4.1:\
:gw=192.168.4.1:\
:hd="/tftpboot":\
:bf="/kernel.diskless":\
:rp="192.168.4.4:/data/misc/diskless":
margaux:ha=0123456789ab:tc=.def100
Preparing a Boot Program with
EtherbootEtherbootEtherboot's Web
site contains
extensive documentation mainly intended for Linux
systems, but nonetheless containing useful information. The
following will just outline how you would use
Etherboot on a FreeBSD
system.You must first install the net/etherboot package or port.You can change the Etherboot
configuration (i.e. to use TFTP instead of
NFS) by editing the Config
file in the Etherboot source
directory.For our setup, we shall use a boot floppy. For other methods
(PROM, or &ms-dos; program), please refer to the
Etherboot documentation.To make a boot floppy, insert a floppy in the drive on the
machine where you installed Etherboot,
then change your current directory to the src
directory in the Etherboot tree and
type:
&prompt.root; gmake bin32/devicetype.fd0devicetype depends on the type of
the Ethernet card in the diskless workstation. Refer to the
NIC file in the same directory to determine the
right devicetype.Booting with PXEBy default, the &man.pxeboot.8; loader loads the kernel via
NFS. It can be compiled to use
TFTP instead by specifying the
LOADER_TFTP_SUPPORT option in
/etc/make.conf. See the comments in
/usr/share/examples/etc/make.conf
for instructions.There are two other make.conf
options which may be useful for setting up a serial console diskless
machine: BOOT_PXELDR_PROBE_KEYBOARD, and
BOOT_PXELDR_ALWAYS_SERIAL.To use PXE when the machine starts, you will
usually need to select the Boot from network
option in your BIOS setup, or type a function key
during the PC initialization.Configuring the TFTP and NFS ServersTFTPdiskless operationNFSdiskless operationIf you are using PXE or
Etherboot configured to use
TFTP, you need to enable
tftpd on the file server:Create a directory from which tftpd
will serve the files, e.g. /tftpboot.Add this line to your
/etc/inetd.conf:tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpbootIt appears that at least some PXE versions want
the TCP version of TFTP. In this case, add a second line,
replacing dgram udp with stream
tcp.Tell inetd to reread its configuration
file. The must be in
the /etc/rc.conf file for this
command to execute correctly:&prompt.root; /etc/rc.d/inetd restartYou can place the tftpboot
directory anywhere on the server. Make sure that the
location is set in both inetd.conf and
dhcpd.conf.In all cases, you also need to enable NFS and export the
appropriate file system on the NFS server.Add this to /etc/rc.conf:nfs_server_enable="YES"Export the file system where the diskless root directory
is located by adding the following to
/etc/exports (adjust the volume mount
point and replace margaux corbieres
with the names of the diskless workstations):/data/misc -alldirs -ro margaux corbieresTell mountd to reread its configuration
file. If you actually needed to enable NFS in
/etc/rc.conf
at the first step, you probably want to reboot instead.&prompt.root; /etc/rc.d/mountd restartBuilding a Diskless Kerneldiskless operationkernel configurationIf using Etherboot, you need to
create a kernel configuration file for the diskless client
with the following options (in addition to the usual ones):
options BOOTP # Use BOOTP to obtain IP address/hostname
options BOOTP_NFSROOT # NFS mount root file system using BOOTP info
You may also want to use BOOTP_NFSV3,
BOOT_COMPAT and BOOTP_WIRED_TO
(refer to NOTES).These option names are historical and slightly misleading as
they actually enable indifferent use of DHCP and
BOOTP inside the kernel (it is also possible to force strict BOOTP
or DHCP use).Build the kernel (see ),
and copy it to the place specified
in dhcpd.conf.When using PXE, building a kernel with the
above options is not strictly necessary (though suggested).
Enabling them will cause more DHCP requests to be
issued during kernel startup, with a small risk of inconsistency
between the new values and those retrieved by &man.pxeboot.8; in some
special cases. The advantage of using them is that the host name
will be set as a side effect. Otherwise you will need to set the
host name by another method, for example in a client-specific
rc.conf file.In order to be loadable with
Etherboot, a kernel needs to have
the device hints compiled in. You would typically set the
following option in the configuration file (see the
NOTES configuration comments file):hints "GENERIC.hints"Preparing the Root Filesystemroot file systemdiskless operationYou need to create a root file system for the diskless
workstations, in the location listed as
root-path in
dhcpd.conf.Using make world to populate rootThis method is quick and
will install a complete virgin system (not only the root file system)
into DESTDIR.
All you have to do is simply execute the following script:#!/bin/sh
export DESTDIR=/data/misc/diskless
mkdir -p ${DESTDIR}
cd /usr/src; make buildworld && make buildkernel
cd /usr/src/etc; make distributionOnce done, you may need to customize your
/etc/rc.conf and
/etc/fstab placed into
DESTDIR according to your needs.Configuring SwapIf needed, a swap file located on the server can be
accessed via NFS.NFS SwapThe kernel does not support enabling NFS
swap at boot time. Swap must be enabled by the startup scripts,
by mounting a writable file system and creating and enabling a
swap file. To create a swap file of appropriate size, you can do
like this:&prompt.root; dd if=/dev/zero of=/path/to/swapfile bs=1k count=1 oseek=100000To enable it you have to add the following line to your
rc.conf:swapfile=/path/to/swapfileMiscellaneous IssuesRunning with a Read-only /usrdiskless operation/usr read-onlyIf the diskless workstation is configured to run X, you
will have to adjust the XDM configuration file, which puts
the error log on /usr by default.Using a Non-FreeBSD ServerWhen the server for the root file system is not running FreeBSD,
you will have to create the root file system on a
FreeBSD machine, then copy it to its destination, using
tar or cpio.In this situation, there are sometimes
problems with the special files in /dev,
due to differing major/minor integer sizes. A solution to this
problem is to export a directory from the non-FreeBSD server,
mount this directory onto a FreeBSD machine, and
use &man.devfs.5; to allocate device nodes transparently for
the user.ISDNISDNA 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.HellmuthMichaelisContributed by ISDN CardsISDNcardsFreeBSD's ISDN implementation supports only the DSS1/Q.931
(or Euro-ISDN) standard using passive cards. Some active cards
are supported where the firmware
also supports other signaling protocols; this also includes the
first supported Primary Rate (PRI) ISDN card.The isdn4bsd software allows you to connect
to other ISDN routers using either IP over raw HDLC or by using
synchronous PPP: either by using kernel PPP with isppp, a
modified &man.sppp.4; driver, or by using userland &man.ppp.8;. By using
userland &man.ppp.8;, channel bonding of two or more ISDN
B-channels is possible. A telephone answering machine
application is also available as well as many utilities such as
a software 300 Baud modem.Some growing number of PC ISDN cards are supported under
FreeBSD and the reports show that it is successfully used all
over Europe and in many other parts of the world.The passive ISDN cards supported are mostly the ones with
the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
but also ISDN cards with chips from Cologne Chip (ISA bus only),
PCI cards with Winbond W6692 chips, some cards with the
Tiger300/320/ISAC chipset combinations and some vendor specific
chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
AVM Fritz!Card PnP.Currently the active supported ISDN cards are the AVM B1
(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.For documentation on isdn4bsd,
have a look at /usr/share/examples/isdn/
directory on your FreeBSD system or at the homepage of
isdn4bsd which also has pointers to hints, erratas and
much more documentation such as the isdn4bsd
handbook.In case you are interested in adding support for a
different ISDN protocol, a currently unsupported ISDN PC card or
otherwise enhancing isdn4bsd, please
get in touch with &a.hm;.For questions regarding the installation, configuration
and troubleshooting isdn4bsd, a
&a.isdn.name; mailing list is available.ISDN Terminal 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 set up. However, at the same time any problems you
experienced with the PPP program and are going to persist.If you want maximum stability, use the kernel PPP option, not the userland PPP.The following TA's are known to work with FreeBSD:Motorola BitSurfer and Bitsurfer 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 that, like modems,
you need a good serial card in your computer.You should read the FreeBSD Serial
Hardware tutorial for a detailed understanding of
serial devices, and the differences between asynchronous and
synchronous serial ports.A TA running off a standard PC serial port (asynchronous) limits
you to 115.2 Kbs, even though you have a 128 Kbs connection.
To fully utilize the 128 Kbs that ISDN is capable of,
you must move the TA to a synchronous serial card.Do not be fooled into buying an internal TA and thinking you have
avoided the synchronous/asynchronous issue. Internal TA's simply have
a standard PC serial port chip built into them. All this will do is
save you having to buy another serial cable and find another empty
electrical socket.A synchronous card with a TA is at least as fast as a stand-alone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.The choice of synchronous card/TA v.s. stand-alone router is largely a
religious issue. There has been some discussion of this in
the mailing lists. We suggest you search the archives for
the complete discussion.Stand-alone ISDN Bridges/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 section, the terms router and bridge will
be used interchangeably.As the cost of low end ISDN routers/bridges comes down, it
will likely become a more and more popular choice. An ISDN
router is a small box that plugs directly into your local
Ethernet network, and manages its own connection to the other
bridge/router. It has built in software to communicate via
PPP and other popular protocols.A router will allow you much faster throughput than a
standard TA, since it will be using a full synchronous ISDN
connection.The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem.
If you are planning to connect to an Internet provider, you
should discuss your needs with them.If you are planning to connect two LAN segments together,
such as your home LAN to the office LAN, this is the simplest
lowest
maintenance solution. Since you are buying the equipment for
both sides of the connection you can be assured that the link
will work.For example to connect a home computer or branch office
network to a head office network the following setup could be
used:Branch Office or Home 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
|
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 (usually expensive) models
that
have two serial ports. Do not confuse this with channel bonding, MPP,
etc.This can be a very useful feature if, for example, you
have an dedicated ISDN connection at your office and would
like to tap into it, but do not want to get another ISDN line
at work. A router at the office location can manage a
dedicated B channel connection (64 Kbps) to the Internet
and use the other B channel for a separate data connection.
The second B channel can be used for dial-in, dial-out or
dynamically bonding (MPP, etc.) with the first B channel for
more bandwidth.IPX/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.ChernLeeContributed by Network Address TranslationOverviewnatdFreeBSD's Network Address Translation daemon, commonly known as
&man.natd.8; is a daemon that accepts incoming raw IP packets,
changes the source to the local machine and re-injects these packets
back into the outgoing IP packet stream. &man.natd.8; does this by changing
the source IP address and port such that when data is received back,
it is able to determine the original location of the data and forward
it back to its original requester.Internet connection sharingNATThe 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
increasingly in need of an Internet Connection Sharing solution. The
ability to connect several computers online through one connection and
IP address makes &man.natd.8; a reasonable choice.Most commonly, a user has a machine connected to a cable or DSL
line with one IP address and wishes to use this one connected computer to
provide Internet access to several more over a LAN.To do this, the FreeBSD machine on the Internet must act as a
gateway. This gateway machine must have two NICs—one for connecting
to the Internet router, the other connecting to a LAN. All the
machines on the LAN are connected through a hub or switch.There are many ways to get a LAN connected to the Internet
through a &os; gateway. This example will only cover a
gateway with at least two NICs. _______ __________ ________
| | | | | |
| Hub |-----| Client B |-----| Router |----- Internet
|_______| |__________| |________|
|
____|_____
| |
| Client A |
|__________|Network LayoutA setup like this is commonly used to share an Internet
connection. One of the LAN machines is
connected to the Internet. The rest of the machines access
the Internet through that gateway
machine.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="" Sets up the machine to act as a gateway. Running
sysctl net.inet.ip.forwarding=1 would
have the same effect.Enables the firewall rules in
/etc/rc.firewall at boot.This specifies a predefined firewall ruleset that
allows anything in. See
/etc/rc.firewall for additional
types.Indicates which interface to forward packets through
(the interface connected to the Internet).Any additional configuration options passed to
&man.natd.8; on boot.Having the previous options defined in
/etc/rc.conf would run
natd -interface fxp0 at boot. This can also
be run manually.It is also possible to use a configuration file for
&man.natd.8; when there are too many options to pass. In this
case, the configuration file must be defined by adding the
following line to /etc/rc.conf:natd_flags="-f /etc/natd.conf"The /etc/natd.conf file will
contain a list of configuration options, one per line. For
example the next section case would use the following
file:redirect_port tcp 192.168.0.2:6667 6667
redirect_port tcp 192.168.0.3:80 80For more information about the configuration file,
consult the &man.natd.8; manual page about the
option.Each machine and interface behind the LAN should be
assigned IP address numbers in the private network space as
defined by RFC 1918
and have a default gateway of the natd machine's internal IP
address.For example, client A and
B behind the LAN have IP addresses of 192.168.0.2 and 192.168.0.3, while the natd machine's
LAN interface has an IP address of 192.168.0.1. Client A
and B's default gateway must be set to that
of the natd machine, 192.168.0.1. The natd machine's
external, or Internet interface does not require any special
modification for &man.natd.8; to work.Port RedirectionThe drawback with &man.natd.8; is that the LAN clients are not accessible
from the Internet. Clients on the LAN can make outgoing connections to
the world but cannot receive incoming ones. This presents a problem
if trying to run Internet services on one of the LAN client machines.
A simple way around this is to redirect selected Internet ports on the
natd machine to a LAN client.
For example, an IRC server runs on client A, and a web server runs
on client B. For this to work properly, connections received on ports
6667 (IRC) and 80 (web) must be redirected to the respective machines.
The must be passed to
&man.natd.8; with the proper options. The syntax is as follows: -redirect_port proto targetIP:targetPORT[-targetPORT]
[aliasIP:]aliasPORT[-aliasPORT]
[remoteIP[:remotePORT[-remotePORT]]]In the above example, the argument should be: -redirect_port tcp 192.168.0.2:6667 6667
-redirect_port tcp 192.168.0.3:80 80
This will redirect the proper tcp ports to the
LAN client machines.
The argument can be used to indicate port
ranges over individual ports. For example, tcp
192.168.0.2:2000-3000 2000-3000 would redirect
all connections received on ports 2000 to 3000 to ports 2000
to 3000 on client A.These options can be used when directly running
&man.natd.8;, placed within the
natd_flags="" option in
/etc/rc.conf,
or passed via a configuration file.For further configuration options, consult &man.natd.8;Address Redirectionaddress redirectionAddress redirection is useful if several IP addresses are
available, yet they must be on one machine. With this,
&man.natd.8; can assign each LAN client its own external IP address.
&man.natd.8; then rewrites outgoing packets from the LAN clients
with the proper external IP address and redirects
all traffic incoming on that particular IP address back to
the specific LAN client. This is also known as static NAT.
For example, the IP addresses 128.1.1.1,
128.1.1.2, and
128.1.1.3 belong to the natd gateway
machine. 128.1.1.1 can be used
as the natd gateway machine's external IP address, while
128.1.1.2 and
128.1.1.3 are forwarded back to LAN
clients A and B.The syntax is as follows:-redirect_address localIP publicIPlocalIPThe internal IP address of the LAN client.publicIPThe external IP address corresponding to the LAN client.In the example, this argument would read:-redirect_address 192.168.0.2 128.1.1.2
-redirect_address 192.168.0.3 128.1.1.3Like , these arguments are also placed within
the natd_flags="" option of /etc/rc.conf, or passed via a configuration file. With address
redirection, there is no need for port redirection since all data
received on a particular IP address is redirected.The external IP addresses on the natd machine must be active and aliased
to the external interface. Look at &man.rc.conf.5; to do so.Parallel Line IP (PLIP)PLIPParallel Line IPPLIPPLIP lets us run TCP/IP between parallel ports. It is
useful on machines without network cards, or to install on
laptops. In this section, we will discuss:Creating a parallel (laplink) cable.Connecting two computers with PLIP.Creating a Parallel CableYou can purchase a parallel cable at most computer supply
stores. If you cannot do that, or you just want to know how
it is done, the following table shows how to make one out of a normal parallel
printer cable.
Setting Up PLIPFirst, you have to get a laplink cable.
Then, confirm that both computers have a kernel with &man.lpt.4; driver
support:&prompt.root; grep lp /var/run/dmesg.boot
lpt0: <Printer> on ppbus0
lpt0: Interrupt-driven portThe parallel port must be an interrupt driven port,
you should have lines similar to the
following in your in the
/boot/device.hints file:hint.ppc.0.at="isa"
hint.ppc.0.irq="7"Then check if the kernel configuration file has a
device plip line or if the
plip.ko kernel module is loaded. In both
cases the parallel networking interface should appear when you
use the &man.ifconfig.8; command to display it:&prompt.root; ifconfig plip0
plip0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500Plug the laplink cable into the parallel interface on
both computers.Configure the network interface parameters on both
sites as root. For example, if you want to connect
the host host1 with another machine host2: host1 <-----> host2
IP Address 10.0.0.1 10.0.0.2Configure the interface on host1 by doing:&prompt.root; ifconfig plip0 10.0.0.1 10.0.0.2Configure the interface on host2 by doing:&prompt.root; ifconfig plip0 10.0.0.2 10.0.0.1You now should have a working connection. Please read the
manual pages &man.lp.4; and &man.lpt.4; for more details.You should also add both hosts to
/etc/hosts:127.0.0.1 localhost.my.domain localhost
10.0.0.1 host1.my.domain host1
10.0.0.2 host2.my.domain host2To confirm the connection works, go to each host and ping
the other. For example, on host1:&prompt.root; ifconfig plip0
plip0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000
&prompt.root; netstat -r
Routing tables
Internet:
Destination Gateway Flags Refs Use Netif Expire
host2 host1 UH 0 0 plip0
&prompt.root; ping -c 4 host2
PING host2 (10.0.0.2): 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
--- host2 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 msAaronKaplanOriginally Written by TomRhodesRestructured and Added by BradDavisExtended by IPv6IPv6 (also known as IPng IP next generation) is
the new version of the well known IP protocol (also known as
IPv4). Like the other current *BSD systems,
FreeBSD includes the KAME IPv6 reference implementation.
So your FreeBSD system comes with all you will need to experiment with IPv6.
This section focuses on getting IPv6 configured and running.In the early 1990s, people became aware of the rapidly
diminishing address space of IPv4. Given the expansion rate of the
Internet there were two major concerns:Running out of addresses. Today this is not so much of a concern
anymore since RFC1918 private address space
(10.0.0.0/8,
172.16.0.0/12, and
192.168.0.0/16)
and Network Address Translation (NAT) are
being employed.Router table entries were getting too large. This is
still a concern today.IPv6 deals with these and many other issues:128 bit address space. In other words theoretically there are
340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
available. This means there are approximately
6.67 * 10^27 IPv6 addresses per square meter on our planet.Routers will only store network aggregation addresses in their routing
tables thus reducing the average space of a routing table to 8192
entries.There are also lots of other useful features of IPv6 such as:Address autoconfiguration (RFC2462)Anycast addresses (one-out-of many)Mandatory multicast addressesIPsec (IP security)Simplified header structureMobile IPIPv6-to-IPv4 transition mechanismsFor more information see:IPv6 overview at playground.sun.comKAME.netBackground on IPv6 AddressesThere are different types of IPv6 addresses: Unicast, Anycast and
Multicast.Unicast addresses are the well known addresses. A packet sent
to a unicast address arrives exactly at the interface belonging to
the address.Anycast addresses are syntactically indistinguishable from unicast
addresses but they address a group of interfaces. The packet destined for
an anycast address will arrive at the nearest (in router metric)
interface. Anycast addresses may only be used by routers.Multicast addresses identify a group of interfaces. A packet destined
for a multicast address will arrive at all interfaces belonging to the
multicast group.The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
by multicast addresses in IPv6.
Reserved IPv6 addressesIPv6 addressPrefixlength (Bits)DescriptionNotes::128 bitsunspecifiedcf. 0.0.0.0 in
IPv4::1128 bitsloopback addresscf. 127.0.0.1 in
IPv4::00:xx:xx:xx:xx96 bitsembedded IPv4The lower 32 bits are the IPv4 address. Also
called IPv4 compatible IPv6
address::ff:xx:xx:xx:xx96 bitsIPv4 mapped IPv6 addressThe lower 32 bits are the IPv4 address.
For hosts which do not support IPv6.fe80:: - feb::10 bitslink-localcf. loopback address in IPv4fec0:: - fef::10 bitssite-localff::8 bitsmulticast001 (base
2)3 bitsglobal unicastAll global unicast addresses are assigned from
this pool. The first 3 bits are
001.
Reading IPv6 AddressesThe canonical form is represented as: x:x:x:x:x:x:x:x, each
x being a 16 Bit hex value. For example
FEBC:A574:382B:23C1:AA49:4592:4EFE:9982Often an address will have long substrings of all zeros
therefore one such substring per address can be abbreviated by ::.
Also up to three leading 0s per hexquad can be omitted.
For example fe80::1
corresponds to the canonical form
fe80:0000:0000:0000:0000:0000:0000:0001.A third form is to write the last 32 Bit part in the
well known (decimal) IPv4 style with dots .
as separators. For example
2002::10.0.0.1
corresponds to the (hexadecimal) canonical representation
2002:0000:0000:0000:0000:0000:0a00:0001
which in turn is equivalent to
writing 2002::a00:1.By now the reader should be able to understand the following:&prompt.root; ifconfigrl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500
inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
ether 00:00:21:03:08:e1
media: Ethernet autoselect (100baseTX )
status: activefe80::200:21ff:fe03:8e1%rl0
is an auto configured link-local address. It is generated from the MAC
address as part of the auto configuration.For further information on the structure of IPv6 addresses
see RFC3513.Getting ConnectedCurrently there are four ways to connect to other IPv6 hosts and networks:Contact your Internet Service Provider to see if they
offer IPv6 yet.SixXS offers
tunnels with end-points all around the globe.Tunnel via 6-to-4 (RFC3068)Use the net/freenet6 port if you are on a dial-up connection.DNS in the IPv6 WorldThere used to be two types of DNS records for IPv6. The IETF
has declared A6 records obsolete. AAAA records are the standard
now.Using AAAA records is straightforward. Assign your hostname to the new
IPv6 address you just received by adding:MYHOSTNAME AAAA MYIPv6ADDRTo your primary zone DNS file. In case you do not serve your own
DNS zones ask your DNS provider.
Current versions of bind (version 8.3 and 9)
and dns/djbdns (with the IPv6 patch)
support AAAA records.Applying the needed changes to /etc/rc.confIPv6 Client SettingsThese settings will help you configure a machine that will be on
your LAN and act as a client, not a router. To have &man.rtsol.8;
autoconfigure your interface on boot all you need to add is:ipv6_enable="YES"To statically assign an IP address such as
2001:471:1f11:251:290:27ff:fee0:2093, to your
fxp0 interface, add:ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"To assign a default router of
2001:471:1f11:251::1
add the following to /etc/rc.conf:ipv6_defaultrouter="2001:471:1f11:251::1"IPv6 Router/Gateway SettingsThis will help you take the directions that your tunnel provider has
given you and convert it into settings that will persist through reboots.
To restore your tunnel on startup use something like the following in
/etc/rc.conf:List the Generic Tunneling interfaces that will be configured, for
example gif0:gif_interfaces="gif0"To configure the interface with a local endpoint of
MY_IPv4_ADDR to a remote endpoint of
REMOTE_IPv4_ADDR:gifconfig_gif0="MY_IPv4_ADDR REMOTE_IPv4_ADDR"To apply the IPv6 address you have been assigned for use as your
IPv6 tunnel endpoint, add:ipv6_ifconfig_gif0="MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR"Then all you have to do is set the default route for IPv6. This is
the other side of the IPv6 tunnel:ipv6_defaultrouter="MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR"IPv6 Tunnel SettingsIf the server is to route IPv6 between the rest of your network
and the world, the following /etc/rc.conf
setting will also be needed:ipv6_gateway_enable="YES"Router Advertisement and Host Auto ConfigurationThis section will help you setup &man.rtadvd.8; to advertise the
IPv6 default route.To enable &man.rtadvd.8; you will need the following in your
/etc/rc.conf:rtadvd_enable="YES"It is important that you specify the interface on which to do
IPv6 router solicitation. For example to tell &man.rtadvd.8; to use
fxp0:rtadvd_interfaces="fxp0"Now we must create the configuration file,
/etc/rtadvd.conf. Here is an example:fxp0:\
:addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:Replace fxp0 with the interface you
are going to be using.Next, replace 2001:471:1f11:246::
with the prefix of your allocation.If you are dedicated a /64 subnet
you will not need to change anything else. Otherwise, you will need to
change the prefixlen# to the correct value.HartiBrandtContributed by Asynchronous Transfer Mode (ATM)Configuring classical IP over ATM (PVCs)Classical IP over ATM (CLIP) is the
simplest method to use Asynchronous Transfer Mode (ATM)
with IP. It can be used with
switched connections (SVCs) and with permanent connections
(PVCs). This section describes how to set up a network based
on PVCs.Fully meshed configurationsThe first method to set up a CLIP with
PVCs is to connect each machine to each other machine in the
network via a dedicated PVC. While this is simple to
configure it tends to become impractical for a larger number
of machines. The example supposes that we have four
machines in the network, each connected to the ATM network
with an ATM adapter card. The first step is the planning of
the IP addresses and the ATM connections between the
machines. We use the following:HostIP AddresshostA192.168.173.1hostB192.168.173.2hostC192.168.173.3hostD192.168.173.4To build a fully meshed net we need one ATM connection
between each pair of machines:MachinesVPI.VCI couplehostA - hostB0.100hostA - hostC0.101hostA - hostD0.102hostB - hostC0.103hostB - hostD0.104hostC - hostD0.105The VPI and VCI values at each end of the connection may
of course differ, but for simplicity we assume that they are
the same. Next we need to configure the ATM interfaces on
each host:hostA&prompt.root; ifconfig hatm0 192.168.173.1 up
hostB&prompt.root; ifconfig hatm0 192.168.173.2 up
hostC&prompt.root; ifconfig hatm0 192.168.173.3 up
hostD&prompt.root; ifconfig hatm0 192.168.173.4 upassuming that the ATM interface is
hatm0 on all hosts. Now the PVCs
need to be configured on hostA (we assume that
they are already configured on the ATM switches, you need to
consult the manual for the switch on how to do this).hostA&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr
hostA&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr
hostA&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr
hostB&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr
hostB&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr
hostB&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr
hostC&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr
hostC&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr
hostC&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr
hostD&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr
hostD&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr
hostD&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubrOf course other traffic contracts than UBR can be used
given the ATM adapter supports those. In this case the name
of the traffic contract is followed by the parameters of the
traffic. Help for the &man.atmconfig.8; tool can be
obtained with:&prompt.root; atmconfig help natm addor in the &man.atmconfig.8; manual page.The same configuration can also be done via
/etc/rc.conf.
For hostA this would look like:network_interfaces="lo0 hatm0"
ifconfig_hatm0="inet 192.168.173.1 up"
natm_static_routes="hostB hostC hostD"
route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr"
route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr"
route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"The current state of all CLIP routes
can be obtained with:hostA&prompt.root; atmconfig natm showTomRhodesContributed by Common Access Redundancy Protocol (CARP)CARPCommon Access Redundancy ProtocolThe Common Access Redundancy Protocol, or
CARP allows multiple hosts to share the same
IP address. In some configurations, this may
be used for availability or load balancing. Hosts may use separate
IP addresses as well, as in the example provided
here.To enable support for CARP, the &os;
kernel must be rebuilt with the following option:device carpCARP functionality should now be available
and may be tuned via several sysctl
OIDs:OIDDescriptionnet.inet.carp.allowAccept incoming CARP packets.
Enabled by default.net.inet.carp.preemptThis option downs all of the CARP
interfaces on the host when one of them goes down.
Disabled by defaultnet.inet.carp.logA value of 0 disables any logging.
A Value of 1 enables logging of bad
CARP packets. Values greater than
1 enables logging of state changes for
the CARP interfaces. The default value
is 1.net.inet.carp.arpbalanceBalance local network traffic using
ARP. Disabled by default.net.inet.carp.suppress_preemptA read only OID showing the status
of preemption suppression. Preemption can be suppressed
if link on an interface is down. A value of
0, means that preemption is not
suppressed. Every problem increments this
OID.The CARP devices themselves may be created
via the ifconfig command:&prompt.root; ifconfig carp0 createIn a real environment, these interfaces will need unique
identification numbers known as a VHID. This
VHID or Virtual Host Identification will be
used to distinguish the host on the network.Using CARP For Server Availability (CARP)One use of CARP, as noted above, is for
server availability. This example will provide failover support
for three hosts, all with unique IP
addresses and providing the same web content. These machines will
act in conjunction with a Round Robin DNS
configuration. The failover machine will have two additional
CARP interfaces, one for each of the content
server's IPs. When a failure occurs, the
failover server should pick up the failed machine's
IP address. This means the failure should
go completely unnoticed to the user. The failover server
requires identical content and services as the other content
servers it is expected to pick up load for.The two machines should be configured identically other
than their issued hostnames and VHIDs.
This example calls these machines
hosta.example.org and
hostb.example.org respectively. First, the
required lines for a CARP configuration have
to be added to rc.conf. For
hosta.example.org, the
rc.conf file should contain the following
lines:hostname="hosta.example.org"
ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0"
cloned_interfaces="carp0"
ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24"On hostb.example.org the following lines
should be in rc.conf:hostname="hostb.example.org"
ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0"
cloned_interfaces="carp0"
ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"It is very important that the passwords, specified by the
option to ifconfig,
are identical. The carp devices will
only listen to and accept advertisements from machines with the
correct password. The VHID must also be
different for each machine.The third machine,
provider.example.org, should be prepared so that
it may handle failover from either host. This machine will require
two carp devices, one to handle each
host. The appropriate rc.conf
configuration lines will be similar to the following:hostname="provider.example.org"
ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0"
cloned_interfaces="carp0 carp1"
ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24"
ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"Having the two carp devices will
allow provider.example.org to notice and pick
up the IP address of either machine should
it stop responding.The default &os; kernel may have
preemption enabled. If so,
provider.example.org may not relinquish the
IP address back to the original content
server. In this case, an administrator may have to manually
force the IP back to the master. The following command
should be issued on
provider.example.org:&prompt.root; ifconfig carp0 down && ifconfig carp0 upThis should be done on the carp
interface which corresponds to the correct host.At this point, CARP should be completely
enabled and available for testing. For testing, either networking has
to be restarted or the machines need to be rebooted.More information is always available in the &man.carp.4;
manual page.
diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
index bbef68bd85..c5a7560f34 100644
--- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
@@ -1,4963 +1,4963 @@
MurrayStokelyReorganized by Network ServersSynopsisThis chapter will cover some of the more frequently used
network services on &unix; systems. We will cover how to
install, configure, test, and maintain many different types of
network services. Example configuration files are included
throughout this chapter for you to benefit from.After reading this chapter, you will know:How to manage the inetd
daemon.How to set up a network file system.How to set up a network information server for sharing
user accounts.How to set up automatic network settings using DHCP.How to set up a domain name server.How to set up the Apache HTTP Server.How to set up a File Transfer Protocol (FTP) Server.How to set up a file and print server for &windows;
clients using Samba.How to synchronize the time and date, and set up a
time server, with the NTP protocol.Before reading this chapter, you should:Understand the basics of the
/etc/rc scripts.Be familiar with basic network terminology.Know how to install additional third-party
software ().ChernLeeContributed by Updated for &os; 6.1-RELEASE by The &os; Documentation ProjectThe inetdSuper-ServerOverview&man.inetd.8; is sometimes referred to as the Internet
Super-Server because it manages connections for
several services. When a
connection is received by inetd, it
determines which program the connection is destined for, spawns
the particular process and delegates the socket to it (the program
is invoked with the service socket as its standard input, output
and error descriptors). Running
inetd for servers that are not heavily used can reduce the
overall system load, when compared to running each daemon
individually in stand-alone mode.Primarily, inetd is used to
spawn other daemons, but several trivial protocols are handled
directly, such as chargen,
auth, and
daytime.This section will cover the basics in configuring
inetd through its command-line
options and its configuration file,
/etc/inetd.conf.Settingsinetd is initialized through
the &man.rc.8; system. The
inetd_enable option is set to
NO by default, but may be turned on
by sysinstall during installation,
depending on the configuration chosen by the user.
Placing:inetd_enable="YES"orinetd_enable="NO"into
/etc/rc.conf will enable or disable
inetd starting at boot time.
The command:&prompt.root; /etc/rc.d/inetd rcvar
can be run to display the current effective setting.Additionally, different command-line options can be passed
to inetd via the
inetd_flags option.Command-Line OptionsLike most server daemons, inetd
has a number of options that it can be passed in order to
modify its behaviour. The full list of options reads:inetdOptions can be passed to inetd using the
inetd_flags option in
/etc/rc.conf. By default,
inetd_flags is set to
-wW -C 60, which turns on TCP wrapping for
inetd's services, and prevents any
single IP address from requesting any service more than 60 times
in any given minute.Novice users may be pleased to note that
these parameters usually do not need to be modified,
although we mention the rate-limiting options below as
they be useful should you find that you are receiving an
excessive amount of connections. A full list of options
can be found in the &man.inetd.8; manual.-c maximumSpecify the default maximum number of simultaneous
invocations of each service; the default is unlimited.
May be overridden on a per-service basis with the
parameter.-C rateSpecify the default maximum number of times a
service can be invoked from a single IP address in one
minute; the default is unlimited. May be overridden on a
per-service basis with the
parameter.-R rateSpecify the maximum number of times a service can be
invoked in one minute; the default is 256. A rate of 0
allows an unlimited number of invocations.-s maximumSpecify the maximum number of times a service can be
invoked from a single IP address at any one time; the
default is unlimited. May be overridden on a per-service
basis with the
parameter.inetd.confConfiguration of inetd is
done via the file /etc/inetd.conf.When a modification is made to
/etc/inetd.conf,
inetd can be forced to re-read its
configuration file by running the command:Reloading the inetd
configuration file&prompt.root; /etc/rc.d/inetd reloadEach line of the configuration file specifies an
individual daemon. Comments in the file are preceded by a
#. The format of each entry in
/etc/inetd.conf is as follows:service-name
socket-type
protocol
{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]]
user[:group][/login-class]
server-program
server-program-argumentsAn example entry for the &man.ftpd.8; daemon
using IPv4 might read:ftp stream tcp nowait root /usr/libexec/ftpd ftpd -lservice-nameThis is the service name of the particular daemon.
It must correspond to a service listed in
/etc/services. This determines
which port inetd must listen
to. If a new service is being created, it must be
placed in /etc/services
first.socket-typeEither stream,
dgram, raw, or
seqpacket. stream
must be used for connection-based, TCP daemons, while
dgram is used for daemons utilizing
the UDP transport protocol.protocolOne of the following:ProtocolExplanationtcp, tcp4TCP IPv4udp, udp4UDP IPv4tcp6TCP IPv6udp6UDP IPv6tcp46Both TCP IPv4 and v6udp46Both UDP IPv4 and v6{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] indicates whether the
daemon invoked from inetd is
able to handle its own socket or not.
socket types must use the
option, while stream socket
daemons, which are usually multi-threaded, should use
. usually
hands off multiple sockets to a single daemon, while
spawns a child daemon for each
new socket.The maximum number of child daemons
inetd may spawn can be set
using the option. If a limit
of ten instances of a particular daemon is needed, a
/10 would be placed after
. Specifying /0
allows an unlimited number of childrenIn addition to , two other
options which limit the maximum connections from a single
place to a particular daemon can be enabled.
limits
the number of connections from any particular IP address
per minutes, e.g. a value of ten would limit any particular
IP address connecting to a particular service to ten
attempts per minute.
limits the number of children that can be started on
behalf on any single IP address at any moment. These
options are useful to prevent intentional or unintentional
excessive resource consumption and Denial of Service (DoS)
attacks to a machine.In this field, either of or
is mandatory.
,
and
are
optional.A stream-type multi-threaded daemon without any
,
or
limits
would simply be: nowait.The same daemon with a maximum limit of ten daemons
would read: nowait/10.The same setup with a limit of twenty
connections per IP address per minute and a maximum
total limit of ten child daemons would read:
nowait/10/20.These options are utilized by the default
settings of the &man.fingerd.8; daemon,
as seen here:finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -sFinally, an example of this field with a maximum of
100 children in total, with a maximum of 5 for any one
IP address would read:
nowait/100/0/5.userThis is the username that the particular daemon
should run as. Most commonly, daemons run as the
root user. For security purposes, it is
common to find some servers running as the
daemon user, or the least privileged
nobody user.server-programThe full path of the daemon to be executed when a
connection is received. If the daemon is a service
provided by inetd internally,
then should be
used.server-program-argumentsThis works in conjunction with
by specifying the
arguments, starting with argv[0],
passed to the daemon on invocation. If
mydaemon -d is the command line,
mydaemon -d would be the value of
. Again, if
the daemon is an internal service, use
here.SecurityDepending on the choices made at install time, many
of inetd's services may be enabled
by default. If there is no apparent need for a particular
daemon, consider disabling it. Place a # in front of the
daemon in question in /etc/inetd.conf,
and then reload the
inetd configuration. Some daemons, such as
fingerd, may not be desired at all
because they provide
information that may be useful to an attacker.Some daemons are not security-conscious and have long, or
non-existent, timeouts for connection attempts. This allows an
attacker to slowly send connections to a particular daemon,
thus saturating available resources. It may be a good idea to
place ,
or limitations on certain
daemons if you find that you have too many connections.By default, TCP wrapping is turned on. Consult the
&man.hosts.access.5; manual page for more information on placing
TCP restrictions on various inetd
invoked daemons.Miscellaneousdaytime,
time,
echo,
discard,
chargen, and
auth are all internally provided
services of inetd.The auth service provides
identity
network services, and is
configurable to a certain degree, whilst the others are simply on or off.Consult the &man.inetd.8; manual page for more in-depth
information.TomRhodesReorganized and enhanced by BillSwingleWritten by Network File System (NFS)NFSAmong the many different file systems that FreeBSD supports
is the Network File System, also known as NFS. NFS allows a system to share directories and
files with others over a network. By using NFS, users and programs can
access files on remote systems almost as if they were local
files.Some of the most notable benefits that
NFS can provide are:Local workstations use less disk space because commonly
used data can be stored on a single machine and still remain
accessible to others over the network.There is no need for users to have separate home
directories on every network machine. Home directories
could be set up on the NFS server and
made available throughout the network.Storage devices such as floppy disks, CDROM drives, and
&iomegazip; drives can be used by other machines on the network.
This may reduce the number of removable media drives
throughout the network.How NFS WorksNFS consists of at least two main
parts: a server and one or more clients. The client remotely
accesses the data that is stored on the server machine. In
order for this to function properly a few processes have to be
configured and running.The server has to be running the following daemons:NFSserverfile serverUNIX clientsrpcbindmountdnfsdDaemonDescriptionnfsdThe NFS daemon which services
requests from the NFS
clients.mountdThe NFS mount daemon which carries out
the requests that &man.nfsd.8; passes on to it.rpcbind This daemon allows
NFS clients to discover which port
the NFS server is using.The client can also run a daemon, known as
nfsiod. The
nfsiod daemon services the requests
from the NFS server. This is optional, and
improves performance, but is not required for normal and
correct operation. See the &man.nfsiod.8; manual page for
more information.
Configuring NFSNFSconfigurationNFS configuration is a relatively
straightforward process. The processes that need to be
running can all start at boot time with a few modifications to
your /etc/rc.conf file.On the NFS server, make sure that the
following options are configured in the
/etc/rc.conf file:rpcbind_enable="YES"
nfs_server_enable="YES"
mountd_flags="-r"mountd runs automatically
whenever the NFS server is enabled.On the client, make sure this option is present in
/etc/rc.conf:nfs_client_enable="YES"The /etc/exports file specifies which
file systems NFS should export (sometimes
referred to as share). Each line in
/etc/exports specifies a file system to be
exported and which machines have access to that file system.
Along with what machines have access to that file system,
access options may also be specified. There are many such
options that can be used in this file but only a few will be
mentioned here. You can easily discover other options by
reading over the &man.exports.5; manual page.Here are a few example /etc/exports
entries:NFSexport examplesThe following examples give an idea of how to export
file systems, although the settings may be different depending
on your environment and network configuration. For instance,
to export the /cdrom directory to three
example machines that have the same domain name as the server
(hence the lack of a domain name for each) or have entries in
your /etc/hosts file. The
flag makes the exported file system
read-only. With this flag, the remote system will not be able
to write any changes to the exported file system./cdrom -ro host1 host2 host3The following line exports /home to
three hosts by IP address. This is a useful setup if you have
a private network without a DNS server
configured. Optionally the /etc/hosts
file could be configured for internal hostnames; please review
&man.hosts.5; for more information. The
flag allows the subdirectories to be
mount points. In other words, it will not mount the
subdirectories but permit the client to mount only the
directories that are required or needed./home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4The following line exports /a so that
two clients from different domains may access the file system.
The flag allows the
root user on the remote system to write
data on the exported file system as root.
If the -maproot=root flag is not specified,
then even if a user has root access on
the remote system, he will not be able to modify files on
the exported file system./a -maproot=root host.example.com box.example.orgIn order for a client to access an exported file system,
the client must have permission to do so. Make sure the
client is listed in your /etc/exports
file.In /etc/exports, each line represents
the export information for one file system to one host. A
remote host can only be specified once per file system, and may
only have one default entry. For example, assume that
/usr is a single file system. The
following /etc/exports would be
invalid:# Invalid when /usr is one file system
/usr/src client
/usr/ports clientOne file system, /usr, has two lines
specifying exports to the same host, client.
The correct format for this situation is:/usr/src /usr/ports clientThe properties of one file system exported to a given host
must all occur on one line. Lines without a client specified
are treated as a single host. This limits how you can export
file systems, but for most people this is not an issue.The following is an example of a valid export list, where
/usr and /exports
are local file systems:# Export src and ports to client01 and client02, but only
# client01 has root privileges on it
/usr/src /usr/ports -maproot=root client01
/usr/src /usr/ports client02
# The client machines have root and can mount anywhere
# on /exports. Anyone in the world can mount /exports/obj read-only
/exports -alldirs -maproot=root client01 client02
/exports/obj -roThe mountd daemon must be forced to
recheck the /etc/exports file whenever it has
been modified, so the changes can take effect. This can be
accomplished either by sending a HUP signal to the running daemon:&prompt.root; kill -HUP `cat /var/run/mountd.pid`or by invoking the mountd &man.rc.8; script
with the appropriate parameter:&prompt.root; /etc/rc.d/mountd onereloadPlease refer to for more
information about using rc scripts.Alternatively, a reboot will make FreeBSD set everything
up properly. A reboot is not necessary though.
Executing the following commands as root
should start everything up.On the NFS server:&prompt.root; rpcbind
&prompt.root; nfsd -u -t -n 4
&prompt.root; mountd -rOn the NFS client:&prompt.root; nfsiod -n 4Now everything should be ready to actually mount a remote file
system. In these examples the
server's name will be server and the client's
name will be client. If you only want to
temporarily mount a remote file system or would rather test the
configuration, just execute a command like this as root on the
client:NFSmounting&prompt.root; mount server:/home /mntThis will mount the /home directory
on the server at /mnt on the client. If
everything is set up correctly you should be able to enter
/mnt on the client and see all the files
that are on the server.If you want to automatically mount a remote file system
each time the computer boots, add the file system to the
/etc/fstab file. Here is an example:server:/home /mnt nfs rw 0 0The &man.fstab.5; manual page lists all the available
options.LockingSome applications (e.g. mutt)
require file locking to operate correctly. In the case of
NFS, rpc.lockd
can be used for file locking. To enable it, add the following
to the /etc/rc.conf file on both client
and server (it is assumed that the NFS
client and server are configured already):rpc_lockd_enable="YES"
rpc_statd_enable="YES"Start the application by using:&prompt.root; /etc/rc.d/lockd start
&prompt.root; /etc/rc.d/statd startIf real locking between the NFS clients
and NFS server is not required, it is
possible to let the NFS client do locking
locally by passing to &man.mount.nfs.8;.
Refer to the &man.mount.nfs.8; manual page for further details.
Practical UsesNFS has many practical uses. Some of
the more common ones are listed below:NFSusesSet several machines to share a CDROM or other media
among them. This is cheaper and often a more convenient
method to install software on multiple machines.On large networks, it might be more convenient to
configure a central NFS server in which
to store all the user home directories. These home
directories can then be exported to the network so that
users would always have the same home directory,
regardless of which workstation they log in to.Several machines could have a common
/usr/ports/distfiles directory. That
way, when you need to install a port on several machines,
you can quickly access the source without downloading it
on each machine.WylieStilwellContributed by ChernLeeRewritten by Automatic Mounts with amdamdautomatic mounter daemon&man.amd.8; (the automatic mounter daemon)
automatically mounts a
remote file system whenever a file or directory within that
file system is accessed. Filesystems that are inactive for a
period of time will also be automatically unmounted by
amd. Using
amd provides a simple alternative
to permanent mounts, as permanent mounts are usually listed in
/etc/fstab.amd operates by attaching
itself as an NFS server to the /host and
/net directories. When a file is accessed
within one of these directories, amd
looks up the corresponding remote mount and automatically mounts
it. /net is used to mount an exported
file system from an IP address, while /host
is used to mount an export from a remote hostname.An access to a file within
/host/foobar/usr would tell
amd to attempt to mount the
/usr export on the host
foobar.Mounting an Export with amdYou can view the available mounts of a remote host with
the showmount command. For example, to
view the mounts of a host named foobar, you
can use:&prompt.user; showmount -e foobar
Exports list on foobar:
/usr 10.10.10.0
/a 10.10.10.0
&prompt.user; cd /host/foobar/usrAs seen in the example, the showmount shows
/usr as an export. When changing directories to
/host/foobar/usr, amd
attempts to resolve the hostname foobar and
automatically mount the desired export.amd can be started by the
startup scripts by placing the following lines in
/etc/rc.conf:amd_enable="YES"Additionally, custom flags can be passed to
amd from the
amd_flags option. By default,
amd_flags is set to:amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"The /etc/amd.map file defines the
default options that exports are mounted with. The
/etc/amd.conf file defines some of the more
advanced features of amd.Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more
information.JohnLindContributed by Problems Integrating with Other SystemsCertain Ethernet adapters for ISA PC systems have limitations
which can lead to serious network problems, particularly with NFS.
This difficulty is not specific to FreeBSD, but FreeBSD systems
are affected by it.The problem nearly always occurs when (FreeBSD) PC systems are
networked with high-performance workstations, such as those made
by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS
mount will work fine, and some operations may succeed, but
suddenly the server will seem to become unresponsive to the
client, even though requests to and from other systems continue to
be processed. This happens to the client system, whether the
client is the FreeBSD system or the workstation. On many systems,
there is no way to shut down the client gracefully once this
problem has manifested itself. The only solution is often to
reset the client, because the NFS situation cannot be
resolved.Though the correct solution is to get a
higher performance and capacity Ethernet adapter for the
FreeBSD system, there is a simple workaround that will allow
satisfactory operation. If the FreeBSD system is the
server, include the option
on the mount from the client. If the
FreeBSD system is the client, then mount
the NFS file system with the option .
These options may be specified using the fourth field of the
fstab entry on the client for automatic
mounts, or by using the parameter of the
&man.mount.8; command for manual mounts.It should be noted that there is a different problem,
sometimes mistaken for this one, when the NFS servers and
clients are on different networks. If that is the case, make
certain that your routers are routing the
necessary UDP information, or you will not get anywhere, no
matter what else you are doing.In the following examples, fastws is the host
(interface) name of a high-performance workstation, and
freebox is the host (interface) name of a FreeBSD
system with a lower-performance Ethernet adapter. Also,
/sharedfs will be the exported NFS
file system (see &man.exports.5;), and
/project will be the mount point on the
client for the exported file system. In all cases, note that
additional options, such as or
and may be desirable in
your application.Examples for the FreeBSD system (freebox)
as the client in /etc/fstab on
freebox:fastws:/sharedfs /project nfs rw,-r=1024 0 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
8 K (though it may do fragments of smaller sizes). Since
the maximum Ethernet packet is around 1500 bytes, the NFS
block gets split into multiple Ethernet
packets, even though it is still a single unit to the
upper-level code, and must be received, assembled, and
acknowledged as a unit. The
high-performance workstations can pump out the packets which
comprise the NFS unit one right after the other, just as close
together as the standard allows. On the smaller, lower
capacity cards, the later packets overrun the earlier packets
of the same unit before they can be transferred to the host
and the unit as a whole cannot be reconstructed or
acknowledged. As a result, the workstation will time out and
try again, but it will try again with the entire 8 K
unit, and the process will be repeated, ad infinitum.By keeping the unit size below the Ethernet packet size
limitation, we ensure that any complete Ethernet packet
received can be acknowledged individually, avoiding the
deadlock situation.Overruns may still occur when a high-performance
workstations is slamming data out to a PC system, but with the
better cards, such overruns are not guaranteed on NFS
units. When an overrun occurs, the units
affected will be retransmitted, and there will be a fair
chance that they will be received, assembled, and
acknowledged.BillSwingleWritten by EricOgrenEnhanced by UdoErdelhoffNetwork Information System (NIS/YP)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 &unix; like systems
(&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD,
etc) support NIS.yellow pagesNISNIS
was formerly known as Yellow Pages, but because of trademark
issues, Sun changed the name. The old term (and yp) is still
often seen and used.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 the &windowsnt; domain system; although
the internal implementation of the two are not at all similar,
the basic functionality can be compared.Terms/Processes You Should 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 as an NIS client:rpcbindportmapTermDescriptionNIS domainnameAn NIS master server and all of its clients
(including its slave servers) have a NIS domainname.
Similar to an &windowsnt; domain name, the NIS
domainname does not have anything to do with
DNS.rpcbindMust be running in order to enable
RPC (Remote Procedure Call, a
network protocol used by NIS). If
rpcbind is not running, it
will be impossible to run an NIS server, or to act as
an NIS client.ypbindBinds 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.ypservShould only be running on NIS servers; this is
the NIS server process itself. If &man.ypserv.8;
dies, then the server will no longer be able to
respond to NIS requests (hopefully, there is a slave
server to take over for it). There are some
implementations of NIS (but not the FreeBSD one), that
do not try to reconnect to another server if the
server it used before dies. Often, the only thing
that helps in this case is to restart the server
process (or even the whole server) or the
ypbind process on the
client.
rpc.yppasswddAnother process that should only be running on
NIS master servers; this is a daemon that will allow NIS
clients to change their NIS passwords. If this daemon
is not running, users will have to login to the NIS
master server and change their passwords there.How Does It Work?There are three types of hosts in an NIS environment:
master servers, slave servers, and clients. Servers act as a
central repository for host configuration information. Master
servers hold the authoritative copy of this information, while
slave servers mirror this information for redundancy. Clients
rely on the servers to provide this information to
them.Information in many files can be shared in this manner.
The master.passwd,
group, and hosts
files are commonly shared via NIS. Whenever a process on a
client needs information that would normally be found in these
files locally, it makes a query to the NIS server that it is
bound to instead.Machine TypesNISmaster serverA NIS master server. This
server, analogous to a &windowsnt; primary domain
controller, maintains the files used by all of the NIS
clients. The passwd,
group, and other various files used
by the NIS clients live on the master server.It is possible for one machine to be an NIS
master server for more than one NIS domain. However,
this will not be covered in this introduction, which
assumes a relatively small-scale NIS
environment.NISslave serverNIS slave servers. Similar to
the &windowsnt; backup domain controllers, NIS slave
servers maintain copies of the NIS master's data files.
NIS slave servers provide the redundancy, which is
needed in important environments. They also help to
balance the load of the master server: NIS Clients
always attach to the NIS server whose response they get
first, and this includes slave-server-replies.NISclientNIS clients. NIS clients, like
most &windowsnt; workstations, authenticate against the
NIS server (or the &windowsnt; domain controller in the
&windowsnt; workstations case) to log on.Using NIS/YPThis section will deal with setting up a sample NIS
environment.PlanningLet us assume that you are the administrator of a small
university lab. This lab, which consists of 15 FreeBSD
machines, currently has no centralized point of
administration; each machine has its own
/etc/passwd and
/etc/master.passwd. These files are
kept in sync with each other only through manual
intervention; currently, when you add a user to the lab, you
must run adduser on all 15 machines.
Clearly, this has to change, so you have decided to convert
the lab to use NIS, using two of the machines as
servers.Therefore, the configuration of the lab now looks something
like:Machine 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 will not be
prone to being rebooted regularly, or one that might be
used for development. The NIS server should ideally be a
stand alone machine whose sole purpose in life is to be an
NIS server. If you have a network that is not very
heavily used, it is acceptable to put the NIS server on a
machine running other services, just keep in mind that if
the NIS server becomes unavailable, it will affect
all of your NIS clients
adversely.NIS Servers The canonical copies of all NIS information are stored
on a single machine called the NIS master server. The
databases used to store the information are called NIS maps.
In FreeBSD, these maps are stored in
/var/yp/[domainname] where
[domainname] is the name of the NIS
domain being served. A single NIS server can support
several domains at once, therefore it is possible to have
several such directories, one for each supported domain.
Each domain will have its own independent set of
maps.NIS master and slave servers handle all NIS requests
with the ypserv daemon.
ypserv is responsible for receiving
incoming requests from NIS clients, translating the
requested domain and map name to a path to the corresponding
database file and transmitting data from the database back
to the client.Setting Up a NIS Master 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.Depending on your NIS setup, you may need to add
further entries. See the section about NIS
servers that are also NIS clients, below, for
details.Now, all you have to do is to run the command
/etc/netstart as superuser. It will
set up everything for you, using the values you defined in
/etc/rc.conf.Initializing the NIS MapsNISmapsThe NIS maps are database files,
that are kept in the /var/yp
directory. They are generated from configuration files in
the /etc directory of the NIS master,
with one exception: the
/etc/master.passwd file. This is for
a good reason, you do not want to propagate passwords to
your root and other administrative
accounts to all the servers in the NIS domain. Therefore,
before we initialize the NIS maps, you should:&prompt.root; cp /etc/master.passwd /var/yp/master.passwd
&prompt.root; cd /var/yp
&prompt.root; vi master.passwdYou should remove all entries regarding system
accounts (bin,
tty, kmem,
games, etc), as well as any accounts
that you do not want to be propagated to the NIS clients
(for example root and any other UID 0
(superuser) accounts).Make sure the
/var/yp/master.passwd is neither group
nor world readable (mode 600)! Use the
chmod command, if appropriate.Tru64 UNIXWhen you have finished, it is time to initialize the
NIS maps! FreeBSD includes a script named
ypinit to do this for you (see its
manual page for more information). Note that this script
is available on most &unix; Operating Systems, but not on
all. On Digital UNIX/Compaq Tru64 UNIX it is called
ypsetup. Because we are generating
maps for an NIS master, we are going to pass the
option to ypinit.
To generate the NIS maps, assuming you already performed
the steps above, run:ellington&prompt.root; ypinit -m test-domain
Server Type: MASTER Domain: test-domain
Creating an YP server will require that you answer a few questions.
Questions will all be asked at the beginning of the procedure.
Do you want this procedure to quit on non-fatal errors? [y/n: n] n
Ok, please remember to go back and redo manually whatever fails.
If you don't, something might not work.
At this point, we have to construct a list of this domains YP servers.
rod.darktech.org is already known as master server.
Please continue to add any slave servers, one per line. When you are
done with the list, type a <control D>.
master server : ellington
next host to add: coltrane
next host to add: ^D
The current list of NIS servers looks like this:
ellington
coltrane
Is this correct? [y/n: y] y
[..output from map generation..]
NIS Map update completed.
ellington has been setup as an YP master server without any errors.ypinit should have created
/var/yp/Makefile from
/var/yp/Makefile.dist.
When created, this file assumes that you are operating
in a single server NIS environment with only FreeBSD
machines. Since test-domain has
a slave server as well, you must edit
/var/yp/Makefile:ellington&prompt.root; vi /var/yp/MakefileYou should comment out the line that saysNOPUSH = "True"(if it is not commented out already).Setting up a NIS Slave ServerNISslave 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 these entries are
not mandatory, since the master server attempts to ensure
any changes to its NIS maps are communicated to its slaves
and because password information is vital to systems
depending on the server, it is a good idea to force the
updates. This is more important on busy networks where map
updates might not always complete.Now, run the command /etc/netstart on the
slave server as well, which again starts the NIS server.NIS Clients An NIS client establishes what is called a binding to a
particular NIS server using the
ypbind daemon.
ypbind checks the system's default
domain (as set by the domainname command),
and begins broadcasting RPC requests on the local network.
These requests specify the name of the domain for which
ypbind is attempting to establish a binding.
If a server that has been configured to serve the requested
domain receives one of the broadcasts, it will respond to
ypbind, which will record the server's
address. If there are several servers available (a master and
several slaves, for example), ypbind will
use the address of the first one to respond. From that point
on, the client system will direct all of its NIS requests to
that server. ypbind will
occasionally ping the server to make sure it is
still up and running. If it fails to receive a reply to one of
its pings within a reasonable amount of time,
ypbind will mark the domain as unbound and
begin broadcasting again in the hopes of locating another
server.Setting Up a NIS 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, remove all user accounts from your
/etc/master.passwd file and use
vipw to add the following line to
the end of the file:+:::::::::This line will afford anyone with a valid account in
the NIS server's password maps an account. There are
many ways to configure your NIS client by changing this
line. See the netgroups
section below for more information.
For more detailed reading see O'Reilly's book on
Managing NFS and NIS.You should keep at least one local account (i.e.
not imported via NIS) in your
/etc/master.passwd and this
account should also be a member of the group
wheel. If there is something
wrong with NIS, this account can be used to log in
remotely, become root, and fix things.To import all possible group entries from the NIS
server, add this line to your
/etc/group file:+:*::After completing these steps, you should be able to run
ypcat passwd and see the NIS server's
passwd map.NIS SecurityIn general, any remote user can issue an RPC to
&man.ypserv.8; and retrieve the contents of your NIS maps,
provided the remote user knows your domainname. To prevent
such unauthorized transactions, &man.ypserv.8; supports a
feature called securenets which can be used to
restrict access to a given set of hosts. At startup,
&man.ypserv.8; will attempt to load the securenets information
from a file called
/var/yp/securenets.This path varies depending on the path specified with the
option. This file contains entries that
consist of a network specification and a network mask separated
by white space. Lines starting with # are
considered to be comments. A sample securenets file might look
like this:# allow connections from local host -- mandatory
127.0.0.1 255.255.255.255
# allow connections from any host
# on the 192.168.128.0 network
192.168.128.0 255.255.255.0
# allow connections from any host
# between 10.0.0.0 to 10.0.15.255
# this includes the machines in the testlab
10.0.0.0 255.255.240.0If &man.ypserv.8; receives a request from an address that
matches one of these rules, it will process the request
normally. If the address fails to match a rule, the request
will be ignored and a warning message will be logged. If the
/var/yp/securenets file does not exist,
ypserv will allow connections from any
host.The ypserv program also has support for
Wietse Venema's TCP Wrapper package.
This allows the administrator to use the
TCP Wrapper configuration files for
access control instead of
/var/yp/securenets.While both of these access control mechanisms provide some
security, they, like the privileged port test, are
vulnerable to IP spoofing attacks. All
NIS-related traffic should be blocked at your firewall.Servers using /var/yp/securenets
may fail to serve legitimate NIS clients with archaic TCP/IP
implementations. Some of these implementations set all
host bits to zero when doing broadcasts and/or fail to
observe the subnet mask when calculating the broadcast
address. While some of these problems can be fixed by
changing the client configuration, other problems may force
the retirement of the client systems in question or the
abandonment of /var/yp/securenets.Using /var/yp/securenets on a
server with such an archaic implementation of TCP/IP is a
really bad idea and will lead to loss of NIS functionality
for large parts of your network.TCP WrappersThe use of the TCP Wrapper
package increases the latency of your NIS server. The
additional delay may be long enough to cause timeouts in
client programs, especially in busy networks or with slow
NIS servers. If one or more of your client systems
suffers from these symptoms, you should convert the client
systems in question into NIS slave servers and force them
to bind to themselves.Barring Some Users from Logging OnIn our lab, there is a machine basie that
is supposed to be a faculty only workstation. We do not want
to take this machine out of the NIS domain, yet the
passwd file on the master NIS server
contains accounts for both faculty and students. What can we
do?There is a way to bar specific users from logging on to a
machine, even if they are present in the NIS database. To do
this, all you must do is add
-username to the
end of the /etc/master.passwd file on the
client machine, where username is
the username of the user you wish to bar from logging in.
This should preferably be done using vipw,
since vipw will sanity check your changes
to /etc/master.passwd, as well as
automatically rebuild the password database when you finish
editing. For example, if we wanted to bar user
bill from logging on to
basie we would:basie&prompt.root; vipw[add -bill to the end, exit]
vipw: rebuilding the database...
vipw: done
basie&prompt.root; cat /etc/master.passwd
root:[password]:0:0::0:0:The super-user:/root:/bin/csh
toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
operator:*:2:5::0:0:System &:/:/sbin/nologin
bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
+:::::::::
-bill
basie&prompt.root;UdoErdelhoffContributed by Using NetgroupsnetgroupsThe method shown in the previous section works reasonably
well if you need special rules for a very small number of
users and/or machines. On larger networks, you
will forget to bar some users from logging
onto sensitive machines, or you may even have to modify each
machine separately, thus losing the main benefit of NIS:
centralized administration.The NIS developers' solution for this problem is called
netgroups. Their purpose and semantics
can be compared to the normal groups used by &unix; file
systems. The main differences are the lack of a numeric ID
and the ability to define a netgroup by including both user
accounts and other netgroups.Netgroups were developed to handle large, complex networks
with hundreds of users and machines. On one hand, this is
a Good Thing if you are forced to deal with such a situation.
On the other hand, this complexity makes it almost impossible to
explain netgroups with really simple examples. The example
used in the remainder of this section demonstrates this
problem.Let us assume that your successful introduction of NIS in
your laboratory caught your superiors' interest. Your next
job is to extend your NIS domain to cover some of the other
machines on campus. The two tables contain the names of the
new users and new machines as well as brief descriptions of
them.User Name(s)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 &man.ypinit.8; does not create this map by
default, but its NIS implementation will support it once it has
been created. To create an empty map, simply 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 the 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
configuration on each and every machine... As the old saying
goes: Errors in centralized planning lead to global
mess.NIS' ability to create netgroups from other netgroups can
be used to prevent situations like these. One possibility
is the creation of role-based netgroups. For example, you
could create a netgroup called
BIGSRV to define the login
restrictions for the important servers, another netgroup
called SMALLSRV for the less
important servers and a third netgroup called
USERBOX for the normal
workstations. Each of these netgroups contains the netgroups
that are allowed to login onto these machines. The new
entries for your NIS map netgroup should look like this:BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN 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 of
dozen or even hundreds of identical machines for student labs,
you should use role-based netgroups instead of machine-based
netgroups to keep the size of the NIS map within reasonable
limits.Important Things to 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 do not want to be propagating
administrative accounts and passwords to machines that
will have users that should not have access to those
accounts.Keep the NIS master and slave secure, and
minimize their downtime. If somebody either
hacks or simply turns off these machines, they have
effectively rendered many people without the ability to
login to the lab.This is the chief weakness of any centralized administration
system. If you do
not protect your NIS servers, you will have a lot of angry
users!NIS v1 Compatibility FreeBSD's ypserv has some
support for serving NIS v1 clients. FreeBSD's NIS
implementation only uses the NIS v2 protocol, however other
implementations include support for the v1 protocol for
backwards compatibility with older systems. The
ypbind daemons supplied with these
systems will try to establish a binding to an NIS v1 server
even though they may never actually need it (and they may
persist in broadcasting in search of one even after they
receive a response from a v2 server). Note that while support
for normal client calls is provided, this version of
ypserv does not handle v1 map
transfer requests; consequently, it cannot be used as a master
or slave in conjunction with older NIS servers that only
support the v1 protocol. Fortunately, there probably are not
any such servers still in use today.NIS Servers That Are Also NIS Clients Care must be taken when running
ypserv in a multi-server domain
where the server machines are also NIS clients. It is
generally a good idea to force the servers to bind to
themselves rather than allowing them to broadcast bind
requests and possibly become bound to each other. Strange
failure modes can result if one server goes down and others
are dependent upon it. Eventually all the clients will time
out and attempt to bind to other servers, but the delay
involved can be considerable and the failure mode is still
present since the servers might bind to each other all over
again.You can force a host to bind to a particular server by running
ypbind with the
flag. If you do not want to do this manually each time you
reboot your NIS server, you can add the following lines to
your /etc/rc.conf:nis_client_enable="YES" # run client stuff as well
nis_client_flags="-S NIS domain,server"See &man.ypbind.8; for further information.Password FormatsNISpassword formatsOne of the most common issues that people run into when trying
to implement NIS is password format compatibility. If your NIS
server is using DES encrypted passwords, it will only support
clients that are also using DES. For example, if you have
&solaris; NIS clients in your network, then you will almost certainly
need to use DES encrypted passwords.To check which format your servers
and clients are using, look at /etc/login.conf.
If the host is configured to use DES encrypted passwords, then the
default class will contain an entry like this:default:\
:passwd_format=des:\
:copyright=/etc/COPYRIGHT:\
[Further entries elided]Other possible values for the passwd_format
capability include blf and md5
(for Blowfish and MD5 encrypted passwords, respectively).If you have made changes to
/etc/login.conf, you will also need to
rebuild the login capability database, which is achieved by
running the following command as
root:&prompt.root; cap_mkdb /etc/login.confThe format of passwords already in
/etc/master.passwd will not be updated
until a user changes his password for the first time
after the login capability database is
rebuilt.Next, in order to ensure that passwords are encrypted with
the format that you have chosen, you should also check that
the crypt_default in
/etc/auth.conf gives precedence to your
chosen password format. To do this, place the format that you
have chosen first in the list. For example, when using DES
encrypted passwords, the entry would be:crypt_default = des blf md5Having followed the above steps on each of the &os; based
NIS servers and clients, you can be sure that they all agree
on which password format is used within your network. If you
have trouble authenticating on an NIS client, this is a pretty
good place to start looking for possible problems. Remember:
if you want to deploy an NIS server for a heterogenous
network, you will probably have to use DES on all systems
because it is the lowest common standard.GregSutterWritten by Automatic Network Configuration (DHCP)What Is DHCP?Dynamic Host Configuration ProtocolDHCPInternet Software Consortium (ISC)DHCP, the Dynamic Host Configuration Protocol, describes
the means by which a system can connect to a network and obtain the
necessary information for communication upon that network. FreeBSD
versions prior to 6.0 use the ISC (Internet Software
Consortium) DHCP client (&man.dhclient.8;) implementation.
Later versions use the OpenBSD dhclient
taken from OpenBSD 3.7. All
information here regarding dhclient is for
use with either of the ISC or OpenBSD DHCP clients. The DHCP
server is the one included in the ISC distribution.What This Section CoversThis section describes both the client-side components of the ISC and OpenBSD DHCP client and
server-side components of the ISC DHCP system. The
client-side program, dhclient, comes
integrated within FreeBSD, and the server-side portion is
available from the net/isc-dhcp3-server port. The
&man.dhclient.8;, &man.dhcp-options.5;, and
&man.dhclient.conf.5; manual pages, in addition to the
references below, are useful resources.How It 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 Integration&os; fully integrates the ISC or OpenBSD DHCP client,
dhclient (according to the &os; version you run). DHCP client support is provided
within both the installer and the base system, obviating the need
for detailed knowledge of network configurations on any network
that runs a DHCP server. dhclient has been
included in all FreeBSD distributions since 3.2.sysinstallDHCP is supported by
sysinstall. When configuring a
network interface within
sysinstall, the second question
asked is: Do you want to try DHCP configuration of
the interface?. Answering affirmatively will
execute dhclient, and if successful, will
fill in the network configuration information
automatically.There are two things you must do to have your system use
DHCP upon startup:DHCPrequirementsMake sure that the bpf
device is compiled into your kernel. To do this, add
device bpf to your kernel
configuration file, and rebuild the kernel. For more
information about building kernels, see .The
bpf device is already part of
the GENERIC kernel that is supplied
with FreeBSD, so if you do not have a custom kernel, you
should not need to create one in order to get DHCP
working.For those who are particularly security conscious,
you should be warned that bpf
is also the device that allows packet sniffers to work
correctly (although they still have to be run as
root). bpfis required to use DHCP, but if
you are very sensitive about security, you probably
should not add bpf to your
kernel in the expectation that at some point in the
future you will be using DHCP.Edit your /etc/rc.conf to
include the following:ifconfig_fxp0="DHCP"Be sure to replace fxp0 with the
designation for the interface that you wish to dynamically
configure, as described in
.If you are using a different location for
dhclient, or if you wish to pass additional
flags to dhclient, also include the
following (editing as necessary):dhclient_program="/sbin/dhclient"
dhclient_flags=""DHCPserverThe DHCP server, dhcpd, is included
as part of the net/isc-dhcp3-server port in the ports
collection. This port contains the ISC DHCP server and
documentation.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;
manual 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
.Installing and Configuring a DHCP ServerWhat This Section CoversThis section provides information on how to configure
a FreeBSD system to act as a DHCP server using the ISC
(Internet Software Consortium) implementation of the DHCP
server.The server is not provided as part of
FreeBSD, and so you will need to install the
net/isc-dhcp3-server
port to provide this service. See for
more information on using the Ports Collection.DHCP Server InstallationDHCPinstallationIn order to configure your FreeBSD system as a DHCP
server, you will need to ensure that the &man.bpf.4;
device is compiled into your kernel. To do this, add
device bpf to your kernel
configuration file, and rebuild the kernel. For more
information about building kernels, see .The bpf device is already
part of the GENERIC kernel that is
supplied with FreeBSD, so you do not need to create a custom
kernel in order to get DHCP working.Those who are particularly security conscious
should note that bpf
is also the device that allows packet sniffers to work
correctly (although such programs still need privileged
access). bpfis required to use DHCP, but if
you are very sensitive about security, you probably
should not include bpf in your
kernel purely because you expect to use DHCP at some
point in the future.The next thing that you will need to do is edit the sample
dhcpd.conf which was installed by the
net/isc-dhcp3-server port.
By default, this will be
/usr/local/etc/dhcpd.conf.sample, and you
should copy this to
/usr/local/etc/dhcpd.conf before proceeding
to make changes.Configuring the DHCP ServerDHCPdhcpd.confdhcpd.conf is
comprised of declarations regarding subnets and hosts, and is
perhaps most easily explained using an example :option domain-name "example.com";
option domain-name-servers 192.168.4.100;
option subnet-mask 255.255.255.0;
default-lease-time 3600;
max-lease-time 86400;
ddns-update-style none;
subnet 192.168.4.0 netmask 255.255.255.0 {
range 192.168.4.129 192.168.4.254;
option routers 192.168.4.1;
}
host mailhost {
hardware ethernet 02:03:04:05:06:07;
fixed-address mailhost.example.com;
}This option specifies the domain that will be provided
to clients as the default search domain. See
&man.resolv.conf.5; for more information on what this
means.This option specifies a comma separated list of DNS
servers that the client should use.The netmask that will be provided to clients.A client may request a specific length of time that a
lease will be valid. Otherwise the server will assign
a lease with this expiry value (in seconds).This is the maximum length of time that the server will
lease for. Should a client request a longer lease, a lease
will be issued, although it will only be valid for
max-lease-time seconds.This option specifies whether the DHCP server should
attempt to update DNS when a lease is accepted or released.
In the ISC implementation, this option is
required.This denotes which IP addresses should be used in
the pool reserved for allocating to clients. IP
addresses between, and including, the ones stated are
handed out to clients.Declares the default gateway that will be provided to
clients.The hardware MAC address of a host (so that the DHCP server
can recognize a host when it makes a request).Specifies that the host should always be given the
same IP address. Note that using a hostname is
correct here, since the DHCP server will resolve the
hostname itself before returning the lease
information.Once you have finished writing your
dhcpd.conf,
you should enable the DHCP server in
/etc/rc.conf, i.e. by adding:dhcpd_enable="YES"
dhcpd_ifaces="dc0"Replace the dc0 interface name with the
interface (or interfaces, separated by whitespace) that your DHCP
server should listen on for DHCP client requests.Then, you can proceed to start the server by issuing the
following command:&prompt.root; /usr/local/etc/rc.d/isc-dhcpd.sh startShould you need to make changes to the configuration of your
server in the future, it is important to note that sending a
SIGHUP signal to
dhcpd does not
result in the configuration being reloaded, as it does with most
daemons. You will need to send a SIGTERM
signal to stop the process, and then restart it using the command
above.FilesDHCPconfiguration files/usr/local/sbin/dhcpddhcpd is statically linked and
resides in /usr/local/sbin. The
&man.dhcpd.8; manual page installed with the
port gives more information about
dhcpd./usr/local/etc/dhcpd.confdhcpd requires a configuration
file, /usr/local/etc/dhcpd.conf before it
will start providing service to clients. This file needs to
contain all the information that should be provided to clients
that are being serviced, along with information regarding the
operation of the server. This configuration file is described
by the &man.dhcpd.conf.5; manual page installed
by the port./var/db/dhcpd.leasesThe DHCP server keeps a database of leases it has issued
in this file, which is written as a log. The manual page
&man.dhcpd.leases.5;, installed by the port
gives a slightly longer description./usr/local/sbin/dhcrelaydhcrelay is used in advanced
environments where one DHCP server forwards a request from a
client to another DHCP server on a separate network. If you
require this functionality, then install the net/isc-dhcp3-relay port. The
&man.dhcrelay.8; manual page provided with the
port contains more detail.ChernLeeContributed by TomRhodesDanielGerzoDomain Name System (DNS)OverviewBIND&os; utilizes, by default, a version of BIND (Berkeley
Internet Name Domain), which is the most common implementation
of the DNS protocol. DNS
is the protocol through which names are mapped to
IP addresses, and vice versa. For example, a
query for www.FreeBSD.org will
receive a reply with the IP address of The
&os; Project's web server, whereas, a query for ftp.FreeBSD.org will return the
IP address of the corresponding
FTP machine. Likewise, the opposite can
happen. A query for an IP address can
resolve its hostname. It is not necessary to run a name server
to perform DNS lookups on a system.&os; currently comes with BIND9
DNS server software by default. Our
installation provides enhanced security features, a new file
system layout and automated &man.chroot.8; configuration.DNSDNS is coordinated across the Internet
through a somewhat complex system of authoritative root, Top
Level Domain (TLD), and other smaller-scale
name servers which host and cache individual domain
information.Currently, BIND is maintained by the
Internet Software Consortium
.TerminologyTo understand this document, some terms related to
DNS must be understood.resolverreverse DNSroot zoneTermDefinitionForward DNSMapping of hostnames to IP addresses.OriginRefers to the domain covered in a particular zone
file.named, BIND, name serverCommon names for the BIND name server package within
&os;.ResolverA system process through which a
machine queries a name server for zone information.Reverse DNSThe opposite of forward DNS;
mapping of IP addresses to
hostnames.Root zoneThe beginning of the Internet zone hierarchy.
All zones fall under the root zone, similar to how
all files in a file system fall under the root
directory.ZoneAn individual domain, subdomain, or portion of the
DNS administered by the same
authority.zonesexamplesExamples of zones:. is the root zone.org. is a Top Level Domain
(TLD) under the root zone.example.org. is a
zone under the org.
TLD.1.168.192.in-addr.arpa is a zone
referencing all IP addresses which fall
under the 192.168.1.*
IP space.As one can see, the more specific part of a hostname appears
to its left. For example, example.org. is more specific than
org., as org. is more specific
than the root zone. The layout of each part of a hostname is
much like a file system: the
/dev directory falls
within the root, and so on.Reasons to Run a Name ServerName servers usually come in two forms: an authoritative
name server, and a caching name server.An authoritative name server is needed when:One wants to serve DNS information to
the world, replying authoritatively to queries.A domain, such as example.org, is registered and
IP addresses need to be assigned to
hostnames under it.An IP address block requires reverse
DNS entries (IP to
hostname).A backup or second name server, called a slave, will
reply to queries.A caching name server is needed when:A local DNS server may cache and
respond more quickly than querying an outside name
server.When one queries for www.FreeBSD.org, the resolver usually
queries the uplink ISP's name server, and
retrieves the reply. With a local, caching
DNS server, the query only has to be made
once to the outside world by the caching DNS
server. Every additional query will not have to look to the
outside of the local network, since the information is cached
locally.How It WorksIn &os;, the BIND daemon is called
named for obvious reasons.FileDescription&man.named.8;The BIND daemon.&man.rndc.8;Name server control utility./etc/namedbDirectory where BIND zone information resides./etc/namedb/named.confConfiguration file of the daemon.Depending on how a given zone is configured on the server,
the files related to that zone can be found in the master, slave, or dynamic subdirectories of the
/etc/namedb directory.
These files contain the DNS information that
will be given out by the name server in response to queries.Starting BINDBINDstartingSince BIND is installed by default, configuring it all is
relatively simple.The default named configuration
is that of a basic resolving name server, ran in a
&man.chroot.8; environment. To start the server one time with
this configuration, use the following command:&prompt.root; /etc/rc.d/named forcestartTo ensure the named daemon is
started at boot each time, put the following line into the
/etc/rc.conf:named_enable="YES"There are obviously many configuration options for
/etc/namedb/named.conf that are beyond the
scope of this document. However, if you are interested in the
startup options for named on &os;,
take a look at the
named_* flags in
/etc/defaults/rc.conf and consult the
&man.rc.conf.5; manual page. The
section is also a good read.Configuration FilesBINDconfiguration filesConfiguration files for named
currently reside in
/etc/namedb directory and
will need modification before use, unless all that is needed is
a simple resolver. This is where most of the configuration will
be performed.Using make-localhostTo configure a master zone for the localhost visit the
/etc/namedb directory
and run the following command:&prompt.root; sh make-localhostIf all went well, a new file should exist in the
master subdirectory.
The filenames should be localhost.rev for
the local domain name and localhost-v6.rev
for IPv6 configurations. As the default
configuration file, required information will
be present in the named.conf file./etc/namedb/named.conf// $FreeBSD$
//
// Refer to the named.conf(5) and named(8) man pages, and the documentation
// in /usr/share/doc/bind9 for more details.
//
// If you are going to set up an authoritative server, make sure you
// understand the hairy details of how DNS works. Even with
// simple mistakes, you can break connectivity for affected parties,
// or cause huge amounts of useless Internet traffic.
options {
directory "/etc/namedb";
pid-file "/var/run/named/pid";
dump-file "/var/dump/named_dump.db";
statistics-file "/var/stats/named.stats";
// If named is being used only as a local resolver, this is a safe default.
// For named to be accessible to the network, comment this option, specify
// the proper IP address, or delete this option.
listen-on { 127.0.0.1; };
// If you have IPv6 enabled on this system, uncomment this option for
// use as a local resolver. To give access to the network, specify
// an IPv6 address, or the keyword "any".
// listen-on-v6 { ::1; };
// In addition to the "forwarders" clause, you can force your name
// server to never initiate queries of its own, but always ask its
// forwarders only, by enabling the following line:
//
// forward only;
// If you've got a DNS server around at your upstream provider, enter
// its IP address here, and enable the line below. This will make you
// benefit from its cache, thus reduce overall DNS traffic in the Internet.
/*
forwarders {
127.0.0.1;
};
*/Just as the comment says, to benefit from an uplink's
cache, forwarders can be enabled here.
Under normal circumstances, a name server will recursively
query the Internet looking at certain name servers until it
finds the answer it is looking for. Having this enabled will
have it query the uplink's name server (or name server
provided) first, taking advantage of its cache. If the uplink
name server in question is a heavily trafficked, fast name
server, enabling this may be worthwhile.127.0.0.1 will
not work here. Change this
IP address to a name server at your
uplink. /*
* If there is a firewall between you and nameservers you want
* to talk to, you might need to uncomment the query-source
* directive below. Previous versions of BIND always asked
* questions using port 53, but BIND versions 8 and later
* use a pseudo-random unprivileged UDP port by default.
*/
// query-source address * port 53;
};
// If you enable a local name server, don't forget to enter 127.0.0.1
// first in your /etc/resolv.conf so this server will be queried.
// Also, make sure to enable it in /etc/rc.conf.
zone "." {
type hint;
file "named.root";
};
zone "0.0.127.IN-ADDR.ARPA" {
type master;
file "master/localhost.rev";
};
// RFC 3152
zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA" {
type master;
file "master/localhost-v6.rev";
};
// NB: Do not use the IP addresses below, they are faked, and only
// serve demonstration/documentation purposes!
//
// Example slave zone config entries. It can be convenient to become
// a slave at least for the zone your own domain is in. Ask
// your network administrator for the IP address of the responsible
// primary.
//
// Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
// (This is named after the first bytes of the IP address, in reverse
// order, with ".IN-ADDR.ARPA" appended.)
//
// Before starting to set up a primary zone, make sure you fully
// understand how DNS and BIND works. There are sometimes
// non-obvious pitfalls. Setting up a slave zone is simpler.
//
// NB: Don't blindly enable the examples below. :-) Use actual names
// and addresses instead.
/* An example master zone
zone "example.net" {
type master;
file "master/example.net";
};
*/
/* An example dynamic zone
key "exampleorgkey" {
algorithm hmac-md5;
secret "sf87HJqjkqh8ac87a02lla==";
};
zone "example.org" {
type master;
allow-update {
key "exampleorgkey";
};
file "dynamic/example.org";
};
*/
/* Examples of forward and reverse slave zones
zone "example.com" {
type slave;
file "slave/example.com";
masters {
192.168.1.1;
};
};
zone "1.168.192.in-addr.arpa" {
type slave;
file "slave/1.168.192.in-addr.arpa";
masters {
192.168.1.1;
};
};
*/In named.conf, these are examples of
slave entries for a forward and reverse zone.For each new zone served, a new zone entry must be added
to named.conf.For example, the simplest zone entry for
example.org can look
like:zone "example.org" {
type master;
file "master/example.org";
};The zone is a master, as indicated by the
statement, holding its zone information
in /etc/namedb/master/example.org
indicated by the statement.zone "example.org" {
type slave;
file "slave/example.org";
};In the slave case, the zone information is transferred
from the master name server for the particular zone, and saved
in the file specified. If and when the master server dies or
is unreachable, the slave name server will have the
transferred zone information and will be able to serve
it.Zone FilesBINDzone filesAn example master zone file for example.org (existing within
/etc/namedb/master/example.org) is as
follows:$TTL 3600 ; 1 hour
example.org. IN SOA ns1.example.org. admin.example.org. (
2006051501 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ; Minimum TTL
)
; DNS Servers
IN NS ns1.example.org.
IN NS ns2.example.org.
; MX Records
IN MX 10 mx.example.org.
IN MX 20 mail.example.org.
IN A 192.168.1.1
; Machine Names
localhost IN A 127.0.0.1
ns1 IN A 192.168.1.2
ns2 IN A 192.168.1.3
mx IN A 192.168.1.4
mail IN A 192.168.1.5
; Aliases
www IN CNAME @
Note that every hostname ending in a . is an
exact hostname, whereas everything without a trailing
. is referenced to the origin. For example,
www is translated into
www.origin.
In our fictitious zone file, our origin is
example.org., so www
would translate to www.example.org.
The format of a zone file follows:
recordname IN recordtype valueDNSrecords
The most commonly used DNS records:
SOAstart of zone authorityNSan authoritative name serverAa host addressCNAMEthe canonical name for an aliasMXmail exchangerPTRa domain name pointer (used in reverse DNS)
example.org. IN SOA ns1.example.org. admin.example.org. (
2006051501 ; Serial
10800 ; Refresh after 3 hours
3600 ; Retry after 1 hour
604800 ; Expire after 1 week
86400 ) ; Minimum TTL of 1 dayexample.org.the domain name, also the origin for this
zone file.ns1.example.org.the primary/authoritative name server for this
zone.admin.example.org.the responsible person for this zone,
email address with @
replaced. (admin@example.org becomes
admin.example.org)2006051501the serial number of the file. This
must be incremented each time the zone file is
modified. Nowadays, many admins prefer a
yyyymmddrr format for the serial
number. 2006051501 would mean
last modified 05/15/2006, the latter
01 being the first time the zone
file has been modified this day. The serial number
is important as it alerts slave name servers for a
zone when it is updated.
IN NS ns1.example.org.
This is an NS entry. Every name server that is going to reply
authoritatively for the zone must have one of these entries.
localhost IN A 127.0.0.1
ns1 IN A 192.168.1.2
ns2 IN A 192.168.1.3
mx IN A 192.168.1.4
mail IN A 192.168.1.5
The A record indicates machine names. As seen above,
ns1.example.org would resolve
to 192.168.1.2.
IN A 192.168.1.1This line assigns IP address
192.168.1.1 to the current origin,
in this case example.org.
www IN CNAME @
The canonical name record is usually used for giving aliases
to a machine. In the example, www is
aliased to the master machine which name equals
to domain name example.org
(192.168.1.1).
CNAMEs can be used to provide alias
hostnames, or round robin one hostname among multiple
machines.
MX record
IN MX 10 mail.example.org.
The MX record indicates which mail
servers are responsible for handling incoming mail for the
zone. mail.example.org is the
hostname of the mail server, and 10 being the priority of
that mail server.
One can have several mail servers, with priorities of 10,
20 and so on. A mail server attempting to deliver to example.org would first try the
highest priority MX (the record with the lowest priority
number), then the second highest, etc, until the mail can be
properly delivered.
For in-addr.arpa zone files (reverse DNS), the same format is
used, except with PTR entries instead of
A or CNAME.
$TTL 3600
1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
2006051501 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
IN NS ns1.example.org.
IN NS ns2.example.org.
1 IN PTR example.org.
2 IN PTR ns1.example.org.
3 IN PTR ns2.example.org.
4 IN PTR mx.example.org.
5 IN PTR mail.example.org.This file gives the proper IP address to hostname
mappings of our above fictitious domain.Caching Name ServerBINDcaching name serverA caching name server is a name server that is not
authoritative for any zones. It simply asks queries of its
own, and remembers them for later use. To set one up, just
configure the name server as usual, omitting any inclusions of
zones.SecurityAlthough BIND is the most common implementation of DNS,
there is always the issue of security. Possible and
exploitable security holes are sometimes found.
While &os; automatically drops
named into a &man.chroot.8;
environment; there are several other security mechanisms in
place which could help to lure off possible
DNS service attacks.It is always good idea to read CERT's security advisories
and to subscribe to the &a.security-notifications; to stay up to
date with the current Internet and &os; security issues.If a problem arises, keeping sources up to date and
having a fresh build of named would
not hurt.Further ReadingBIND/named manual pages:
&man.rndc.8; &man.named.8; &man.named.conf.5;Official ISC BIND
PageOfficial ISC BIND
Forum
BIND9 FAQO'Reilly
DNS and BIND 5th EditionRFC1034
- Domain Names - Concepts and FacilitiesRFC1035
- Domain Names - Implementation and SpecificationMurrayStokelyContributed by Apache HTTP Serverweb serverssetting upApacheOverview&os; is used to run some of the busiest web sites in the
world. The majority of web servers on the Internet are using
the Apache HTTP Server.
Apache software packages should be
included on your FreeBSD installation media. If you did not
install Apache when you first
installed FreeBSD, then you can install it from the www/apache13 or www/apache22 port.Once Apache has been installed
successfully, it must be configured.This section covers version 1.3.X of the
Apache HTTP Server as that is the
most widely used version for &os;. Apache 2.X introduces many
new technologies but they are not discussed here. For more
information about Apache 2.X, please see .ConfigurationApacheconfiguration fileThe main Apache HTTP Server configuration file is
installed as
/usr/local/etc/apache/httpd.conf on &os;.
This file is a typical &unix; text configuration file with
comment lines beginning with the #
character. A comprehensive description of all possible
configuration options is outside the scope of this book, so
only the most frequently modified directives will be described
here.ServerRoot "/usr/local"This specifies the default directory hierarchy for
the Apache installation. Binaries are stored in the
bin and
sbin subdirectories
of the server root, and configuration files are stored in
etc/apache.ServerAdmin you@your.addressThe address to which problems with the server should
be emailed. This address appears on some
server-generated pages, such as error documents.ServerName www.example.comServerName allows you to set a host name which is
sent back to clients for your server if it is different
to the one that the host is configured with (i.e., use www
instead of the host's real name).DocumentRoot "/usr/local/www/data"DocumentRoot: The directory out of which you will
serve your documents. By default, all requests are taken
from this directory, but symbolic links and aliases may
be used to point to other locations.It is always a good idea to make backup copies of your
Apache configuration file before making changes. Once you are
satisfied with your initial configuration you are ready to
start running Apache.Running ApacheApachestarting or stoppingApache does not run from the
inetd super server as many other
network servers do. It is configured to run standalone for
better performance for incoming HTTP requests from client web
browsers. A shell script wrapper is included to make
starting, stopping, and restarting the server as simple as
possible. To start up Apache for
the first time, just run:&prompt.root; /usr/local/sbin/apachectl startYou can stop the server at any time by typing:&prompt.root; /usr/local/sbin/apachectl stopAfter making changes to the configuration file for any
reason, you will need to restart the server:&prompt.root; /usr/local/sbin/apachectl restartTo restart Apache without
aborting current connections, run:&prompt.root; /usr/local/sbin/apachectl gracefulAdditional information available at
&man.apachectl.8; manual page.To launch Apache at system
startup, add the following line to
/etc/rc.conf:apache_enable="YES"or for Apache 2.2:apache22_enable="YES"If you would like to supply additional command line
options for the Apachehttpd program started at system boot, you
may specify them with an additional line in
rc.conf:apache_flags=""Now that the web server is running, you can view your web
site by pointing a web browser to
http://localhost/. The default web page
that is displayed is
/usr/local/www/data/index.html.Virtual HostingApache supports two different
types of Virtual Hosting. The first method is Name-based
Virtual Hosting. Name-based virtual hosting uses the clients
HTTP/1.1 headers to figure out the hostname. This allows many
different domains to share the same IP address.To setup Apache to use
Name-based Virtual Hosting add an entry like the following to
your httpd.conf:NameVirtualHost *If your webserver was named www.domain.tld and
you wanted to setup a virtual domain for
www.someotherdomain.tld then you would add
the following entries to
httpd.conf:<VirtualHost *>
ServerName www.domain.tld
DocumentRoot /www/domain.tld
</VirtualHost>
<VirtualHost *>
ServerName www.someotherdomain.tld
DocumentRoot /www/someotherdomain.tld
</VirtualHost>Replace the addresses with the addresses you want to use
and the path to the documents with what you are using.For more information about setting up virtual hosts,
please consult the official Apache
documentation at: .Apache ModulesApachemodulesThere are many different Apache modules available to add
functionality to the basic server. The FreeBSD Ports
Collection provides an easy way to install
Apache together with some of the
more popular add-on modules.mod_sslweb serverssecureSSLcryptographyThe mod_ssl module uses the OpenSSL library to provide
strong cryptography via the Secure Sockets Layer (SSL v2/v3)
and Transport Layer Security (TLS v1) protocols. This
module provides everything necessary to request a signed
certificate from a trusted certificate signing authority so
that you can run a secure web server on &os;.If you have not yet installed
Apache, then a version of Apache
1.3.X that includes mod_ssl may be installed with the www/apache13-modssl port. SSL
support is also available for Apache 2.X in the
www/apache22 port,
where it is enabled by default.Language BindingsThere are Apache modules for most major scripting
languages. These modules typically make it possible to
write Apache modules entirely in
a scripting language. They are also often used as a
persistent interpreter embedded into the server that avoids
the overhead of starting an external interpreter and the
startup-time penalty for dynamic websites, as described in
the next section.Dynamic Websitesweb serversdynamicIn the last decade, more businesses have turned to the
Internet in order to enhance their revenue and increase
exposure. This has also increased the need for interactive
web content. While some companies, such as µsoft;,
have introduced solutions into their proprietary products,
the open source community answered the call. Modern options
for dynamic web content include Django, Ruby on Rails,
mod_perl, and
mod_php.DjangoPythonDjangoDjango is a BSD licensed framework designed to allow
developers to write high performance, elegant web
applications quickly. It provides an object-relational
mapper so that data types are developed as Python objects,
and a rich dynamic database-access API is provided for those
objects without the developer ever having to write SQL. It
also provides an extensible template system so that the
logic of the application is separated from the HTML
presentation.Django depends on mod_python,
Apache, and an SQL database
engine of your choice. The FreeBSD Port will install all of
these pre-requisites for you with the appropriate flags.Installing Django with Apache2, mod_python3, and PostgreSQL&prompt.root; cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQLOnce Django and these pre-requisites are installed, you
will need to create a Django project directory and then
configure Apache to use the embedded Python interpreter to
call your application for specific URLs on your site.Apache Configuration for Django/mod_pythonYou will need to add a line to the apache
httpd.conf file to configure Apache
to pass requests for certain URLs to your web
application:<Location "/">
SetHandler python-program
PythonPath "['/dir/to/your/django/packages/'] + sys.path"
PythonHandler django.core.handlers.modpython
SetEnv DJANGO_SETTINGS_MODULE mysite.settings
PythonAutoReload On
PythonDebug On
</Location>Ruby on RailsRuby on RailsRuby on Rails is another open source web framework that
provides a full development stack and is optimized to make
web developers more productive and capable of writing
powerful applications quickly. It can be installed easily
from the ports system.&prompt.root; cd /usr/ports/www/rubygem-rails; make all install cleanmod_perlmod_perlPerlThe Apache/Perl integration project brings together the
full power of the Perl programming language and the Apache
HTTP Server. With the mod_perl module it is possible to
write Apache modules entirely in Perl. In addition, the
persistent interpreter embedded in the server avoids the
overhead of starting an external interpreter and the penalty
of Perl start-up time.mod_perl is available a few
different ways. To use mod_perl
remember that mod_perl 1.0 only
works with Apache 1.3 and
mod_perl 2.0 only works with
Apache 2.X.
mod_perl 1.0 is available in
www/mod_perl and a
statically compiled version is available in
www/apache13-modperl.
- mod_perl 2.0 is avaliable in
+ mod_perl 2.0 is available in
www/mod_perl2.TomRhodesWritten by mod_phpmod_phpPHPPHP, also known as PHP:
Hypertext Preprocessor is a general-purpose scripting
language that is especially suited for Web development.
Capable of being embedded into HTML its
syntax draws upon C, &java;, and Perl with the intention of
allowing web developers to write dynamically generated
webpages quickly.To gain support for PHP5 for the
Apache web server, begin by
installing the
lang/php5
port.If the lang/php5 port
is being installed for the first time, available
OPTIONS will be displayed automatically.
If a menu is not displayed, i.e. because the lang/php5 port has been installed
some time in the past, it is always possible to bring the
options dialog up again by running:&prompt.root; make configin the port directory.In the options dialog, check the
APACHE option to build
mod_php5 as a loadable module for
the Apache web server.A lot of sites are still using PHP4
for various reasons (i.e. compatibility issues or already
deployed web applications). If the
mod_php4 is needed instead of
mod_php5, then please use the
lang/php4 port. The
lang/php4 port supports
many of the configuration and build-time options of the
lang/php5 port.This will install and configure the modules required
to support dynamic PHP applications. Check
to ensure the following sections have been added to
/usr/local/etc/apache/httpd.conf:LoadModule php5_module libexec/apache/libphp5.soAddModule mod_php5.c
<IfModule mod_php5.c>
DirectoryIndex index.php index.html
</IfModule>
<IfModule mod_php5.c>
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps
</IfModule>Once completed, a simple call to the
apachectl command for a graceful
restart is needed to load the PHP
module:&prompt.root; apachectl gracefulFor future upgrades of PHP, the
make config command will not be required;
the selected OPTIONS are saved
automatically by the &os; Ports framework.The PHP support in &os; is extremely
modular so the base install is very limited. It is very easy
to add support using the
lang/php5-extensions port.
This port provides a menu driven interface to
PHP extension installation.
Alternatively, individual extensions can be installed using
the appropriate port.For instance, to add support for the
MySQL database server to
PHP5, simply install the
databases/php5-mysql
port.After installing an extension, the
Apache server must be reloaded to
pick up the new configuration changes:&prompt.root; apachectl gracefulMurrayStokelyContributed by File Transfer Protocol (FTP)FTP serversOverviewThe File Transfer Protocol (FTP) provides users with a
simple way to transfer files to and from an FTP server. &os;
includes FTP
server software, ftpd, in the base
system. This makes setting up and administering an FTP server on FreeBSD
very straightforward.ConfigurationThe most important configuration step is deciding which
accounts will be allowed access to the FTP server. A normal
FreeBSD system has a number of system accounts used for
various daemons, but unknown users should not be allowed to
log in with these accounts. The
/etc/ftpusers file is a list of users
disallowed any FTP access. By default, it includes the
aforementioned system accounts, but it is possible to add
specific users here that should not be allowed access to
FTP.You may want to restrict the access of some users without
preventing them completely from using FTP. This can be
accomplished with the /etc/ftpchroot
file. This file lists users and groups subject to FTP access
restrictions. The &man.ftpchroot.5; manual page has all of
the details so it will not be described in detail here.FTPanonymousIf you would like to enable anonymous FTP access to your
server, then you must create a user named
ftp on your &os; system. Users will then
be able to log on to your FTP server with a username of
ftp or anonymous and
with any password (by convention an email address for the user
should be used as the password). The FTP server will call
&man.chroot.2; when an anonymous user logs in, to restrict
access to only the home directory of the
ftp user.There are two text files that specify welcome messages to
be displayed to FTP clients. The contents of the file
/etc/ftpwelcome will be displayed to
users before they reach the login prompt. After a successful
login, the contents of the file
/etc/ftpmotd will be displayed. Note
that the path to this file is relative to the login environment, so the
file ~ftp/etc/ftpmotd would be displayed
for anonymous users.Once the FTP server has been configured properly, it must
be enabled in /etc/inetd.conf. All that
is required here is to remove the comment symbol
# from in front of the existing
ftpd line :ftp stream tcp nowait root /usr/libexec/ftpd ftpd -lAs explained in ,
the inetd configuration must be reloaded
after this configuration file is changed. Please refer to
for details on enabling
inetd on your system.Alternatively, ftpd can also be
started as a stand-alone server. In this case, it is sufficient to
set the appropriate variable in
/etc/rc.conf:ftpd_enable="YES"After setting the above variable, the stand-alone server will be
started at the next reboot, or it can be started manually by
executing the following command as root:&prompt.root; /etc/rc.d/ftpd startYou can now log on to your FTP server by typing:&prompt.user; ftp localhostMaintainingsysloglog filesFTPThe ftpd daemon uses
&man.syslog.3; to log messages. By default, the system log
daemon will put messages related to FTP in the
/var/log/xferlog file. The location of
the FTP log can be modified by changing the following line in
/etc/syslog.conf:ftp.info /var/log/xferlogFTPanonymousBe aware of the potential problems involved with running
an anonymous FTP server. In particular, you should think
twice about allowing anonymous users to upload files. You may
find that your FTP site becomes a forum for the trade of
unlicensed commercial software or worse. If you do need to
allow anonymous FTP uploads, then you should set up the
permissions so that these files can not be read by other
anonymous users until they have been reviewed.MurrayStokelyContributed by File and Print Services for µsoft.windows; clients (Samba)Samba serverMicrosoft Windowsfile serverWindows clientsprint serverWindows clientsOverviewSamba is a popular open source
software package that provides file and print services for
µsoft.windows; clients. Such clients can connect to and
use FreeBSD filespace as if it was a local disk drive, or
FreeBSD printers as if they were local printers.Samba software packages should
be included on your FreeBSD installation media. If you did
not install Samba when you first
installed FreeBSD, then you can install it from the net/samba3 port or package.ConfigurationA default Samba configuration
file is installed as
/usr/local/share/examples/samba/smb.conf.default. This
file must be copied to
/usr/local/etc/smb.conf and customized
before Samba can be used.The smb.conf file contains runtime
configuration information for
Samba, such as definitions of the
printers and file system shares that you would
like to share with &windows; clients. The
Samba package includes a web based
tool called swat which provides a
simple way of configuring the smb.conf
file.Using the Samba Web Administration Tool (SWAT)The Samba Web Administration Tool (SWAT) runs as a
daemon from inetd. Therefore, the
following line in /etc/inetd.conf
should be uncommented before swat can be
used to configure Samba:swat stream tcp nowait/400 root /usr/local/sbin/swat swatAs explained in ,
the inetd configuration must be reloaded after this configuration
file is changed.Once swat has been enabled in
inetd.conf, you can use a browser to
connect to . You will
first have to log on with the system root account.Once you have successfully logged on to the main
Samba configuration page, you can
browse the system documentation, or begin by clicking on the
Globals tab. The Globals section corresponds to the
variables that are set in the [global]
section of
/usr/local/etc/smb.conf.Global SettingsWhether you are using swat or
editing /usr/local/etc/smb.conf
directly, the first directives you are likely to encounter
when configuring Samba
are:workgroupNT Domain-Name or Workgroup-Name for the computers
that will be accessing this server.netbios nameNetBIOSThis sets the NetBIOS name by which a Samba server
is known. By default it is the same as the first
component of the host's DNS name.server stringThis sets the string that will be displayed with
the net view command and some other
networking tools that seek to display descriptive text
about the server.Security SettingsTwo of the most important settings in
/usr/local/etc/smb.conf are the
security model chosen, and the backend password format for
client users. The following directives control these
options:securityThe two most common options here are
security = share and security
= user. If your clients use usernames that
are the same as their usernames on your &os; machine
then you will want to use user level security. This
is the default security policy and it requires clients
to first log on before they can access shared
resources.In share level security, client do not need to log
onto the server with a valid username and password
before attempting to connect to a shared resource.
This was the default security model for older versions
of Samba.passdb backendNIS+LDAPSQL databaseSamba has several
different backend authentication models. You can
authenticate clients with LDAP, NIS+, a SQL database,
or a modified password file. The default
authentication method is smbpasswd,
and that is all that will be covered here.Assuming that the default smbpasswd
backend is used, the
/usr/local/private/smbpasswd file must
be created to allow Samba to
authenticate clients. If you would like to give
your &unix; user accounts access from &windows; clients, use the
following command:&prompt.root; smbpasswd -a usernameSince Samba 3.0.23c, the actual
directory for authentication files is
/usr/local/etc/samba. The
recommended backend is now tdbsam, and the
following command should be used to add user accounts:&prompt.root; pdbedit usernamePlease see the
Official Samba HOWTO
for additional information about configuration
options. With the basics outlined here, you should have
everything you need to start running
Samba.Starting SambaThe net/samba3 port adds
a new startup script, which can be used to control
Samba. To enable this script, so
that it can be used for example to start, stop or restart
Samba, add the following line to the
/etc/rc.conf file:samba_enable="YES"Or, for fine grain control:nmbd_enable="YES"smbd_enable="YES"This will also configure Samba
to automatically start at system boot time.It is possible then to start
Samba at any time by typing:&prompt.root; /usr/local/etc/rc.d/samba start
Starting SAMBA: removing stale tdbs :
Starting nmbd.
Starting smbd.Please refer to for more
information about using rc scripts.Samba actually consists of
three separate daemons. You should see that both the
nmbd and smbd daemons
are started by the samba script. If
you enabled winbind name resolution services in
smb.conf, then you will also see that
the winbindd daemon is started.You can stop Samba at any time
by typing :&prompt.root; /usr/local/etc/rc.d/samba stopSamba is a complex software
suite with functionality that allows broad integration with
µsoft.windows; networks. For more information about
functionality beyond the basic installation described here,
please see .TomHukinsContributed by Clock Synchronization with NTPNTPOverviewOver time, a computer's clock is prone to drift. The
Network Time Protocol (NTP) is one way to ensure your clock stays
accurate.Many Internet services rely on, or greatly benefit from,
computers' clocks being accurate. For example, a web server
may receive requests to send a file if it has been modified since a
certain time. In a local area network environment, it is
essential that computers sharing files from the same file
server have synchronized clocks so that file timestamps stay
consistent. Services such as &man.cron.8; also rely on
an accurate system clock to run commands at the specified
times.NTPntpdFreeBSD ships with the &man.ntpd.8; NTP server which can be used to query
other NTP
servers to set the clock on your machine or provide time
services to others.Choosing Appropriate NTP ServersNTPchoosing serversIn order to synchronize your clock, you will need to find
one or more NTP servers to use. Your network
administrator or ISP may have set up an NTP server for this
purpose—check their documentation to see if this is the
case. There is an online
list of publicly accessible NTP servers which you can
use to find an NTP server near to you. Make sure you are
aware of the policy for any servers you choose, and ask for
permission if required.Choosing several unconnected NTP servers is a good idea in
case one of the servers you are using becomes unreachable or
its clock is unreliable. &man.ntpd.8; uses the responses it
receives from other servers intelligently—it will favor
unreliable servers less than reliable ones.Configuring Your MachineNTPconfigurationBasic ConfigurationntpdateIf you only wish to synchronize your clock when the
machine boots up, you can use &man.ntpdate.8;. This may be
appropriate for some desktop machines which are frequently
rebooted and only require infrequent synchronization, but
most machines should run &man.ntpd.8;.Using &man.ntpdate.8; at boot time is also a good idea
for machines that run &man.ntpd.8;. The &man.ntpd.8;
program changes the clock gradually, whereas &man.ntpdate.8;
sets the clock, no matter how great the difference between a
machine's current clock setting and the correct time.To enable &man.ntpdate.8; at boot time, add
ntpdate_enable="YES" to
/etc/rc.conf. You will also need to
specify all servers you wish to synchronize with and any
flags to be passed to &man.ntpdate.8; in
ntpdate_flags.NTPntp.confGeneral ConfigurationNTP is configured by the
/etc/ntp.conf file in the format
described in &man.ntp.conf.5;. Here is a simple
example:server ntplocal.example.com prefer
server timeserver.example.org
server ntp2a.example.net
driftfile /var/db/ntp.driftThe server option specifies which
servers are to be used, with one server listed on each line.
If a server is specified with the prefer
argument, as with ntplocal.example.com, that server is
preferred over other servers. A response from a preferred
server will be discarded if it differs significantly from
other servers' responses, otherwise it will be used without
any consideration to other responses. The
prefer argument is normally used for NTP
servers that are known to be highly accurate, such as those
with special time monitoring hardware.The driftfile option specifies which
file is used to store the system clock's frequency offset.
The &man.ntpd.8; program uses this to automatically
compensate for the clock's natural drift, allowing it to
maintain a reasonably correct setting even if it is cut off
from all external time sources for a period of time.The driftfile option specifies which
file is used to store information about previous responses
from the NTP servers you are using. This file contains
internal information for NTP. It should not be modified by
any other process.Controlling Access to Your ServerBy default, your NTP server will be accessible to all
hosts on the Internet. The restrict
option in /etc/ntp.conf allows you to
control which machines can access your server.If you want to deny all machines from accessing your NTP
server, add the following line to
/etc/ntp.conf:restrict default ignoreThis will also prevent access from your server to
any servers listed in your local configuration. If you
need to synchronise your NTP server with an external NTP
server you should allow the specific server. See the
&man.ntp.conf.5; manual for more information.If you only want to allow machines within your own
network to synchronize their clocks with your server, but
ensure they are not allowed to configure the server or used
as peers to synchronize against, addrestrict 192.168.1.0 mask 255.255.255.0 nomodify notrapinstead, where 192.168.1.0 is
an IP address on your network and 255.255.255.0 is your network's
netmask./etc/ntp.conf can contain multiple
restrict options. For more details, see
the Access Control Support subsection of
&man.ntp.conf.5;.Running the NTP ServerTo ensure the NTP server is started at boot time, add the
line ntpd_enable="YES" to
/etc/rc.conf. If you wish to pass
additional flags to &man.ntpd.8;, edit the
ntpd_flags parameter in
/etc/rc.conf.To start the server without rebooting your machine, run
ntpd being sure to specify any additional
parameters from ntpd_flags in
/etc/rc.conf. For example:&prompt.root; ntpd -p /var/run/ntpd.pidUsing ntpd with a Temporary Internet
ConnectionThe &man.ntpd.8; program does not need a permanent
connection to the Internet to function properly. However, if
you have a temporary connection that is configured to dial out
on demand, it is a good idea to prevent NTP traffic from
triggering a dial out or keeping the connection alive. If you
are using user PPP, you can use filter
directives in /etc/ppp/ppp.conf. For
example: set filter dial 0 deny udp src eq 123
# Prevent NTP traffic from initiating dial out
set filter dial 1 permit 0 0
set filter alive 0 deny udp src eq 123
# Prevent incoming NTP traffic from keeping the connection open
set filter alive 1 deny udp dst eq 123
# Prevent outgoing NTP traffic from keeping the connection open
set filter alive 2 permit 0/0 0/0For more details see the PACKET
FILTERING section in &man.ppp.8; and the examples in
/usr/share/examples/ppp/.Some Internet access providers block low-numbered ports,
preventing NTP from functioning since replies never
reach your machine.Further InformationDocumentation for the NTP server can be found in
/usr/share/doc/ntp/ in HTML
format.