view · edit · print · history

UpSlug2? is designed to be portable.

Alas, upslug2 does things which, given current APIs?, are inherently not portable. These things are abstracted into the C++ class Wire and are implemented, for different operating systems, in files with names like:


At present there are two implementations. linux_wire.cc should work on any operating system which supports packet(7) as documented for Linux. pcap_wire.cc should work for many, but not all, operating systems which support libpcap. Linux supports libpcap and the code compiles, but it does not work.

The basic requirements of uplsug2 are as follows:

  1. The wire: the NSLU2 upgrade protocol is defined only for ethernet and requires a way to send packets with protocol number 0x8888 to the NSLU2. At present (and probably for all time) the implementation assumes an Ethernet (IEEE 802) network which can send ethernet packets to the NSLU2 to be upgraded.
  2. Security: a way to securely access an ethernet device capable of sending these packets to the NSLU2. The implementation assumes POSIX 1003.1 and uses seteuid in a POSIX conformant way to temporarily assert root privilege while accessing the ethernet device. If you need to change this you will have to edit the main program, upslug2.cc as well as the implementation of Wire.
  3. Raw ethernet packets: a way to send a raw (OSI layer 2) packet to the NSLU2.

So far as I can see it is not necessary to understand what OSI layer 2 is - certainly I don't. It is sufficient to understand that the aim is to generate an IEEE 802 (ethernet) packet with the following properties:

  1. The destination is the MAC address of the NSLU2
  2. The source is the MAC address of the machine sending the upgrade (and this must be specified correctly - if you succeed in leaving out the information the gates of slug hell are opened and packets pour out without limit).
  3. The protocol is 0x8888 (chosen, apparently, because it obviates the need to byte swap the value).

Even this level of understanding is not necessary - the linux_wire.cc and the pcap_wire.cc contain enough copiable code for this code to be portable to any platform with little understanding and a small, but significant, amount of effort.

Getting started

Try it. It may work. If it builds try the commmand upslug2, possibly with the name of an ethernet device on the --device option (use ifconfig to find the devices). If this returns the information about all the NSLU2 machines in upgrade mode (it is well worth trying with more than one in upgrade mode on the same network) and the command only outputs the addresses once then it almost certainly works.

When it doesn't work

Make sure that there is some way on your chosen operating system of sending a raw ethernet packet with an arbitrary (effectively user defined) protocol. If there isn't you can't use the machine running the hardware to upgrade an NSLU2 - you must be able to send and receive ethernet packets with fixed MAC addresses and protocol 0x8888.

If libpcap is implemented on your operating system there is almost certainly a way of doing it. You may need to look at the source of libpcap for your OS.

Security problems

Try removing the class EUID from the Wire implementation and the POSIX geteuid and getuid calls from upslug.cc - you should then also be able to remove the #include of unistd.h from the relevant files.

On sensible operating systems security is configured using capabilities (or privileges or whatever the OS implementors chose to call them). Then you simply add the ethernet device access capability. For testing purposes it is fine to add more capabilities than you need, but there are security implications in installing upslug2 with such capabilities.

uplsug2 reads arbitrary files and sends them over the network. Therefore if you configure an upslug2 implementation to allow (for example) 'Administrator' access you have given away access to everyone's files. The hokey POSIX 1003.1 seteuid stuff avoids this by only asserting administrator (root) privilege when it does network stuff.

Packet problems

Most likely you will need to re-implement class Wire for your operating system. This is not a big deal if it is possible. Copy linux_wire.cc and edit this.

Use linux_wire.cc, not pcap_wire.cc, because the Linux implementation is closer to the raw ethernet. All it really does is fabricate the data portion of a packet then send it out on the ether.

Examine the pcap_wire.cc implementation to find the exact byte level format of the Ethernet packet - the Linux interface builds this in the kernel, the libpcap implementation builds it in memory.

Building a GUI

Building a GUI interface for upslug2 is a relatively easy but immensely fulfilling task.

Simply replace upslug2.cc with a 'main program' which presents the interface implemented as a command line (using getopt(3)) in upslug2.cc as a GUI. The exception handling in upslug2.cc should be implemented by error boxes - probably using the generic easily integratable exception handler provided by your chosen GUI.

The Upgrade function in upslug2.cc can simply be copied, along with the relatively short blocks of code which invoke it.

The progress bar can, initially, be left out by commenting out the fprintf statements in the upslug2.cc implementation, however the upslug2_progress.h template is intended for GUI use as well and, since every GUI has a sophisticated yet easy to use progress bar, if nothing else, there should be no problems.

The remainder of upslug2.cc is boilerplate code which, as we all know, modern GUIs? make trivial.

Thankyou for volunteering.

view · edit · print · history · Last edited by jbowler.
Originally by jbowler.
Page last modified on September 04, 2005, at 07:38 PM