UpSlug2? is designed to be portable.
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:
- 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.
- 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
- 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:
- The destination is the MAC address of the NSLU2
- 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).
- 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.
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.
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.
Try removing the
class EUID from the
Wire implementation and the POSIX
getuid calls from
upslug.cc - you should then also be able to remove the
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.
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.
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.
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.
upslug2.cc with a 'main program' which presents the interface implemented as a command line (using
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.
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.