CUWIN Manual

Preface: Building Your CUWiNware Wireless Network

This manual will walk you through all the decisions that need to be made when purchasing and building hardware for a CUWiNware network.

First, a few definitions. CUWiNware (pronounced "Q-N-Ware") is the wireless server software created by the Champaign-Urbana Community Wireless Network project. A CUWiNware network is simply a mesh of access points, or nodes, running the CUWiNware software. A node consists of a computer, a wireless network card (NIC), an enclosure, an antenna, and all the neccessary cable and mounting equipment. Because these nodes can be built using any brand of computer and hardware store parts, you are not bound to any one hardware manufacturer, giving you the flexibility to build the ideal network for your situation.

Index

Hardware Design and Construction

Node Placement

Other Node Options

User's Guide

Downloading the Software

Installing the Software

Network Topology

Exploring Your Node

How-to Guides

Technical Documents

Hardware Design and Construction

Introduction

A CUWiNware network is a mesh of nodes running the CUWiNware software. A node consists of a computer, a wireless NIC, an enclosure, an antenna, and all the necessary cable and mounting equipment. This manual will walk you through all the decisions that need to be made when purchasing and building hardware for a CUWiNware network.

Many of the decisions that you will make will be based on the local circumstances of your community. Topology, budget, available labor, available materials, network type, and network size will all be factors that go into your decisions. One of the biggest tradeoffs is between time and money -- for each option there is generally a way to do it cheaply that takes a lot of time and a way to do it quickly that is more expensive.

Node Placement

Where a node is located can make or break the quality of its connection to the mesh. Ideally, antennas will have a line-of-sight to each other in order to get the best reception. In order to minimize signal degradation, the cabling between the antenna and the wireless receiver card should be as short as possible. This often means that you need to put both the antenna and the rest of the node above as many buildings and trees as possible. On the roof tends to be the standard node placement location.

Isolated Areas

Areas that are isolated from the local mesh can often get a signal from the main mesh by using a well placed directional antenna instead of an omnidirectional antenna. Such isolated areas can then use an omnidirectional antenna to share the connection with neighbors. In this manner, areas that were out of reach to the mesh can become connected satellite meshes. When the mesh extends itself in the future to encompass the satellite, both meshes will merge seamlessly with each-other.

Rural, suburb, and other fringe areas often find themselves without any broadband service provider. These communities can find a donor business or home in a nearby community that has broadband and is willing to share by setting up an Internet gateway node. Once a link is established with the distant community, the mesh can be spread wirelessly among the members of the community that was once isolated. In this manner, communities can equip themselves with both broadband and a municipal network.

Using consumer grade equipment, links of over 50 miles (80.4 km) have been established. See the antenna guide for more information on antennas.

Coverage Requirements

A common question that immediately pops into the minds of people planning a wireless mesh is "How many nodes will be required to cover our area?" Unfortunately, this is one of the hardest to answer because of the variety of aspects involved.

The amount of radio activity in your area is one influential factor. Sources of radio interference can be as powerful as the government and various utility companies. Sources of interference can also be as mundane as a cordless phone or the microwave oven. A wireless signal may be strong in an area, until someone picks up the phone and the reception drops to zero.

The terrain of an area also strongly affects the quality of a signal. Even a few feet of soil will block a signal entirely, so a node that is in a valley will have much worse reception than a node on a hill. If there is a hill between a node and the rest of the mesh, a second node may be needed to route the signal over or around the hill. Similarly, a node that is located at the top of a hill may be able to establish a weak link to very distant nodes. Distance records for longest link are often set by using directional antennas on mountaintops.

Foliage such as trees also play an important role in signal strength. The water in trees and the needles of some types of conifers are fairly effective at absorbing a wireless signal. It is not unheard of for a weak wireless link to be usable in the winter when the leaves are off of trees, but unusable in the summer. There is a similar problem with wet leaves (such as during a rain) blocking a signal.

Buildings will also block a signal as effectively as small hills. Brick, stone, and metal siding are the most opaque building materials, and may need to be routed around. It is far better to place a node on top of a tall building than beside it.

After all this, what would we say are normal coverage requirements? The twin cities of Champaign and Urbana in Illinois, where CUWiNware is being developed, are about as flat as cities get. We don't have particularly tall buildings here, but we have many tall trees, so we should be around average. Currently our longest link is around 400 meters. Of course, if you are planning a new network, it is best to put nodes closer to each-other than 400 meters, 100-200 meters is ideal (depending on the area, as discussed in previous paragraphs).

One of the CUWiNware developers did the calculations for how much a mesh would cost to cover one square mile at $350 per node. If you can reliably obtain one thousand foot links, you only need nine nodes at a total cost of $3150. If you can only obtain two hundred and fifty foot links, you will need one hundred and forty two nodes at a cost of $49700. It should be noted, though, that a long term goal of CUWiN is to run on hardware that costs less than $100. That would move the cost of the setup with two hundred and fifty foot links down to $14200.

Supported Chipsets

One of the most important choices you face when building a CUWiNware node is what wireless NIC to buy. Wireless NICs use a variety of chipsets depending on the the manufacturer that makes them. The chipset that your wireless NIC uses must have drivers in NetBSD that support Ad-Hoc mode.

Theoretically different chipsets can be used in different nodes on a CUWiNware network as long as they are supported by NetBSD but because of various bugs/quirks in the firmwares of various chipsets, it is often best to standardize on a single supported chipset for all the nodes in your network.

Chipsets

Intersil Prism - The prism (version 2, 2.5, or 3) chipset is used in some PCMCIA and PCI cards manufactured by D-Link, Proxim, SMC, and others. This chipset is well supported in Ad-Hoc mode with no real bells and whistles. This may be the best chipset available if low cost PCI cards are needed for low-resource nodes.
Atheros - Atheros makes the most advanced 802.11x NICs currently available. This is the chipset currently recommended by the CUWiN team. Most tri-mode a/b/g cards on the market use the Atheros chipset. The Atheros chipset features a Hardware Abstraction Layer which puts most of what would traditionally be in the firmware into software. This means that when/if the interface to the cards is fully opened up to programmers, arbitrary control of power levels and other low level features will be possible. Because future versions of CUWiNware will take advantage of this fine grained control we recommend investing in cards with this chipset now. Atheros cards may be a bit more expensive than some of their competitors and the drivers for the Atheros cards are not as mature as those for the Prism cards so there may be bugs, but these drivers are being actively developed and debugged by the CUWiN team.
Hermes - Most cards made by Orinoco, Lucent, WaveLAN, and Proxim use the Hermes chipset. These cards have very good sensitivity with low power radios and they are supported in NetBSD but they suffer from serious firmware problems relating to their IBSS ids. The IBSS id needs to be the same throughout the mesh but cards with this chipset often "split" the IBSS in a way that can only be fixed by rebooting all nodes on the network in a certain order. This chipset should generally be avoided for any Ad-Hoc network as just one Hermes chipset mixed in with other nodes can cause a serious network split. Firmware upgrades do not appear to completely solve this problem. Aironet/Cisco chipsets have the same problem.
Other Chipsets - Development of drivers for new chipsets is constantly in progress. Some manufacturers publish the specs for their hardware which makes driver development fairly straightforward. Other manufacturers keep their specifications proprietary which means that NetBSD developers have to reverse engineer the interfaces. Support for the ADMTek ADM8211A is available now and support for other ADMTek chipsets such as ADMtek ADM8211C/CR is expected soon. Support for the Realtek RTL8180 chipset has also been added.

Constructing a Rugged Outdoor Node

One of the biggest sources of signal loss in a wireless network is in the cable between the low power radio in each node and the antenna. High quality antenna cable is very expensive. In order to maximize signal strength and to minimize cost, it is best to put the node as close to its antenna as possible. This generally means putting the node outdoors on the rooftop on the the same mounting pole as the node itself.

Outdoor nodes need to have no moving parts, withstand extreme temperatures, withstand rain, snow, wind, sand, and other local climate conditions and be upgradable without physical access.

Single Board Computer

The first component of any outdoor node is the single board computer. This is a small form factor motherboard built for embedded computing applications. Typically a single board computer will be built to industrial standards and will be much more rugged than a typical consumer motherboard.

Typically a single board computer will have a processor (CPU), some memory, some compact flash storage (or a slot for it), one or two Mini-PCI or PCMCIA slots, one or more ethernet jacks, a serial port, and an input for DC power.

In order to run current versions of CUWiNware you will need a single board computer with an x86 CPU, preferably 486 or better running at 100 MHz or better. It will need at least 64MB of RAM and 64MB of compact flash.

The 64MB of compact flash is necessary to contain two full versions of the software which is currently around 32MB in size. The space for the second image is used for on-line upgrades of the node. It may be possible to build custom versions of CUWiNware with on-line upgrades disabled that would only require 32MB of compact flash.

Make sure there is an enclosure available for the board you choose!

We recommend Soekris Engineering's net4526 board which has 1 ethernet interface, 2 Mini-PCI slots, 64MB of on-board compact flash, and 64MB of on-board RAM. This board is small, powerful, rugged, and has good enclosures available.

As I write this (August 2005) a complete, quality, node can be bought for around $300, but it is the eventual goal of the CUWiN project to run on hardware that costs less than $100.

The Wireless NIC

The three requirements for a wireless NIC are that it must have an external antenna connector, it must be compatible with the motherboard you have chosen, and it must use a chipset that is compatible with NetBSD in Ad-Hoc mode.

Interfaces between the motherboard and the wireless NIC include: Mini-PCI, PCI, PCMCIA (a.k.a. Cardbus or PC Card), and USB. Most rugged single board computers will use either PCMCIA or Mini-PCI cards.

Make sure there is a pigtail available for the card you choose!

We recommend Netgate's NL-3054MP Aries Mini-PCI 802.11b/g or SL-5354MP Mini-PCI 802.11a/b/g cards. These use the Atheros Chipset.

The Enclosure

The enclosure you choose must allow your single board computer to be mounted. Many enclosures come with a special mounting plate that the manufacturer can custom drill to work with any single board computer that you specify. Many manufacturers make enclosures specifically for Soekris boards. The enclosure must have holes for an ethernet cable gland and and an N connector for the antenna connection.

Any enclosure for an outdoor wireless node should be rated at least NEMA Type 4x. Type 4X NEMA enclosures protect against falling dirt, rain, snow, blown dust/sand, splashing water, and ice.

The enclosure should be white in order to reflect rather than absorb external heat from sunlight. If the enclosure is plastic, it must be a type of plastic that doesn't break down when exposed to UV light.

It is vitally important that any and all holes on the enclosure be on the side that faces downwards. No matter how well sealed the hole, with mastic tape or with a cable gland and gasket, if it is on top water will pool around it and freezing/thawing will allow the water to seep in. After months or years of operation the node will fill with water and fail.

It is best not to mount the antenna directly onto the enclosure but to mount both the enclosure and the antenna on a mast. Antennas directly mounted on the enclosure put a huge amount of stress on the joint between the antenna and the enclosure and this can cause leaks.

