Adding and configuring a network card is a common task for any FreeBSD administrator.
First, determine the model of the network interface card and the chip it uses. FreeBSD supports a wide variety of network interface cards. Check the Hardware Compatibility List for the FreeBSD release to see if the card is supported.
If the card is supported, determine the name of the FreeBSD
driver for the card. Refer to
/usr/src/sys/conf/NOTES and
/usr/src/sys/
for the list of network interface 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.arch/conf/NOTES
The drivers for common network cards are already present
in the GENERIC kernel, meaning the card
should show up during boot, as in this example:
In this example, two cards using the dc(4) driver are present on the system.
If the driver for the interface is not present in
GENERIC, but a driver is available, the
driver will need to be loaded before the interface 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
network card with 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; notable examples of
devices for which modules do not exist are ISA
cards.
Alternatively, statically compile support for the card
into a custom kernel. Refer to
/usr/src/sys/conf/NOTES,
/usr/src/sys/
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 9, Configuring the FreeBSD Kernel. If the card was detected
at boot, the kernel does not need to be recompiled.arch/conf/NOTES
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 two choices: develop the drivers by a long and pain-staking process of reverse engineering or using the existing driver binaries available for the Microsoft® Windows® platforms. Most developers, including those involved with FreeBSD, have taken the latter approach.
Thanks to the contributions of Bill Paul (wpaul) there is “native” support for the Network Driver Interface Specification (NDIS). The FreeBSD NDISulator (otherwise known as Project Evil) takes a Windows® driver binary and basically tricks it into thinking it is running on Windows®. Because the ndis(4) driver is using a Windows® binary, it only runs on i386™ and amd64 systems. PCI, CardBus, PCMCIA (PC-Card), and USB devices are supported.
To use the NDISulator, three things are needed:
Kernel sources
Windows® XP driver binary
(.SYS extension)
Windows® XP driver configuration file
(.INF extension)
Locate the files for the specific card. Generally,
they can be found on the included CDs 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.SYSndisgen(8) is interactive and prompts for any extra information it requires. A new kernel module is written in the current directory. Use kldload(8) to load the new module:
# kldload ./W32DRIVER_SYS.koIn 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_ndisThe first command loads the NDIS miniport driver wrapper, the second loads the actual network interface.
Now, check dmesg(8) to see if there were any errors loading. If all went well, the output should be similar to the following:
From here you can treat the
ndis0 device like any other network
interface (e.g., dc0).
To configure the system to load the NDIS modules at
boot time, copy the generated module,
W32DRIVER_SYS.ko, to the /boot/modules directory. Then,
add the following line to
/boot/loader.conf:
Once the right driver is loaded for the network card, the card needs to be configured. As with many other things, the network card may have been configured at installation time by sysinstall.
To display the configuration for the network interfaces, enter the following command:
% ifconfig
dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
options=80008<VLAN_MTU,LINKSTATE>
ether 00:a0:cc:da:da:da
inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255
media: Ethernet autoselect (100baseTX <full-duplex>)
status: active
dc1: flags=8802<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
options=80008<VLAN_MTU,LINKSTATE>
ether 00:a0:cc:da:da:db
inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255
media: Ethernet 10baseT/UTP
status: no carrier
lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384
options=3<RXCSUM,TXCSUM>
inet6 fe80::1%lo0 prefixlen 64 scopeid 0x4
inet6 ::1 prefixlen 128
inet 127.0.0.1 netmask 0xff000000
nd6 options=3<PERFORMNUD,ACCEPT_RTADV>In this example, the following devices were displayed:
dc0: The first Ethernet
interface
dc1: The second Ethernet
interface
lo0: The loopback
device
FreeBSD uses the driver name followed by the order in which
one the card is detected at the kernel boot to name the
network card. For example sis2 would
be the third network card on the system using the sis(4)
driver.
In this example, the dc0 device
is up and running. The key indicators are:
UP means that the card is
configured and ready.
The card has an Internet (inet)
address (in this case
192.168.1.3).
It has a valid subnet mask
(netmask;
0xffffff00 is the same as
255.255.255.0).
It has a valid broadcast address (in this case,
192.168.1.255).
The MAC address of the card (ether)
is 00:a0:cc:da:da:da
The physical media selection is on autoselection mode
(media: Ethernet autoselect (100baseTX
<full-duplex>)). In this example,
dc1 was 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.
If the ifconfig(8) output had shown something similar to:
it would indicate the card has not been configured.
To configure the card, you will need
root privileges. The network card
configuration can be performed from the command line with
ifconfig(8) but will not persist after a reboot unless
the network card's configuration is also added to
/etc/rc.conf using an editor. Add a
line for each network card present on the system, as seen in
this example:
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 was configured during installation, some
lines about the network card(s) may be already present.
Double check /etc/rc.conf before adding
any lines.
If the network is not using DNS, edit
/etc/hosts to add the names and the IP
addresses of various machines of the LAN, if they are not
already there. For more information, refer to hosts(5)
and to
/usr/share/examples/etc/hosts.
If there is no DHCP server and access to the Internet is needed, manually configure the default gateway and the nameserver:
# echo 'defaultrouter="your_default_router"' >> /etc/rc.conf
# echo 'nameserver your_DNS_server' >> /etc/resolv.confOnce the necessary changes in
/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 restartIf a default gateway has been set in
/etc/rc.conf, use also this
command:
# service routing restartOnce the networking system has been relaunched, test the network interfaces.
To verify that an Ethernet card is configured correctly, ping the interface itself, and then ping another machine on the LAN:
% ping -c5 192.168.1.3
PING 192.168.1.3 (192.168.1.3): 56 data bytes
64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms
64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms
64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms
64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms
64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms
--- 192.168.1.3 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms% ping -c5 192.168.1.2
PING 192.168.1.2 (192.168.1.2): 56 data bytes
64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms
64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms
64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms
64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms
64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms
--- 192.168.1.2 ping statistics ---
5 packets transmitted, 5 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 msTo test network resolution, use the machine name instead
of 192.168.1.2. If there is
no DNS server on the network,
/etc/hosts must first be
configured.
Troubleshooting hardware and software configurations is always a pain, and a pain which can be alleviated by checking the simple things first. Is the network cable plugged in? Are the network services properly configured? Is the firewall configured correctly? Is the network card supported by FreeBSD? Always before sending a bug report, check the hardware notes, update the version of FreeBSD to the latest STABLE version, check the mailing list archives, and search the Internet.
If the card works, yet performance is poor, it would be worthwhile to read over the tuning(7) manual page. Also, check the network configuration as incorrect network settings can cause slow connections.
Some users experience one or two device timeout messages, which is normal for some cards. If they continue, or are bothersome, determine if the device is conflicting with another device. Double check the cable connections. Consider trying another card.
At times, users see a few watchdog timeout errors. The first thing to do is to 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 network card and the motherboard documentation to determine if that may be the problem.
No route to host messages occur
if the system is unable to route a packet to the destination
host. This can happen if no default route is specified, or
if a cable is unplugged. Check the output of
netstat -rn and make sure there is a
valid route to the host. If there is not, read on to
Chapter 32, Advanced Networking.
ping: sendto: Permission denied
error messages are often caused by a misconfigured firewall.
If ipfw is enabled in the kernel but no
rules have been defined, then the default policy is to deny
all traffic, even ping requests! Read on to
Chapter 31, Firewalls for more information.
Sometimes performance of the card is poor, or below
average. In these cases it is best to set the media
selection mode from autoselect to the
correct media selection. While this usually works for most
hardware, it may not resolve this issue for everyone.
Again, check all the network settings, and read over the
tuning(7) manual page.
This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.