11.5.Â Setting Up Network Interface Cards

Adding and configuring a network interface card
(NIC) is a common task for any FreeBSD
administrator.

11.5.1.Â Locating the Correct Driver

First, determine the model of the NIC
and the chip it uses. FreeBSD supports a wide variety of
NICs. Check the Hardware Compatibility
List for the FreeBSD release to see if the NIC
is supported.

If the NIC is supported, determine
the name of the FreeBSD driver for the NIC.
Refer to /usr/src/sys/conf/NOTES and
/usr/src/sys/arch/conf/NOTES
for the list of NIC drivers with some
information about the supported chipsets. When in doubt, read
the manual page of the driver as it will provide more
information about the supported hardware and any known
limitations of the driver.

The drivers for common NICs are already
present in the GENERIC kernel, meaning
the NIC should be probed during boot. The
system's boot messages can be viewed by typing
more /var/run/dmesg.boot and using the
spacebar to scroll through the text. In this example, two
Ethernet NICs using the dc(4) driver
are present on the system:

If the driver for the NIC is not
present in GENERIC, but a driver is
available, the driver will need to be loaded before the
NIC can be configured and used. This may
be accomplished in one of two ways:

The easiest way is to load a kernel module for the
NIC using kldload(8). To also
automatically load the driver at boot time, add the
appropriate line to
/boot/loader.conf. Not all
NIC drivers are available as
modules.

Alternatively, statically compile support for the
NIC into a custom kernel. Refer to
/usr/src/sys/conf/NOTES,
/usr/src/sys/arch/conf/NOTES
and the manual page of the driver to determine which line
to add to the custom kernel configuration file. For more
information about recompiling the kernel, refer to ChapterÂ 8, Configuring the FreeBSD Kernel. If the NIC
was detected at boot, the kernel does not need to be
recompiled.

11.5.1.1.Â Using WindowsÂ® NDIS Drivers

Unfortunately, there are still many vendors that do not
provide schematics for their drivers to the open source
community because they regard such information as trade
secrets. Consequently, the developers of FreeBSD and other
operating systems are left with two choices: develop the
drivers by a long and pain-staking process of reverse
engineering or using the existing driver binaries available
for MicrosoftÂ®Â WindowsÂ® platforms.

FreeBSD provides “native” support for the
Network Driver Interface Specification
(NDIS). It includes ndisgen(8)
which can be used to convert a WindowsÂ®Â XP driver into a
format that can be used on FreeBSD. Because the ndis(4)
driver uses a WindowsÂ®Â XP binary, it only runs on i386™
and amd64 systems. PCI, CardBus,
PCMCIA, and USB
devices are supported.

Download the .SYS and
.INF files for the specific
NIC. Generally, these can be found on
the driver CD or at the vendor's website. The following
examples use W32DRIVER.SYS and
W32DRIVER.INF.

The driver bit width must match the version of FreeBSD.
For FreeBSD/i386, use a WindowsÂ® 32-bit driver. For
FreeBSD/amd64, a WindowsÂ® 64-bit driver is needed.

The next step is to compile the driver binary into a
loadable kernel module. As
root, use
ndisgen(8):

#ndisgen /path/to/W32DRIVER.INF/path/to/W32DRIVER.SYS

This command is interactive and prompts for any extra
information it requires. A new kernel module will be
generated in the current directory. Use kldload(8)
to load the new module:

#kldload ./W32DRIVER_SYS.ko

In addition to the generated kernel module, the
ndis.ko and
if_ndis.ko modules must be loaded.
This should happen automatically when any module that
depends on ndis(4) is loaded. If not, load them
manually, using the following commands:

#kldload ndis#kldload if_ndis

The first command loads the ndis(4) miniport driver
wrapper and the second loads the generated
NIC driver.

Check dmesg(8) to see if there were any load
errors. If all went well, the output should be similar to
the following:

FreeBSD uses the driver name followed by the order in which
the card is detected at boot to name the
NIC. For example,
sis2 is the third
NIC on the system using the sis(4)
driver.