There is some debate among community networkers as to the utility of a drain hole in the bottom of your node enclosure. If you trust that your node will remain absolutely water tight even after months or years of freezing and thawing then it may be best to not include a drain hole. A drain hole is for water that does get into the enclosure due to condensation/humidity or due to leaks. A desiccant package placed in a sealed node may do a better job of defeating small amounts of moisture. A drain hole may be susceptible to sand or dust in a desert environment and would definitely not be recommended in that case.

A very labor intensive but low material cost way to build an enclosure is to use a surplus military ammunition can painted white with a custom plexiglas mounting assembly. These cans are built to be very rugged and waterproof and are essentially free if you can find a source of them. They do, however, corrode after prolonged exposure to the elements and will eventually fail.

We recommend the NEMA-4x enclosures sold by Metrix Communications for use with Soekris 4526 boards.

The Antenna

Antennas must be made for the band (or frequency) that you are using: 2.4GHz (802.11b/g) or 5.8GHz (802.11a). They should use an N connector for the cable connection. The N connector is most appropriate for the high frequency signals used by 802.11x.

Choices in antenna selection include: omni vs. directional, manufactured vs. homebrew, and amount of gain.

Typically mesh nodes will use omnidirectional antennas. This is recommended for most cases. These transmit and receive equally in any direction towards the horizon. This allows the formation of arbitrary meshes without having to aim (or re-aim after a high wind) antennas. It also means that there may be "wasted" radio energy that causes interference for nearby nodes.

You may want to choose a directional (sector or beam) antenna if you are creating a long distance point-to-point link within the mesh or if you know for sure that no nodes will ever be placed on the null side of the directional antenna. Sector antennas focus all radio energy in an area of a wide angle (e.g. 60 or 120 degrees). Beam antennas focus radio energy into an even tighter beam. Directional antennas come in many types such as Yagi, Sector, Dish, and Patch and Panel.

In a very dense network the interference caused by nearby nodes using omnidirectional antennas can cause a major drop in throughput. This problem can be addressed by replacing key omni nodes with multiple nodes with sector antennas. Collectively the nodes form 360 degree coverage and are linked via their wired ethernet cables.

There are many designs on the internet for homebrew antennas that you can make from common household items and cheap hardware using simple tools. The antennas can be pretty time intensive to build and their quality will vary greatly. The easiest designs are for directional beam antennas. Homebrew omnidirectional antennas are very difficult to build.

Every antenna will include a "gain" rating. This is a measure of how much the antenna increases the signal power in the direction that the antenna points. For omnidirectional antennas a high gain means that less power is radiated "up" or "down" and more power is radiated "outwards". For a directional antenna a high gain means less power is radiated out the "back" and more out the "front" and higher directional gain also means a tighter beam. Gain is logarithmic so every increase of 3dB gain means a doubling of power.

The best antenna cable to use for microwave applications such as 802.11x is LMR-400. The antenna cable is a major source of signal loss so it is very important to use only short runs of high quality cable with N connector ends. Installing your own ends on raw cable is very time consuming and requires special tools.

For most generic mesh applications we recommend the HyperLink Technologies HGV-2409U 2.4GHz 8dbi omnidirectional antenna. This antenna features a flared base which makes it less susceptible to wind-shear than other similar antennas from other manufacturers.

Mast and Mounting Hardware

Microwave signals are extremely dependent on line of site. The higher your antenna can be the more likely other nodes are to have line of sight to it.

Generally, you can use an antenna mast on a rooftop to achieve height. If you live in a tall building you may be able to just place the node in a window. If you have access to a radio tower then you can achieve the best heights.

There are several ways to mount an antenna mast on a rooftop. For flat roofs there is a great non-destructive flat roof mounting platform that is held in place by cinderblocks. There are special mounts for gables and chimneys, as well as tripod mounts.

Any hardware designed for television antenna mounting will suffice for a mesh node antenna.

We recommend the Radio Shack ratchet style Chimney Mount (cat no 15-839) and any 5 foot antenna mast typically sold for television antennas.

Grounding and Lightning Arrest

Tall metal polls on your rooftop can be a major fire hazard as well as a risk to all electronic equipment connected to the node in any way. It is important to follow proper grounding guidelines to protect your safety and your equipment.

Lightning can travel down either of the 2 conductors in the antenna cable and they can't both be directly connected to ground. In order to protect this signal from lightning you need to install an inline gas-discharge lightning arrestor and connect that to ground.

See the ARRL Antenna Handbook for tips on grounding antennas.

Outdoor Cat-5e Cable and Power over Ethernet Injector

The cable from the node into the user's house is a CAT-5 ethernet cable which also carries the node's power. Although it is more expensive, you should get special outdoor CAT-5 cable. The outdoor cable's jacket will not break down in UV light and it is filled with a waterproof gel that prevents condensation-related corrosion of the conductors. Regular CAT-5 cable will still work, but may need replacement after a few years.

In order to send power to the node over the ethernet cable you will need a power over ethernet (PoE) injector. Many power over ethernet injectors claim to provide protection against reversing the cables (so that you are sending power back into your LAN rather than up into your node) but this is not implemented on any PoE injectors that we have used. Be careful that you connect the power side to the node and the data side to your LAN.

Information on Battery/Solar Powered WAPs

http://seattlewireless.net/~mattw/gallery/mobnode

Consider that you may have to protect the system against theft in such a situation
Use devices that only draw a minimum of power - every watt you waste makes the system more bulky. You end up with big solarpanels and huge batteries.

Constructing a Low-Resource Node

While rooftop nodes are more manageable, more efficient, more durable, and more reliable, their cost of a few hundreds of dollars can be prohibitive to many communities. Community networks built on a budget may wish to make use of recycled desktop computers. This is possible with CUWiNware's CD (ISO) image.

Typically a low resource node is placed in an attic to minimize the cable run to an antenna on the rooftop. A low resource node may also be placed near a window with an antenna in a tall building or a building very close to another CUWiNware node.

Most hardware issues from the Rugged Outdoor node apply to the indoor low resource node. Here are notes on additional considerations.

CPU and Motherboard Considerations

While the CUWiNware software will operate on most 486 or better platforms, most old consumer-grade 486 and original Pentium desktop machines have such old motherboards that PCI Wireless NICs or PCI/PCMCIA bridge cards will not function properly. Check to see if your wireless card requires PCI 2.0 and, if so, whether the motherboard of the desktop you are using has a PCI 2.0 compliant motherboard.

Your options for a wireless NIC are to use a PCI wireless card, a USB wireless card, or a PCI/PCMCIA bridge card with a PCMCIA wireless NIC. It is probably easiest and cheapest to find a compatible PCI card.

It is easiest if the BIOS on your low resource node supports booting from CD-ROM. Some very old motherboards do not support this. If you can't boot from CD-ROM, it is possible to bootstrap with a special floppy disk which will then hand over control to the CD image.

An attic-based node will probably not have a keyboard attached to it. You'll want to disable the requirement in the BIOS that a keyboard be attached. Otherwise every time the node is turned off and back on it will hang on boot while it waits for a keyboard to be connected.

Other Considerations

A low resource node has many moving parts, this is what makes it less reliable. You will need a CD-ROM drive, optionally a floppy drive (if you can only boot from floppy or if you want the node to remember configuration changes across reboots), an wired ethernet NIC, and a wireless NIC. There is no need for a keyboard, monitor, mouse, or hard drive.

If you wish to reduce the amount of moving parts you can install an IDE compact flash drive instead of a CD-ROM and Floppy.

Console

n order to interact directly with the node you will need a serial console. Some messages may show up on a monitor connected to the node but the only way to interact with the node is not through the keyboard but through a terminal program on the serial port. The settings are 19200 N81. You will however need to use a monitor and keyboard to access the BIOS settings when you first set up the node.

Antenna Options

In addition to the high gain antennas that are typically used with outdoor nodes, it is possible for an indoor node that is very close to another CUWiNware node to simply use the low gain omnidirectional "rubber duck" antenna that comes with the wireless card, especially if it can be put in a window facing the other nearby node.

Motherboard/CPU Considerations

Other Node Possibilities

There are many other possible form-factors for CUWiNware nodes. These are currently untried but an adventurous community network designer could easily experiment with these possibilities.

An old laptop or tablet PC could be converted into a node. It already has the PCMCIA slots and a small form factor. Because it is battery powered you could create a truly ad-hoc on-the-spot network anywhere if you had several of them.
It is also possible that a laptop running the HSLS daemon on top of it's regular operating system could be a sort of "roaming" node on the mesh.
The dream of cheap mesh nodes could be realized by flashing Access Points with CUWiNware. In order to do this CUWiNware will need to be stripped down to operate under MUCH tighter constraints but we believe this may be possible.
CUWiNware could be installed on a hard drive in a node for R&D purposes. Then it'd be easier to tweak the contents of the running software without having to build and burn a new CD or compact flash image.

User's Guide

Introduction

The User's Guide section of the CUWiN manual is designed to help you after you have already decided which hardware setup is most relevant to you. Contained within this section is are how-to guides, node configuration information, and a trouble-shooting guide.

The CUWiNware package provides a completely self-contained, self-configuring bootable disk image for creating mesh wireless nodes for community wireless networks. The CUWiN developers distribute pre-built generic disk images for common disk types on the x86 architecture. Advanced users can also custom build a CUWiNware disk image from source code.

Because CUWiN is still engaged in an intensive development process, the software changes rapidly, as will the troubleshooting issues. When possible, we will try to be diligent about noting that particular troubleshooting issues are taken care of by particular upgrades. Also, we will try to transfer useful information from the developer's list regarding troubleshooting, but anyone responsible for maintaining a CUWiN network would be well advised to join the development list, which you can do under the Get Involved >> Mailing Lists.

Download Software

All images are distributed compressed with gzip. ISO and Compact Flash images will need to be uncompressed before they are copied onto media.

Images for official CUWiNware releases can be downloaded from SourceForge or from cuwireless.net.

Compact Flash Images ISO (CD-ROM) Updater Tarball

Compact Flash Images

Compact Flash images must be distributed according to the geometry of the compact flash device for which they are targeted. We distribute official images for SanDisk 64MB and for SanDisk 126MB Compact Flash cards. If you have a different compact flash card you will have to do a custom build from source code. It is important to note that the Soekris net4526 board which has 64MB of compact flash on board is NOT compatible with the SanDisk 64MB image. If you install a SanDisk 64MB image on a Soekris net4526 it will be bootable but it will not be online-upgradable.

The command to copy the staboot.img file to compact flash in NetBSD is
dd if=staboot.img of=/dev/rwd0d bs=8k
where rwd0d should be replaced with the raw device for the compact flash card.

ISO (CD-ROM)

ISO images are meant to be burned to CD-R which will then be bootable. Use your CD-R burning software to burn the disk. If the target platform can not boot from the CD-ROM drive then you will have to create a boot floppy. The CD-ROM you create will contain a file called /cuwboot/boot.img.

The command to copy the boot.img file to a floppy disk in NetBSD is
dd if=boot.img of=/dev/fd0a bs=1024 count=1440.

Updater Tarball

