User Tools

Site Tools


documentation:end-users_docs

User Guide

Hardware Compatibility List

For BSDRP you need:

  • a 256Mb Compact Flash/USB stick.
  • a minimum of 256MB RAM.

All hardware supported by FreeBSD 9.2 is supported by BSDRP with the exception of following drivers:

Wireless, PCMCIA cards, SCSI adapters, USB printer, fire wire, etc. drivers were removed from the FreeBSD kernel.

Filename convention

The BSDRP images use this filename convention:

BSDRP_release_image type_arch_console.img.xz

The value image type can be:

  • full : To be used for installing BSDRP. This image contain full BSDRP filesystem (bootloader, 2 systems partitions, cfg partition and data partition)
  • upgrade : To be used for upgrading BSDRP. This image contain only one system partition.

The value arch can be:

  • i386 : for i486, i586 and i686 CPU
  • amd64 : for all x86-64 CPU (amd64 or intel 64)

The value console can be:

  • vga: To be used with a vga card and keyboard as default console (but it's still possible to connect to the serial port)
  • serial: For headless use, use only serial port as default console

Examples:

  • BSDRP_0.3_full_i386_vga.img, means full image, for arch i386, with keyboard/vga as console.
  • BSDRP_0.3_upgrade_amd64_serial.img, means upgrade image, for arch amd64 on headless serial.

The *.mtree.xz files are used for system integrity check.

Installation

To a flash media (CF/USB)

Windows users

Here are the 2 steps for writing the image to a CF/USB removable media:

  1. Decompress the BSDRP image file 7-Zip: You need to obtain a file with .img extension.
  2. Use Image Writer for Windows for writing the image file .img (and not the file with .xz extension) on your CF/USB connected to your PC.
Linux users

Connect your Compact Flash or USB disk and write down the device name (sd4 for a usb key in this exemple).

Then unzip the file and byte copy it to your drive (Warning: Double check that you had choosen the good destination disk!!!):

xzcat BSDRP_full_amd64_vga.1.0.img.xz | dd of=/dev/sd4 bs=64k

You can boot from this media now.

FreeBSD users

Connect your Compact Flash or USB disk and write down the device name (da0 for a usb key in this exemple).

Then unzip the file and byte copy it to your drive (Warning: Double check that you had choosen the good destination disk!!!):

xzcat BSDRP_full_amd64_vga.1.0.img.xz | dd of=/dev/da0 bs=64k

You can boot from this media now.

Mac OS X users

Insert the USB key, and run mount in a terminal (or disk utility if you prefer graphical method) to see what device OSX has assigned to your USB key. You should see something like this:

/dev/disk0s2 on / (hfs, local, journaled)
devfs on /dev (devfs, local)
fdesc on /dev (fdesc, union)
map -hosts on /net (autofs, automounted)
map auto_home on /home (autofs, automounted)
/dev/disk3s1 on /Volumes/UNTITLED (msdos, local, nodev, nosuid, noowners)

The last line is your USB device. Unmount it and write the BSDRP image to it with:

sudo umount -f /dev/disk3s1
xzcat BSDRP_full_amd64_vga.1.0.img.xz | dd of=/dev/disk3 bs=64k

If successful, OSX will pop up an error dialog telling you it doesn't recognize the disk. Click 'Eject', remove the USB key, and you're done.

To an hard drive

Boot BSDRP from the previously generated usb key, then from BSDRP, display the BSDRP system diskname:

[root@router]~# glabel status | grep BSDRP
 ufs/BSDRPs3     N/A  da0s3
 ufs/BSDRPs4     N/A  da0s4
ufs/BSDRPs1a     N/A  da0s1a

⇒ On this example BSDRP is on disk da0 (USB key)

Display all the system disks:

[root@router]~# sysctl kern.disks
kern.disks: ad0 da0

⇒ On this example, because da0 is the BSDRP disk, ad0 is the hard-drive where we want install BSDRP.

First, avoid the error message “the primary GPT table is corrupt or invalid.” by cleaning the 2 GPT tables on the destination hard drive

setenv DRIVE "da0"
dd if=/dev/zero of=/dev/${DRIVE} bs=1m count=1
dd if=/dev/zero of=/dev/${DRIVE} bs=1m oseek=`diskinfo ${DRIVE} | awk '{print int($3 / (1024*1024)) - 4;}'`

Then copy the BSDRP disk to the hard-drive:

[root@router]~# dd if=/dev/da0 of=/dev/ad0 bs=64k
3920+0 records in
3920+0 records out
256901120 bytes transferred in 8.803739 secs (29180910 bytes/sec)
GEOM: ad0s1: geometry does not match label (255h,63s != 16h,63s).

Reboot your system (and don't forget to remove the USB key).

Once rebooted from your hard drive, you can expand the /data slice for using all the free space:

system expand-data-slice

Into a Virtual Machine

For using BSDRP as a Virtual Machine, refers to chapter How to run in the Technical docs.

Once BSDRP is started for the first time, don't forget to lower the default kern.HZ value that is not optimized for a VM usage by entering this command:

system virtualized

Special step for PC-Engines WRAP platform

The FreeBSD (BSDRP) bootloader default configuration isn't compatible with the WRAP: You need to change the bootloader mode before to use it on a WRAP platform. From a FreeBSD host, once you had installed the image on your CF, change the bootloader mode (replace daX by your device):

boot0cfg -o nopacket /dev/daX

Upgrading BSDRP on WRAP is not possible: The PC-Engines WRAP is not able to boot from the second partition (BIOS limitation)

Quick start

Login as root with no password.

If you are using the serial version, serial port parameters are: 38400,8,N,1,MODEM (the freebsd bootloaler is still in 9600 baud). Why 38400 ? Because on current server, BIOS redirection to serial port is almost unusable because too slow at 9600 baud.

Start by using the help:

help

Create a password for root (mandatory for SSH):

passwd

Enter in quagga mode:

cli

Do your quagga configuration, and save quagga config and exit quagga cli:

wr
exit

Then save all changes:

config save

Configuration files

All modifications done in configuration files (/etc/*, /usr/local/etc/*) need to be saved before a reboot.

Use the config command for saving configuration:

[root@R1]~#config
BSD Router Project configuration tool
Usage: /usr/local/sbin/config option
  - diff     : Show diff between current and saved config
  - save     : Save current config
  - apply    : Apply current config
  - rollback : Revert to previous config
  - put      : Put the saved config to a remote server
  - get      : Get config from remote server
  - reset    : Return to default configuration
  - help (h) [option]  : Display this help message.
                        If [option] given, display more detail about the option

Don't modify /boot/loader.conf: Your changes will be lost after an upgrade. In place, create a new file /boot/loader.conf.local and put your modifications on this file.

Upgrading

Using a SCP(SSH) server

This method requiered a SCP server:

From the router:

  1. Download BSDRP-upgrade.image.xz file with SCP
  2. Extract the image
  3. Use the upgrade script

All these steps are done with this command:

ssh my-user@my-ssh-server cat /path-to/BSDRP-upgrade.image.xz | xzcat | upgrade

Using a SSH client

This method requiered a SSH client (all Linux/Unix should include it).

From the client, enter this command:

cat BSDRP_1.2_upgrade_amd64_vga.img.xz | ssh root@a.b.c.d "xzcat | upgrade"

Using a SCP Client or fetching upgrade file from BSDRP

This method required:

  • A minimum of 60MB of free RAM on your BSDRP (mem_avail value in the “show mem” output)
  • One of this:
    • Sending the upgrade file with a SCP client (FileZilla or WinSCP as example)
    • Or downloading upgrade file directly from BSDRP

Resume:

  1. Create a 40MB ram disk on BSDRP
  2. Transfert the BSDRP image upgrade on the ram disk using the SCP client or download the image directly
  3. Upgrade the system

Step 1: Creating the ram disk

On BSDRP, enter theses commands:

set RAMDRIVE=`mdconfig -a -t malloc -s 40m`
newfs -m 0 -n $RAMDRIVE
mount /dev/$RAMDRIVE /mnt/

Step 2: Transfering the image file in the temporary RAM drive

Using your SCP client, send the BSDRP upgrade image to the router's /mnt folder.

Or from BSDRP:

cd /mnt
fetch URL/BSDRP-upgrade.image.xz

Step 3: After transfer complete, On BSDRP, enter this command:

xzcat /mnt/BSDRP-upgrade.image.xz | upgrade
umount /mnt

Security

SSH access

SSH access with the root user is not available by default: You need to set-up a password for the root account before with the passwd command.

Example:

[root@R1]~# passwd
Changing local password for root
New Password: XXXXXXXX
Retype New Password: XXXXXXXX

System integrity check

Reference mtree file are provided for checking the integrity of all your files on your router.

You can check your BSDRP system integrity using these references files by downloading the corresponding file into your router and using “system integrity” command.

As example, if you are using 0.35 amd64-serial release, from your BSDRP router (if it had DNS resolution and Internet access configured):

cd /tmp
fetch http://downloads.sourceforge.net/project/bsdrp/BSD_Router_Project/0.35/BSDRP_0.35_amd64_serial.mtree.xz
system integrity BSDRP_0.35_amd64_serial.mtree.xz

System Management

Serial port

Enabling dual console vga/serial

If you are using the vga release of BSDRP, you can enable the serial access (COM1) with the command

system dual-console

baud rate

Serial port baud rate need to be modified in 2 different files:

  • /boot.config
  • /etc/ttys

For modifying the /boot.config file you need to mount RW the /:

mount -uw /

Change the speeed value just after the ”-S” option (don't remove the other -D or/and -h options!) in the /boot.config file.

Check that you didn't have legacy values (boot_serial, comconsole_speed, console) configured on your /boot/loader.conf.local: There are useless with the use of /boot.config.

Once done, mount RO /:

mount -ur /

Then edit etc/ttys and change the baud rate in line ttyu0 (if you need to change the first serial port).

Changing the default serial port used for console

If you need to change the default serial port to use for console (like Supermicro that use COM2 for sol):

  • Start by displaying the list of available serial ports
  • Then change the value in /boot/loader.conf.local
root@bsdrp# grep uart /var/run/dmesg.boot
uart0: <16550 or compatible> port 0x3f8-0x3ff irq 4 flags 0x10 on acpi0
uart0: console (38400,n,8,1)
uart1: <16550 or compatible> port 0x2f8-0x2ff irq 3 on acpi0
root@bsdrp# mount -uw /
root@bsdrp# echo 'comconsole_port="0x2f8"' >> /boot/loader.conf.local
root@bsdrp# mount -ur /

IPMI

If you need to configure the local IPMI board, you have to load the IPMI drivers.

Edit /etc/rc.conf and check that module “ipmi” is declared on the kld_list variable:

kld_list='ipmi'

You can load it from the shell too:

kldload ipmi

Then you can use ipmitool for configuring it.

For connecting with IPMI to serial port with IPMI SOL (Serial over lAN) from a remote machine, change the baud-rate of the serial line to 38400 and to connect to it (example with default password for IBM x3550):

ipmitool -H 192.168.1.11 -U USERID -P PASSW0RD sol set non-volatile-bit-rate 38.4
ipmitool -H 192.168.1.11 -U USERID -P PASSW0RD sol set volatile-bit-rate 38.4
ipmitool -H 192.168.1.11 -U USERID -P PASSW0RD -I lanplus -a sol activate

Watchdog

Add to /etc/rc.conf:

# Load Intel ICH watchdog interrupt timer driver
kld_list='ichwd'
# Start watchdogd dameon
watchdogd_enable="yes"

And start it:

kldload ichwd
service watchdogd start

If you already load ipmi module, watchdogd can use IPMI in place of ichwd.

SNMP

Enable bsdnmpd:

sysrc bsnmpd_enable=YES

Edit /etc/snmpd.config according to your needs and start the daemon:

service bsnmpd start

Then you can check it locally (it uses public as default snmp community):

[root@BSDRP]~# bsnmpget sysDescr.0
sysDescr.0 = router.bsdrp.net 2059309898 FreeBSD 9.1-RELEASE-p1

Syslog

For generating syslog message, just edit /etc/syslog.conf and check the example:

# uncomment this to enable logging to a remote loghost named loghost
#*.*                                            @loghost

Then restart syslogd:

service syslogd restart

BSDRP v1.4 and earlier have a default configuration that prevent remote syslog. This behavior can be changed by editing /etc/rc.conf.misc and replacing syslogd_flags=”-ss” by syslogd_falgs=”-s”

Going further

BSDRP is a FreeBSD, then you need to read how to configure a FreeBSD for using it.

Here is a list of useful documentations:

Advanced customization

Scripts

The root filesystem is in read-only mode, then you can't modify or create your own script on it.

For modify the existing script (don't forget to send us your improvement), use the “data” partition. Here is an example for customizing the config script:

mount /data
cp /usr/local/bin/config /data
vi /data/config

Now you can add your great patches to config script. And test it:

sh /data/config

Then, don't forget to umount the /data partition:

umount /data

System

You can modify the full filesystem by re-mount the active slice in read-write mode:

mount -uw /

Now you can modify all files or removing/installing package.

Here is how to remove bird as example:

[root@router]~#pkg_info | grep bird
bird-1.2.1 Dynamic IP routing daemon
[root@router]~#pkg_delete bird-1.2.1

After your changes, re-mount it in read-only mode:

mount -ur /

But warning: All your changes (with the exception of /boot/loader.conf.local) will be lost after an upgrade!

Improving network speed

Polling can be used in 2 cases:

  • On old hardware only (where Ethernet card doesn't support Intelligent interrupt management), using the “polling” mode can improve performance by reducing CPU interrupt

For enabling polling mode:

  1. Edit /etc/rc.conf.misc and replace polling_enable=“NO” by polling_enable=“YES”
  2. Execute: service polling start

Check the FreeBSD forwarding Performance page for more information.

NIC drivers compatibility matrix

BSDRP can use some special features on somes NIC:

And only theses devices support these modes:

name Description Polling ALTQ
age Attansic/Atheros L1 Gigabit Ethernet driver no yes
ale Atheros AR8121/AR8113/AR8114 Gigabit/Fast Ethernet driver no yes
bce Broadcom NetXtreme II (BCM5706/5708/5709/5716) PCI/PCIe Gigabit Ethernet adapter driver no yes
bge Broadcom BCM570x/5714/5721/5722/5750/5751/5752/5789 PCI Gigabit Ethernet adapter driver yes no
dc DEC/Intel 21143 and clone 10/100 Ethernet driver yes yes
de DEC DC21x4x Ethernet device driver no yes
ed NE-2000 and WD-80×3 Ethernet driver no yes
em Intel(R) PRO/1000 Gigabit Ethernet adapter driver yes yes
ep Ethernet driver for 3Com Etherlink III (3c5x9) interfaces no yes
fwip standard IP over FireWire (IEEE 1394) based on the protocols described in RFC 2734 and RFC 3146 yes no
fxp Intel EtherExpress PRO/100 Ethernet device driver yes yes
gem ERI/GEM/GMAC Ethernet device driver no yes
hme Sun Microelectronics STP2002-STQ Ethernet interfaces device driver no yes
ixgb Intel(R) PRO/10GbE Ethernet driver yes no
jme JMicron Gigabit/Fast Ethernet driver no yes
le AMD Am7900 LANCE and Am79C9xx ILACC/PCnet Ethernet interface driver no yes
msk Marvell/SysKonnect Yukon II Gigabit Ethernet adapter driver no yes
mxge Myricom Myri10GE 10 Gigabit Ethernet adapter driver no yes
my Myson Technology Ethernet PCI driver no yes
nfe NVIDIA nForce MCP Ethernet driver yes yes
nge National Semiconductor PCI Gigabit Ethernet adapter driver yes no
nve NVIDIA nForce MCP Networking Adapter device driver no yes
re RealTek 8139C+/8169/816xS/811xS/8101E PCI/PCIe Ethernet adapter driver yes yes
rl RealTek 8129/8139 Fast Ethernet device driver yes yes
sf Adaptec AIC‐6915 “Starfire” PCI Fast Ethernet adapter driver yes yes
sis SiS 900, SiS 7016 and NS DP83815/DP83816 Fast Ethernet device driver yes yes
sk SysKonnect SK-984x and SK-982x PCI Gigabit Ethernet adapter driver yes yes
ste Sundance Technologies ST201 Fast Ethernet device driver yes yes
stge Sundance/Tamarack TC9021 Gigabit Ethernet adapter driver yes yes
txp 3Com 3XP Typhoon/Sidewinder (3CR990) Ethernet interface no yes
vge VIA Networking Technologies VT6122 PCI Gigabit Ethernet adapter driver yes yes
vr VIA Technologies Rhine I/II/III Ethernet device driver yes yes
xl 3Com Etherlink XL and Fast Etherlink XL Ethernet device driver yes yes

Using others NIC will works too :-)

documentation/end-users_docs.txt · Last modified: 2014/03/12 23:24 by olivier