Differences

This shows you the differences between two versions of the page.

--- documentation:end-users_docs [2012/04/19 17:10]
+++ documentation:end-users_docs [2013/03/24 13:31] (current)
olivier [Hardware Compatibility List]
@@ Line 1: / Line 1: @@
+====== User Guide ======
+{{description>BSD Router Project User Guide}}
+===== Hardware Compatibility List =====
+For BSDRP you need:
+  * a 256Mb Compact Flash/USB stick.
+  * a minimum of 256MB RAM.
+[[http://www.freebsd.org/releases/9.1R/hardware.html|All hardware supported by FreeBSD 9.1]] 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
++0 records in
++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 SSH client ====
+This method requiered a SSH client (all Linux/Unix should include it).
+From the client, enter this command:
+<code>
+cat BSDRP_1.2_upgrade_amd64_vga.img.xz | ssh root@a.b.c.d "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 30m`
+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, /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>
+<note>
+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.
+</note>
+===== 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 (with the exception of /boot/loader.conf.local) 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 forwarding 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 :-)

BSD Router Project

User Tools

Site Tools

Differences

Page Tools