In this example, dc0 is up and
running. The key indicators are:

UP means that the card is
configured and ready.

The card has an Internet (inet)
address, 192.168.1.3.

It has a valid subnet mask
(netmask), where
0xffffff00 is the
same as 255.255.255.0.

It has a valid broadcast address, 192.168.1.255.

The MAC address of the card
(ether) is 00:a0:cc:da:da:da.

The physical media selection is on autoselection mode
(media: Ethernet autoselect (100baseTX
<full-duplex>)). In this example,
dc1 is configured to run with
10baseT/UTP media. For more
information on available media types for a driver, refer
to its manual page.

The status of the link (status) is
active, indicating that the carrier
signal is detected. For dc1, the
status: no carrier status is normal
when an Ethernet cable is not plugged into the
card.

The card must be configured as
root. The
NIC configuration can be performed from the
command line with ifconfig(8) but will not persist after
a reboot unless the configuration is also added to
/etc/rc.conf. If a
DHCP server is present on the LAN,
just add this line:

Replace dc0 and
dc1 and the IP
address information with the correct values for the system.
Refer to the man page for the driver, ifconfig(8), and
rc.conf(5) for more details about the allowed options and
the syntax of /etc/rc.conf.

If the network is not using DNS, edit
/etc/hosts to add the names and
IP addresses of the hosts on the
LAN, if they are not already there. For
more information, refer to hosts(5) and to
/usr/share/examples/etc/hosts.

Note:

If there is no DHCP server and
access to the Internet is needed, manually configure the
default gateway and the nameserver:

11.5.3.Â Testing and Troubleshooting

Once the necessary changes to
/etc/rc.conf are saved, a reboot can be
used to test the network configuration and to verify that the
system restarts without any configuration errors.
Alternatively, apply the settings to the networking system
with this command:

#service netif restart

Note:

If a default gateway has been set in
/etc/rc.conf, also issue this
command:

#service routing restart

Once the networking system has been relaunched, test the
NICs.

11.5.3.1.Â Testing the Ethernet Card

To verify that an Ethernet card is configured correctly,
ping(8) the interface itself, and then ping(8)
another machine on the LAN:

To test network resolution, use the host name instead
of the IP address. If there is no
DNS server on the network,
/etc/hosts must first be
configured. To this purpose, edit
/etc/hosts to add the names and
IP addresses of the hosts on the
LAN, if they are not already there. For
more information, refer to hosts(5) and to
/usr/share/examples/etc/hosts.

11.5.3.2.Â Troubleshooting

When troubleshooting hardware and software
configurations, check the simple things first. Is the
network cable plugged in? Are the network services properly
configured? Is the firewall configured correctly? Is the
NIC supported by FreeBSD? Before sending
a bug report, always check the Hardware Notes, update the
version of FreeBSD to the latest STABLE version, check the
mailing list archives, and search the Internet.

Some users experience one or two
device timeout messages, which is
normal for some cards. If they continue, or are bothersome,
determine if the device is conflicting with another device.
Double check the cable connections. Consider trying another
card.

To resolve watchdog timeout
errors, first check the network cable. Many cards
require a PCI slot which supports bus
mastering. On some old motherboards, only one
PCI slot allows it, usually slot 0.
Check the NIC and the motherboard
documentation to determine if that may be the
problem.

No route to host messages occur
if the system is unable to route a packet to the destination
host. This can happen if no default route is specified or
if a cable is unplugged. Check the output of
netstat -rn and make sure there is a
valid route to the host. If there is not, read
SectionÂ 31.2, “Gateways and Routes”.

ping: sendto: Permission denied
error messages are often caused by a misconfigured firewall.
If a firewall is enabled on FreeBSD but no rules have been
defined, the default policy is to deny all traffic, even
ping(8). Refer to
ChapterÂ 30, Firewalls for more information.

Sometimes performance of the card is poor or below
average. In these cases, try setting the media
selection mode from autoselect to the
correct media selection. While this works for most
hardware, it may or may not resolve the issue. Again,
check all the network settings, and refer to
tuning(7).