These files are just gzipped tars of the contents of the disk image. They are geometry independent. These tar files can be loaded by a special updater program on the compact flash versions of the software.

Installing the Software

Now that you have the software, you will need to install it on the node. Installing the software can be a complicated process. This page describes the various methods used to install software on the node. These methods can be broken down into the following methods: PXE Booting, Using the ISO, and Online Upgrading. So which one do you want to use? If you have purchased a Soekris board (or something similar), you will need to PXE Boot. If you are making a node out of an old computer, you are going to want to use the ISO. If you already have a functioning node but need to update the software, you can upgrade the node online (or by PXE booting, if you find that easier).

PXE Booting

A brand new net4526 or net4826 node has to be flashed with an initial version of the software. This is done by PXE booting the node, logging into it, and executing a dd to it's flash drive. PXE is a protocol for booting remotely over ethernet. In order to do this you will need to set up a PXE server.

If the node is already non-bootable then it'll default to PXE booting. If it has a bootable but non-upgradable image on it then you can render it unbootable by logging in and wiping out the boot block:
dd if=/dev/zero of=/dev/rwd0d count=32

Just connect the non-bootable node's ethernet to the same ethernet segment as the PXE server and turn it on. Within 2 minutes or so you should be able to log in to the node over the ethernet wire via SSH. You can then issue the following command:
dd if=/staboot.net4526.img of=/dev/rwd0d bs=8k
You can get the appropriate IP address to connect to by checking the PXE server's DHCP log or by pinging the broadcast address.

Instructions for PXE booting and setting up a PXE Server can be found in the "How-to" section of this manual.

Installing from an ISO

If you are using an old computer, you simply need to insert the live CD-ROM you created when you downloaded the software into the CD player. The system should boot on its own to CD-ROM. If it fails to do that, you will need to change your CMOS settings, which you can do by entering either Del, F1, or Esc shortly after start-up. You will need to set your CD-ROM to be bootable before the harddrive becomes bootable.

Online Updates

If a compact flash node is bootable then it should be possible to do an on-line upgrade without a PXE boot server. This can be done over the wire or over the air.

Log into the node, become root, and run the script
/sbin/upgrade user@host:/path/to/upgrade.tgz

You will need to have the .tgz file on a host that is running sshd and is accessible to the node. Luckily sshd is available for all major platforms, including Windows (with Cygwin) so it is easy to turn any laptop into a roving upgrade platform.

Sometimes upgrades go badly. If you need to revert to your former installation, you should follow these instructions, provided by spditner.

If you find that the upgraded version isn't working all the great, you can roll back to the previously installed image by marking the alternate partition as "active".

# fdisk wd0
Partition table:
0: NetBSD (sysid 169)
start 63, size 62497 (31 MB, Cyls 0/1/32-488/3/1)
1: NetBSD (sysid 169)
start 62560, size 62496 (31 MB, Cyls 488/3/1-977), Active
2:
3:

Set partition 0 as active:



# fdisk -af -0 wd0
# reboot

Network Topology

The node's IP settings run under one of two basic configurations. One configuration is that the node can act simply as a router that connects to the wireless mesh and routes packets through the mesh. If another node on the mesh is acting as a gateway to the Internet, the local node will discover it and can route any packets destined for the Internet to that gateway. In the other configuration, if your LAN has an Internet connection, the local node will function as an internet gateway that provides an internet connection to other nearby nodes. In either configuration, you can use the resources of the wireless mesh. If there happens to be a local independent band sharing their music on the wireless mesh, anyone with a node can download it and an Internet connection is not required.

It should be noted that every machine on every LAN in the wireless mesh is accessible by every other machine in the wireless mesh. This is a very powerful feature because it enables anyone to create content and serve it to everyone on the mesh via their desktop computer with no additional cost. Local births, weddings, and deaths could be posted on the web via the county clerk's desktop computer. The municipal pool could broadcast their hours in a similar manner. Local radio stations could stream music to listeners on the wireless mesh. The imagination's the limit. The problem is that someone sitting in a van on the edge of town, or the latest computer virus outbreak, can also access everyone's computers if your firewall isn't set up appropriately. So it is important to remember to secure your computer(s) and place firewalls where appropriate.

It is the intention of the developers of CUWiNware that the final software incorporate firewall functionality into each node. Ideally, nodes would auto-configure themselves to allow others to only access the services that are advertised by their LAN, and allow users to explicitly allow others to access non-zeroconf services. None of this has been implemented as of this writing.

A major advantage of CUWiNware is that the mesh doesn't need an Internet connection to function properly. Everything described in this manual should function if a single backbone is used, if multiple volunteers provide home DSL lines, or if no Internet connection is used. It is completely stand alone.

Wired Interface

On the wired LAN side of the local node, CUWiNware checks for a DHCP server on the LAN. If one is found, the node takes the IP address assigned to it and provides an Internet gateway to other wireless nodes. If no DHCP server is found, the node assumes that it should function as a router and DHCP server for the LAN. The node creates a wired IP address for itself in the form 10.A.B.254. A and B are chosen via the MAC address to minimize IP address collisions with other LANs on the network, but because they are based on the MAC, they are the same every time the node is booted. The DHCP server assigns leases to addresses in the range 10.A.B.1 - 10.A.B.253. If you need to assign IP settings manually, that can be done via the SSH interface.

Wireless Interface

The wireless IP address is another number based on the MAC address that is in the form 10.0.A.B. In places, you may see a reference to a 192.254.A.B address. Do not be alarmed. Because of suttlties in the kernel, CUWiNware uses the 192.254.A.B address for link-local routing traffic.

At this time, you cannot use a node as a wireless access point, even if it has two wireless cards in it. Also, the nodes only serve as repeaters for mesh traffic, they don't route any other traffic. Each node can only connect wirelessly to each other node. The only public interface is through the ethernet port. At some point in the future when, the developers have more time or volunteers, much more wireless functionality will be included.

Channel and Mode Selection

Currently, CUWiNware uses a user defined channel (the default is 11) in the 802.11b mode. Currently, the mode selection selection is made at compile time, but there are plans to make CUWiNware automatically adapt the network to the best mode and channel for the area on the fly.

Can you change the radio used by CUWiN?

Posted to the developer's mailing list on July 13th, 2005 by David Young.

I cannot think of any reason the driver should not work for 802.11a. I have some a/b/g cards on our indoor testbed. I will give .11a a try sometime next week.

The problem I anticipate is a lot more mundane than device driver compatibility: we set the operating mode to 802.11b at "compile time." You have to fiddle with some scripts to use any other mode. To use 802.11a, you have a few choices:

compile-time configuration: you can build a CUWiN distribution that sets the mode to 802.11a, instead. (Change the text 'mode 11b' to 'mode 11a' in cuw/trunk/src/boot-image/extras/etc/ifconfig.wireless.tmpl.) CUWiN can help you with that.

you can change our web configuration widget so that it lets you program the operating mode (.11a, .11b, or .11g). CUWiN can also help you with that.

When you add a second radio, things get a little bit more complicated, because presumably you want to operate them on different channels, or even on different bands. The first problem is that the web configuration widget only works on one radio; that will have to be changed. It's not hard, just nobody has done it, yet.) You can do "compile-time" configuration of multiple radios, but you have to make assumptions about the order that radios are enumerated---that is, you have to take care that radio #0 and radio #1 are not reversed in your Metrix boxes, or else that they are not reversed in your configuration files.

Routing

The wireless mesh itself is created via a routing algorithm called HSLS (Hazy Sighted Link State). HSLS is in the family of wireless routing algorithms called FSLS (Fuzzy Sighted Link State). The basic observation behind FSLS algorithms is that changes in links that are far away on the mesh are less important than those links that are nearby. In an FSLS powered mesh, any changes in the link states are propagated quickly to the nearby nodes, but more slowly to distant nodes.

For example, consider a wireless mesh that spans a city and its suburbs. Nodes A, B, and C are located near a small park in the downtown area. Node Z is in the far reaches of the suburbs. Nodes A and B are linked together, but suddenly the link is broken when high winds knock A's antenna off of its mounting pole. C learns of this change within a second, and alters it's routing table, but it is many minutes before Z discovers that the link between A and B has been broken. Once Z learns of this altered link, no changes are made to its routing table because it doesn't use the link between A and B in its link state calculations anyway.

For more information see the HSLS documentation in this manual.

Scalability: Maximum Network Size

Generally, in ad-hoc mesh networks, the factor limiting the size of the mesh is the routing algorithm. Often, when an ad-hoc mesh reaches a certain size, it collapses because the routing algorithm doesn't scale. This can be due to a number of reasons. With some routing algorithms, the network spends all of its resources transmitting all link changes to each other node on the mesh, and no useful traffic can be transmitted. With other algorithms, link changes are not transmitted soon enough, and the packets are dropped because a node does not have enough information to transmit the packet to the next node. Other types of meshes do not scale because they require very specialized human intervention to define the routing table for each node. Sometimes, a mesh fails because the latency from one side to the other becomes too high. Because of these problems, many meshes have not been able to scale over twenty nodes.

The HSLS algorithm used by CUWiNware is intended to scale to at least thousands or tens of thousands of nodes. To be honest, though, we will not know for sure how well it scales until a community pushes the boundaries.

Exploring Your Node

So you just got your node running. You think. How can you tell what is going on in your node?

Remote Shell

You can use SSH to login to the node, but it is much less user friendly than the web interface. It is recommended that you use the web interface if at all possible.

To login over SSH, you should use the user name "guest" and the password "guest". If you were logging in from the command line, it would look like "ssh guest@10.A.B.254". The default root password is "changeme", but remote root login is disabled. If you are logged in as guest and you want root privileges, you can use the "su root" command.

Here is a list of fun commands for rooting out information about the node and network:

cat /var/run/dmesg.boot: This will print out all of the boot messages.
ifconfig -a: This displays information about all interfaces in the system.
netstat -rn -f inet: This displays your current routing table.

Changing Your Root Password

When you download one of the publicly available builds of CUWiNware, there is a standard root password "changeme". As requested, it is a good idea to change the root password to prevent others from doing interesting things to your node without your permission. Unfourtunately, any changes made to the system will be erased upon reboot unless you make the changes in writable memory. If you are using flash media, you can make the changes in "/permanent/" and they will be preserved. The following guide was taken from the forums.

$ su root: Gain root privileges.
Password:: "changeme"
# mount | head -1: Display how the current file system is mounted.
/dev/wd0a on / type ffs (read-only, local): Hrm, read-only. That will need to be changed.
# mount -u -w /: Change the status of the filesystem at / (the root file system) to be read and write.
# mount | head -1: Display current file system again.
/dev/wd0a on / type ffs (local): It's not read-only anymore.
# passwd: Change the password for the current user.
Changing local password for root.

New password:: Find a creative password that no one will guess. "password" or "12345" are not good passwords.
Retype new password:
# cp /etc/master.passwd /permanent/etc: Copy the password files to the permanent directory.
# cp /etc/spwd.db /permanent/etc
# cp /permanent/etc/spwd.db /permanent/etc/garbage: Work around for old bug when writing to flash.
# mount -u -r /: Change the root file system to be read-only again.
# mount | head -1: Display that the file system is, in fact, read-only.
/dev/wd0a on / type ffs (read-only, local)

