= Welcome to 'building the !WirelessLeiden NanoBSD image' = [http://www.freebsd.org/doc/en/articles/nanobsd/index.html FreeBSD default method] for installing [http://www.freebsd.org FreeBSD] on embedded devices, like [http://www.soekris.com Soekris], [http://www.pcengines.ch/alix.htm Alix] and others. The manual described below is (loosely) based on the [source:"doc/Concept v0.3.pdf" Concept plan of Tim Baas], but also consists of many hints by [http://www.freebsd.org/doc/en/articles/nanobsd/index.html official 'Introduction to NanoBSD' manual] and other stuff found on the net ;-) = Have to remember links = * [http://people.freebsd.org/~phk/nanobsd/soekris_4x26/make.soekris_4x26.conf] * Active work in progress node images at [http://webfolder.wirelessleiden.nl/rick/nodefactory/] * [http://forums.freebsd.org/showthread.php?t=2198 Getting Xircom pcmcia network adapter to work] * [http://lists.freebsd.org/pipermail/freebsd-usb/2009-March/006503.html How to add a USB vendor] * [https://projects.math.leidenuniv.nl/trac/howto/wiki/FreeBSD_install LIACS wiki] = Procedure = Please note that you can find the supporting files in the subdirectory [source:nanobsd]. Also keep a close look at the ''INFO'' ''WARN'' ''ERR'' directives as guide you trough the common pitfalls of the guide. == A. Setup a FreeBSD host == ---- WARN: Make sure ''/usr'' is '''at least 5GB''' in size building as building images require quite some space [[BR]] WARN: Make sure you install the '''i386''' release of FreeBSD also when your system does support amd64, as cross compiling can give some nasty surprises [[BR]] ---- Get yourself a fresh i386 freebsd host with ports and subversion installed as follows: A.1. Run the basic CD installer of 7.2. The procedure below has been tested with 7.2-RELEASE (standard developer install - no ports - will fit our needs). Installing FreeBSD is outside the scope of this document, take a look into [http://www.freebsd.org/doc/en/books/handbook/install.html the FreeBSD handbook Chapter 2 Installing FreeBSD] if you do not know the details. Please do mind that all commands below need to be executed as root, due to the many mounts and unmounts done in various phases. Internet connection is required. A.2. get latest sources {{{ $ csup -h cvsup.nl.freebsd.org /usr/share/examples/cvsup/standard-supfile }}} A.3 fetch ports {{{ $ portsnap fetch extract }}} A.4. install subversion (set ftp to passive mode to ensure the firewall is not causing issues if one exists. NOTE: Install all packages via ports to prevent issues later on! {{{ $ setenv FTP_PASSIVE_MODE YES $ cd /usr/ports/devel/subversion; make install clean BATCH=yes }}} A.5. OPTIONAL, every developer has his own preferences, these are mine ;-) {{{ $ (cd /usr/ports/editors/vim-lite; make install clean BATCH=yes) $ (cd /usr/ports/security/sudo; make install clean BATCH=yes) $ (cd /usr/ports/sysutils/screen; make install clean BATCH=yes) }}} == B. Build environment == B.1 Download the environment from the Wireless Leiden svn repository {{{ $ setenv R /root/nanobsd $ svn checkout http://svn.wirelessleiden.nl/svn/projects/iris/nanobsd $R $ cd $R }}} Note: if svn is not found: svn is in /usr/local/bin, alternatively log out and in, or use {{{rehash}}} in a {{{csh}}} shell to make it available. B.2. Compile all required packages using {{{ $ /root/nanobsd/tools/package-build.sh }}} B.3. Set your favorite root password to be used in the image {{{ $ setenv CFG_ROOT_PASSWORD `dd if=/dev/random bs=10k count=10 | & tr -cd '[a-zA-Z0-9]' | cut -c -15` $ echo $CFG_ROOT_PASSWORD }}} If you like a simple password, substitute the {{{ `dd if=/dev/random bs=10k count=10 | & tr -cd '[a-zA-Z0-9]' | cut -c -15` }}} with your password. B.4 Apply kernel patch for pcmcia LAN cards and USB-LAN adapter If you want to be able to use pcmcia LAN cards, like the Xircom RealPort2 Cardbus Ethernet10/100 R2BE-100, you have to apply the patch to the cardbus driver before compiling the kernel: {{{ cd /usr/src/sys/dev/cardbus patch < /root/nanobsd/misc/patches/cardbus_cis.c.patch }}} For use of a Davicom DM9601 USB network controler you have to patch usbdevs and the if_udav driver: {{{ cd /usr/src/sys/dev/usb/ patch < /root/nanobsd/misc/patches/usbdevs.patch patch < /root/nanobsd/misc/patches/if_udav.c.patch }}} To load the driver at boot time add the lin {{{ if_udav_load="YES" }}} to the configuration file /boot/loader.conf B.5. Build nanobsd (make sure to prepare some coffee;-) ) {{{ $ sh /usr/src/tools/tools/nanobsd/nanobsd.sh -c /root/nanobsd/cfg/nanobsd.wleiden }}} Note 1: Take a coffee of go for a hike, this normally takes 2 - 8 hours depending on the machine configuration Note 2: even this little script got flags, check the output of {{{sh /usr/src/tools/tools/nanobsd/nanobsd.sh -h}}} {{{ -b suppress builds (both kernel and world) -k suppress buildkernel -w suppress buildworld -c specify config file ... }}} == C. Fetch node configuration onto image, write to CF disk or remotely update == C.1. Fetch configuration {{{ $ /root/nanobsd/tools/config-image.sh }}} The script is connecting to the [http://svn.wirelessleiden.nl/svn/node-config/genesis/nodes/ Wireless Leiden 'genesis' database]. Pick your situation! You can inspect the image bij mounting as memory disk: {{{ mdconfig -a -t vnode -f /usr/obj/nanobsd.wleiden/_.disk.full mount /dev/md0s1a /mnt ls /mnt umount /mnt mount /dev/md0s3 /mnt ls /mnt umount /mnt }}} C.2. Write the correct image to CF ---- ''NOTE:'' '''''_.disk.full''''' is required for '''new CF cards''' as it contains two base systems and one configuration. [[BR]] '''''_.disk.image''''' on the other hand can be used to update an '''existing CF card''' ---- a. '''New image''': Put full image on compact flash disk (attach a card reader/writer with a CF disk of minimum 1 GB) {{{ $ dd bs=64k if=/usr/obj/nanobsd.wleiden/_.disk.full of=/dev/da0 }}} (assuming {{{/dev/da0}}} is your compact flash entry; this takes about 15 minutes; you may wish to check afterwards with fdisk whether there are three partitions on the disk, you can also mount /dev/da0s1a and /dev/da0s3 and check the configuration) a. '''Existing image''': Put partial image on slice (slice 2) (attach a card reader/writer with the CF disk containing the existing image) {{{ $ dd bs=64k if=/usr/obj/nanobsd.wleiden/_.disk.image of=/dev/da0s2 }}} a. '''Existing image remote update''' (slice 2) (network connection to machine 172.x.y.z required) For remotely updating an existing configuration use: {{{ dd if=/usr/obj/nanobsd.wleiden/_.disk.image bs=10k | ssh root@172.x.y.z /tools/updatep2 }}} You may adjust the block size to make the transfer more efficient (additionally ssh -C is possible) and you can use Ctrl-T to check progress. == D. Check the cf card and apply last minute changes == D.1. Check cf card While the cf card is still in your flash card reader you can check whether the image has been written correctly. Check whether you can mount the partitions, e.g. {{{ mount /dev/da0s1a /mnt ls /mnt umount /mnt }}} and the configuration partition: {{{ mount /dev/da0s3 /mnt ls /mnt }}} If you cannot mount the partitions, take a fresh cf card and start again with writing the image. D.2 apply wi-driver hack, if applicable If you are using wi-drivers in master mode (hostap) you may have to adjust the rc.node.local file on /dev/da0s3. There is a bug in the wi-driver: the channel is always set to 1. You can set the correct channel by adding a line to rc.node.local like: {{{ ifconfig_wi0_alias0="channel {channel number}" }}} D.3 adjust lvrouted conf If the node has a /28 subnet that should be routable modify the /conf/base/etc/rc.conf file: {{{ lvrouted_flags="-u -m 28 -s s00p3rs3kr3t" }}} (for a /24 subnet use -m 24) == E. All done! Load the machine == Place the new CF disk in the machine and boot it up (existing nodes: just reboot), you should be good to go! Especially first time booting can take a long time, depending also on hardware. In a Soekris4521 this takes about ten minutes. You can follow the boot process using e.g. minicom or tip, via a serial connection (communication parameters: 9600 8N1). Note. For subsequent nodes you can skip the build and go directly for step C, or take a look at development if you have to rebuild the image (after small changes). == F. Applying Updates == For small changes there is a shortcut in the build (to save you some coffee ;-)). Pick the situation applicable 1. First lets pump it's source to the latest version {{{ $ svn up /root/nanobsd }}} 2. Set your favorite root password to be used in the image {{{ $ setenv CFG_ROOT_PASSWORD `dd if=/dev/random bs=10k count=10 | & tr -cd '[a-zA-Z0-9]' | cut -c -15`; echo $CFG_ROOT_PASSWORD }}} If you like a simple password, substitute the {{{ `dd if=/dev/random bs=10k count=10 | & tr -cd '[a-zA-Z0-9]' | cut -c -15` }}} with your password. 3. Next step depends on the kind of changes: a. Only changes in kernel options - `kernel.wleiden` altered - ETA 0:45 {{{ $ sh /usr/src/tools/tools/nanobsd/nanobsd.sh -w -c /root/nanobsd/cfg/nanobsd.wleiden }}} a. Only changes in world options - `CONF_{BUILD,COMMON,INSTALL}` in `nanobsd.wleiden` altered - ETA 2:00 - 6:00 {{{ $ sh /usr/src/tools/tools/nanobsd/nanobsd.sh -k -c /root/nanobsd/cfg/nanobsd.wleiden }}} a. _NO_ changes in build options - any other file altered - ETA 0:10 {{{ $ sh /usr/src/tools/tools/nanobsd/nanobsd.sh -b -c /root/nanobsd/cfg/nanobsd.wleiden }}} = G, Development = == Handy tools == Some handy tools are available in the /tools directory, such as * /tools/wl-version : to get information on the configuration that is running * /tools/image-build.sh for building images (replaces long command lines and prevents unintentional, time-consuming rebuilds; do not forget to '''setenv the root password'''!) == Light based packages suggestions == * dnsmasq has been implemented instead of isc-dhcp30-server and bind * thttpd instead of apache == Further research == * stumber `/usr/src/tools/tools/net80211/stumber` == Background == * Packages needed are to be found in source:/nanobsd/tools/package-build.sh i.e. {{{ $PORTSDIR/dns/dnsmasq $PORTSDIR/www/py-cherrypy $PORTSDIR/www/tinyproxy $PORTSDIR/editors/vim-lite $PORTSDIR/net-mgmt/net-snmp $PORTSDIR/net-mgmt/nrpe2 $PORTSDIR/benchmarks/iperf $PORTSDIR/net/pen $PORTSDIR/net/rsync # Wireless Leiden ports at $WL_PORTSDIR $WL_PORTSDIR/net/lvrouted $WL_PORTSDIR/net/transproxy }}} == Testing Images == * [wiki:KnownErrorMessages] * [wiki:TestingViaNFS] * [wiki:TestMatrix] == Hardware == * Soekris 4521, bios version 1.23, 1.31b, 1.32, 1.33 * Alix 2D3, only use latest bios: 0.99h = H. Hints = * You could always decide to install your FreeBSD base instance into a [http://www.freebsd.org/doc/en/books/handbook/virtualization-guest.html virtual environment] * {{{cvsup.nl.freebsd.org}}} is the local dutch cvsup mirror, replace `nl` with your proper country code * It seems tempting to follow {{{/usr/share/examples/cvsup/stable-supfile}}} instead of {{{/usr/share/examples/cvsup/standard-supfile}}} please __DO NOT__ unless your like big trouble as stable-supfile is the stable __DEVELOPMENT__ branch e.g. upcoming stable. * Default username/password = root/, so please do mind, _when no password is set ssh login is disabled_. * Always use `cu` or `putty` for serial communication minicom, screen, putty all issues of some kind. = Comments, questions or remarks? = Feel free to edit this page or [mailto:techniek@lijst.wirelessleiden.nl?subject=NanoBSD%20odefactory%improvement send an email] to our [http://lijst.wirelessleiden.nl/mailman/listinfo/techniek techniek mailinglist] * Handy .cshrc hints {{{ alias quicknano sh /usr/src/tools/tools/nanobsd/nanobsd.sh -b -c /root/nanobsd/cfg/nanobsd.wleiden alias slownano sh /usr/src/tools/tools/nanobsd/nanobsd.sh -c /root/nanobsd/cfg/nanobsd.wleiden alias slownewkernelnano sh /usr/src/tools/tools/nanobsd/nanobsd.sh -w -c /root/nanobsd/cfg/nanobsd.wleiden alias slownewworldnano sh /usr/src/tools/tools/nanobsd/nanobsd.sh -k -c /root/nanobsd/cfg/nanobsd.wleiden alias prepare-nfs /root/nanobsd/tools/prepare-nfs.sh -f -n }}}