====== User Guide ======

{{description>BSD Router Project User Guide}}
===== Hardware Compatibility List =====

For BSDRP you need:
  * a 256Mb Compact Flash/USB stick.
  * a minimum of 128MB RAM.

[[http://www.freebsd.org/releases/8.2R/hardware.html|All hardware supported by FreeBSD 8.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:
  - Decompress the BSDRP image file [[http://www.7-zip.org/|7-Zip]]: You need to obtain a file with .img extension.
  - Use [[https://launchpad.net/win32-image-writer|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!!!**):
<code>
xzcat BSDRP_full_amd64_vga.1.0.img.xz | dd of=/dev/sd4 bs=64k
</code>

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!!!**):
<code>
xzcat BSDRP_full_amd64_vga.1.0.img.xz | dd of=/dev/da0 bs=64k
</code>

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:

<code>
/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)
</code>
The last line is your USB device. Unmount it and write the BSDRP image to it with:
<code>
sudo umount -f /dev/disk3s1
xzcat BSDRP_full_amd64_vga.1.0.img.xz | dd of=/dev/disk3 bs=64k
</code>
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: 

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

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

Display all the system disks:
<code>
[root@router]~# sysctl kern.disks
kern.disks: ad0 da0
</code>

=> 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
<code>
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;}'`
</code>
 
Then copy the BSDRP disk to the hard-drive:

<code>
[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).
</code>

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:
<code>
system expand-data-slice
</code>
=== Into a Virtual Machine ===

For using BSDRP as a Virtual Machine, refers to chapter [[Documentation:Technical docs#how_to_run|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:
<code>
system virtualized
</code>

=== 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):

<code>
boot0cfg -o nopacket /dev/daX
</code>

<note warning>Upgrading BSDRP on WRAP is not possible: The PC-Engines WRAP is not able to boot from the second partition (BIOS limitation)</note>
===== Upgrading =====


==== Using a SCP(SSH) server ====

This method requiered a SCP server:
  * any unix/linux with SSH enabled
  * or a [[http://en.wikipedia.org/wiki/List_of_SFTP_server_software|MS Windows with SSH server software]]

From the router:
  - Download BSDRP-upgrade.image.xz file with SCP
  - Extract the image
  - Use the upgrade script


All these steps are done with this command:

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

==== Using a SCP Client ====

This method requiered:
  * A minimum of 50MB of free RAM on your BSDRP (mem_avail value in the "show mem" output)
  * A SCP client on your MS Windows ([[http://filezilla-project.org/|FileZilla]] or [[http://winscp.net|WinSCP]] for example)

Resume:
  - Create a 25MB ram disk on BSDRP
  - Transfert the BSDRP image upgrade on the ram disk using the SCP client
  - Upgrade the system

Step 1: Creating the ram disk

On BSDRP, enter theses commands:

<code>
set RAMDRIVE=`mdconfig -a -t malloc -s 25m`
newfs -m 0 -n $RAMDRIVE
mount /dev/$RAMDRIVE /mnt/
</code>

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

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

<code>
xzcat /mnt/BSDRP-upgrade.image.xz | upgrade
umount /mnt
</code>

===== Using BSDRP =====
==== Quick start ====

Login as root with no password.

If you are using the serial version, serial port parameters are: 38400,8,N,1,MODEM

Start by using the help:
<code>
help
</code>

Create a password for root (mandatory for SSH):
<code>
passwd
</code>

Enter in quagga mode:
<code>
cli
</code>
Do your quagga configuration, and save quagga config and exit quagga cli:
<code>
wr
exit
</code>

Then save all changes:
<code>
config save
</code>

==== Configuration ====

BSDRP is a FreeBSD, then you need to read how to configure a FreeBSD for using it.
 
Here is a list of useful documentations:
  * [[Documentation:Examples|BSDRP Examples]]
  * [[http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/|FreeBSD Handbook]]:
    * [[http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-bridging.html|Bridging]]
    * [[http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-aggregation.html|Link Aggregation and Failover]]
    * [[http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html|Alternate Queuing]]
    * [[http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-ipv6.html | IPv6]]
  * [[http://www.freebsd.org/cgi/man.cgi|FreeBSD Man Pages]]
  * [[http://www.quagga.net/docs/quagga.html|Quagga Manual]]
  * [[http://bird.network.cz/?get_doc&f=bird.html|Bird user manual]]

===== Managing configuration =====

All configuration changes (/etc or /usr/local/etc) need to be saved before a reboot.

Use the config command for saving configuration:

<code>
[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
</code>

===== 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:
<code>
[root@R1]~# passwd
Changing local password for root
New Password: XXXXXXXX
Retype New Password: XXXXXXXX
</code>


==== System integrity check ====

[[:downloads#mtree_files_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):
<code>
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
</code>

===== 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:
<code>
mount /data
cp /usr/local/bin/config /data
vi /data/config
</code>
Now you can add your great patches to config script.
And test it:
<code>
sh /data/config
</code>
Then, don't forget to umount the /data partition:
<code>
umount /data
</code>
==== System ====

You can modify the full filesystem by re-mount the active slice in read-write mode:
<code>
mount -uw /
</code>

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

Here is how to remove bird as example:
<code>
[root@router]~#pkg_info | grep bird
bird-1.2.1 Dynamic IP routing daemon
[root@router]~#pkg_delete bird-1.2.1
</code>
After your changes, re-mount it in read-only mode:

<code>
mount -ur /
</code>

<note warning>
But warning: All your changes will be lost after an upgrade!
</note>
===== Improving network speed ====

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:
  - Edit /etc/rc.conf.misc and replace //polling_enable="NO"// by //polling_enable="YES"//
  - Execute: /usr/local/etc/rc.d/polling start


Check the [[Documentation:Technical docs:Performance|FreeBSD networking Performance]] page for more information.
==== NIC drivers compatibility matrix ====
BSDRP can use some special features on somes NIC:
  * [[http://www.freebsd.org/cgi/man.cgi?query=polling&apropos=0&sektion=4&manpath=FreeBSD+8.1-RELEASE&format=html|Ethernet device polling]] for high performance with Ethernet controllers that didn't include interrupt management feature.
  * [[http://www.freebsd.org/cgi/man.cgi?query=altq&apropos=0&sektion=0&manpath=FreeBSD+8.1-RELEASE&format=html|ALTQ]] for queuing

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-80x3 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 :-)