# reboot: Reboot the node.

At this time, you cannot make changes to nodes booted from CD-ROM (ROM stands for Read Only Memory). There is talk about using a floppy drive to allow users to configure a node, but at this time (v0.5.8) no one has written the code for that.

Nodeconfig: A Web Interface

The easiest way to see how your node is set up is to view the web interface of your node.

If you are using your node as a router, you can type the address "http://192.168.0.1/" into your web browser to load the web interface. Currently the only feature for understanding your node is RouteViz. You can also use the web interface to configure your node.

To view the web interface on a remote node, you can use the command "ssh -L 8000:localhost:80 guest@10.0.A.B" to log in to the remote node. Replace "10.0.A.B" with the IP address of the ethernet interface of the remote node. When you are logged in, you can visit the URL "http://localhost:8000" on the machine that you logged in from to view the remote web interface.

Route Visualization

When you view the "RouteViz" page you will be shown a virtual map of the network as the current node sees it. This map is built from HSLSd's adjacency database. HSLSd one of the important programs used to build the routing table.

Unless you customize the installation of CUWiNware with a special local map file for the area around your community network, the layout of nodes will simply be what "looks good". RouteViz will attempt to make a best guess at where nodes are located based on the quality of the signal between each node. Walls (especially metal) greatly degrade the wireless signal, while open spaces will let a signal travel a long distance. Because the node has no way of determining the terrain around it, the locations of nodes on the RouteViz map may be skewed and are simply a best guess.

Click on a node to get information about it.

The links between nodes show the current link quality as measured by ETX. Red links are nodes a ways down the street, while green links are your near neighbors (in a wireless sense). If a node has only red links connected to it, it should be investigated to increase the quality of its connection to the mesh.

Configuring a node

Compact flash nodes and CD-ROM nodes with a floppy drive installed can be configured via a web-interface and clicking on "Config".

Configurable values are:

channel: This can be any valid channel for the protocol being used. For 802.11b this is any integer between 1 and 11. Every node in a given mesh must be on the same channel.
wired interface: This can be set to "auto", "dhcpd", or "dhclient". Depending on the setting the node will either act as a DHCP client or a DHCP server. If it is a DHCP client then it will act as an "internet connected node". The default is "auto".
hostname: This is the name by which this host identifies itself.
latitude, longitude: The latitude and longitude for use by the visualization engine. Do not set these unless you have also custom configured RouteViz with a local map and it's latitude and longitude corners.
nameservers: A comma separated list of nameservers that will be used locally and given out to DHCP clients to use for their lookups. You should choose something local to your ISP or a public DNS server.
ssid: A unique identifier for the whole mesh cloud, this must be the same one all machines that wish to be part of the mesh.

Configuring a node creates the file /etc/cuw_config on a node. That file which is simply a flat file containing variable assignments. You can untar an upgrade image, replace it's cuw_config file, then retar it and then apply it as an upgrade. This is an easy way to create a localized distribution from the standard builds.

Troubleshooting Guide

The visualization tool is the best way to start troubleshooting.

From the viz page you can test the connection between you and the node. You can also test the connectivity along the route to the internet. If the local network has packet loss then the problem is probably with your Wireless Access Point or your LAN rather than with the CUWiN wireless mesh network. If your path to the internet has packet loss then it is time to investigate the viz map for bad links. If you can't access the software at all then either the node is down or you have found a bug in the node code.

If you identify a problem on the mesh as the reason for your network outage, please send the text from the Test Local Network and Test Internet Connectivity links to cu-wireless-support@cuwireless.net along with a description of the problem that you are having.

If your node has been completely knocked offline, you will most likely need to climb up on the roof and check it out. Nodes have been known to fill with water when there is a leak in the top, but no leak in the bottom. Lightning strikes also occur.

What follows is a list of helpful commands that are useful in troubleshooting the network.

df -h: Shows all of the mounted partitions; -h makes numbers easy to read. Use this to show the memory space. If nfs is small, programs will be unable to run.
netstat -rn -f inet: Shows routing tables.
ifconfig -av: All the information about your network interfaces will be displayed in verbose mode.
ping -n google.com: Tests to see if the node can use the network to reach google.com
traceroute -n google.com: Documents the route that a packet to reach google.com

The following is a list of important files that you will want to use the less command to look at:

less /var/db/linkstates: Shows all the linkstate information.
less /var/log/daemon*: Demonstrates exactly what hsls is doing.
less /var/log/messages*: Registers all error messages

To see what Zebra is up to:

telnet localhost 2601
password: wireless
show ip route: Shows zebra routes.

How-to Guides

CUWiN is always seeking ways to help people use our software and hardware. To that end, we are committed to providing the how-to documents that break things down in the simplest possible manner. We have started this part of the manual with two documents: how-to build a CUWiN Metrix node and how-to PXEboot a Soekris 4526 using NetBSD. These documents are dynamic in that we are constantly changing the way we build wireless networks to take advantage of new technologies, new hardware, and the software that we develop. Therefore, if you having a problem with a particular document, check back to make sure that it has been updated. If it hasn't been updated, email us, giving as much detail as possible about the place in the document where you are having trouble.

Since we have a limited staff and always seem to have about ten more irons in the fire than we can possibly deal with, we encourage you to develop your own how-to guides and submit them to us via email. We are always happy to add new things that can help people do it themselves.

Flashing a Meraki Mini

Flashing the Meraki Mini with NetBSD

NOTE: This process will clobber the load of Linux on this unit. I have not been able to successfully save the original image, but that was probably largely due to my own pilot error -- it turns out that Linux uses the entire flash memory.

First, you must have an image compiled. Redboot prefers to load srecords, and the default kernel builds an srecord file.

% ./build.sh -m evbmips-eb kernel=MERAKI

We're going to use HTTP to load the files. I just put the resulting netbsd.srec file into the root htdocs on my server. You could probably put it somewhere else too.

% cp sys/arch/evbmips/compile/obj/MERAKI/netbsd.srec \
                /var/apache/htdocs

Next we need to connect to the Mini via a serial line. I set up a line called "usb" in /etc/remote, so that I can tip in like this:

% tip -115200 usb

connected

However you connect, its 115200 8N1. Once you power up the unit, you'll see something like this:

        Ethernet eth0: MAC address 00:18:0a:01:06:d1
        IP: 192.168.84.1/255.255.255.0, Gateway: 0.0.0.0
        Default server: 192.168.84.9

        RedBoot(tm) bootstrap and debug environment [ROMRAM]
        Release, version V1.04 - built 12:24:00, Apr 17 2006

        Copyright (C) 2000, 2001, 2002, 2003, 2004 Red Hat, Inc.

        Board: Meraki Mini 
        RAM: 0x80000000-0x82000000, [0x8003d110-0x80fe1000] available
        FLASH: 0xa8000000 - 0xa87e0000, 128 blocks of 0x00010000 bytes each.
        == Executing boot script in 2.000 seconds - enter ^C to abort

Quickly press Control-C to interrupt the boot. Run "fconfig" to update the configuration data flash.

        RedBoot> fconfig

Now it will prompt you for all the flash parameters. You might want to record the old parameters in case you want to restore them. I didn't bother.

The following is what I entered, I have the Mini configured as 192.168.251.93 and I have a HTTP server providing the srecord image on 192.168.251.21. It is possible that BOOTP could be used too, but I've not tested it. Redboot isn't particularly robust.

        Run script at boot: false
        Use BOOTP for network configuration: false
        Gateway IP address: 192.168.251.1
        Local IP address: 192.168.251.93
        Local IP address mask: 255.255.255.0
        Default server IP address: 192.168.251.21
        Console baud rate: 115200
        GDB connection port: 9000
        Force console for special debug messages: false
        Network debug at boot time: false
        Update RedBoot non-volatile configuration - continue (y/n)? y
        ... Erase from 0xa87d0000-0xa87e0000: .
        ... Program from 0x80ff0000-0x81000000 at 0xa87d0000: .

Next we reset the board, so the new parameters will take effect.

        RedBoot> reset

Wait a short bit (~2 secs or less) for the unit to reboot. It will not autoboot this time, instead going right to the prom property.

        Ethernet eth0: MAC address 00:18:0a:01:06:d1
        IP: 192.168.251.93/255.255.255.0, Gateway: 192.168.251.1
        Default server: 192.168.251.21

        RedBoot(tm) bootstrap and debug environment [ROMRAM]
        Release, version V1.04 - built 12:24:00, Apr 17 2006

        Copyright (C) 2000, 2001, 2002, 2003, 2004 Red Hat, Inc.

        Board: Meraki Mini 
        RAM: 0x80000000-0x82000000, [0x8003d110-0x80fe1000] available
        FLASH: 0xa8000000 - 0xa87e0000, 128 blocks of 0x00010000 bytes each.
        RedBoot>

Now we load our netbsd.srec file. The following assumes the path to it on your HTTP server is /netbsd.srec. Adjust accordingly if you need to.

        RedBoot> load -m http /netbsd.srec
        Entry point: 0x80041000, address range: 0x80041000-0x80202350

At this point, if you just type "go", the NetBSD kernel you loaded will boot. This is the safest way to run NetBSD on the Meraki, becuase it never disrupts flash.

                        ===========
                        | WARNING |
                        ===========

        Proceeding from this point will erase the flash on your unit,
        and might leave it unusable.  Proceed at your own risk.

If you're still here, you must want to write NetBSD to flash. It is instructive to look at what is already in flash:

        RedBoot> fis list
        Name              FLASH addr  Mem addr    Length      Entry point
        RedBoot           0xA8000000  0xA8000000  0x00030000  0x00000000
        stage2            0xA8030000  0x80100000  0x00020000  0x80100000
        FIS directory     0xA87D0000  0xA87D0000  0x0000F000  0x00000000
        RedBoot config    0xA87DF000  0xA87DF000  0x00001000  0x00000000

Note that the flash starts at 0xA8000000. Allocation is done in flash sector sizes of 64K at a time. (I.e. except for the RedBoot config, all flash addresses should end in 0000 when displayed in hex.)

Unfortunately, the Linux code doesn't properly allocate everything in RedBoot. It turns out that stage2 is the Linux bootloader. There is a JFFS2 image located at 0xa8050000 thru 0xa8150000. The Linux kernel is located at 0xa8150000 through 0xa8490000. I mistakenly believed the data between 0xa849000 and 0xa87d0000 to be free. But I was wrong. Pretty much the whole flash is used.

I have not tested this theory, but it should be possible to read the flash data that we are going to overwrite, and save it in a file. Then in theory we could restore it. I only had the one unit, and I neglected to perform this step. Doh!

