Welcome to the fbled README

This project aims at providing an open-source daemon to update the front-panel
LEDs of the Watchguard Firebox II and Firebox III. These boxes are basically PC-
based appliances based on the x86 architecture. They feature 3 10/100 Ethernet
ports and a programmable LED panel.

The home of this code is
 
                              https://github.com/fmertz/fbled

Watchguard and Firebox are used here for identification purposes, and are no
doubt the property on their owner. This project has no connection whatsoever
with the manufacturer of the appliances. Other trademarks are referred to for 
identification as well.

Of direct interest for this project, these boxes feature a front panel with a number
of programmable LEDs. The LEDs are grouped in 3 stacks and a triangle. There is
a stack for specific statuses (SYS A, SYS B, ARMED, DISARMED and POWER), a stack
of 8 LEDs for LOAD and another stack of 8 LEDs for Traffic. The Triangle (meant to
have each vertex for an Ethernet port) has LEDs at each vertex, plus 2 LEDs in
each direction from all vertices.

These white LEDs can only be controlled as on or off, but can be controlled
individually. They are already behind colored masks, so they appear colored
yellow, green or red already.

The idea of the fbled project is to be able to walk up to one of these boxes and
have a sense of what the machine is up to.

The code is logically separated into a Driver and a Client. The Driver is
responsible for updating the LEDs based on input parameters, and deals with
low-level I/O ports. The driver might be reimplemented as a real Linux driver/
module at a later point. The Client is responsible for gathering the live values
from the running system, parse them, normalize them, then pass them to the
Driver.

From a development perspective, a choice was made early on to make it
available for others to use, study and hopefully contribute. It is clear that
fbled is meant for the x86 architecture only, but it is less clear what operating
system it could run under. Therefore, in the interest of portability across OS,
this project uses the Autotools. The idea is to have just one code base, and
be able to compile it under various combinations of operating system versions
and even different C libraries for various kernels. This is the part where it is
discovered that functions behave somewhat differently, whatever functions
return is structured differently, and the definitions needed to achieve the
result are placed in header files whose location vary. A great number of hours
are spent in the airgap between the meanings of similar and identical.

In order to assist with development, a mini emulator was coded. It simply
mirrors the LEDs in text on the command line. Once coded, this emulator
made it possible to compile and run fbled on several architectures. 

fbled is licensed under GPLv3, and is offered to others in the spirit of giving
something back to the free software movement.

USAGE:
fbled just runs. As any user-space process in need of control of individual I/O
port, it needs to be privileged, i.e. run as "root". This can be accomplished in
a number of ways:
- It can be started as a part of the boot process by init
- It can be started directly by the root user
- It can be stored on the file system with setuid-root, i.e. be owned by root,
  and have execution bits set to setuid. This way, it can be run by any user.
- If can be started with sudo, provided sudo is setup for the current user

OPERATING SYSTEM
Altogether, the appliance boots with a BIOS. The BIOS then boots off of IDE
storage. There is no special boot locking, so anything that can be booted
could run. There are some online guides, but basically, the jumpers can be
setup so the internal flash drive is set as slave, and a replacement, larger
capacity primary drive is setup with an image of choice. CompactFlash is easy
and cheap to setup. Real hard drives could work, too.

Folks seem to be using Linux-based or BSD-based distributions:

Linux, with the GNU C Library glibc(or eglibc)/libc.so.6:
	Vyatta

Linux, with the uClibc C Library uclibc/libc.so.1
	Open-WRT
	DD-WRT

FreeBSD:
	pfSense
	m0n0wall

ARCHITECTURE
Obviously, fbled is coded to update the actual LEDS of the x86-based appliances
from Watchguard. Running fbled with the emulator is possible on other
architectures, though. fbled compiles and runs under Linux on ARM, SPARC, MIPS
and PowerPC. fbled is expected to compile and run on non x86 FreeBSD as well.
Conversely, fbled can run the emulator on x86 as well. In order to do so, fbled
needs to be compiled with the LED_EMU symbol defined.

Folks are encouraged to use the wiki to share their experience and help others

                                      https://github.com/fmertz/fbled/wiki

LINUX NOTES:
Load: getloadavg() from the C library, except uClibc reads from /proc/loadavg.
Traffic: getifaddrs() from the C library. except uClibc reads from /proc/net/dev
Triangle Tips: Netlink socket to kernel for ULOG messages
	In order to work, the firewall needs to be modified. When you want to have a
	triangle tip blink for some condition, the conditions need to be configured in
	the firewall, and when the conditions match, the packet need to be sent to 
	ULOG. ULOG then multicasts the packet over netlink, and fbled can get it.

	Example: Blink the triangle tip when someone attempts to login over ssh

			iptables -I INPUT -p tcp --dport 22 -j ULOG --ulog-cprange 1

	Note: This target changes nothing in terms of accepting/rejecting/dropping
		the packet. ULOG does the job and continues the chain.

Triangle Arrows: <FUTURE> Light up based on the number of connections as
	per the connections table conntrack.


FREEBSD NOTES:
Load: getloadavg from the FreeBSD C Library
Traffic: getifaddrs from the FreeBSD C Library
Triangle Tips: packet capture of the pflog: device. pf can be configured to send
  packets to the log. fbled uses the pcap library to capture raw frames from the
  pflog: device where pf sent them, and report captures on the dc<x> devices
  to the right triangle corner.
Triangle: <FUTURE> Interface with pf (?)