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.
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 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 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.
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.
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).
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.
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.
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:
(WARNING, THIS WILL MODIFY YOUR PARTITION TABLE)
# fdisk -af -0 wd0
# reboot
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.
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.
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.
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.
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.
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.
So you just got your node running. You think. How can you tell what is going on in your node?
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.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.
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.
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.
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:
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.
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 -hnetstat -rn -f inetifconfig -avping -n google.comtraceroute -n google.comThe following is a list of important files that you will want to use the less command to look at:
less /var/db/linkstatesless /var/log/daemon*less /var/log/messages*To see what Zebra is up to:
telnet localhost 2601password: wirelessshow ip route