Anyway our kernels are always under 2MB, so we allocate based on that. (If you put an mfs in your kernel, it will be bigger, and you might need to change some parameters appropriately. I recommend leaving the first 320K of flash alone. You _must_ leave the first 192K alone, because it is used by RedBoot, and the 128K after that is useful if you ever want to restore Linux. I'm not sure if the Meraki Linux code drop includes the source for this bit.)

Recall our kernel load from above (if you do it again, its harmless):

        RedBoot> load -m http /netbsd.srec
        Entry point: 0x80041000, address range: 0x80041000-0x80202350

So, lets write it to flash. The fis create command below should all be typed on one line, but to facilitate display, I've broken it up and used a backslash "\" to indicate that the data should continue unbroken. Don't type the backslash.

The results look like this (it will take a while to do this, maybe a couple of minutes, the SPI flash is not fast):

        RedBoot> fis create -b 0x80041000 -l 0x200000 -f 0xa8490000 \
                -e 0x80041000 -r 0x80041000 netbsd
        ... Erase from 0xa8490000-0xa8690000: ................................
        ... Program from 0x80041000-0x80241000 at 0xa8490000: ................................
        ... Erase from 0xa87d0000-0xa87e0000: .
        ... Program from 0x80ff0000-0x81000000 at 0xa87d0000: .
        RedBoot>

Notice that it did two erases/programs. That's because we also updated the RedBoot directory in upper flash. In case you were wondering:
  -b indicates the source address to copy from
  -l indicates the image length (2 MB)
  -f indicates the destination flash address
  -e indicates the entry address when the image is loaded
  -r indicates the image load address when the image is loaded
  netbsd is the image name (you could name it something else!)

If you change the flash destination address and length, you can store a larger kernel. I recommend never starting your flash address lower than 0xa8150000 and you must not let the image extend beyond 0xa87d0000.

Here's the image listing in flash:

        RedBoot> fis list
        Name              FLASH addr  Mem addr    Length      Entry point
        RedBoot           0xA8000000  0xA8000000  0x00030000  0x00000000
        stage2            0xA8030000  0x80100000  0x00020000  0x80100000
        netbsd            0xA8490000  0x80041000  0x00200000  0x80041000
        FIS directory     0xA87D0000  0xA87D0000  0x0000F000  0x00000000
        RedBoot config    0xA87DF000  0xA87DF000  0x00001000  0x00000000

Lets reset and make sure that we can use it.

        RedBoot> reset
        Ethernet eth0: MAC address 00:18:0a:01:06:d1
        IP: 192.168.251.93/255.255.255.0, Gateway: 192.168.251.1
        Default server: 192.168.251.21

        RedBoot(tm) bootstrap and debug environment [ROMRAM]
        Release, version V1.04 - built 12:24:00, Apr 17 2006

        Copyright (C) 2000, 2001, 2002, 2003, 2004 Red Hat, Inc.

        Board: Meraki Mini 
        RAM: 0x80000000-0x82000000, [0x8003d110-0x80fe1000] available
        FLASH: 0xa8000000 - 0xa87e0000, 128 blocks of 0x00010000 bytes each.
        RedBoot>

Now lets try loading the NetBSD image from flash:

RedBoot> fis load netbsd

It will take a few seconds to load the image from flash. Now lets boot!

RedBoot> go


[ netbsd boots... dmesg begins...
MIPS32/64 params: cpu arch: 32
...

That's it. After this, the rest is just normal NetBSD. If you want to set this up automatically, you can setup an automatic boot script using fconfig. The commands you want to setup in the script are just:

fis load netbsd
go

Enjoy.

How-to Build a CUWiN Metrix-based Node

To build a standard CUWiN node you'll need the following components (from left to right) -- patch cable, omni antenna, power-over-ethernet injector, Metrix node, and a pole & pole-mount (not shown):

Antenna

HGV-2409U (8dBi)

Once you gather these supplies, the second step is to fasten the antenna to its antenna mount:

Attach the antenna to it's mounting hardware.

Metrix Box

Metrix Kit Mark I

Third, you'll want to install the components of the Metrix box (soekris board and mini-PCI radio):

Weatherizing Connections:

Next we'll attach and weatherize the patch cable. First, screw the cable onto the antenna:

Next, using electrical tape, cover the connection point:

Then, use weatherizing "goo" and cover the electrical tape. Note that you should knead the goo until it's smooth and work out any major air bubbles:

And then cover the "goo" with a second wrapping of electrical tape -- congrats, you've weatherized the connection!

Now the connection point is weatherized.

Once the connection point is weatherized, you can fasten the antenna assembly onto your mounting pole:

Assembling Metrix Box Mounting Hardware:

The most complicated part of building a CUWiN node is correctly assembling the mounting hardware for the Metrix node. But, a few tips and tricks will make this an easy task. The mounting hardware consists of various and sundry screws, bolts, washers, and nuts, along with two mounting plates (the two long black rectangles) and (my favorite, but not pictured) two clevis hangers:

You will certainly be tempted to put a bunch of the hardware together and mount it onto the back of your Metrix node (as I've done in the left-hand metrix box)... DON'T DO THIS -- it is pretty much impossible to actually attach the clevis hanger (those two funny-looking gray do-hickies in the lower-right quadrant) to that bolt (trust me, I've tried). Instead, put the large bolt through the mounting plate (as shown on the right-hand side of the picture) and disassemble the clevis hangers:

Then hold the bolt steady with a crescent wrench and, using a socket wrench, tighten down the nut:

Once you're done, you'll have a nifty little widget:

Attach this to the back of the Metrix box:

Attaching the mounting plate to the Metrix box.

Then do the same steps with the second set of hardware. Once attached, then reassemble the clevis hangers. If you follow these simple directions you should end up with a Metrix box that looks like this:

Finishing Up:

Then mount the box beneath the antenna (just slide the box onto the pole and tighten down the bolts that run through the middle of the clevis hanger). NOTE: a 1" clevis hanger will fit a 1.25" pole -- if you use a 1.25" clevis hanger, better use a 1.5-2" pole... It all makes sense once you know the proper use for a clevis hanger, but I'll just let that one gnaw at your curiousity threshold. You'll then attach the other end of the patch cable to the node:

Finally, you'll want to weatherize the patch cable connection, add your ethernet cable, close up the box (don't forget the desiccant), grab a chimney/eve/wall/etc. mount, and put the node in a high spot:

Congratulations!!! If you've managed to avoid entangling yourself in the CAT5 and ending up hanging upside-down off the side of the roof, you're done!

Upgrading a Node using FreeBSD

Upgrading a Soekris 4526 using FreeBSD

This how-to document is designed to walk people through the process of upgrading the CUWiN software on a Soekris 4526 board using a FreeBSD operating system.

Software Requirements

FreeBSD [OpenBSD and NetBSD commands are similar enough that proficient users should be able to translate the FreeBSD commands offered here. Linux is similar as
well, though the prompts and commands may differ somewhat.)
Wget
ssh client and server

Hardware Requirements

One Ethernet port
One crossover cable
One cat5e cable
One power-over-ethernet injector [POE]

Conventions

Three different command line prompts will be used: # indicates the normal user; $ indicates the root user; and > indicates a prompt from the node. All key strokes (e.g. Shift, Control, Enter, etc...) will use the following syntax: <key> [e.g. <Shift>, <Ctrl>, etc.].

VI Tutorial

For text editing, we use VI, but feel free to use whatever text editor you like. Some useful vi commands:
 - enter the edit mode to change text
<Esc> - to escape the edit mode
:q! - to exit without saving changes
<Shift>zz - to save changes and exit

STEP 1: GETTING THE SOFTWARE IMAGE

The easiest way to get the software for your node is to go to http://cuwireless.net/download#Update and download the upgrade file for your hardware. Download it and place it in your home directory.

Step 2: Start SSHD and login to node [You will need root privileges for this step.]

Start SSH server by entering the following command:
1. $ /etc/rc.d/sshd start
Plug the crossover cable into your computer's Ethernet port and the "Data" port on the POE injector. Make sure that the POE injector has power [there should be a green light on top to indicate that it has power].
To find the node's IP address:
1. $ ifconfig -a
2. Find your ip address. Look for a line similar to:
  inet 10.23.54.27 netmask 0xffffff00 broadcast 10.23.54.255
3. Record the number following “inet”. Record this a second time, replacing the digits following the last period with “254”. In our example, this would be 10.23.54.254 – this is the ip address of the node.
Login to the node using the following command and the ip address of node, found in the previous step:
1. $ ssh root@10.23.54.254
Update the node
1. Log into the node using the root password. The username is “root” and the default password is “changme”. If you have changed the password, use that password.
This command makes the backspace key work the way we expect it to. Its not required, but prevents many headaches when you make a typo.
1. $ stty <space> erase Control-v <Backspace>

Now, upgrade the node. Replace “blah” with your username on your local machine, and the ip address with the ip address of your machine (from step C.2). The “~” stands for you home directory. If the file is not in your home directory, replace “~/” with the correct path to the upgrade file. Also, replace “upgrade.tgz” with the correct name of the upgrade file that you downloaded from the website. If you wish to erase the current configuraton file on the node and use the default one provided in the upgrade, replace the “-f” with a “-C -f”.

$ upgrade -f blah@10.23.54.27:~/upgrade.tgz

When prompted with the following:

“The authenticity of host '10.23.54.27 (10.23.54.27)' can't be established. 
  DSA key fingerprint is a8:75:fe:7d:46:b7:a8:05:65:77:43:7a:67:e7:a4:fc.
  Are you sure you want to continue connecting (yes/no)?”

Respond by typing “yes”.

When prompted to enter your password, enter the password you use to login to your local machine (and that corresponds to the username you used when you issued the “upgrade” command).

If that is successful, you should see something like this:

 
  fdisk: DIOCGDEFLABEL: Invalid argument
  fdisk: DIOCGDINFO: Invalid argument
  Disk: /dev/rwd0d
  NetBSD disklabel disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
  total sectors: 125056

  BIOS disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
  total sectors: 210453442400

  Partition 0:
  NetBSD (sysid 169)
start 32, size 62512 (31 MB, Cyls 0-488/2/17)
  Making partition 0 active.
  Preparing for upgrade on /dev/wd0e.
  /dev/rwd0e: 30.5MB (62512 sectors) block size 8192, fragment size 1024
  using 4 cylinder groups of 7.63MB, 977 blks, 1920 inodes.
  super-block backups (for fsck_ffs -b #) at:
  32, 15664, 31296, 46928,
  Installing the upgrade.
  The authenticity of host '10.23.54.27 (10.23.54.27)' can't be established.
  DSA key fingerprint is a8:75:fe:7d:46:b7:a8:05:65:77:43:7a:67:e7:a4:fc.
  Are you sure you want to continue connecting (yes/no)?yes
  Warning: Permanently added '10.23.54.27' (DSA) to the list of known hosts.
  Password:
  100% |*************************************|  4041 KB  237.68 KB/s    --:-- ETA
  Updating etc/fstab
  Updating primary bootstrap
  Updating active partition
  Disk: /dev/rwd0d
  NetBSD disklabel disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
  total sectors: 125056

  BIOS disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
  total sectors: 210453442400

  Partition 1:
  NetBSD (sysid 169)
start 62544, size 62512 (31 MB, Cyls 488/2/17-977)
  Making partition 1 active.
  Copying existing /etc/cuw_config.
  Upgrade complete (/dev/wd0e).
#

After that runs, type the following at the command line to reboot the node:
1. $ reboot
The node begins to reboot and you are disconnected from the ssh session. Wait a couple minutes and verify that the node is back up and operational. If it is not, please consult our troubleshooting section.

Flashing a Soekris 4526 Node using FreeBSD: Introduction

This how-to document is designed to walk people through the process of installing the software on a Soekris 4526 board using a PXE boot on a FreeBSD operating system. This is the kind of board you might buy from Metrix.net.

Software Requirements

FreeBSD [OpenBSD and NetBSD commands are similar enough that proficient users should be able to translate the FreeBSD commands offered here.
wget or links
Cu [installed by default with Tip in FreeBSD]
lrzsz

Hardware Requirements

One Ethernet port
One serial port [We found that a USB-RS232 Serial Connector worked as well.]
One crossover cable
One cat5e cable
One null-modem cable
One power-over-ethernet injector [POE]

Conventions

Three different command line prompts will be used:

$ indicates the normal user;
# indicates the root user; and

<key>

<Shift>

<Ctrl>

VI Tutorial

For text editing, we use VI, but feel free to use whatever text editor you like. Some useful vi commands:

- enter the edit mode to change text
<Esc> - to escape the edit mode
:q! - to exit without saving changes
<Shift>zz - to save changes and exit

Proceed to Step 1

Flashing Your 4526 Soekris Node: Step 1

You need to make a "tftpboot" directory then move to the new directory

$ mkdir /tftpboot
$ cd /tftpboot

Download the files you need for the initial flash.
- $ wget http://cuwireless.net/files/netbsd.gz
- $ wget http://cuwireless.net/files/pxeboot_ia32_com0_19200.bin
You are almost there. You just need to make the files readable by everyone. [You must be root to do this.)
- $ chmod -R 744 /tftpboot

Proceed to Step 2

Flashing Your 4526 Soekris Node: Step 2

Step 2: Setup the Network for PXE Booting

DHCP Server [You will need root privileges for this step.]
1. # pkg_add -r ics-dhcp3-server
2. Now we need to change the configuration file. We do that with vi.
 - # vi /usr/local/etc/dhcpd.conf
 - Make the file look like this:
 [Remember to type to edit the text, <Esc> to stop editing, and <Shift>ZZ to exit.]
 
 ddns-update-style ad-hoc;
 
 subnet 192.168.1.0 netmask 255.255.255.0 {
 option routers 192.168.1.101;
 option subnet-mask 255.255.255.0;
 range 192.168.1.1 192.168.1.100;
 }
 
 class "pxe-clients-ia32" {
 match if substring(option vendor-class-identifier, 0, 9) = "PXEClient";
 next-server 192.168.1.101;
 filename "pxeboot_ia32_com0_19200.bin";
 }
 
 class "netbsd-pxe-clients-ia32" {
 match if substring(option vendor-class-identifier, 0, 17) =
 "NetBSD:i386:libsa";
 next-server 192.168.1.101;
 filename "tftp:netbsd.gz";
 }
3. Restart the dhcp server and make sure that the dhcp server is running by entering:
 - # dhcpd &
 - # pgrep dhcpd
 - Entering the last code should give you a number. If it doesn't, your dhcpd.conf file needs to be reviewed.
TFTP Server [You will need root privileges for this step.]
1. Now you need to edit the TFTP Server Configuration. TFTPD requires the INETD service. You will need to edit "/etc/inetd.conf"
  1. # vi /etc/inetd.conf
  2. Move to the line below and put the cursor on the "#". Press DEL to remove the "#" mark.
    
    tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -U 777 -s /tftpboot
  3. Exit VI
We also need to edit the /etc/remote file as follows.
- # vi /etc/remote
- Add the following lines at the end of the file:
  
  #cuwin node stuff
  cuw0:dv=/dev/cuad0:br#19200:pa-none:dc:
Reboot and Check
1. Reboot the computer: $ shutdown -r now
2. When the computer reboots, you will want to run the following commands:
  - # dhcpd &
  - # pgrep inetd
    Entering the last code should give you another number. If it doesn't, you tftp service is not running and you should revisit step 2B.
  - # pgrep dhcpd
    Entering the last code should give you a number. If it doesn't, your dhcpd.conf file needs to be reviewed.

Proceed to Step 3

Flashing Your 4526 Soekris Node: Step 3

Step 3: PXE Boot the Node
[You will need root privileges for this step.]

Plug the crossover cable into your computer's Ethernet port and the "Data" port on the POE injector. Make sure that the POE injector has power [there should be a green light on top to indicate that it has power]. Now plug the null-modem cable into the serial port on your computer and the serial port on the Soekris board.

Now you will need to run the tip program as root in order to update the BIOS of the node.

Enter su and the root password when prompted.
Now you will need to access the node console. At the command prompt, enter: # tip cuw0
You will need to reboot your node.

A successful PXEboot looks like this:

Pre-boot eXecution Environment  PXE-2.0 (build 082)
Copyright (C) 1997-2000  Intel Corporation
 
 
CLIENT MAC ADDR: 00 00 24 C3 A8 40
CLIENT IP: 192.168.1.9  MASK: 255.255.255.0  DHCP IP: 192.168.1.101
GATEWAY IP: 192.168.1.101
 
 
>> NetBSD/i386 PXE Boot, Revision 1.1
>> (rgmussel@cuw.ojctech.com, Sun Apr 23 07:50:45 CDT 2006)
>> Memory: 582/64512 k
Press return to boot now, any other key for boot menu
Starting in 0
PXE BIOS Version 2.1
Using PCI device at bus 0 device 6 function 0
Ethernet address 00:00:24:c3:a8:40
net_open: client addr: 192.168.1.9
net_open: subnet mask: 255.255.255.0
net_open: net gateway: 192.168.1.101
net_open: server addr: 192.168.1.101
net_open: file name: tftp:netbsd.gz
2159776+33612688-

Proceed to Step 4

Flashing Your 4526 Soekris Node: Step 4

Step 4: Upgrade the node

Log into the node using the root password. [usually "changeme"]
You need to change a few variables to enable the upgrade.
- > stty <space> erase Control-v <Backspace>
- > ifconfig sip0
 Find a line that looks something like this:
 inet 10.168.64.254 netmask 0xffffff00
- > ifconfig sip0 inet 10.168.64.254 netmask 0xffffff00 -alias
- > ifconfig sip0
 You should now see a line that looks something like this:
 inet 192.168.1.7 netmask 0xffffff00 broadcast 192.168.1.255.
- Ping the server to verify your connection:
 > ping 192.168.1.101 -c 5
 You should see lines like this:
 64 bytes from 192.168.1.101: icmp_seq=0 ttl=64 time=0.656 m

Let's upgrade the node:

> upgrade -f -C blah@192.168.1.101:/tftpboot/upgrade.tgz
[where blah is your user name.]
If that is successful, you should see something like this:

 
fdisk: DIOCGDEFLABEL: Invalid argument
fdisk: DIOCGDINFO: Invalid argument
Disk: /dev/rwd0d
NetBSD disklabel disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
total sectors: 125056

BIOS disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
total sectors: 210453442400

Partition 0:
NetBSD (sysid 169)
     start 32, size 62512 (31 MB, Cyls 0-488/2/17)
Making partition 0 active.
Preparing for upgrade on /dev/wd0e.
/dev/rwd0e: 30.5MB (62512 sectors) block size 8192, fragment size 1024
using 4 cylinder groups of 7.63MB, 977 blks, 1920 inodes.
super-block backups (for fsck_ffs -b #) at:
32, 15664, 31296, 46928,
Installing the upgrade.

Because you won't be an authenticated user, you will be prompted to verify that you want to continue. Answer yes.

The authenticity of host '192.168.1.101 (192.168.1.101)' can't be established.
DSA key fingerprint is a8:75:fe:7d:46:b7:a8:05:65:77:43:7a:67:e7:a4:fc.
Are you sure you want to continue connecting (yes/no)?yes

You will also need to enter your password on the freebsd computer.

Warning: Permanently added '192.168.1.101' (DSA) to the list of known hosts.
Password:
100% |*************************************|  4041 KB  237.68 KB/s    --:-- ETA
Updating etc/fstab
Updating primary bootstrap
Updating active partition
Disk: /dev/rwd0d
NetBSD disklabel disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
total sectors: 125056

BIOS disk geometry:
cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
total sectors: 210453442400

Partition 1:
NetBSD (sysid 169)
     start 62544, size 62512 (31 MB, Cyls 488/2/17-977)
Making partition 1 active.
Copying existing /etc/cuw_config.
Upgrade complete (/dev/wd0e).
 #

After that runs, type the following at the command line to reboot the node:
$ reboot

You will want to exit Tip now. Do that, you should first unplug the serial cable, then enter the following command: <Ctrl>~D [i.e. <Ctrl>-<Shift>-~, release the keys, and then <Ctrl>-<Shift>-d].

Congratulations! If you made it this far, you are ready to put the node on the roof and get to work!

Build and Install on a Soekris 4526 using Arch Linux

INSTRUCTIONS FOR PXEBOOT OF 4526 SOEKRIS BOARD WITH ARCH LINUX

*NOTE* Some of these instructions are specific to Arch Linux. If you would like to contribute instructions for other Linux distributions, please email them to us.

A text version of this document is available here: pxeboot4526archlinux.txt

SOFTWARE REQUIREMENTS:

A current Linux distribution (This tutorial was devised and tested on ArchLinux (http://www.archlinux.org)
GCC 3-4 and G++ 3-4 (and their dependencies)
Subversion (and its dependencies)
Wget
Minicom
Bunzip2

HARDWARE REQUIREMENTS

One Ethernet port
One serial port [We found that a USB-RS232 Serial Connector worked as well.]
One crossover cable
One cat5e cable
One null-modem cable
One power-over-ethernet injector [POE]

CONVENTIONS

Three different command line prompts will be used: # indicates the normal user; $ indicates the root user; and > indicates a prompt from the node. The end of all command line entries are signaled by the following notation: <enter>. All key strokes (e.g. Shift, Control, Enter, etc...) will use the following syntax: <key> [e.g. <Shift>, <Ctrl>, etc.].

VI TUTORIAL

For text editing, we use VI, but feel free to use whatever text editor you like. Some useful vi commands:
i - enter the edit mode to change text
<Esc> - to escape the edit mode
:q! - to exit without saving changes
<Shift>zz - to save changes and exit

STEP 1: GETTING THE SOFTWARE IMAGE

The easiest way to get the software for your node is to go to http://cuwireless.net/node/208. You will need to download the pxeboot_ia32_com0.bin, netbsd.gz, and the update files. Download them and place them in your /var/tftpboot directory. [Directions for making the /var/tftpboot directory are in step 1B10.] Skip to step 1B12.
The best way to get the software is to compile it yourself. This is why we include GCC as a required package. These steps will help you compile the software from scratch. Be sure that you follow these directions as yourself, not as root.
1. In this step, you will make a directory named "cuwin" in your home directory directory. At the command line, enter the following:
 # mkdir ~/cuwin
2. Place the latest version of the CUWiN software in your home directory by typing:
 # svn co http://svn.cuwireless.net/svn/cuw/trunk
3. Now we need to place the latest version of the NetBSD sources in your home directory. Enter:
 # wget http://superb-west.dl.sourceforge.net/sourceforge/wireless/cuwin-0.6.0-netbsd-src.tar.bz2
4. Decompress the NetBSD files by entering the following at the command prompt:
 # tar -jxvf cuwin-0.6.0-netbsd-src.tar.bz2
5. Move these directories and their contents to the directories you just created in 1.B.1:
 1. # mv trunk cuwin/cuw-trunk
 2. # mv cuwin-0.6.0-netbsd-src cuwin/scratch
6. Make your .mkstabootrc file in your home directory and edit it:
 1. # vi .mkstabootrc
 2. Type 
 3. Enter the following, where MACHINE_ARCH equals the processor architecture of your computer(i386 should be fine for most people):
```
 BUILDDIR=$HOME/cuwin/scratch
 SRC=$HOME/cuwin/scratch/src
 LOWER_FAT=yes
 MACHINE_ARCH=i386
```
 4. When you have typed the above information into the file, press <Esc>.
 5. Exit the text editor by using the following command:
 :wq
7. To fix a difference in syntax between Linux and *BSD, you may have to do the following:
 1. Edit the build.sh file in the NetBSD "src" directory
 # vi ~/cuwin/scratch/src/build.sh
 2. Find the line that reads "TOP=$(/bin/pwd -P 2>/dev/null)" by typing /pwd followed by pressing <Enter>
 3. Type 
 4. Edit the line to read "TOP=$(/bin/pwd 2>/dev/null)"
 5. Edit the text editor by typing :wq
8. Move to the bootimage directory in the CUWiN source files by entering the following at the command line:
 # cd ~/cuwin/cuw-trunk/src/boot-image
9. Start the compile process [This step takes a couple of hours to complete, so feel free to make other plans for about three hours.]:
 # ./buildmd
10. Type "ls" at the command line. You should be able to find a file that has something similar to the following name:
```
 23-April-staboot.md 
```
 If you do, you have successfully compiled the software. If not, don't be discouraged, that happens. We are working on a Troubleshooting Guide, but that may not be available for a few months. In the mean time, you should just use the sources provided on the website listed in 2.A.
11. Assuming that you have successfully compiled the software, copy two files to the /var/tftpboot directory. The first command will create the /var/tftpboot directory. The next two commands will copy the required files.
 1. # mkdir /var/tftpboot
 2. # cp ~/cuwin/cuw-trunk/src/boot-image/23-April-staboot.img /var/tftpboot/netbsd
 3. [Because this command line is so long, it has been placed on the next line.]
 # cp ~/cuwin/scratch/O/sys/arch/i386/stand/pxeboot_com0_19200/pxeboot_ia32_com0.bin /var/tftpboot/pxeboot_ia32_com0_19200.bin
12. Before we build the update file, we need to change the user accounts. To do this, we are going to need to move into the boot-image directory and change the passwords for root. Then we can add other users. Before you begin this step, be sure that you know what you want to make the root password and which new users you will want to add.
 1. # cd ~/cuwin/cuw-trunk/src/boot-image
 2. # ./cw_passwd ./pwds root
 3. The previous command prompts you for the new root password.
 4. # ./cw_passwd ./pwds newusername
 5. The previous command prompts you to enter the password for the account "newusername".
13. Now we need to build an update file. First, you will return to the /boot-image directory. Then you will build the upgrade. Then you will copy the upgrade to the /var/tftpboot directory.
 1. # cd ~/cuwin/cuw-trunk/src/boot-image
 2. # ./buildelanup install
 3. # cp upgrade.tgz /var/tftpboot/.
14. Change directories to the /var/tftpboot directory by entering
 # cd /var/tftpboot
15. Compress the netbsd file by entering the following:
 # gzip netbsd
16. Change the ownership and permissions of the /var/tftpboot directory and the files you just copied into /var/tftpboot by entering the following commands:
 1. # chown -R nobody:nobody /var/tftpboot
 2. # chmod -R 777 /var/tftpboot

Step 2: Setup the Network Boot

Get the most recent BIOS update from Soekris.
1. Open your web browser and go to the following page: http://www.soekris.com/downloads.htm
2. Save the most recent version of the BIOS to the /var/tftpboot directory.
DHCP Server [You will need root privileges for this step.]
1. To find out if you have a DHCP Server running, type
 # ps wuax | grep dhcp
 If there is something on the next line (e.g. /etc/init.d/dhcpd or /usr/sbin/dhcpd), you have a DHCP Server already installed and running and you should proceed to Step 2.B.4.
2. To find out if you have a DHCP Server installed, type
 # find /etc /usr/local/etc -name '*dhcp*' print
 If you see a file named "dhcpd.conf", you have a DHCP Server installed and should skip to Step 2.B.4.
3. Install the DHCP Server by entering the appropriate installation command for your distribution:
 1. For ArchLinux:
 # pacman -Sy dhcp
4. At this point, you will need to configure your DHCP server. NOTE: MAKE SURE THAT YOU ARE DISCONNECTED FROM YOUR NETWORK! RUNNING THIS SERVICE MAY DESTROY YOUR NETWORK. Enter the following commands:
 1. # vi /etc/dhcpd.conf
 2. 
 3. Enter the following:
```
 subnet 192.168.1.0 netmask 255.255.255.0 {
 option routers 192.168.1.101;
 option subnet-mask 255.255.255.0;
 range 192.168.1.1 192.168.1.15
 }
 class "pxe-clients-ia32" {
 match if substring(option vendor-class-identifier, 0, 9) = "PXEClient";
 next-server 192.168.1.101;
 filename "pxeboot_ia32_com0_19200.bin";
 }
 class "netbsd-pxe-clients-ia32" {
 match if substring(option vendor-class-identifier, 0, 17) = "NetBSD:i386:libsa";
 next-server 192.168.1.101;
 filename "tftp:netbsd.gz";
 }
```
 4. <Shift>zz
5. Configure your Ethernet Device.
 1. Determine your Ethernet. When you use the following command, the item that says, "Link encap: Ethernet" is the Ethernet device [from here on, the Ethernet device will be indicated by dev0:
 # ifconfig -a
 2. Find out your IP address and subnet mask. The important line should look something like: inet 10.0.0.103 netmask 255.255.255.0 broadcast
 # ifconfig dev0
 3. Release and reset the current IP address by entering the following:
 1. # ifconfig dev0 down
 2. # ifconfig dev0 inet 192.168.1.101 netmask 255.255.255.0
 3. Now, if you enter "ifconfig dev0", you should see a line that reads:
```
 inet 192.168.1.101 netmask 255.255.255.0 broadcast 192.168.1.255 
```
TFTP Server: There are two different ways to do this. The first is to use either inetd or xinetd, and the second is to start the tftpd daemon standalone, either manually or with a script [You will need root privileges for this step.]
1. Now you need to edit the TFTP Server Configuration. TFTPD requires the INETD service. If you have inetd, you will need to edit /etc/inetd.conf.
 1. # vi /etc/inetd.conf
 2. Move to the line below and put the cursor on the "#". Press DEL to remove the comment mark.
```
 tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -U 777 -s /var/tftpboot 
```
 3. <Shift> zz
2. If you are using xinetd, you will have to create a file in your /etc/xinetd.d entitled "tftp"
 1. # vi /etc/xinetd.d/tftp
 2. Type 
 3. Insert the following in the file:
```
 service tftp
 {
 socket_type = dgram
 protocol = udp
 wait = yes
 user = root
 server = /usr/sbin/in.tftpd
 disable = yes
 }
```
3. The other method is to start tftpd manually:
 1. # ls /etc/rc.d/
 Where /etc/rc.d is your init scripts directory. (Possibly /etc/init.d/) If you see a file entitled in.tftpd, tftpd, tftp, or similar, then you can most likely start the daemon by typing at the prompt:
 # /etc/rc.d/tftpd start
 2. Otherwise, you can most likely start tftp manually
 # /usr/sbin/in.tftpd -l -U 777 -s /var/tftpboot
 or
 # /usr/libexec/tftpd -l -U 777 -s /var/tftpboot
Allow the system to run TFTP and DHCP daemons. [You will need root privileges for this step.]
1. Edit your /etc/hosts.allow file
  1. # vi /etc/hosts.allow
  2. Add the line in.tftpd:all
  3. Type :wq

Step 3: Update the BIOS and flash the node [You will need root privileges for this step.]

Restart network services by entering the following commands (Depending on your distribution, your initscripts directory may be something different from /etc/rc.d/, like /etc/init.d/ or /usr/local/etc/rc.d/):
1. # /etc/rc.d/dhcpd start
2. # /etc/rc.d/tftpd start
3. # /etc/rc.d/sshd start
Plug the null-modem cable into the serial port on your computer and the serial port on the Soekris board. If you do not have a serial port on your computer, you may need to use a USB-to-serial adapter cable. Now, plug the Crossover Cable into your computer's Ethernet port and the "Data" port on the POE injector. Make sure that the POE injector has power [there should be a green light on top to indicate that it has power].
Now you will need to run Minicom in order to connect to the node over the serial line
1. Enter su and the root password when prompted.
2. Now you will need to access the node console. At the command prompt, enter: # minicom
3. Hit the key combination Ctrl-A Z to bring up the options screen, and select "Serial Port Setup." The correct settings BP/Par/Bits settings are 19200 8N1, and all flow control should be turned off. The serial device is the device file of your serial port. If you're using USB-to-serial, it will most likely be something like /dev/tts/USB0.
4. Break into the comBIOS monitor with <Ctrl>-P at the beginning of the boot process. [This may happen quickly when the node is started, so be prepared.]
5. At the > prompt, enter the following commands:
 > download <enter> ~C lsx b4501_xxx.bin
 [where xxx is the number of the Soekris BIOS upgrade; note: the ~C can be a bit tricky. Think of it as follows: Press and hold the <Shift> key, then press <~> and then <c>]
6. When you are returned to the > prompt, enter: > flashupdate
7. When the update is complete, you will need to reboot. Do that by entering: > reboot
Set the node to PXE boot.
1. Break into the comBIOS monitor again with <Ctrl>-P.
2. At the prompt, enter: > set bootdrive=f0 80 81 ff
3. Enter: > reboot

At this point, your node should PXEboot from your computer. A successful PXEboot looks like this:

       Pre-boot eXecution Environment  PXE-2.0 (build 082)
       Copyright (C) 1997-2000  Intel Corporation


       CLIENT MAC ADDR: 00 00 24 C3 A8 40
       CLIENT IP: 192.168.1.9  MASK: 255.255.255.0  DHCP IP: 192.168.1.101
       GATEWAY IP: 192.168.1.101


       >> NetBSD/i386 PXE Boot, Revision 1.1
       >> (rgmussel@cuw.ojctech.com, Sun Apr 23 07:50:45 CDT 2006)
       >> Memory: 582/64512 k
       Press return to boot now, any other key for boot menu
       Starting in 0
       PXE BIOS Version 2.1
       Using PCI device at bus 0 device 6 function 0
       Ethernet address 00:00:24:c3:a8:40
       net_open: client addr: 192.168.1.9
       net_open: subnet mask: 255.255.255.0
       net_open: net gateway: 192.168.1.101
       net_open: server addr: 192.168.1.101
       net_open: file name: tftp:netbsd.gz
       2159776+33612688-

Update the node

Log into the node using the root password: changeme
Enter: # stty <space> erase Control-v <bksp>
Enter: # fixlabel
Enter: # ifconfig sip0
Find a line that looks something like this:
```
 inet 10.168.64.254 netmask 0xffffff00 
```
Enter:
# ifconfig sip0 inet 10.168.64.254 netmask 0xffffff00 -alias
Enter: # ifconfig sip0
You should see a line that looks something like this:
```
 inet 192.168.1.7 netmask 0xffffff00 broadcast 192.168.1.255 
```
Ping the server to verify your connection:
# ping 192.168.1.101 -c 5
You should see lines like this:
```
 64 bytes from 192.168.1.101: icmp_seq=0 ttl=64 time=0.656 m 
```

Enter:
# upgrade -f blah@192.168.1.101:/var/tftpboot/upgrade.tgz
where blah is your user name. If that is successful, you should see something like this:

       fdisk: DIOCGDEFLABEL: Invalid argument
       fdisk: DIOCGDINFO: Invalid argument
       Disk: /dev/rwd0d
       NetBSD disklabel disk geometry:
       cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
       total sectors: 125056

       BIOS disk geometry:
       cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
       total sectors: 210453442400

       Partition 0:
       NetBSD (sysid 169)
            start 32, size 62512 (31 MB, Cyls 0-488/2/17)
       Making partition 0 active.
       Preparing for upgrade on /dev/wd0e.
       /dev/rwd0e: 30.5MB (62512 sectors) block size 8192, fragment size 1024
        using 4 cylinder groups of 7.63MB, 977 blks, 1920 inodes.
       super-block backups (for fsck_ffs -b #) at:
       32, 15664, 31296, 46928,
       Installing the upgrade.
       The authenticity of host '192.168.1.101 (192.168.1.101)' can't be established.
       DSA key fingerprint is a8:75:fe:7d:46:b7:a8:05:65:77:43:7a:67:e7:a4:fc.
       Are you sure you want to continue connecting (yes/no)?yes
       Warning: Permanently added '192.168.1.101' (DSA) to the list of known hosts.
       Password:
       100% |*************************************|  4041 KB  237.68 KB/s    --:-- ETA
       Updating etc/fstab
       Updating primary bootstrap
       Updating active partition
       Disk: /dev/rwd0d
       NetBSD disklabel disk geometry:
       cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
       total sectors: 125056

       BIOS disk geometry:
       cylinders: 977, heads: 4, sectors/track: 32 (128 sectors/cylinder)
       total sectors: 210453442400

       Partition 1:
       NetBSD (sysid 169)
            start 62544, size 62512 (31 MB, Cyls 488/2/17-977)
       Making partition 1 active.
       Copying existing /etc/cuw_config.
       Upgrade complete (/dev/wd0e).
        #

After that runs, type the following at the command line to reboot the node: shutdown -r now

When you are finished, you will want to exit Minicom. Do that by typing Shift-Q.

Technical Documentation

HSLS

HSLS is the routing protocol that has been developed by CUWiN based on a technical paper from BBN. This routing protocol is specially designed to be scalable for ad-hoc mesh wireless networks. The HSLS daemon communicates with the kernel's routing tables via the Zebra daemon which provides some future portability to other operating systems.

The HSLS README explains how to invoke the HSLS daemon. On the standard CUWiNware image hslsd is started with these parameters.

CUWiNware has specified an HSLS packet format.

The ETX Protocol

Introduction

This protocol is intended to provide the expected transmission count (ETX) routing metric based on the work of the M.I.T. Computer Science and Artificial Intelligence Laboratory [1], and be used between routers on ad hoc wireless networks.

Protocol Description

The Expected Transmission Count (ETX) path metric is a simple, proven routing path metric that favors high-capacity, reliable links. The ETX metric is found from the proportion of beacons sent but not received in both directions on a wireless link.

Each participant router broadcasts a beacon to its one hop neighbors at a configurable interval. Each beacon contains the protocol version, flags and a sequence number. The beacon contains a list of the router's one hop neighbors. For each neighbor a history of whether or not the beaconing router received a beacon from this neighbor is included. The history includes the last BITFIELD_LENGTH (32) of this neighbor's beacon intervals. An optional set of extensions may be included. No extensions exist at this time.

At a configurable interval, the cost of the link associated with each peer is computed based on expected probability of beacons to be transmitted and received. See Receiving Beacons and Computing Link Costs.

Beacon Flags

ETX_F_INIT - this flag MUST be set for the first BITFIELD_LENGTH transmissions made by an ETX router. It is used to distinguish sequence number wrap-around. See Sending Beacons and Receiving Beacons.

ETX_F_EXTENSIONS - indicates that a beacon contains extensions. If set, each peer block in the beacon MUST contain at least one extension block. See Extensions.

ETX_F_SUSPEND - May be set by a router to indicate that it will be out of communication for some length of time. If set, the beacon MUST contain the 32-bit time of return field. See Transmitting Beacons.

Receiving Beacons

Upon receiving a beacon it is implicitly required that certain data must be available in order for the router to conform to the protocol. For example it is necessary to have accurate expectations regarding the arrival of future beacons from this neighbor.

When beacons are received from a previously unheard of neighbor, the data for the new neighbor are initialized appropriately. It is added to the neighbor list and the contents of the bit field are processed in full (dependent on the ETX_F_INIT flag).

If the beacon is from a neighbor that is already known, its sequence number is compared to the sequence number of the last beacon received from this neighbor. If the sequence number of the received beacon is less than or equal to the most recently received sequence number these statistics are recorded for MIB. If the sequence number of the received beacon is within BITFIELD_LENGTH intervals of the last heard sequence number, the previous bits of the affected bits in the bitfield are set accordingly.

The sequence number of the incoming beacon is compared to the currently expected sequence number from this neighbor. If it is less or more than expected these statistics are recorded for MIB. The bitfield is updated with the available data.

A sequentially valid beacon is processed as follows. Each sequence number that has passed since the last beacon received from this neighbor it is inferred that no beacon was received. Beacon received is set for the current beacon interval. This updated bitfield is used to recompute the probability of beacons being received from this peer. See Computing Link Costs.

Additionally, we expect that the received beacon will contain a peer block for the localhost. The bitfield from this block is used to recompute the probability of beacons being transmitted to this peer. See Computing Link Costs.

Transmitting Beacons

At each beacon interval, the router must assemble and broadcast a beacon to its one-hop neighbors. The sequence number MUST start at 0 and be incremented by exactly 1 with each beacon transmitted. The ETX_F_INIT flag MUST be set for the initial BITFIELD_LENGTH beacons transmitted.

For each known neighbor a valid bitfield must be determined. If a beacon was expected but not received, the bitfield must be updated accordingly (an expected and received beacon will have already been processed). If this neighbors beacon interval
is longer than the local beacon interval, the bitfield should not be updated until the neighbor beacon interval has expired. If the neighbor interval is shorter than the local interval, the extra bits of the bitfield must be evaluated (if these beacons have been received, they will already be set correctly).

Computing Link Costs

Periodically, the data of known peers is used to compute the cost associated with the link to that peer. To do so, smoothed probability ratings of transmission to and reception from each peer are used. Let 'srxp_k' and 'stxp_k' represent these respective probabilities for some peer at interval 'k'.

The cost of the link with this peer is computed as

cost_k = 1 / (srxp_k * stxp_k)

The probability of receiving from this peer is computed as

	Let srxp_0 = rx_0
	    srxp_k = h * srxp_k-1 + (1-h) * rx_k 
	where rx_k = 1 if a beacon was received, 0 otherwise.

The values of rx_k are read from the bitfield associated with this peer. 'h' is a configurable value that specifies the influence of a single interval on the probability.

In the event that either srxp_k = 0 or stxp_k = 0, the cost is set to 1.

The probability of transmitting to this peer may be computed in the same manner, in this case the values of tx_k are read from the peer block corresponding to the localhost in the beacon received from this peer.

It is possible that no tx data is available for a number of reasons:

a beacon was not received from this peer. A configurable tentative value is used for tk_k. If this beacon is received late, the actual value must be substituted in at that time.
the received beacon did not contain a peer block referring to the receiver. The value of tk_k = 0 is used.
the beacon's ETX_F_INIT flag is set and the 'k' interval is not yet valid (as determined by the sequence nubmer). This interval should not be included in computing the link cost.

For efficiency it is not desirable to recompute the probabilities at every

CUWIN Manual

Preface: Building Your CUWiNware Wireless Network

Index

Hardware Design and Construction

Introduction

Node Placement

Isolated Areas

Coverage Requirements

Supported Chipsets

Chipsets

Links

Constructing a Rugged Outdoor Node

Single Board Computer

Links

The Wireless NIC

Links

The Enclosure

Links

The Antenna

Links

Mast and Mounting Hardware

Grounding and Lightning Arrest

Outdoor Cat-5e Cable and Power over Ethernet Injector

Information on Battery/Solar Powered WAPs

Constructing a Low-Resource Node

CPU and Motherboard Considerations

Other Considerations

Console

Antenna Options

Motherboard/CPU Considerations

Other Node Possibilities

User's Guide

Introduction

Download Software

Compact Flash Images

ISO (CD-ROM)

Updater Tarball

Installing the Software

PXE Booting

Installing from an ISO

Online Updates

Network Topology

Wired Interface

Wireless Interface

Channel and Mode Selection

Routing

Scalability: Maximum Network Size

Exploring Your Node

Remote Shell

Changing Your Root Password

Nodeconfig: A Web Interface

Route Visualization

Configuring a node

Troubleshooting Guide

How-to Guides

Flashing a Meraki Mini

Flashing the Meraki Mini with NetBSD

How-to Build a CUWiN Metrix-based Node

Antenna

Metrix Box

Weatherizing Connections:

Assembling Metrix Box Mounting Hardware:

Finishing Up:

Upgrading a Node using FreeBSD

Upgrading a Soekris 4526 using FreeBSD

Software Requirements

Hardware Requirements

Conventions

VI Tutorial

STEP 1: GETTING THE SOFTWARE IMAGE

Step 2: Start SSHD and login to node [You will need root privileges for this step.]

Flashing a Soekris 4526 Node using FreeBSD: Introduction

Software Requirements

Hardware Requirements

Conventions

VI Tutorial

Flashing Your 4526 Soekris Node: Step 1

Flashing Your 4526 Soekris Node: Step 2

Step 2: Setup the Network for PXE Booting

Flashing Your 4526 Soekris Node: Step 3

Step 3: PXE Boot the Node
[You will need root privileges for this step.]