IPv6 Introduction

First, the basics….

Understanding IPv6 networking may first come off as an extremely complicated endeavor however it’s not that much different from IPv4.  The biggest thing about IPv6 is the massive amount of IPs that are made available by the change in the network protocol.  To put it in perspective, the entirety of the existing IPv4 address space consists of approximately 4,228,250,625 addresses (from 0.0.0.0 to 255.255.255.255, or 255^4 including private network blocks and multicast addresses) An IPv6 network block (like the /64 network block that we’ll get from Hurricane Electric) contains  18,446,744,073,709,551,616 IPs.  The /64 network assigned to us from Hurricane Electric is only a minuscule fraction of the entire IPv6 address space.

An IP address in IPv4 uses four numbers in a dotted quad notation with numbers between 0 and 255, like 192.168.1.4 and will include a subnet mask like 255.255.255.0.  This is used to establish the “network” that an IP address is a member of. An IPv6 address is radically different, with 8 hexidecimal (from 0000 to FFF) numbers seperated by a colon (:), then following up with a subnet mask in CIDR notation. An example of an IPv6 address (in this case, ipv6.google.com) is 2001:4860:4002:0802:0000:0000:0000:1010.  Rather than spell all that out, you can use :: to represent one contiguous block of zeros, and leading zeros can be removed.  The formidable example address now becomes slightly less scary 2001:4860:4002:802::1010.  Another example of an IPv6 address in this “compressed” notation, would be the IP address for Facebook 2620:0:1cfe:face:b00c::3 (faceb00c, lol). Yet another funny IPv6 address is cisco.com, at 2001:420:80:1:c:15:c0:d06:f00d (c15co, f00d).

Some differences in IPv4 and IPv6

The biggest difference in IPv6 from a network standpoint is that it virtually eliminates the requirement for Network Address Translation.  Instead of proxying an IP address for multiple home networks/hosts, your IPv6 network is fully routable, meaning that you can access your home computer from the Internet without the need of using port forwarding or IP masquerading.  While you technically can NAT an IPv6 address, it’s no longer an absolute requirement for Internet access. Because the Internet can now access your network, it is especially important that your firewall is configured to deny incoming connections from the Internet and explicitly allow connections on an as-needed basis (like running a web server from home, etc..). We will establish a common ruleset later on, once we have completed the IPv6 configuration.

Another significant change in IPv6 is changes made to the DHCP protocol.  Instead of a DHCP server telling a host what the default gateway is for the attached network, the host will instead listen for a router advertisement and will use that in its internal routing table to know how to get to the public Internet.  This router advertisement is handled by radvd which announces the router’s IP address to the network.

A few things to consider

When World IPv6 Test Day was enacted and executed last June, many major websites went online and started offering IPv4 and IPv6 dual stack websites for the purpose of testing the world’s readiness for IPv6.  Many important things were discovered that day including the fact that most CPE devices (like Linksys routers, DSL and Cable modems and other devices) were not IPv6 compatible.  This was later broadened to include many Internet-connected devices like DVRs, Media machines and other devices were also not ready for IPv6. While some sites maintain IPv6 connectivity, once World IPv6 Test Day closed, so did many sites on IPv6 connectivity.

Before you start out on bringing IPv6 into your network, it is important to understand that IPv6 is still regarded as being an experimental protocol. Most of the sites you are used to won’t work in a pure IPv6 environment so we are going to set up a dual-stack network.  This means that you will be able to bring in IPv6 connectivity for IPv6 only sites and still be able to access your IPv4 sites just like your network has done in the past.

It is also important to realize that most embedded class devices will not use IPv6.  Devices like embedded media players, game systems, WiFi access points, printers and the like  may not support IPv6 even with firmware updates from the manufacturer.  Some devices may get support later on through vendor updates however many devices will probably not work.

At the very least you will learn a lot about IPv6 deployment, and you will have plenty of time to test your equipment prior to IPv6 becoming mandatory.

Enough of the theory already, Let’s get started.

In order to bring IPv6 into your home, we will be using an IPb6 tunnel provided by Hurricane Electric’s TunnelBroker.net service.  The service is free, and they provide you with a full /64 IPv6 network to play with.  In addition, they provide a certification service to test your IPv6 knowledge and skills once your IPv6 connectivity is up and running.  They give you a series of goals to accomplish even after your tunnel is up and you’re routing away and plus, it makes for great bragging rights.

In order to pull this off, you’ll need the following:

• PfSense 2.0 installed and working at the edge router on your network.
• A client computer for testing. ( Windows Xp, Windows Vista, Windows 7, Linux, etc..)
• Network switch, etc to make sure your client computer is connected to your router.
• A WAN Internet connection.  (DHCP, Static, PPPoE, etc does not matter as long as it’s broadband)

Please Note: Due to the fact that we are using git to sync experimental code, you cannot use pfSense Embedded.  I tried to find a way around this, but unfortunately even at the 4GB disk image size, I was never able to get it to fit and work.

The IPv6 configuration will be split up into six sections:

1. Configuring your existing pfSense router to sync up the latest IPv6 code.
2. Registering for an IPv6 Tunnel from Hurricane Electric.
3. Configuring pfSense for the tunnel, and DHCPv6.
4. Configuring workstations for IPv6.
5. Performing website testing

1: Sync up the latest IPv6 code

We’ll start off with our already established and running pfSense router. We will need to enable SSH on the router so we can get to the commandline.  This will be the only time you will need to access the commandline however I do recommend leaving it enabled so you can troubleshoot the IPv6 connection later on.

Start off by logging into the router.  Click on “System”, then “Advanced”.  Place a check box next to “Enable Secure Shell”.  If you don’t want to use the standard port of “22″, you can specify a different port below.  Scroll down to the bottom and hit “Save”.  Don’t worry about opening up your SSH port, this does not enable it on the WAN interface.

Enabling SSH in pfSense

Open up PuTTY and type in the IP address of your router.  If you specified an SSH port, be sure to specify it here as well.  For reference, here is my PuTTY configuration.

PuTTY settings

Upon successful connection, you will be prompted for a username.  Use the same username and password you use for the Web UI (admin/pfsense).  Once you have successfully logged in, you will get the same status screen like you see on the serial port showing the WAN and LAN statuses and a menu.

SSH menu

Select option 8 (Shell) and then type in the following command:  pkg_add -r http://ftp-archive.freebsd.org/pub/FreeBSD-Archive/ports/i386/packages-8.1-release/Latest/git.tbz  This will install GIT and perform the update.  This will take several minutes to download and install all of the packages required to perform the sync.

Installing Git

Once it has completed, type in exit or hit Ctrl-D to return to the SSH menu. At the SSH menu, type option 12 for the “pfSense Developer Menu”.

Accessing the Developer Shell

Now we will do the GIT sync. It is important to follow these instructions exactly as this is where the current running pfSense code is synched up with the pfSense developer code.    At the pfSense developer shell prompt, type in playback gitsync and hit enter.

Performing the Git sync

You will be prompted for the git branch to sync against.  Type in master and hit enter.  The next prompt will be for a custom RCS branch, just hit enter as we want to use the master branch only.  After you hit enter, the GIT Sync will begin.

Specifying the Git Branch

Ok, now here’s the kicker.  You must reboot! In the screenshot below, it looks like the upgrade has terminated and the device has restarted services however there are settings that have been changed that will only take effect on the next reboot.  The SSH Session should drop you back to the main SSH menu (what you saw when you initially logged in).  From here, select option 5 and answer y to reboot the device.

Reboot after your SSH session gets terminated

When the router has successfully rebooted, check that your Internet connection works and that all is working well.  The one thing that remains is to set up an ICMP rule to allow Hurricane Electric to ping your WAN interface.  This is required as part of the tunnel setup. Login to your router, click on “Firewall“, then “Rules“.  Click the “+” add button at the bottom and add a new rule.  Set the interface to WAN, protocol to ICMP, and ICMP Type to Any.  (This can be modified later).  For the source, set the type to “Single Host or Alias” and enter the IP address of 66.24.2.74.  This is the IP address of the IPv6 test endpoint.  Set the destination to “WAN Address” and lastly, enter a description.   Refer to the screenshot below if you need help.

WAN Ping rule

Now that everything is in place in your router, it’s time to get your tunnel.

2:Registering with Hurricane Electric

Now that our router is prepped for the IPv6 installation, it’s time to register the account with Hurricane Electric.  Head on over to tunnelbroker.net and register an account.  Once you’ve registered the account, you will get an email with the account information and a validation link.  After you validate, click on the “Create Regular Tunnel” on the left hand sidebar and you will be provided a form similar to the one in the screenshot below.  Be sure to select an endpoint that is as geographically close to you as possible or let the tool recommend the closest endpoint.  (Note: Hurricane Electric allows you to create up to five tunnels. If this is your first tunnel, you will not see the “You currently have 1 of 5 tunnels” message.)  Type your WAN IP address into the “IPv4 Endpoint” field, select the endpoint, then scroll down and hit “Create Tunnel”.

Hurricane Electric Tunnel Setup

After your tunnel has been successfully created, you will get a page that shows your tunnel information.  At the bottom of the page, you will notice that the rDNS delegation fields are blank. Click the “delegate to dns.he.net” link to autofill the reverse nameservers with Hurricane Electric’s default nameservers.  Click “Save” to commit the changes, then print this page. You will need it for the pfSense page.  Keep in mind that the tunnel IP address and the Routed /64 are off by one digit. This will be important later on.

Tunnel Information Page

If you are on a dynamic IP connection (DSL, Cable Internet, FiOS, etc…), there’s one more thing you need to be aware of.  Should your WAN IP change, you will need to update your tunnel. When you login to Hurricane Electric, you will get a page similar to the below, showing all of the configured tunnels on your account.

Tunnel List Page

To edit the tunnel, click on the tunnel name and you’ll be taken to the Tunnel Information page.  Click on the Client IPv4 address and make your IP change then simply click elsewhere on the page (not on a link) and wait for the text field to turn back to a link.  If it does not, it will provide an error message indicating the error (usually that it can not ping the WAN).

WAN IP Setup Error

3: Configuring pfSense

Building up our tunnel endpoint

Note:  From here on out, I will be using the example IPs of 2001:470:1234:5678:: for the IPv6 tunnel and 2001:470:1234:5679:: for the Routed /64.  In your tunnelbroker.net configuration, you should have a similar offset (your tunnel is one IP less than your routed netblock).  Please keep this in mind as we go through the next steps as you can not get the two confused.

We have a synched router and we have our tunnel configuration. Now it’s time to start configuring pfSense.  We will start out by building out the tunnel endpoint. Login to the router and click on Interfaces > Assign and click on the GIF tab.  We will be adding a GIF tunnel in order to bring in the IPv6 connectivity to our router. GIF uses RFC2893 to encapsulate IPv6 into an IPv4 packet.  When we receive an encapsulated packet, pfSense will “unpack” it and reassemble it into an IPv6 packet before acting on it according to the firewall policy.  On the GIF tab, click the “+” link and enter your IPv6 tunnel endpoint information.

• Parent Interface should be set to WAN
• GIF Remote Address should be the “Server IPv4 address”
• GIF Tunnel Local Address should be the “Client IPv6 address”
• GIF Tunnel Remote Address should be the “Server IPv6 address”
• Description should be something descriptive but can be freeform.

GIF interface page

Once complete, hit “Save”. This will add the tunnel endpoint to the router. Click on Interface Assignments so we can assign it to a virtual interface.  To do this, click on the “+” icon and the GIF tunnel should show up as an OPT interface as shown in the screenshot below.

Interfaces page

Now we need to configure the OPT interface. Click on Interfaces > OPT1.  This will be the equivalent to the “WAN” of our IPv6 network.  Since it has never been used before, it is disabled by default. Place a checkbox next to “Enable Interface” which will add the IPv6 configuration section shown here. Set the

Click on the text “Add a new one” in the Gateway section and enter the configuration as shown.

• Default v6 Gateway should be Checked.
• Gateway Name IPV6 is a brief one-word name to help you identify the gateway.  I have chosen “IPV6GW”.
• Gateway IPv6 should be the Server IPv6 Address.
• Description is an arbitrary length text to describe this gateway definition.

When you’re done, you should have something similar to what is in the below screenshot.  For some reason, the gateway text showed up very small, so I increased the zoom so it was readable.

IPV6WAN setup

Click on “Save Gateway” first to commit the gateway information. You should see te IPv6 gateway show up in a dropdown.  Next, scroll down and click “Save” to save the Interface information.  Finally, click “Apply Changes” to apply the interface configuration and start the tunnel.  You can validate the tunnel’s operation by checking the dashboard (click on the pfSense logo).  If you don’t have the Interfaces and the Gateways windows, they can be added by clicking on the “+“  and selecting the relevant options.

Dashboard status page

Now that the endpoint is up and running, it’s time to configure the LAN interface.

Setting up the LAN interface

Since we’re running in a dual-stack configuration, we are going to just add the IPv6 information to the existing IPv4 interface.  As an option, you could theoretically set up a VLAN and a new LAN interface and create an IPv6 only network.  This is something I’m planning on my network and something I’m sure I’ll cover in another article. Let’s start off by pulling up the LAN configuration via Interfaces > LAN.

First thing to do is set the IPv6 Configuration Type to Static IPv6. This will show the IPv6 configuration section.  Enter the first IP address in the Routed /64 section from the tunnel information.  When complete, you should have something like the screenshot below.  Scroll down and hit Save to write the settings, then Apply to make the new settings active.

LAN configuration page

Setting up DHCPv6

In order to bring the IPv6 configuration to your workstations, we will set up DHCPv6.  This is entirely optional as right now you could go ahead and set up static IPv6 addresses just as well as using DHCP however rather than typing insanely larger addresses into all of your workstations, it’s easier and faster to set up DHCPv6 and let the client OSes pull the DHCPv6 as needed.  To get started, click on Services > DHCPv6 Server and then on the LAN tab.

• Set the Router Advertisements to Assisted.  This controls the radvd daemon mentioned earlier.  By setting the mode to “Assisted”, you are telling radvd to perform router advertisements on the local network. The radvd broadcasts are used by the DHCP client applications to set the default router.
• Place a check next to Enable the DHCPv6 server on the LAN interface.
• Enter the desired start and end addresses for your network DHCP range. Please note that unlike the “short notation” using the double colon, you must explicitly declare the zeroes for all octets.  In my example, I’m using 2001:470:1234:5679:0:0:0:100 as my start point and 2001:470:1234:5679:0:0:0:200 as my end point, allocating 256 addresses to DHCP (remember, IPv6 addresses are hexidecimal.)
• Enter the Anycasted IPv6 DNS server from the Hurricane Electric tunnel configuration into the DNS server field.

DHCPv6 configuration

Configure some Firewall rules

At this point, we have the router configured however without some firewall rules in place, we will not be able to route out or get a DHCP address. We will need to add a rule so that our IPv6 traffic can get out.  Click on Firewall -> Rules then click on the LAN tab.  We are going to duplicate the outbound rule created for the LAN outbound.   In the rule listing, click on the “+” icon to the right of the IPv4 outbound rule and change the protocol from IPv4 to IPv6.  Once done, hit Save then Apply.  When you’re done, your LAN rules should look like the below.

Duplicated Firewall rules

 4: Configure your workstations

After you get the router configured, it’s time to set up a workstation.  For this test, I used a Linux box and a Windows 7 workstation.  For Windows, all that is needed is to make sure that the NIC has IPv6 support bound to it.  To do this, go to the Network and Sharing Center and click on the “Adapter Settings” on the left hand sidebar.  Right click the adapter and go to Properties.  Make sure that IPv6 is listed and checked as shown below:

Windows 7 Network protocols list

To test that it’s working properly, open up a command prompt and check to see that ipconfig is showing the proper IP address.  Disregard any fe80:: addresses as these are link-local and not routable for our purposes. Your output should look something similar to my output below:

Windows 7 ipconfig

In Linux, the setup is even easier.   Most Linux operating systems already have IPv6 enabled, so it’s just a matter of pulling an IP address.  Run sudo dhclient -6 -v {interface} where {interface} is your network interface.  In my output below, I am using wlan0.  The -v parameter is optional, this is only to show what dhclient is doing and that it picked up the address from pfSense.

Linux dhcpcd output

This next screenshot shows ifconfig with three IP addresses: One IPv4 address, one link local IPv6 address and the routeable IPv6 address.

Linux ifconfig output

If you want to make the IPv6 settings permanent, you can set this information in Network Manager.  Edit your existing network connection, click on IPv6 Network, set the “Method” dropdown to Automatic and hit Save.  I didn’t provide screenshots on this because it depends on the network type and connection name and it ended up being way more complex than necessary.  IPv6 connectivity should work on both wired and wireless Ethernet adapters.

5: Time to test!

There are several sites that are available that allow IPv6 testing and IPv6/v4 dual-stack testing. My favorite is http://test-ipv6.net.  The site does IPv6 and IPv4 dual stack testing and ensures that you are able to connect to IPv6 and IPv4 sites.  There is also test surfing to http://ipv6.google.com which is an IPv6 only site.   If all goes well, you should receive output like the below:

Test-ipv6.com test results

So, what now?

With IPv6 properly working on your network, you are good to go however there’s probably not much to look at.  Most of the sites I tested were IPv4 only and the few IPv6 sites I could find were mostly broken.    From a consumer-side standpoint, you will notice no difference in the operation of websites.  From a server standpoint, each IP address is routeable meaning that each and every IP in your netblock can run web-accessible services.  The thing now is to pay close attention to your firewall.

Remember that all IPs are routeable!  Prior to this setup, your router implicitly “protected” your LAN by using network address translation. By default, the router would allow LAN connections to exit the router but any unsolicited connection from the Internet could not access the LAN workstations due to how NAT works.  We used port forwarding to allow outside Internet computers inside to access local services.  IPv6 has no such requirement and all IPv6 addresses are public.  You need to make sure that your router’s firewall is set up properly and only allows incoming connections to IPs as needed by your network.  Our firewall configuration is set up with a default deny policy with an explicit LAN outbound rule.  This means that inside IPv6 addresses can surf the Internet uninhibited but any unsolicited connection from the Internet is automatically blocked.

Test your network devices! Test all of your devices, from your computers to your smartphones, printers and anything else that plugs into the network.  You’ll get a quick idea of what works on IPv6 and what doesn’t. You’ll also have a good idea of which manufacturers and what devices to look for firmware updates in order to get ready for when IPv6 goes live.

For further things to do with your tunnel, take a look at Hurricane Electric’s IPv6 certification test.  The IPv6 certification test will test your knowledge of IPv6 and setting up various services on an IPv6 server including email and a Web server.  It’s a good idea to give it a shot so you can get experience working with the new IPv6 network.

Hopefully all went well in your IPv6 configuration and you’re up and running. If not, post a reply and I’ll try my best to help out.

Happy Hacking!
FIRESTORM_v1

After publishing the last post on networking and the security series, I felt it was necessary to go ahead and publish a piece on building a custom router.  I have been a fan of pfSense for the past four years and swear by it. It has the ease of use of a commercial GUI-driven router and unrivaled flexibility limited only by the hardware it is installed on.  In this howto article, we will cover installing pfSense on an embedded platform and initial configuration for getting your router up and running.

First, an introduction to pfSense

PfSense is a lightweight FreeBSD based distribution geared towards router and firewall installations. It has been around since 2004 when it was forked from the m0n0wall project and has since turned into an excellent stand-alone distribution for routing and firewalling.  Although pfSense is generally intended towards full-PC installations, they offer an embedded image for use without skimping on the features.  pfSense is well known in the Linux/Unix/BSD community and is very highly regarded for both it’s feature set and it’s flexibility.

A question I get asked a lot is “Why pfSense? Why not just buy a Linksys?”  The answer is about hardware and software.  While I do own a couple of Linksys routers and do admire Linksys for bringing NAT devices to the common user, their hardware is restrictive and is only usable in the standard configuration (1 WAN and 4 LAN/WIFI) Even though it has been proven several times that the hardware they use for the LAN portion can support advanced features like VLAN support, bridging, multiple interfaces/IP’s, they will never release this functionality to those that want it and will instead force the advanced user to look elsewhere. In Linksys’s view, the router dictates the network.  With pfSense, I can build a custom configuration however I deem fit, with multiple NICs for WAN and LAN, with custom configurations and with VLAN support.  Not to mention that “stock” pfSense even supports DHCP, Captive Portal (like “free wifi”) , DNS, VPN support, Fail Over mode and many other options that Linksys wouldn’t ever make available.  Even if I never use VPN support or use the Failover mode, it’s nice to know those features are there should I ever need them.

Hardware Requirements:

In order to use pfSense Embedded, you will need a computer that adheres to the below spec.  Of course more is better, but these are the minimum specs as posted on the pfSense website.

• CPU: 100MHZ x86 Pentium or equivalent.
• RAM: 128 MB RAM
• Serial Port
• 512MB Flash storage or 1GB hard drive
• Two Network Adapters (NICs)

Please note that some of the advanced features like VPN support, Captive Portal and some high-bandwidth connections may require faster processors than what is outlined below.  If you want to make sure your embedded platform matches spec, take a look at pfSense’s hardware sizing guide which covers some of the items more in depth.

A note on storage:

The pfSense distribution comes in two flavors.  You have the “desktop PC” version for full-size computers with a CD ROM and a hard drive, and you have an “embedded” version which is for devices without a CDROM or hard drive and use some method of flash storage.  While you may be able to install the desktop PC version on the embedded device, it is not recommended as the distribution will be tailored for running on a hard drive, not a solid state memory device.  If you intend to use a hard drive, install the PC version.

You can use any IDE device for storage as long as it is recognized by your computer’s BIOS and is supported by FreeBSD.  I have not had a problem with either of these two stipulations, so you should not have any problems with it. One thing to consider is the use of an IDE to CF adapter like this one on Newegg.  This particular device fits right into the IDE header on the motherboard and allows you to use a Compact Flash cartridge as an IDE hard drive which is perfect for installing and running pfSense.  The router in my home is a slightly different model, but is running on a Sandisk 4GB CF cartridge and has been doing so for the last two years without fail.

My hardware:

In this howto, I will be using a Transcend 1GB IDE solid-state device that I got on Ebay. This device plugs into the 40 pin IDE header and mimics a standard hard drive.  It is fast and will definitely get the job done.  The hardware I will be using is a set top box device I scavenged from a computer show a long time ago.  It has a 233MHz Cyrix processor , 512MB RAM, an onboard serial port, an IDE port, an onboard NIC and a single PCI riser slot where I will be installing a dual 10/100 Intel NIC.

Getting Started:

If you are using the CF to IDE adapter mentioned earlier, you can use a USB-CF reader and an application to burn the image to the CF cartridge.

In order to proceed, you will need the following items

• A Linux based computer with one free IDE port
• An IDE-CF adapter with an appropriately sized CF card minimum 512MB, recommended 1GB, referred hereafter as flash cartridge.
• The “target system” that will ultimately run pfSense with at least two NICs.
• A third NIC (optional, for guest network, discussed in the “Advanced” section below).
• A serial cable (Female to Female) and a Null Modem Adapter.
• A pocket switch with a small patch cord.

Identify your Flash device

First, attach your flash cartridge to your Linux PC and boot it.  Make sure that it boots your Linux distribution first and does not attempt to boot from the flash cartridge.  Once booted, login as root and run dmesg. Look for the /dev entry for your flash module.  You may be able to look for the manufacturer name as is the case in my output below:

My dmesg output.

In the output above, my Transcend module was recognized as hda (primary master HD), so my /dev entry is /dev/hda.  We will need this later on to burn the image.

Download, validate, burn:

Now that we know what device we need to burn to, it’s time to get the image.  Head on over to the pfSense Mirror selection page and pick a server that’s closest to you.

You should then be presented with a list of images named pfSense-1.2.3-RELEASE-XXXX-nanobsd.img.gz where XXXX is a choice of 512mb, 1g, 2g and 4g images.  In my particular case, I will be using pfSense-1.2.3-RELEASE-1g-nanobsd.img.gz as it is pre-built to a 1gig flash cartridge.

Use wget to download the image along with the accompanying .md5 file as shown in the sample output below. Note: URLs in the below image may differ depending on the mirror you are using, but the filenames will be the same.

wget download of files

Once both files have downloaded, use md5sum -c to check the file for consistency against the provided md5 checksum as shown in the sample output below.

md5sum validation

If the MD5 check returns OK then you are clear to proceed. If not, go back and re-download the file again. Make sure you downloaded the same file and md5 checksum.  In order to burn it, we will use zcat to cat the zipped image out to the /dev entry mentioned earlier.  My syntax will be zcat pfSense-1.2.3-RELEASE-1g-nanobsd.img.gz | dd of=/dev/hda bs=16khowever, if your flash cartridge shows up at another location other than /dev/hda, be sure that you change the command above to point to the proper device.  Once the command completes, it should look like this:

Image Burn Completed

Now that the image burn is done, shutdown the Linux box and pull your flash cartridge out and install it in the device that is going to run pfSense.  Go ahead and connect it up but do not attach any network cables to the interfaces just yet.  You will also need to connect the serial cable with a null modem adapter to the device to continue initial setup.

Initial Configuration and Setup

Now that we’ve burned the image, we are ready to do the initial setup.  This entails doing some NIC probing to find the network adapters in the system and to assign them to their respective duties (WAN, LAN, Optional Interface 1, etc).  You should only ever need to do this once as once the NICs are set up and the router is running, you can do everything including re-assign the interfaces from the web-based GUI.

Open up PuTTY, Hypertrm or your favorite terminal application and set the serial port parameters to 9600 baud, no parity 8 data bits, 1 stop bit.  Turn on the embedded device and after a moment, you should see some BSD boot stuff flash past.  Wait until it prompts you to set up VLAN information as shown below:

Vlan Setup Prompt

If you are lucky, you should see two interfaces, one for each NIC.  If you have three network cards in your system, you will see three different interfaces.  In the above screenshot, I have em0, em1 and fxp0.  Since we will not use VLANs for our basic or our advanced configurations, we will answer “N” here.

Now, we will do some network probing to figure out exactly which NIC  goes to which interface using the pocket switch and the patch cord.  Don’t plug anything in yet.

Probe for LAN interface

With nothing plugged into the network interfaces, hit a and hit enter.  This will start the autodetection process. When prompted, attach the pocket switch to the interface you will use as the LAN interface and make sure that the LINK light on the switch and the NIC come on.  Hit Enter and you should see a message where it detected the LAN interface link come up.  It will then prompt you for the WAN interface.  Hit a then enter again and move the patch cord to the WAN interface and hit enter.  Repeat this process for the Optional interface (OPT1) or if your router only has two NICs, just hit enter.  Refer to the below output.

Assigned NICs

Be sure that you only change the patch cord when it tells you to.  If you disconnect the cable at the “hit A for autodetect” prompt, it may not detect link when it should.  If you run into this issue, disconnect the patch cord and restart your router.  Allow it to boot up and start over.  Once you get done assigning interfaces, simply hit Enter to exit assignment.  It will print the current assignments of the interfaces and ask you to validate.  Answer Y if the displayed assignments are correct and hit Enter, otherwise hit N and start over or restart the device.

Assuming all went well, you will see it do a bunch of additional configuration.  Once you get to the menu as shown below, you can then disconnect the serial cable and proceed with the configuration of the pfSense router.

Configuration Completed

Continuing the Configuration

Connect the pocket switch up to the LAN port of the router and connect your router’s WAN port to your Internet connection.  Connect a computer to an unused port on the pocket switch and start it up. Once booted, you should have an IP address in the 192.168.1.x subnet and depending on whether or not your Internet connection is DHCP, you may already be able to surf.

Open a browser and go to http://192.168.1.1 and when prompted login with the username of admin and the password of pfsense.  If all goes well, you should see a screen that looks like the one below.

pfSense Wizard

Click “Next”

On this screen, you will set some basic network configuration parameters like the pfSense’s hostname, local domain and the two DNS servers.  Use the ISP provided DNS servers here and click Next.

pfSense Wizard, page 2

On this screen, we will set up the timeserver and the timezone of the firewall.  Set the timezone where appropriate and then either use the provided time server or set your own.  I left it default and have not noticed any issues with time reporting.

pfSense Wizard, page 3

The next screen is where we will set up the WAN parameters.  Start off with selecting which type of WAN link you have.  Choices are DHCP (default),  Static IP, PPPoE and PPTP.  For each selection, there is a relevant section that must be completed.  Since I use DHCP, I left it as default.

pfSense Wizard, page 4

Pay special attention to the bottom two options.  The first option “Block RFC1918 networks” prevents LAN IP addresses from the “private” networks from entering from the WAN interface. Private networks are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.  Unless you are using this router inside another NAT environment, this option is best left turned on.

The other option “Block Bogon Networks” should be left enabled. This prevents non-routed and not-assigned networks from being routed against from your WAN interface. Since these addresses are not routed and not assigned, they should never contact your router anyways.

pfSense Wizard, page4, Bogon networks and RFC1918 options

Now we are at the LAN configuration.  This is where we can change the router’s internal IP address and subnet mask.  Please note that most of pfSense uses CIDR notation, so you may want to get familiar with it or have a CIDR calculator at the ready. Tip: a /24 is the same as 255.255.255.0

pfSense Wizard, page 5

This screen allows us to change the default password of pfsense.  I highly recommend changing it to something memorable.  If you forget it, you can always reset it via a serial connection without resetting the router back to factory settings.

pfSense Wizard, page 6

Finally we have reached the end of the wizard.  Click “Reload” and wait a few minutes.  During this time, the router will reboot itself to get adjusted into the new environment.  Let the web page reload the router’s admin page and it should take you to a configuration page like the one below.

pfSense main status page

Once you are at this screen, you should be able to browse the Internet.

Some basic tips:

• Portforwarding can be set up under Firewall -> NAT and works pretty much like you would expect a Linksys box to work.  Be sure to leave the “Auto Add a firewall rule to permit traffic through this NAT rule” at the bottom checked.  This will create a matching rule on the WAN side to allow traffic along with the rule to bring the traffic from the WAN to your destination computer.
• You can see each interface’s status by going to Status -> Interfaces.  If you are on a PPPoE or PPTP connection, you can disconnect and reconnect from this page.  If you are using DHCP, you can also release and renew your IP here.
• If you run into trouble performing port forwarding, you can access the system firewall logs via Status -> System Logs.  Be sure to turn on Logging on your rules so you can see new connections as they are being performed.
• If you’re having problems with a specific host, you can access a packet capture utility via Diagnostics -> Packet Capture
• If you want to diagnose upstream Internet connectivity issues, you can access Traceroute via Diagnostics -> Traceroute. and a ping utility via Diagnostics -> Ping
• Like numbers and graphs? Check out the system traffic graph (Status-> Traffic Graph) and the system RRD graph (Status -> RRD Graphs).  You may need to install the Adobe SVG viewer to view these graphs.
• Unlike a Linksys box, it is recommended to halt the router before powering down and use the reboot function if a restart is needed.  Both options appear under Diagnostics with the labels “Halt system” and “Reboot system” respectively.

What’s next?

Even in its basic configuration you already have a very powerful router on your hands.  The sky’s the limit. The pfSense installation can support a great many different configurations and options so don’t think that you’re locked into a single configuration.  Out of the box, pfSense has the software support for DHCP, DNS server, and other basic functionality as well as more things like CARP Failover, Open NTPD (Time server), OpenVPN, Remote Syslog, Traffic aggregation, and many other features that warrant exploration.

In a follow up article, I will explore setting up an advanced configuration, establishing a VLAN to isolate a wireless network from the wired network while still providing Internet access.  This is a useful configuration for you that like to share your Internet access but don’t want to make your home network vulnerable.

Happy Hacking!

FIRESTORM_v1

Structured wiring in businesses and the enterprise are as expected as the sun shining and a regular paycheck, however in the home a structured wiring solution can be an unexpected gift from the Gods of Ethernet.  While structured wiring in an apartment complex is usually done central to a utility closet or shelf, sometimes the central point isn’t always convenient for your router or you find yourself needing to run multiple networks.  In this tutorial, I will show you how to turn one structured wiring drop into two drops for carrying two different network segments, something that can be of benefit should you ever need it.

What these splitters do and what they don’t do.

Before we begin slicing up cables, it’s important to understand what is going on here so you can decide if this will work for you.  Generally speaking, these splitters can be used if you want to carry two different networks over the same drop. If you are simply looking for more connections to your home network, and you are not doing anything special, you will more than likely want to save some time and get a mini-switch instead.  Here’s a good rundown of some scenarios of why you should and should not consider these splitters:

These splitters would be a good idea for the following scenarios:

• Moving your router from the default ingress point.  In my case, the central “panel” is in the utility closet, but I want my router on my desk.  I use the “1″ portion of the splitter to transport the WAN segment to the WAN port of my router, then use the “2″ portion of the splitter to transport the LAN segment to a mini-hub in the closet to activate the rest of the jacks in the house.
• Moving a “hostile” segment or Guest network to another location.  An example would be having a router installed at the ingress point and using a splitter to transport a “Guest Network” and a “LAN” connection via the same drop.  In this case, the Guest Network feeds an open access point, while the LAN feeds a desktop computer. In this application, the Guest Network is kept physically separate from the LAN via the splitters but allows you to position the access point somewhere more convenient while maintaining the availability of the LAN.
• Transporting two Ethernet drops to a managed switch located in a central closet.  An example for this would be to allow per-port monitoring and administration of both drops individually as opposed to using a mini-switch which would force you to  perform the change across all devices attached to the mini-switch.

These splitters would not be a good idea for the following scenarios:

• Creating more Ethernet ports for the same network and you are not using a managed switch.   If you are plugging two devices into your LAN at the same location, just use a mini-switch and save yourself the trouble. There’s no benefit to using splitters in a non-managed switch environment. Additionally, you may incur additional costs with having to buy an additional mini-switch to split the connections off at the central panel anyways.
• You are using Gigabit Ethernet and do not want to drop the line speed in the location you are looking at.
• You are using Power over Ethernet at this location and do not want to move the power supply.

A little bit on structured wiring and Ethernet standards

In a structured wiring environment, a “drop” is the term for a 4 pair (8 wire) cable run through ceilings, walls, etc from a faceplate with proper termination to a central wiring panel with proper termination (usually a patch panel of sorts).  It’s called structured wiring as the wiring is usually planned out first with attention to detail and locations of equipment like access points, computers, etc.  Generally speaking, if you are in a structured wiring location and you see an RJ-45 jack marked “Cat-5″ this generally means that it’s an Ethernet jack and that the cabling and connectors comply with the Cat-5 standard.

Speaking of wiring standards, you may want to take a look at this link which provides more detail into the wiring convention commonly used in structured wiring for Ethernet networks.

In standard 10/100 Ethernet cabling that uses an RJ-45 jack, you have two wires(a pair) for transmit and two wires(a pair) for receive.  In most locations, the extra two pairs (four wires) are simply left idle and untouched. In rare situations (at least in residential equipment) these extra pairs are used for Power over Ethernet which use these spare pairs to deliver power to a network device where it is not convenient to use a standard “wall-wart” power supply. This requires special adapters (not unlike our splitters) to send power and network connectivity over the same drop, then split it again at the device end.   As mentioned before, if you are using PoE to feed a device using a drop that you need two connections for, you will either need to move the PoE power supply to another location or use our splitter elsewhere.

Unfortunately, Gigabit Ethernet requires all four pairs be used for sending and receiving at Gig-E speeds. If you are not willing to move the Gig-E device and are not willing to drop the speed to 10/100 , you will need to use the splitter elsewhere.

Do the Splits!

In order to pull this off, you will need the following:

• Two Cat-5 patch cords
• A RJ45 crimper
• Four RJ45 Crimp Ends suitable for the wire in your patch cords. (more if you are new at this, just in case)
• Heatshrink that is big enough to accommodate twice the diameter of your patch cords.
• Lighter
• Diagonal cutters
• Sharpie (not pictured)
• Cat-5 tester (Optional, not pictured)
• Cat-5 Female to Female junction adapter (optional, not pictured)

Tools

To start off, cut one CAT-5 end off of your patch cord and determine how far back you want to strip the jacket off.  In my example, I wanted this splitter to go next to a managed switch where the ports are close together so I used about 8 inches which leaves about 4 inches for each “branch”.   If you are using a pocket switch and a computer, you may want to use one foot (12 inches) which leaves you with two 6 inch branches.

Start snipping the jacket of the patch cord, paying close attention to not damage any of the wires underneath. If you do snip a wire, cut the rest of them at the same length and repeat the process.   Once you have managed to snip the jacket clean, begin pulling the jacket off of the cable in one piece.  When completed, you should have eight wires similar to the below picture.

Stripped Wiring

Split the wires into two groups.  Separate the White/Blue and the White/Brown pairs from the White/Green and White/Orange pairs.  Slip the heatshrink tube over all four pairs down past the cut jacket.

Fold the stripped away jacket in half and cut at the half line.  Slip one piece of the jacket over the White/Blue and White/Brown pairs, and thread the White/Green and White/Orange pairs through the remaining piece of the jacket.  Use the image below as a guide.

Wires threaded through Jacket

Slide the two jacket pieces down as far as they will go, then push the heatshrink tube at least one inch past the split.  This will toughen the split to ensure it doesn’t fall apart with use.  Use the lighter to shrink the tubing around the three pieces of jacket.

Now for the fun part.  At the ends of the two pieces of jacket, you now have one piece with a White/Blue pair and a White/Brown pair and another piece with White/Orange and White/Green. We need to put ends on these wires so we can start using them.  Start off by spreading the wires out and untwisting them like in the image below.

Separated Wires

Trim the wires so that there is approximately one inch sticking out of the jacket and make sure that the wires are laid out like so:

• Solid Green (or green with white dots)
• White/Green – white wire with green stripe
• Solid Orange (or orange with white dots)
• White/Orange – white wire with orange stripe

The important part is when you insert them into the crimp end, the solid green wire must go into position 3, and the rest will go into positions 6, 7 and 8 as shown below.  Please take note that the orientation of the RJ-45 crimp end is that the spring clip is pointing towards you, and the wiring enters from the left.

• Position 1 – Blank
• Position 2 – Blank
• Position 3 – Solid Green
• Position 4 – Blank
• Position 5 – Blank
• Position 6 – White/Green
• Position 7 – Solid Orange
• Position 8 – White/Orange

Before you crimp the RJ45 onto the wires, hold the whole thing up to a bright light and ensure that the wires are long enough to hit the end of the connector.  Sometimes, a bad crimp can result if the wires are too short.  Use the below image as a reference and take some time to make sure your wiring is correct.  If all looks good, go ahead and crimp!

Visual Inspection

Now for the White/Blue and White/Brown pairs, you must perform the same process, except this time we will use White/Brown in place of the White/Orange pair and the White/Blue will substitute the White/Green.  Our wiring diagram will change to below:

• Position 1 – Blank
• Position 2 – Blank
• Position 3 – Solid Blue (or Blue wire with White dots)
• Position 4 – Blank
• Position 5 – Blank
• Position 6 – White/Blue
• Position 7 – Solid Brown (or Brown wire with White dots)
• Position 8 – White/Brown

Do the same inspection as you did for the first crimp and check, recheck and crimp your second connector.    Mark the crimp with the White/Orange and White/Green wires as “1″ and the other crimp with the White/Blue and White/Brown wires as “2″.  This will be important later on when you implement your splitters.

Do it again, Sam!

Now that you have one splitter, go ahead and do it again with the other Cat-5 patch cord.  When you are complete, your patch cord should look like the following image.

Finished Splitter

Final Thoughts

Now that you have a pair of these splitters, you should be able to enjoy a bit more freedom when setting up your network in a structured wiring environment where additional cable runs are simply not feasible.  In my particular installation, I am using my splitters to feed the router’s output that carries VLAN tagged traffic into a managed switch.  The other leg of the splitter, goes back to the wiring closet to feed a mini-switch with network connectivity.  VLAN tagged traffic will not traverse a non-managed switch so for me this was the only way to be able to use my VLAN tagged network and my “primary” network without having to give up either.  Below is an image of my splitter feeding my 24 port switch. Yes the switch is on however it appears that the flash washed the lights out.

Installed Splitter

I hope you enjoyed this quick post as I did making the splitters.  Reply to this post and tell others how you intend to use your splitters.

Happy Hacking!

FIRESTORM_v1

A few months ago, I posted a hardware teardown of the CVS Sylvania Netbook pictured above. After working with it and performing a lot of research on it, I promised a follow up article, and here it is.  To sum it all up, with a bit of modification to the software, a spare SD card and a lot of patience, you can actually turn this thing into a somewhat useful Linux device.  There’s also some improvements and suggestions to be had for improving the Windows CE side of things should you decide to continue using it in its default state.

When I posted the original teardown, I was somewhat distressed at how little information there was for this device. There was a ton of “marketing” material online however very few real-world posts.  This appears to have changed and although most of the reviews lamblasted the device as a horrible design and underpowered, I have found that for the price I paid for it, it’s not bad at all.  In this article, we will be focusing on software because as much as I’d like to say I’ve done a lot of hardware mods to this thing, the truth of the matter is that I haven’t.  Time has continued to get away from me and I’ve had to put a lot of projects on hold.  But let’s not start this article off on a downbeat.

In the three months that I’ve been doing research on the Sylvania Netbook, I have uncovered a lot of information that can help turn this machine into a pretty useful piece of equipment.  The fact that it has a pretty decent battery in of itself should be of merit to justify the time invested in fine-tuning it.

1: Windows CE

In my research, there have been two key complaints against the Sylvania netbook in regards to a “stock” configuration.  The first complaint has been that it is running Windows CE (affectionately called “WinCE”) and the second being that the WinCE installation is really badly implemented.

• The key thing to remember with working with Windows CE is that Windows CE is NOT Windows like on your desktop or “normal” laptop! Windows CE was designed for small form factor devices and although it shares the same name as it’s bigger brother desktop OS, Windows CE can not run Native Windows applications. This appears to be the biggest hurdle in locating user software for the device as people will attempt to download software then when they get the software into the netbook, they are thrown off by an error message stating it’s not a “valid” application.  Consider it like taking a MacOS program designed for MacOS and attempting to get it running in Windows XP.  It ain’t gonna happen.  That being said, there is Windows CE applications out there, however the pickings are slim.

• The other issue with working with the stock Windows CE installation is that the OS software is so badly implemented on the netbook that most things that should work, don’t.  Thankfully for us there is a patch available that will make things easier.  From research, the patch addresses several performance issues with the core OS, several updates to the builtin applications as well as an update to Internet Explorer.  Unfortunately, IE will still render mobile sites by default, but the rendering won’t take as long.  The patch also fixes the issue with the wireless card not being able to properly associate with WPA/WPA2 secured networks and DHCP release/DHCP renew works as expected.  I have uploaded the patch to here.  In order to install the patch, follow the below instructions. You will need a spare SD card at least 128MB in size.

Here’s how to download and perform the OS update:

1. Download the patch from here:  sylvania_laptop_OS_update.zip
2. Extract the executable to an SD card.
3. Insert the SD card into the Sylvania netbook.
4. Browse to the SD card slot (Computer -> SD Card)
5. Launch the patch and follow the on screen prompts.

2:On the Linux side of things…

When I did my original research, I was fortunate to have come by a site dedicated to a Linux distribution made solely for the WM8505 series devices like the Sylvania Netbook. The site and the distribution were called Bento Linux and much like the Japanese namesake, the distribution was very small and was designed to be able to run within the computer’s limited spec.  Unfortunately, the site www.bento-linux.org no longer exists but thankfully I still have the documentation and files needed to pull it off.  If you are the owner of bento-linux.org and are willing to give me the site files, I would be more than happy to host it here. Please contact me in the comments.

One of the added benefits of Bento-Linux is that unlike some replacement OS installations, this is a sidecar installation meaning that all work is done on the SD card.  If you want to boot to Windows CE, halt the Linux OS, pop out the SD card and power the Netbook back on and you’re up and running like nothing happened.  Although the Bento Linux site did have instructions for performing an installation to the device’s flash ram, it is not recommended as if you accidentally mess up the Linux distribution, there may be no recovery. In a sidecar installation, you can pop the SD card into another device, make your changes, and then put the SD card into the netbook and you’re up and running again.

Although the site claimed that the distro could run on a 512MB SD card, I will up the recommendation to at least a 2GB card.  Prices are low and SD cards are very commonplace so it’s worth it to get a larger chip.  I started out on a 2GB SD card, but later upgraded to a 4GB Microdrive and noticed a significant performance increase going from solid-state memory to a USB Microdrive. Your mileage will vary, but it is recommended to stick with an SD card first, then perform upgrades and additional installations as needed later on.  As far as USB devices are concerned, you can use any USB storage device/keydrive that is recognized by the usb mass-storage driver in Linux.

Please note that the version of Bento I was running is usable however it did not appear that the sound card was operational. Since I am intending to use this as an external serial console, this was not a deal breaker for me.

Installation (SD Card Only)

Bento-linux comes in two parts. One part is for a FAT16 partition placed at the beginning of the SD card and it contains the boot commands needed to tell u-boot (the Netbook’s bootloader) how to boot the linux kernel and the root filesystem.  The other part contains the linux kernel and the filesystem in an EXT3 filesystem and will contain all the files needed to run Linux.

1. You will need to start with an SD card at least 1GB in size.  I used a 2GB which gave me some room to play around on and of course the bigger, the better.
2. Partition the SD card with a 20MB FAT16 partition at the beginning of the card and the rest of the disk space can be allocated for an EXT3 partition.  Do not create a swap partition.
3. Download the file fatpart.tgz and extract it into the root of the FAT partition on the SD card.
4. Download the file extpart.tgz and extract it into the root of the EXT3 partition of the SD card.
5. Unmount the card and insert into the Sylvania’s SD cardslot and power on the machine. It should boot the Bento Linux distribution

Installation (SD Card + USB stick)

This setup does not require special partitioning, however it does require that the SD card be formatted FAT16.   You will also need a USB storage device formatted EXT3.

1. Download the file fatpartusb.tgz and extract it to the root of the FAT formatted SD card.
2. Download the file extpart.tgz and extract it to the root of the EXT3 formatted USB stick (or hard drive).
3. Insert the SD card into the Sylvania’s SD slot and insert the USB stick into a free USB port on the Sylvania.

In either instance, when you first boot the distro, it will simply bring you to a console prompt and you are good to go.  There are a couple of things you may want to do:

• (Pretty much required)  Set a root password.
• Install fluxbox (light weight graphical interface) and wicd for wireless control.
• Install aurora (lightweight firefox lookalike)
• Install other applications though apt-get as desired.

Although the bento-linux site is no longer in existence, it appears that all the repositories that come with the distribution point to the arm ports of the official Debian repositories.  Prior to them going offline, I saw a note about Bento-Linux had the sources for the WM8505 however it appears that VIA has recently released the sources for the WM8585/VT8505 chips that drive the netbook so if you have any custom drivers, it appears that now there is an easier method for getting the drivers compiled in.  I am not a kernel compiler expert so I can’t advise on this process, however some brief research does seem to indicate that there is some element of truth to this.

Linux Impressions and final words

After getting the Bento Linux distribution working comfortably in the netbook, I played around with it and made some tweaks here and there that did give some notable boost in performance.   If you are using a spinning platter form of storage, creation of a  swap file or swap partition is recommended as it will give you a performance boost.  Attempting to make a swap file on the SD card or on a solid-state USB drive are not recommended because of the performance hit when writing to these devices and also due to the issue of “burn-in” when a storage cell is written to frequently.  I found that the device works decently enough for quick tasks and light webpages however it will not handle flash at all, nor will it be able to render sites with large amounts of images.  In my testing, I was able to use this device to configure Cisco switches and other devices through a USB-Serial adapter and Linux’s “minicom” terminal emulator.

While I believe it was a valiant effort by Sylvania to enter into the netbook market, I do believe that they should have done more research.  The Sylvania netbook, even running Linux and with all the performance tweaks mentioned, still is easily beat by Asus’ first offerings into the Netbook market. The two biggest things that seem to harm this device are the lack of RAM in the system (mine only has 128MB RAM) and the sub-par processor less than 1GHz.  If you have one, then you may be able to make it work for you, however if you are considering one, I’d stay clear.  It’s not worth the price they are asking for it at CVS.

A couple of comments left by Syed and Dave to the original CVS netbook post indicates that there are people out there that are able to get Android running on this device.  If you have information or an article written on how you did it, let me know in the comments.  I’m interested in trying it out and finding out what works on this machine.

In this final article in the three part Ubuntu IDS series, we will go over installing, compiling and configuring Snort and Nessus on our new IDS device.  We will use Snort to analyze traffic as seen by the IDS and we will use Nessus to perform vulnerability testing on the network. The process for installing Snort will also cover installing SnortReport provided by Symmetrix Technologies so we can translate Snort’s cryptic messages into a more readable format that we can take action on.  Read on as we wrap up the installation and finish our IDS device.

This article is divided into three sections. The first section will cover installing Snort, then we will move on to customizing Snort beyond the steps covered in the first section for our specific installation.  Finally we will end with installing Nessus.

1:  Installing Snort

Admittedly, this was the longest part in the series. I had tried manually to compile and install Snort from sources over and over again and wasn’t getting anywhere fast.  I had performed research over and over again on what options to use and was no further along than when I had unzipped the sources.  Luckily my research finally turned up a complete HOWTO article written by Symmetrix Technologies which provided instructions on how to compile and set up Snort.  You can download their HOWTO from this site:  http://www.symmetrixtech.com/articles/004-snortinstallguide286.pdf

There are some discrepancies that you must take note of: If you are using the bonded interface as described in the prior articles, you will need to use the interface “bond0″ instead of the document’s provided eth1 interface for monitoring.  If you monitor an ethX interface, you will only get half of the conversation, and since most of Snort’s ability to detect traffic relies on analyzing stimulus and the responses to that stimulus, you will be severely cutting down on Snort’s effectiveness.

2: Snort Tuning

If you’re this far in, then it’s safe to assume that you have already downloaded Snort, the associated ruleset and have SnortReport installed and running.  There are some things that the Snort installation howto did not entirely touch on and these are things that we will cover here.

Adding BPF to /etc/init.d/rc.local

One of the things missing from the Installation HOWTO was to add a BPF expression to the snort command line. BPF stands for “Berkeley Packet Filter” and is used by Snort and tcpdump to control what traffic is being analyzed by the respective tool.  In our configuration, we need to add an exception for the IDS’s management traffic otherwise when we install and run Nessus, we will end up triggering a ton of alerts.

Edit the /etc/rc.local file and locate the snort line.  Add ” not host 192.168.0.253″ to the end of the snort line. Replace 192.168.0.253 with that of the IP of the management interface of your IDS.  This is the BPF syntax that tells it to monitor your network but not the IP of your IDS device. By adding it to the end of the snort command, we are effectively telling Snort to not listen to the traffic generated by Nessus when we decide to fire it off.

Password Protect SnortReport:

Regardless of whether or not your IDS device can be reached from the Internet, there exists several vulnerabilities in SnortReport including one that allows potential code execution.  This could allow someone that knows you run SnortReport to execute code on your IDS and would be counterproductive to our efforts.  Until SnortReport has been fixed by SymmetrixTech, we will have to use a more basic method of securing it.  In order to provide minimal protection for SnortReport, we will add .htaccess protection to the directory that SnortReport was installed in so that way only authorized people will have access to SnortReport.

As root, we will use htpasswd to create the password file.  If you forget it later on, you can recreate the file easily using the below steps. Use the below command to make the password file and replace “joe” with that of your desired username.

# htpasswd -c /var/snortreportpasswd joe

Now, we need to create a .htaccess file in /var/www/snortreport-1.3.1 to reference it.  Copy the below code and enter it into /var/www/snortreport-1.3.1/.htaccess and don’t forget the . in the filename.

AuthName "SnortReport"
AuthType Basic
AuthUserFile /var/snortreportpasswd
Require valid-user

Finally, there is one more change we need to make to Apache2 to get the .htaccess protection working.  Edit /etc/apache2/sites-available/default and look for the clause that looks like the one below:

<Directory /var/www/>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
allow from all
</Directory>

Change the “AllowOverride None” to “AllowOverride All” and then restart apache2 via /etc/init.d/apache2 restart . Now try it out by going to http://(your IDS IP address)/snortreport-1.3.1/alerts.php. You should  get a password prompt. Type in the password that you created using the htpasswd command earlier and you should see a green page that says SnortReport.

When you first load the page, you will see two dropdowns for Timeframe and Day.  If your IDS has received any incidents, you will see it show the incidents here.   Clicking on the incident summary will show more details including the source and destination IP addresses. Clicking on the IP will return correlated events that include the source or destination IP you clicked on and will show packet payloads and IP addressing information.

Now that you have a way to read the incidents that the IDS receives, it’s up to you to decide whether or not the incidents generated are something to take action against. However, installing an IDS is only one half of the solution.  In order to be aware of the effect an attack may have on your network, you first must know what vulnerabilities exist on your network.  For that, we turn to the free vulnerability scanner, Nessus.

3: Installing Nessus

Nessus is widely used as a professional commercial-grade vulnerability scanner. It can generate reports that indicate per host what vulnerabilities exist and can provide information on where to go to learn more about patching or mitigating the threat.  Keep in mind that while Nessus is often used on Linux, it is a commercial product.  It does have a home version which we will be using in our installation however the home version can not be used in a commercial environment.

The Nessus HomeFeed provides your Nessus installation with the most up-to-date vulnerability detection methods and signatures.  Access to the HomeFeed does come at a cost, however the benefits of having a vulnerability scanner outweigh the loss of a couple of features. Most notably, a feature that is only available to their commercial feed is that you can not set up recurring scans of you home network, e.g. you can’t tell the IDS to automatically scan your network and generate reports on a regular schedule.  The only other limitation that I have been able to find is that the scans are limited to 16 active hosts per report so if you have 32 hosts, you will need to run two scans. Despite the two limitations mentioned above, Nessus is still a great scanner, and will work quite well for identifying vulnerabilities on your network.

All that being said, let’s get started.

First off, head to Tenable Security’s website at http://www.tenable.com/products/nessus/nessus-homefeed and register to receive your activation code. Keep your email handy, you will need it later.

Next, head to http://www.tenable.com/products/nessus/nessus-download-agreement and agree to the license, then download the Ubuntu debian package that is appropriate for your distribution.  Since this tutorial is based on using Ubuntu 10.04, I downloaded the Ubuntu 10.04 32 bit version. Although the filename says “ubuntu910″, this version was recommended by Tenable as the version to use for 10.04.

Now, SCP the installation package to the IDS and then use dpkg -i Nessus-4.4.1-ubuntu910_i386.deb to install it into the server. Please note: If your Ubuntu Server is running a 64 bit kernel, please download the 64bit version of Nessus.

Once installed, you will need to add a Nessus user to the service so you can login.  Nessus users are seperate from OS users, so you can have multiple users without having to add multiple users to the system.  To start this process, run /sbin/nessus-adduser and follow the prompts.  For the first user that you add, you will want to add an administrative user. This user will be able to adjust Nessus’s scan policies, behaviors and other settings within Nessus.

Now that you’ve added a user, you will need to register your Nessus installation using the HomeFeed code in your email.  Run the command /opt/nessus/bin/nessus-fetch –register <Activation Code> and allow it to complete the installation. Substitute <Activation Code> with the HomeFeed code in the email.  Please note: This step may take a considerable amount of time due to the fact that Nessus will download and update itself according to the HomeFeed subscription.  This only took about an hour on my system, your mileage may vary depending on Internet connectivity speeds.

Now that the Nessus service is installed, registered and updated, it’s time to test the installation.  Open a web browser and go to https://your-ids-ip-address:8834 .  If you are running Firefox and are using Noscript, AdblockPlus or Flashblock, you will need to add exceptions for Javascript and Flash for the IDS IP.  This is required as the Nessus UI relies entirely on Javascript and Flash.

Now that you have Nessus installed, it is highly recommended to take a read through the Nessus User’s Guide: http://cgi.tenable.com/nessus_4.4_user_guide.pdf While Nessus is a vulnerability scanner, some of the tests it performs can cause unpredictable results. It is recommended to set up a “safe” scan that performs basic testing and then set up a “full” scan for aggressive testing.

How to read the scan results:

Once you have made it through the User’s Guide and have performed your first scan, you can download or view the report.  The report is listed according to IP address, then service name, then vulnerability. Each vulnerability will include the service name, port, protocol, related CVE information (links to the CVE database for more information), as well as common fixes for the vulnerability.

I recommend taking a look at the vulnerability list in this order:

1. Externally accessible services: A vulnerability in Apache that listens to the outside world threatens your internal network.  Address this first!
2. Internally accessible services on the same server as external services:  Should the external service be compromised, internal services could be used to further compromise the network.
3. Internally accessible services: A service listening internally may not pose much of a threat, but may be a possible point of compromise should another host get infected.  ( A common example is a weakness in older versions of Samba that would allow for remote code execution.)

Generally speaking, it is a good idea to keep up to date with all service packs, updates and patches as this will prevent any known exploits from turning into full-blown worms.  Remember, it only takes one vulnerability to get compromised.

Final thoughts:

This has definitely been quite a project. I have learned a whole lot about network security in the course of my GCIA training and in building this project. I honestly think that building an IDS device from scratch is a great way to get acquainted with network security and how to perform vulnerability assessments.  Using Snort Report to analyze suspicious traffic and incoming threats and using Nessus to identify vulnerabilities in your system will help your home network stay secure against the ever evolving threats going around the Internet.

Always remember that security is no use if the warnings go unheeded.  While you don’t have to turn into a complete security nut, make it a good habit to take a look at Snort Report once a week at least.  Personally, I record the number of events logged and if it changes, I then investigate further however I haven’t picked up any incidents in the last month so for me it’s a pretty easy check.  If you find yourself with tons of IRC events and you don’t use IRC, it’s very possible that you have an active trojan on your hands and may warrant further investigation.

I hope you had fun and learned a lot from this project. I had a lot of fun building it and working out the kinks to make it all work together.  If you have any comments or questions, please leave me a comment and I’ll do my best to answer.

FIRESTORM_v1

In an earlier article, I demonstrated how you can build a passive monitoring device for an Ethernet network as the first part to a three part project to build a home IDS device.  In this article, the second in the series, I will describe how to set up the networking for an IDS using the passive tap that I built earlier.This setup will involve using a technique called bonding to take two physical interfaces and bond them together, creating a logical interface that we can use for Snort.  This article will also explain where is the best location to place the tap and what you can expect to see once the networking is set up using common Linux utilities like tcpdump.

Requirements

• A Passive Tap as mentioned in “Build a Passive Ethernet Tap” or similar device.
• Three network cards or a single network card with  three interfaces.
• A new installation of Ubuntu Server. (I am using Ubuntu Server 10.04LTS).
• Beer. (Always)

The requirements for this project aren’t that extensive and chances are you have most if not all the equipment you need in your parts bin. The most significant item in this list is the three network cards.  If you followed the steps in my first article in this series, you already have a machine with two or three network cards in it so you’re pretty much there. If not, then go ahead and get three network cards in your Ubuntu server and ensure that all three cards re properly recognized by the system even if there’s no IP address. for them.

The first two network cards will be combined together to form the monitoring interface while the third card will be for our management interface.  The management interface will be assigned an IP address and will be how we acccess the server’s commandline (via SSH), and the scanning and reporting tools we will install in Part 3.

Getting things set up

With the proper hardware in hand, we can now set about performing the configuration necessary to getting our interfaces configured properly. In the code below, you can see the interfaces (eth0, eth1 and eth2) and that eth0 has been configured with an IP address.  If you haven’t configured yours with an IP address, this will be covered while we perform the configuration.

matt@ids-01:~$ ifconfig -a
eth0      Link encap:Ethernet  HWaddr 00:18:f3:18:1c:25 
 inet addr:192.168.0.222  Bcast:192.168.0.255  Mask:255.255.255.0
 inet6 addr: fe80::218:f3ff:fe18:1c25/64 Scope:Link
 UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 RX packets:45458 errors:0 dropped:0 overruns:0 frame:0
 TX packets:23861 errors:0 dropped:0 overruns:0 carrier:2
 collisions:0 txqueuelen:1000
 RX bytes:55984695 (55.9 MB)  TX bytes:2326303 (2.3 MB)

eth1      Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 RX packets:11505094 errors:2 dropped:0 overruns:0 frame:2
 TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000
 RX bytes:3057886364 (3.0 GB)  TX bytes:218 (218.0 B)

eth2      Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 RX packets:8061127 errors:1 dropped:0 overruns:0 frame:1
 TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000
 RX bytes:1434430796 (1.4 GB)  TX bytes:250 (250.0 B)

lo        Link encap:Local Loopback 
 inet addr:127.0.0.1  Mask:255.0.0.0
 inet6 addr: ::1/128 Scope:Host
 UP LOOPBACK RUNNING  MTU:16436  Metric:1
 RX packets:48 errors:0 dropped:0 overruns:0 frame:0
 TX packets:48 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:0
 RX bytes:3948 (3.9 KB)  TX bytes:3948 (3.9 KB)

In this output, you can see eth0 is my management interface as it has been assigned an IP, eth1 and eth2 are both going to become a new interface called bond0.  When we set up Snort, we will use bond0 as our monitoring interface so that way we can take advantage of Snort’s stateful analysis and because it will be critical for any network analysis to hear both sides of the conversation on the passive tap.

In order to set up bonding, we will need to install the ifenslave package.  As root, run the below command:

# apt-get install ifenslave

Once apt-get completes, let’s check a few things.  First, let’s take a look at /etc/modprobe.d/aliases.conf.  Make sure that the two lines below appear in the file:

alias bond0 bonding
options mode=0 miimon=100 downdelay=200 updelay=200

If you will be making more than one bonding interface, you will need to add another alias line to coincide with the bond interfaces you wish to add (bond1, bond2, etc..) and you will need to add max_bonds=X to the end of the options line. Set X to the maximum number of bonding interfaces you will be using.

Now this is where things get interesting.  In order to test this out, we will bond the interfaces using the command below:

# ifenslave bond0 eth1 eth2

It does not matter which order the two eth interfaces appear, however bond0 must come first.  This command tells the Linux kernel to take eth1 and eth2 and pair them together into a single interface (bond0).  Now that we have done that, ifconfig -a will present a new interface:

root@ids-01:~# ifconfig -a
bond0     Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 inet6 addr: fe80::2e0:b6ff:fe00:a206/64 Scope:Link
 UP BROADCAST RUNNING PROMISC MASTER MULTICAST  MTU:1500  Metric:1
 RX packets:19568527 errors:3 dropped:0 overruns:0 frame:3
 TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:0
 RX bytes:198240524 (198.2 MB)  TX bytes:468 (468.0 B)

eth0      Link encap:Ethernet  HWaddr 00:18:f3:18:1c:25 
 inet addr:192.168.0.222  Bcast:192.168.0.255  Mask:255.255.255.0
 inet6 addr: fe80::218:f3ff:fe18:1c25/64 Scope:Link
 UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 RX packets:45907 errors:0 dropped:0 overruns:0 frame:0
 TX packets:24117 errors:0 dropped:0 overruns:0 carrier:2
 collisions:0 txqueuelen:1000
 RX bytes:56024505 (56.0 MB)  TX bytes:2411029 (2.4 MB)

eth1      Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 UP BROADCAST RUNNING SLAVE MULTICAST  MTU:1500  Metric:1
 RX packets:11506043 errors:2 dropped:0 overruns:0 frame:2
 TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000
 RX bytes:3058301702 (3.0 GB)  TX bytes:218 (218.0 B)

eth2      Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 UP BROADCAST RUNNING SLAVE MULTICAST  MTU:1500  Metric:1
 RX packets:8062484 errors:1 dropped:0 overruns:0 frame:1
 TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000
 RX bytes:1434906118 (1.4 GB)  TX bytes:250 (250.0 B)

lo        Link encap:Local Loopback 
 inet addr:127.0.0.1  Mask:255.0.0.0
 inet6 addr: ::1/128 Scope:Host
 UP LOOPBACK RUNNING  MTU:16436  Metric:1
 RX packets:48 errors:0 dropped:0 overruns:0 frame:0
 TX packets:48 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:0
 RX bytes:3948 (3.9 KB)  TX bytes:3948 (3.9 KB)

Now that we have the bonding interface up, we need to write the configuration in /etc/networking/interfaces so that they will be brought up at boot time.  After struggling with this for a few moments, I finally found out the proper rules needed in order to do this:

1. You have to define your bonding interface first.
2. You must use an “up” statement to specify how to bring up the interfaces. We will be using the parameter promisc to ensure that the interfaces are ready for when we install Snort.
3. We must use bonding-specific statements to specify how the bonding interface will be created and for each interface’s role in the bonding configuration.

Edit /etc/networking/interfaces and remove the existing information.  Add the below lines, but be sure to add the proper IP addressing information for your management interface.

# The primary network interface
auto eth0
iface eth0 inet static
 address 172.20.1.253
 netmask 255.255.255.0
 broadcast 172.20.1.255
 gateway 172.20.1.250

auto bond0
iface bond0 inet manual
 bond-slaves none
 bond-mode 0
 bond-miimon 100
 up ifconfig bond0 promisc up

auto eth1
iface eth1 inet manual
 up ifconfig eth1 promisc up
 bond-master bond0
 bond-primary eth1 eth2

auto eth2
iface eth2 inet manual
 up ifconfig eth2 promisc up
 bond-master bond0
 bond-primary eth1 eth2

In the above configuration, the up parameter tells the network scripts to bring up the selected interface up with the promiscuous mode enabled so we can prepare the interfaces at boot time for  listening to network traffic. The bond-master and bond-primary parameters indicate which bonding interface the physical interface should be added to.  Granted for one bond interface it would appear faster to just single keywords however if you decide to set up multiple bonded interfaces, the keywords would lose meaning quickly.

When all is said and configured, reboot the computer.  When the computer comes back up, check ifconfig -a and see if you see something like the below.

root@ids-01:~# ifconfig -a
bond0     Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 inet6 addr: fe80::2e0:b6ff:fe00:a206/64 Scope:Link
 UP BROADCAST RUNNING PROMISC MASTER MULTICAST  MTU:1500  Metric:1
 RX packets:19570074 errors:3 dropped:0 overruns:0 frame:3
 TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:0
 RX bytes:198918392 (198.9 MB)  TX bytes:468 (468.0 B)

eth0      Link encap:Ethernet  HWaddr 00:18:f3:18:1c:25 
 inet addr:172.20.1.253  Bcast:192.168.0.255  Mask:255.255.255.0
 inet6 addr: fe80::218:f3ff:fe18:1c25/64 Scope:Link
 UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 RX packets:46106 errors:0 dropped:0 overruns:0 frame:0
 TX packets:24224 errors:0 dropped:0 overruns:0 carrier:2
 collisions:0 txqueuelen:1000
 RX bytes:56042559 (56.0 MB)  TX bytes:2427777 (2.4 MB)

eth1      Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 UP BROADCAST RUNNING PROMISC SLAVE MULTICAST  MTU:1500  Metric:1
 RX packets:11506719 errors:2 dropped:0 overruns:0 frame:2
 TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000
 RX bytes:3058600599 (3.0 GB)  TX bytes:218 (218.0 B)

eth2      Link encap:Ethernet  HWaddr 00:e0:b6:00:a2:06 
 UP BROADCAST RUNNING PROMISC SLAVE MULTICAST  MTU:1500  Metric:1
 RX packets:8063355 errors:1 dropped:0 overruns:0 frame:1
 TX packets:3 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000
 RX bytes:1435285089 (1.4 GB)  TX bytes:250 (250.0 B)

lo        Link encap:Local Loopback 
 inet addr:127.0.0.1  Mask:255.0.0.0
 inet6 addr: ::1/128 Scope:Host
 UP LOOPBACK RUNNING  MTU:16436  Metric:1
 RX packets:48 errors:0 dropped:0 overruns:0 frame:0
 TX packets:48 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:0
 RX bytes:3948 (3.9 KB)  TX bytes:3948 (3.9 KB)

Now to install it…

In order to install this machine where it will be most effective in your network, there are some things to consider:

• What kind of Internet access do you have? (Cable, DSL, FiOS, etc…..)
• Does your ISP require running a program on your router to connect? (like PPPoE clients, RASPPPoE, others..)
• What is considered the “edge” of your network?
• Where is the location where the IDS would have most visibility to the network traffic generated by your computers either wired or wireless?

In most corporate networks, there is a single switch that handles all the traffic for a network. This makes things a loss less complex as the network traffic is in one place however in most homes, this is simply not the case.  At least in my network, there’s at least four switches between the router (my edge) and the innermost device (my Wireless Access Point). Since I wanted all the traffic monitored, I elected to connect the passive tap between my router and the first switch.  Any internet activity generated by any device on the network will be monitored by the IDS and if malicious will generate an alert.  If you have only a couple of PCs that are wireless but have several embedded devices like gaming consoles or media streaming boxes (not media center PCs, more like Boxee boxes and the like) you may want to move the passive tap between your wireless access point and the switch connecting the embedded devices as they are a lot less likely to generate malicious traffic.  Your configuration may be different, but when in doubt, installing the passive tap and your soon-to-be IDS between your edge router and the rest of your network is a safe bet.

What’s Next?

We’ve covered how to build a passive tap. We just covered how to configure bonding for the passive tap.  In the final article in the series, we will discuss how to install Snort and make this machine into a full blown IDS device.

Happy Hacking!

FIRESTORM_v1

One of the things that the GCIA study has taught me is that being able to monitor the network your computer is on is a critical necessity to maintaining a secure network. Corporate environments can set up IDS devices to monitor traffic however monitoring doesn’t work unless you have proper connectivity to what you want to monitor. Unfortunately, most of us don’t have central wiring in our house and expensive managed switches that can set up span sessions with which to monitor traffic in transit.  In this HOWTO, I will cover how to build your own monitoring connection that you can use on your own network to monitor traffic without breaking the bank. This article is first in a three part series on how to build your own home IDS for monitoring your network traffic. Look for the other two sections soon!

A little bit more info first…

In the early days of affordable Ethernet networking, devices called hubs (or repeaters) were used to bring the signals together from each workstation in order to allow the workstations to communicate with each other. When a packet was sent to the hub, the hub repeated the packet across all ports on the device and all other workstations would receive it, even if it was not destined for that particular workstation.  The hubs gave way to switches as networking technology became cheaper and faster. Unfortunately, the switches also changed the old way of signal transmission. When a workstation sends a packet to a switch, it is sent from the sender’s switch port  and arrives at  the switch port of the workstation that the packet is destined to. It does not get sent to other workstations’ switch ports unlike the hub’s transmission method.  Because of the need for network monitoring, more advanced switches started offering monitor ports (Cisco calls them span sessions) that are used to forward all traffic that goes through a switch out of this specifically configured port.  This port would then be connected to the monitoring device and would allow the monitoring device to “listen” to all packets that traversed the switch.

The good thing is that most if not all managed switches support a monitor port however the bad thing is that a managed switch is way outside the pocketbook of most home network users.

But why not use a hub?

A hub would allow us to listen in on network traffic however a hub would degrade your network’s performance thanks to it’s lack of proper high speed flow control and its susceptability to collisions.  In my testing, I used a 100baseT hub between my firewall and my network and found that my previously rock solid network connection had dropped well below speed and would barely support YouTube streaming, much less Netflix.  Instead of using a hub and risking continued degradation, I decided to research another solution.

So, what’s the solution and how do I use it?

The solution is the Passive Tap.  This device sits between a unmanaged switch and a computer or router and allows a monitor device to listen in on the network connection between a computer and switch.  The word passive in this instance means that there is no way to detect the device’s presence. It does not have a MAC address, it does not repeat. For all intensive purposes, the tap does not exist.

In the image above, we have connected the Passive Tap between a network switch and a monitored host in order to monitor traffic between the host and other machines on the network (in this case the Server).  This would be an ideal setup for monitoring traffic generated by the monitored host and the rest of the network with the focus being on the monitored host. In this configuration, the monitor device would pick up all traffic destined to or originating from the host and any broadcast traffic generated by the network.

This configuration is a bit different than the first image however the scope of the monitor device’s visibility has changed. Instead of just monitoring the Monitored Host, this configuration allows the monitor device to monitor any Internet traffic that passes between any host on the switch and the firewall. If there were additional devices connected to the switch (other desktops, an Xbox, a Wifi Access point, etc..) their communication with the Internet would also be monitored.  The only communication that would not get monitored would be communication between the devices plugged into the switch (for example the Monitored Host and a Wifi Accesspoint, etc.)

Parts List

In order to build a passive tap, you will need the following items.  The parts themselves cost me about $20 at a computer store which is a lot better than the $200 that some eBay sellers want.

• A cat-5 patch cord
• A surface mount biscuit jack / modular mounting box. (See picture below)
• Two CAT5 keystones (they don’t have to be green/red like mine)
• Screwdriver
• Wire cutters/blade
• A M110 punch down tool (If you have one, it makes the installation easier)
• A monitoring computer with two network interfaces and Wireshark installed (windows) or tcpdump(linux)
• A test computer (or device) with one network interface
• A network switch.
• Beer (optional)

Parts

Here’s an image of the parts. The biscuit jack on the left, the two keystones are in the center and the patch cord is on the right.

We’ll start off by first taking a look at the keystones up close.

Keystones

These keystone jacks are wired up and marked in such a way that all you need to do to wire it up properly is to follow the color code. A closer inspection will reveal that there are small numbers in between the symbols for the wire positions. In this page on twisted pair wiring, you can see that of the four pairs in a Cat-5 10/100 cable, only pairs 2 (white/orange) and 3(white/green) are used.  In order to properly receive both sides of the conversation on the wire, we will need to “tap” into both pairs and route them to the proper pins on the two keystones to each jack’s Pair 2 (receive pair) so that the data being sent can arrive at the NIC of our monitoring device.

If you scroll down to the section labeled “568A and 568 B Color Schemes”, you will see that the receive pair is on pins 3 and 6 of the diagram jacks.  Our keystones are similarly labelled and when we are done, we will have one pair of the Cat-5 patch cable going to pins 3 and 6 of one jack, and the other pair of the Cat-5 patch cable going to the other jack.

Let’s get started.

First off, it is important to understand that you must be able to do this WITHOUT NICKING OR CUTTING THE WIRES.  A cut or nick could result in either your tap not working properly or the tap getting all the data but your connected host doesn’t or any one of a whole handful of issues.  Thankfully, Cat-5 patch cords are not very expensive, but it still sucks to put a project on hold because a slip of the knife.

To start, lay out the patch cord and decide on where you want the tap.  Since the hosts are closer to my monitor machine, I’ve decided to create a short end and a long end with the tap being more towards one end.  You may want to have the tap in the middle or very close to one end of your patch.  It electrically does not matter.

Strip back about two to three inches of jacket so that you have something like below.

Stripped Wires

Mount the keystones in the surface mount box as shown below.

mounted keystones

Now that they are mounted, we will then need to take a look at which pair of pins we need to match the wires up to. Below is a better side-view pic of the green jack in detail.  Please note, your jacks may appear different, but all CAT5 keystone jacks that I have seen have both a color designation and a numeric designation. Be sure to pay attention to which is which and where you are placing your wires otherwise it may not work.

Wire/Pin designations

You can click on the picture for a larger more detailed image.  In the above image (using the top set of colors as a guide) we see that the orange/white hash is pin 3 and the solid orange is pin 6. The same goes for the red jack (not shown).  That being said, untwist the orange and green wires, and place them into their respective slots. Make sure that the solid wire goes with the solid pin and the hashed wire goes with the hashed pin. A reversal here will cause the monitor port not to receive data and could affect your host/switch.

Wires ready to crimp

In the above photo, you can see that the white/orange pair are lightly inserted into the wire channels.  If you don’t have the M100 punch tool, you can get away with using the wire caps that came with your keystones.  These caps will push down the wire and crimp it into place over a metal pin that connects the wire to the pin in the jack.  When you are done, you will have something akin to the below:

Tap ready to close

Also of note: To act as a strain relief, I have added tiewraps on the cable. This will serve to protect the cable from getting yanked out and damaged.  In this picture, you can also see the two white caps that have punched the wires down in place. Reassemble the jack and make sure to install the screw in the lid if your jack has one.

Completed Passive Ethernet Tap

Here’s the completed tap in all it’s glory!

Testing the Tap

In order to test the tap, we need at least two computers, one of which must have two network adapters.  The computer with one network adapter will be our “test host” and the other computer will be our monitoring host.  On the test host, I have assigned the IP address 10.0.0.2 and on the monitoring computer, I have assigned one interface (eth0) with the IP of 10.0.0.1.  The monitoring interface (eth1) will have no IP address assigned to it and will be for testing the tap.  Remember that as far as the test host is concerned, the tap is just a CAT-5 patch cable.

Before proceeding, mark the passive tap where the Ethernet cables come out as A and B.  This will be important as this test will also help us label which side of the conversation we are listening to.  One side will be considered “Network to Host” and the other will be considered “Host to Network”.  It is imperative that we get both sides of the conversation, each side represented by one of the two keystone jacks. While it might not be important now, later on when you use this tap for something else (like an IDS project), you will need to know which side of the conversation you are listening to.

To get your test rig set up, connect the long side (side A in my case) of the tap cable to the switch.  Connect the short side (side B in my case) to the test host.  Connect the ethernet interface on the monitoring machine to the switch, but leave the  unmonitored interface disconnected.  Keep in mind that on my monitoring machine, eth0 was the interface with the IP address, and eth3 was the interface that will be used for monitoring. I’m using Linux on my system, you may need to make adjustments where needed.

• On the monitoring host, ensure that you can ping the test host before hooking up the monitoring interface to the tap.
• On the monitoring host, open two terminal windows
• In the first window, start tcpdump using this command:  sudo tcpdump -i eth3 -nvs0 -c 10 ip[9]=1This translates to start tcpdump on eth3, no host resolution (-n), verbose mode (v), no snapshot length (s0), for a count of 10 packets (-c 10) and only on ICMP protocol (ip[9]=1).
• Attach the monitoring interface to one of the two keystones.  I picked the red jack.
• In the second window, ping the test host using the -c 5 parameter:  ping testmachine -c 5 The -c 5 tells ping to try 5 times.
• You should see the below text in your ping window:

$ ping  testmachine -c 5
PING testmachine (10.0.0.2) 56(84) bytes of data.
64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=7.25 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=0.685 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=0.719 ms
64 bytes from 10.0.0.2: icmp_seq=4 ttl=64 time=0.746 ms
64 bytes from 10.0.0.2: icmp_seq=5 ttl=64 time=0.704 ms

• Your TCPDUMP window should show something like this:

21:48:59.093624 IP (tos 0x0, ttl 64, id 27270, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 24899, seq 1, length 64
21:49:00.088502 IP (tos 0x0, ttl 64, id 49871, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 24899, seq 2, length 64
21:49:01.087486 IP (tos 0x0, ttl 64, id 36772, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 24899, seq 3, length 64
21:49:02.086630 IP (tos 0x0, ttl 64, id 27025, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 24899, seq 4, length 64
21:49:03.085505 IP (tos 0x0, ttl 64, id 28037, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 24899, seq 5, length 64

• Keep in mind that there are two packets associated with ping. One is an ICMP Echo Request and the other is an ICMP Echo Reply In this case I received the echo reply which means that the red jack is for “Host to Network” monitoring or B->A. If you got ICMP echo request, then your jack is A->B.
• Mark the jack as B->A and continue testing. At this point, we know that our tap at least hears half the conversation.
• Switch the monitor interface to the other jack (Mine is green) and rerun the ping.  Your ping should show the below just like before:

$ ping 10.0.0.2 -c 5
PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.
64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=9.69 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=0.705 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=0.663 ms
64 bytes from 10.0.0.2: icmp_seq=4 ttl=64 time=0.722 ms
64 bytes from 10.0.0.2: icmp_seq=5 ttl=64 time=0.714 ms

• This time, however, the TCPDUMP output should have changed:

22:00:28.084339 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.1 > 10.0.0.2: ICMP echo request, id 40269, seq 1, length 64
22:00:29.077220 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.1 > 10.0.0.2: ICMP echo request, id 40269, seq 2, length 64
22:00:30.076215 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.1 > 10.0.0.2: ICMP echo request, id 40269, seq 3, length 64
22:00:31.075218 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.1 > 10.0.0.2: ICMP echo request, id 40269, seq 4, length 64
22:00:32.074214 IP (tos 0x0, ttl 64, id 0, offset 0, flags [DF], proto ICMP (1), length 84)
 10.0.0.1 > 10.0.0.2: ICMP echo request, id 40269, seq 5, length 64

• Just like before, I received 5 packets however last time I got the ICMP echo reply, this time I got the ICMP echo request.  This means that the green jack is the A->B connector, that is Network to Host. Mark it as appropriate.

If you’re at this point, then you have demonstrated that the tap works.  It allows the test host to communicate with the network unimpeded, it also allows the monitoring of host to network and network to host data.  My passive tap looks like the one below:

Finished Passive Tap

Now what to do?

At this point, with a good passive tap in hand, you have a whole bunch of things you can do. You could:

1. Establish an IDS for your network (my original plan)
2. Monitor a host’s traffic exchange with the network/Internet.
3. Perform traffic reconstruction for analysis.
4. Monitor network communication between your Wireless access point and the rest of your network

Troubleshooting

Unfortunately, I can’t account for every situation however there may be some situations where the tcpdump test doesn’t exactly work as planned.  Here’s some common solutions if your tests don’t work quite right:

I can see the A->B traffic, but can’t see the B->A traffic. The ping window shows the host responds. (or)

I can see the B->A traffic but can’t see the A->B traffic. The ping window shows the host responds. (or)

I can not see any traffic, but the ping window shows the host responds.

Check your wires on the keystone and make sure the wire went down onto the metal pin. Sometimes when using the caps to crimp down the wires, one of the wires will shift at the last second.

I can see the ICMP Echo Request  on one port but I see nothing on the other. The ping window shows that the host does not respond.

Check to see that the wires didn’t rip apart or that they were not nicked in the construction process.

Last Thoughts

Even if you don’t plan on building a home IDS, having a passive tap in your toolbox is a good idea.  You never know when you will need to intercept and analyze traffic between two devices on a network. This device will allow you to do so with minimal effort and cost all while allowing the host to chatter away unimpeded by the monitoring.

Happy Hacking!

FIRESTORM_v1

Foreword

Please note that per Notch (the Minecraft developer), running the Multiplayer server is still in beta phase so expect it to crash, be buggy and generally not work.  That being said, I can personally tell you that Minecraft Server DOES work and except for a few minor gameplay glitches, the server works quite well. Please keep in mind that this is by no means an exhaustive article on all things Minecraft Server, nor is it written in stone (ba-dum-thish!) as the Minecraft Server application may change.  If it does, I will make changes to this article to keep it current.

I can tell you that having your own Minecraft server is awesome and that you will never go back to playing singleplayer as you won’t have to worry about files to migrate and that your world will continue to evolve even as you are not playing.  This being said, before you disconnect your Minecraft session, it is recommended to make sure that your minecraft player is somewhere safe, be it in your bunker or somewhere where baddies can’t get to you while you are away. Remember, just because you’re not logged in, doesn’t mean that the world stops.

System Requirements

The System Requirements for Minecraft Server have yet to be officially established however there are some guidelines that have turned up during my research into this topic.  The below is a guideline only and not an exhaustive set of requirements.  It’s perfectly fine if you don’t meet all of them however expect performance hits depending on how you use the server.

• Processor: At least a 1.5GHz single core chip, whichever architecture you desire.
• RAM:  At least 1.5GB FREE RAM. If you use the server for anything more than Minecraft, make sure you have at least 1.5GB free RAM at full utilization.
• Disk: At least a 20Gb disk, with swap space allocated. (Using the “Use Full Disk” and “Automatically Setup Partitions” options in the Ubuntu Setup will ensure you have enough swap.  Although the game isn’t that big, the save files and caching elements will be quite large so of course the more the merrier.
• Networking: 10/100 Ethernet is recommended.
• Video:  Doesn’t matter. We will be running Minecraft Server in a Screen session, so there’s no need for a fancyOMGWTFBBQ video card. Save that for the rig you will play Minecraft on.

Please note: In order to take advantage of Minecraft Server, you must purchase the game from Notch at www.minecraft.net and have a username and password. You will still need to use either the Minecraft Beta standalone application or the Minecraft Beta web-based application to access your server.

This is the basic setup of a good single person Minecraft server. While the possibility exists that you may be able to run multiple connected players on the specs above, if you are planning on hosting a lot of players, you may want to consider a beefer rig. My Minecraft server uses the below stats:

• Processor: Dual Core Intel Core 2 Duo 1.86GHz
• RAM:  3.5GB DDR-2
• Disk: 80GB SATA
• Networking: 10/100/1000 Ethernet (onboard)
• Video: whatever’s on the motherboard.

Getting Started

This HOWTO will already assume you’ve installed your core Ubuntu Server installation and have performed no additonal steps. Login with your user account that you created during setup and perform the following steps. While you can technically prepend “sudo” to each command, I find it faster and less frustrating to just “sudo bash” and type your password once.

• apt-get update
• apt-get install openssh-server
• apt-get install screen

This will install the OpenSSH server so you can remotely manage the server.  You will need a client like PuTTY (download from here) in order to access it.  This will also install Screen which will contain the Minecraft server process.  If you don’t install screen, you will not be able to exit the SSH session without the Minecraft server being killed off.

Now for the fun part.  You will need to install Java in order to start the Minecraft server but Minecraft server will require the use of only the Sun JVM. I tried with the other JVM and it did not work at all.

• apt-get install sun-java6-bin sun-java6-jdk sun-java6-jre

In order to ensure that the java environment is correct, run the command “java -version” and make sure it matches the below text.
# java -version
java version “1.6.0_22″
Java(TM) SE Runtime Environment (build 1.6.0_22-b04)
Java HotSpot(TM) Server VM (build 17.1-b03, mixed mode)

If it shows something else, you will need to do the following:

• update-java-alternatives -l

This will list off all the various Java VMs that are installed.
# update-java-alternatives -l
java-6-openjdk 1061 /usr/lib/jvm/java-6-openjdk
java-6-sun 63 /usr/lib/jvm/java-6-sun
You will need to set the proper Java VM to use via the below syntax:

• update-java-alternatives -s java-6-sun

Now, run “java -version” again and it should show the same version information as above. If it does, you’re good to go otherwise check your error messages.

Please note that the rest of these commands are run without root privileges. NEVER EVER RUN MINECRAFT SERVER AS ROOT!

Installing Minecraft Server

If you’re this far, then you’ve got the Java VM set properly and your server is all set for Minecraft Server.  You will need to download the minecraft_server.jar to your computer then use scp to put it on the server. You can download a Windows SCP client called WinSCP from this site. Copy it into your non-root user’s home directory, in my case I’m using “mcserver”.

To start the server, you will need to use the following command:

• java -Xmx1024m -Xms1024m -jar minecraft_server.jar nogui

You will see a lot of text scroll past the screen and you will see it generate a new world via the console messages. Once it settles down, you can then type “help” for a list of commands.

Since we just fired it up, let’s go ahead and stop it. Type in the command “save-all” which forces the server to save the generated map, then “stop” to shut the server down.

Stopping and Starting the server

To start the server, first off make sure you are in a screen session by typing “screen -list” like below:

mcserver@mcserver:~$ screen -list
There is a screen on:
 2434.tty1.mcserver        (01/09/2011 12:58:57 PM)        (Attached)
1 Socket in /var/run/screen/S-mcserver.

This indicates that you are in a screen session.  If you see “(no screens running)” then just type “screen” to start one.

Once in the screen session, type in the command shown below.  This is the exact same command as when we installed it, but this time we’re not going to shut it down.

• java -Xmx1024m -Xms1024m -jar minecraft_server.jar nogui

To disconnect from the screen session, hit Ctrl-A and then the D key, this will drop you back to the shell prompt where you can then type “exit” to logout. The Minecraft Server will continue to run.

To stop the server that is already in a screen session, login to the server using SSH and the non-root user.  To reconnect with the screen session, type in “screen -r”.  You will be reconnected to the server and can then perform the following commands:

• say Server is going down

This lets any players know that the server’s going down.

• save-all

This tells the server to save the entire world.

• stop

This tells the Minecraft Server to shutdown and exit. You will be dropped to a console prompt from there you can shutdown the server or do whatever you need to do.

Other useful commands in MC Server

Console commands:
 help  or  ?               shows this message
 kick <player>             removes a player from the server
 ban <player>              bans a player from the server
 pardon <player>           pardons a banned player so that they can connect again
 ban-ip <ip>               bans an IP address from the server
 pardon-ip <ip>            pardons a banned IP address so that they can connect again
 op <player>               turns a player into an op
 deop <player>             removes op status from a player
 tp <player1> <player2>    moves one player to the same location as another player
 give <player> <id> [num]  gives a player a resource
 tell <player> <message>   sends a private message to a player
 stop                      gracefully stops the server
 save-all                  forces a server-wide level save
 save-off                  disables terrain saving (useful for backup scripts)
 save-on                   re-enables terrain saving
 list                      lists all currently connected players
 say <message>             broadcasts a message to all players

Quick and Easy Start script

Below is a very simple script I wrote because I kept forgetting all the java commands.  In order to use it, save both lines below as a file (like “startmcserver.sh”) and then “chmod +x startmcserver.sh” so that way you can start the server simply by running “./startmcserver.sh”

#!/bin/bash
java -Xmx1024m -Xms1024m -jar minecraft_server.jar nogui

Remember to keep both lines intact.  It’s essentially the same Java command, but it’s easier to type.

Have fun and Happy minecrafting!

FIRESTORM_v1

The Parallax VGA GUI Demo is great for adding a pre-built GUI for your projects. The bonus is that the drivers for using a PS/2 keyboard and mouse and a VGA display are pre-built and ready to run.  With a little bit of configuration, you can add a well built UI to your application and make it easier to display output and receive input from the user.

In this article, I will demonstrate some of the basic options that are needed in order to get the GUI up and running.  While our application is going to be turning on a few LEDs, once you have these basics down you should be able to use this article and build whatever user elements are required for your application.

Prerequisites:

If you haven’t already, I would recommend the Parallax PS/2 and VGA Adapter board. This board provides two PS/2 ports (mouse and keyboard) and a 15 pin VGA port in an easy to use modular design that is breadboard compatible.  Here is a link to the VGA board on Parallax’s site and here is the link to my earlier article.

In addition to the Adapter Board, you will need
- A PS/2 mouse (Not a USB mouse with a PS/2 adapter)
- A PS/2 keyboard (Not a USB keyboard with a PS/2 adapter)
- A 15 pin VGA monitor
- six LEDs, any color
- six 100 ohm resistors (Brown-Black-Brown)
- Jumper Wires for the Adapter board
- A PC with USB port for the PropPlug USB programmer.
- 9V Battery or other 9VDC power source

Understanding the concept of a UI

Before we get started, let’s discuss the basic differences between a Prompt and a UI.

A Prompt:

• – asks for something direct like “Your Name”
• – Reads the response, Input halts until requirement satisfied, e.g. (Press any key to continue)
• – Treats the response as programmed, e.g. $YourName
• – is programmed in a linear fashion. e.g. You prompt for your name, then you prompt for your address, then you prompt for your date of birth, etc…

A GUI:

• Shows multiple items to interact with
• Reads a response when triggered with an event and does not wait.
• Performs actions based on event triggers.
• Can perform actions in a non-linear fashion. e.g. Clicking Button 1, Button 3, Button 2, Button 6, Button 1 again.

Remember, although a GUI can contain prompts (“Click OK to Continue”), it’s not often that a prompt becomes a GUI. Also remember that a GUI is Event driven, not prompted.

Events

It’s important to understand that performing any action with the mouse and keyboard triggers an event. It’s when the event (in most cases, a mouse click) occurs on a GUI element (a checkbox for example), we get something to happen.  By programming the Parallax GUI Demo, you will build GUI Elements (things to click on or type into) using Mouse and Keyboard Events in order to generate some kind of output (Lighting LEDs).

Keep this in mind, as generating events and how to deal with them are the cornerstone of any GUI programming (not just Parallax!).

Elements

Mouse events are nothing without something to interact with, so that brings us to the point where we have to talk about the GUI. Each object in a GUI, checkboxes, menu items, windows, submit buttons, etc. are all considered elements of the GUI. We build the GUI using elements to satisfy our program’s needs.  For the “What is your name?” prompt, we would need a window element (with a Window Title element), a text element saying “What is your name?”, a text field element (so we can get the name back to the program) and a submit button element.  That’s Five elements! Thankfully, only two of them are interactive.  The text field needs to be clicked on (to tell the GUI that keyboard input goes here), and the Submit button needs to be clicked on to tell the program to continue.

Even though we started out with five elements, thankfully we only have to code for two events.

Below is a screenshot of various elements that the Parallax UI is able to generate.

Parallax VGA Demo Screenshot

In this screenshot, we can see the following interactive elements:
- Spin Boxes – A single element with up and down arrows that allow you to select from a list of predefined options. (like a Page Count field on a Print window)
- Checkboxes – A listed series of predefined options that allow for multiple options to be selected.
- Radio Buttons – A listed series of predefined options that allow only a single option be selected.
- Pushbuttons – A single element that is clickable (like a submit button).
- Menu Bar – A horizontal element containing multiple pushbuttons.
- A Text Input field – Another horizontal element that takes input from the keyboard.

We also see the following non-interactive but still needed elements:
- Windows – We need windows to keep these elements organized, otherwise it doesn’t work too well.
- Status Lamps – Think of these as the GUI equivalent to an LED and resistor. They can be toggled on or off.

Now that we know what all the elements are, let’s do something.

Getting the hardware ready

Connect the 15 pin VGA/PS2 breakout kit to the lower right hand corner of the breadboard as shown in the image below. The breadboard should be oriented as shown with the PropPlug mounted on the top, usb cable pointing right. You can then connect the 12 pins straight across (watch out for the crystal) to the 12 pins on the right hand side of the Propeller (P16-P27).  Attach the Vss lead to any of the Vss busses (black lines) on your breadboard.

VGA adapter hooked up

In order to get the required +5V for the PS/2 mouse and keyboard, look closely at the two voltage regulators at the top of the board. There is an LM2940 (back regulator on the picture below) that provides the 5V and a LM2937 (front regulator) which provides a 3.3V source for the Propeller. Be sure to attach to the OUTPUT of the LM2940 as shown in the picture below.  As a hint, my wire is in the third horizontal row from the top of the LM2940 which is its output lead.

+5V location

DO NOT CONNECT YOUR +5V LEAD TO THE +9V BATTERY OTHERWISE DAMAGE TO THE PROPELLER, MOUSE AND KEYBOARD MAY RESULT.

After you have the VGA adapter connected, hook up the LEDs so that the cathodes go to ground and the anodes run through the 100ohm resistors to P0-6 as shown below.

LED connection

Get the software

If you haven’t already done so, download the VGA Text GUI Demo from here:  http://obex.parallax.com/objects/413/

Unzip the archive, load it up in your Propeller Tool application and load it into RAM to save write cycles on your EEPROM.  If everything works properly, you should be able to move the mouse, click on things and be able to type text in to the “COMMAND” field at the bottom. Play around with it for a bit and get used to how the elements interact with each other.  If you want to ensure that your wiring is correct, read the GUIDEMO and GUIBASE section below.

Before proceeding, it’s recommended to make a backup of the unzipped Propeller VGA demo so that you will have something to refer to in case you accidentally delete part of the demo application. Load the copy of the code for the next step and leave the original copy untouched.

Hacking up the Code

Now that you’re up and running with the test code, let’s take a look at the existing code and start modifying it.  We’ll cover important aspects of the existing code along the way. In our application, we will be using the UI to draw a simple window containing six checkboxes that correspond to the six LEDs we have installed.  Once finished, when we check a box, it will light the corresponding LED. If we clear that checkbox, it will extinguish the LED.

So let’s get started.

GUIDEMO.spin

The GUIDemo.spin file is considered the “Top Level” or “root” (if you’re a Linux admin like I am) of the entire  application. This file references sub-codebases through  an OBJ (Object) declaration. Although Parallax called it Top Level, I have always referred to it as the “root” as in the root of the project much like the root of a filesystem.

Without getting into the syntax of Spin (the Propeller coding language, a topic that Parallax is much better suited for than I am) just know that this is the trunk of the tree as far as all other pieces of code in the VGA Demo are concerned.

Code Heirachy

Starting at the top of the GUIDemo.spin file, you see a secion labeled CON. This is for the constants that GUIBase uses to initialize the PS/2 mouse and keyboard and the 15pin VGA port.

The vga_base should point to the I/O pin that is connected to the “V” pin of the PS/2 VGA adapter. The GUIBase will assume that the rest are mapped accordingly.  If you are using something other than the Parallax adapter, you will want to ensure that your adapter is wired up as shown below:

I/O Pin        Function
P16        V – Vertical Scan
P17        H – Horizontal Scan
P18        B0 – Blue Positive?
P19        B1 – Blue Neutral?
P20        G0 – Green Positive?
P21        G1 – Green Neutral?
P22        R0 – Red Positive?
P23        R1 – Red Neutral?

* Please note, the ?’s mean I’m not certain on polarity, but I am sure on the grouping. The reason is that I only have the Parallax VGA adapter so I haven’t tried to fabricate my own adapter.

The mouse and keyboard each require two pins, “dat” and “clk”.  The Parallax Adapter has each pin’s function silkscreened onto the adapter’s PCB for easy connection and are mapped as shown below:

I/O Pin        Function
P24        Mouse Data
P25        Mouse Clock
P26        Keyboard Data
P27        Keyboard Clock

If you’re using Parallax’s VGA adapter, then make sure that your values match what is shown above.  If you are using another adapter, make sure that the values match your respective device’s pins.

The OBJ section is where we declare any additional code that needs to be included. In the original code, you can see there are three objects declared (GUI, TMRS and NUMS) however for our program, we only need the first one (GUI).  Delete the two lines starting with TMRS and NUMS highlighted in the green square in the image below.

External Objects

When it comes time for you to add your own routines, you can include them here by defining them as objects. For now, just scroll down to the next section.

The VAR section is important because the code shows that all of the interactive elements in the GUI require a byte be assigned to them. This is important as this is how the GUI keeps track of what element is called when an event is triggered. It is critical to remember when you are designing your own GUI, that each interactive element has it’s own unique ID. This will be important later when we tie the elements into events. For now, remove all the declared bytes and add the below in it’s place:

Variable Bytes

In the above image, we are declaring six CHKB elements numbers 1 through 6.  The naming convention is important as there is code later on where these get defined.

Scroll down to the PUB statement below. This section is the actual code of the program and where we will be doing most of the editing.  First off, make sure that you can see between the CreateUI statement and the PUB statement (top of the blue section of code as pictured below. We will be removing the code there as it was used with the timers code object (that we removed) was initialized at start.  Just like before, delete all the code within the green box. It’s not needed and will generate errors if you attempt to compile it.

PUBlic function to delete

We will replace the deleted code with our own code. This  is the initialization code for our application and occurs prior to the GUI being set up. All our code does is ensure that the first six I/O pins (P0-P5) are set as outputs and are set low so that the LEDs are off.

When you are developing your own program, be sure that the initialization code occurs before the CreateUI statement for best results.

PUBlic INIT code to add

At this point, we have removed excess objects from our code and declared six variables for our checkbox elements and we have initialized the LEDs. Now we will tell the application what to do when an event has been triggered in order to get the LEDs to light up.

If you look at the code, you will notice that it is a very large repeat loop that contains a case loop inside it. The way it works is that the Propeller will constantly evaluate GUI.ProcessUI. When evaluated, it will check gx against the list of elements and if gx matches a defined element ID, it will then perform the appropriate action.

For now, start at the line that reads “case gx” and highlight the text down until you get to the “START OF UI HELPER FUNCTIONS”. Since we are not using the demo code in our application, we can safely remove it.

Once removed, add the code in the below image to tie in the events with our custom function. (We’ll write it next).

Public Events to add

In the above code, we are calling LEDFunction with a different parameter corresponding to each of the six LEDs. Now we need to write the function LEDFunction so it actually does something.

In your application, you may end up writing all of your code in another .spin file and then using an OBJ to declare it.  If you do that, then you can reference your OBJ functions instead of using a basic function here.

Start off by copying that CON statement and inserting it into the empty space. This will create a line we can use when reading the code to make it easier.  Change it from “UI HELPER FUNCTIONS” to “UI APPLICATION FUNCTIONS” and add the below code as shown.

PRIvate Function to add

In this section of code, we will write our function for the events.  All we are doing is taking the function’s parameter and inverting it’s existing value. If it’s 1 (on) it is then set 0 (off) and vice versa.  Although we return the value of the I/O pin, it is not used elsewhere and will get overwritten elsewhere.

Scroll further down and we finally get to the CreateUI function.  This is where the UI gets built and the bytes for the elements earlier get defined.

We can see that there are a lot of commands listed here. Don’t let that intimidate you as we are going to remove most of them. Find the line that starts off with “vga_cols” and highlight all the way down to the MIT License.  Remove the code and add the code in the picture.

GUI Code to add

This code draws out the Text box for our project and gives it a text label. Don’t worry about the syntax, we’ll cover that in the GUI CODE section later.

Basically what happens here is that a Simple Box (SBOX) gets drawn with the title of “LEDs”.  Inside that box, six checkboxes are drawn, each with their own text description. Pretty straightforward on the UI, right?

We’re almost done and ready to test our new GUI.

GUIBASE

Now, there’s one more thing we need to do before we go loading this project into RAM and seeing if it works. We need to make an edit to GUIBase.
At the very top of GUIBase, in the CON section, you can see that there is a note describing the GUI Element Inventory that must be present.  We need to edit the code and tell GUIBase that we’re only using six checkboxes.  However, as the note describes, we can’t just go set GZ_CHKB to 6 and all others to 0, as this would throw a compiler error.

Go ahead and set all of the GZ_ variables to 1 except for GZ_CHKB which will get a value of 6 since we have six LEDs as shown below.

GUIBase changes

Once modified, be sure to save your work and then go to “Run”, Compile Top, Load RAM.  You should get something like the below image on your display.

Our GUI LED demo

If all went well and you didn’t get a compiler error, you should get this GUI.  The little green square is the mouse cursor.  Go ahead and try it out. Make sure that checking each checkbox lights up an LED and that clearing the checkbox turns it off.

Now that we’ve got a working GUI up and running, let’s review what all we did aside from removing a lot of extra stuff.

• We declared a byte for each GUI element.
• We added initialization code.
• We added a declaration in the main loop to handle events from the UI to point to our function
• We wrote a function that did something based on the events we had given it.
• We updated GUIBase with the element count so that the GUI code knew how much it had to work with.

These are the fundamental steps for creating a UI with the propeller using the GUIBase code. Now that you understand the basics as far as what is required, let’s take a look at some other stuff you can do too.

Looking further into the GUI Code

In the GUIBase.spin file, you can find the code required to draw the various elements of your GUI.  Reading through the code,  most of the options required are in terms of position.  For example, the code for the simple box (window) shown earlier, required an X and Y coordinates (in rows/cols) to place the upper left hand corner of the UI, then the width and length of the box and a title.  The Checkboxes each required an X and Y coordinate, then a text length and finally a label.

If we were to use a Radio Button group, we would need to provide an X and Y coordinates, a text length, a text label and a Group ID.  The Group ID is used to associate the radio buttons together.  Below is a screenshot of my implementation along with an Apply button:

Radio Buttons and Pushbutton code

In the above code, you can see that I have established five radio buttons (RADIO1 to RADIO5) in addition to PUSHBTN1 pushbutton. These are set up in the main loop below:

Push Button UI Code and Functions

In the above code, you can see that the SetLEDStorage passes a number which gets stored in LEDState. When the Apply button is pressed, CommitLEDs takes LEDState and sets the six LEDs to the binary value of whatever was in it.  Below is what the UI looks like:

Radio Button GUI

Just like adding the checkboxes, I followed those same steps here:

• – I declared my additional UI elements’ GUID bytes (RADIO1 to RADIO5), my Radio Button group (RBGID1), my  pushbutton (PUSHBTN1) and my LEDState variable.
• – I added my init code (setting LEDState to 0, not pictured)
• – I added routines for my elements to call user functions. (SetLEDStorage and CommitLEDs)
• – I declared the routines so that they did something (stored the LED value, applied the value to the first six I/O pins)
• – I updated GUIBase.spin with the new list of items ( added five radiobuttons and one pushbutton.)

Give the code a try and you will see that while the checkboxes set the LED state instantly, the radio buttons do nothing until they are applied with clicking on the Apply button. This is important because as you design your GUI, you will need to decide if something must happen when the mouse is clicked right then (immediate action) or if the action will get applied later on via an “Apply” button. This is entirely up to you and there is no need to do things only one way.  Either method works but whether or not it works properly for your application will be your choosing.

Tips and Tricks, and things to watch out for

While developing this article, there were a couple of things I came across that you may want to watch out for. Don’t worry, you won’t blow up your Prop if you make a mistake in coding, however there are a few things you may want to keep an eye on:

• - Load to RAM, load to RAM, load to RAM and check your battery.
  In my writing this article, I found out real quick that driving a display, mouse and full size keyboard will drain a 9V transistor battery very quick.  A symptom of this drain is the Green LED that is present on the Propeller Education Kit. If it starts to pulse and your monitor loses sync, it’s time for a new 9V or consider a 5V USB power cord. Also, to save write cycles on the EEPROM, load to RAM whenever possible. Your computer’s hard  drive is more suited to incremental saves, EEPROMs are not.  Only save to EEPROM when you are ready to test your application in real life.
• - There is no boundary checking.  If you overlap your windows, then there is no going back. When in doubt, you can use the Mouse code to print the mouse coordinates on your project to help you identify and troubleshoot positioning.  Remember that all GUI elements start by defining the upper left hand corner of the element. You will need to include the NUMS object (SimpleNumbers.spin) and the code from the original GUIDEMO.spin (lines 314 to 316) in order to have it show up.  You can see an example of the boundary overlap in the below image.

Button overlaps window

• - There is no off-edge boundary checking either.  If you are setting a text field too far right of the video display or too far down, it will get cut off and your entire GUI will not work right.  In this case, I set the Predefines window to X40,Y75 and 25 columns wide which was out of the limits of the current VGA resolution.  The below image was the result and my UI only partially worked.  Resetting and reloading RAM fixed it.

Window moved out of range

• - Also as demonstrated in the image above, UI elements are not bound to the window you create them under. Assuming that both windows were same size and I mis-typed the coordinates, the Apply button could very easily show up under the checkboxes instead of the radio buttons leading to a confusing display.  You will want to make sure that your UI elements do not overlap at all as this could affect how the UI interprets your mouse actions.

Last Thoughts

There is so much you can do with the Propeller UI to make your applications more interactive.  With little work, you could build something like a serial terminal and embed your project in an LCD monitor or you could make a basic home automation system with a touchscreen LCD and a wireless transceiver. The possibilities are endless and with the Propeller, you can now use full GUI capability with keyboard and mouse support.

As always, Happy Hacking!

FIRESTORM_v1

The reason I haven’t written any more about my fun with the Dockstar was that due to an unfortunate set of circumstances I was left with a bricked dockstar. (read: I did something stupid.)  After performing a lot of research and thanks to a bunch of people over at the PlugApps.com Forum site who helped me, I was able to get it running.  Read more for a complete list of what you will need including how to build an adapter and where to get the needed JTAG kit.

Before we begin

This document demonstrates how to recover your Dockstar and upload a custom bootloader to it using a JTAG cable.  JTAG is used for low-level in-circuit debugging of embedded applications and is very hardware specific. If you are familiar with working with Linksys routers and uploading custom firmware to them, you have heard of the term bricking and you have more than likely heard of something called JTAG that is used to recover it.

Because of the nature of JTAG and the fact that manufacturers don’t typically like us having access to the JTAG port, these ports are often hidden in many different locations, usually unmarked or unpopulated headers, or other odd locations and is the way that the manufacturer loads the firmware for the very first time on to a new device.

By using JTAG, we can place the hardware into a “debug” mode where we can manipulate the microprocessor’s core functionality.  We can also send instructions to it, monitor responses from it, or even pause the chip, leaving it in a state of suspended animation until we issue the command to start it up again or reset the device.

In this particular howto, we will cover how to use the debug mode of the Marvell chip in the Dockstar to upload a new boot loader in order to rewrite the bootloader to the onboard Flash which will result in a working, new Dockstar.  Please note that if you have NOT bricked your dockstar, there is no need to perform the steps in this howto.  This is only for bricked dockstars that have been verified with a serial adapter to be dead. (A dead dockstar will produce NO serial output and the front panel LED will not light up when power is applied.)

Legal Disclaimer

By performing the steps outlined in this document, you agree not to hold firestorm_v1, YourWarrantyIsVoid.com or any other linked sites, forums, companies, liable if you really screw something up.  You can also not hold any of these entities responsible for data loss, physical damage, emotional trauma, spousal abuse or any other act of whatever god(s) that you may have happen to you.  In short, Read twice, type once, hit enter and don’t screw up.  If you’re at this point, then you’ve already come to terms that your dockstar may be unrecoverable already so deal with it.

Parts List

In order to perform this recovery, you will need the following items:

1. The dead seagate dockstar and power supply.
2. A handful of 2.0mm female connectors or one 2.0mm female connector with at least 10 pins (5 pins in 2 rows)
3. A 10 pin header that matches your PCB 2.5mm spacing  (again, 5 pin, 2 row)
4. A bit of holed PCB board 2.5mm pin spacing. (Radio Shack is good for this kind of stuff)
5. A CA-42 cable with the appropriate pins as outlined in my previous Dockstar post.
6. A handful of extra breadboard jumpers.
7. Superglue
8. A Windows PC (2k or XP, untested on vista/7 although plugapps forums says it should work.) with a Parallel Port
9. Whatever provisions needed for the CA-42 cable to work properly.  (I have to use a linux box to SSH to, you can do the same or if your Windows computer works with the CA42 cable, you can use that as well.  You don’t need two PCs for this operation.)
10. A TAIO Buffered/Unbuffered “Universal” Parallel Port JTAG module kit (Here’s the eBay seller where I got mine, ~$21.00 out the door) and a Parallel cable extension (Male to Female) so that you can reach it without having to get behind your PC. For my setup, I used an old iomega Parallel/SCSI Zip drive cable. I also recommend the ebay link as this is the seller that I purchased mine from and it comes with a lot of extra jumpers that are very useful for this project.
11. A USB A to USB mini B cable (for powering up the JTAG adapter).
12. Glue gun with extra gluesticks
13. Heatshrink tubing and lighter/heat source
14. In lieu of building/reinforcing your JTAG cable, you can use a laptop hard drive adapter (3.5 IDE to 2.5IDE) if you’re in a pinch and just need to get it running.

In addition to the above items, you will need the following software applications:

1. Kragorn’s copy of dockstar.cfg – Mirrored Here
2. A copy of OpenOCD – Mirrored Here
3. A copy of the Jeff Doozan’s custom USB-boot capable u-boot (Recommended!) (Mirrored Here) or a copy of another factory or custom uBoot.  If you want to compile your own, there’s a great write-up here: http://jeff.doozan.com/debian/uboot/
4. A copy of PuTTY for Serial/Telnet communication.  You can download it here.

Getting Started

This howto will be divided up into several sections:

Section I:Building an adapter cable – This section will cover how to build the required cable from spare 2MM connectors or if you already have the proper cable, this will describe how to reinforce it for repeated use using heatshrink tubing. I call it a smokestack cable because it resembles a small smokestack sticking out of the Dockstar’s mainboard.

Section II: Wiring it all up – This will cover the Dockstar’s pinout, the TAIO parallel port pinout, the serial port pinout and how to wire it up together.

Section III: Performing the JTAG recovery – This is where the actual recovery process takes place now that we have everything wired up.

Section IV: Notes and credits – As much as I’d like to say this was all my doing, truth is it’s not.  I couldn’t have done it without some great people from the PlugApps forums.

Each section will have lots of pictures that you can use as a guide to make sure you’re making the right connections.

BIG FAT OBNOXIOUS WARNING!!!

Although there are as many JTAG adapters on the market as there fish in the sea, I can not cover each and every device’s unique configuration options. Generally the JTAG port is a universal standard but many vendors implement their own standard, have other standards that they choose to leave out and their pin configurations may not match what is given here.  This article is based on my experience performing the JTAG restoration of a dockstar I broke using the equipment and the software outlined above.  If you are new to JTAG, I recommend using the versions and adapter board listed as other devices/software may not work in the same way.  When in doubt, go with what you know!

Section I: Building out the JTAG adapter cable.

The dockstar’s JTAG port uses a 2.0 mm spacing and while it’s good for tight spaces, isn’t exactly ideal when dealing with breadboard jumpers as most breadboards have a 2.5mm spacing and the jumpers have connectors to match.  In this instance I felt that since I was going to be working on actually developing code for the Dockstar, the inevitable would happen and I would end up bricking it through a random error (namely user failure) and would need a quick and reliable connector that I could use to quickly connect and disconnect the JTAG port as needed during restore and development.

I checked out EPO and managed to find several 2.0mm spaced connectors however these were in groups of three and while they would work, would require significant effort to harden the connectors to something that could stand the test of repeated connections and disconnections. So let’s get started.

Checking the connectors to make sure they would work

This is a shot of the connectors standing out of the Dockstar.  Since I had four connectors with 3 pins each, this means that I had two pins that hung over the connector block on the Dockstar.  Since these two wires were not needed, I cut them and removed the metal connector from inside the plastic, leaving 10 wires for 10 pins of the dockstar’s JTAG port.  We’ll deal with the two vacant holes later.

Little known fact: The pin spacing on the Dockstar’s JTAG port is identical to that of a laptop hard drive (which is why this part of the process is optional.)  In a pinch, you can use a laptop IDE adapter similar to this one (in fact I own several exactly like this).  If you decide to use a laptop IDE adapter, use the part of the adapter opposite the power connector.

Since the goal is to harden the four little connectors to one single connector, I used a dead laptop hard drive and superglued the four connectors together. USE THE SUPERGLUE SPARINGLY!! You do not want to superglue your connectors to a hard drive so only put a tiny amount. It also helps to put a dab of glue on one connector, then put the connectors together as you’re pushing them onto the laptop HD pins.  Make sure they are completely seated so they will be even as possible.  If you see the pins of the laptop HD, you’re not down far enough.

Glued 2.0MM connectors curing on a laptop HD.

Once you get all four connectors onto the laptop HD and properly aligned, let it cure for at least an hour.  This will ensure that the superglue bonds correctly and the connector doesn’t fall apart later.

Glued connectors after the superglue set.

Now that the superglue has set, check that it still fits in the Dockstar. On the connectors used here, my wires were quite long. To alleviate yet another mass of cable snakes on my desk, I cut them down to about three inches, which should be big enough to handle, but small enough to not get in the way. You can cut your wires to any length desired.

In order to solder to the 10 pin header and ensure that the wires would not seperate from use, I chose to use a small piece of PCB as shown below.

Header and Breadboard

Keep in mind that if you cut your own, you’re soldering 10 wires into a 10 pin header, so you will need a 20 hole piece of PCB (5 holes by 4 holes).  The idea here is that the wires will come in on the component side of the PCB and wrap around it then go further down to the 2.0mm connector we just glued together.   Go ahead and solder the header into the center two rows of the PCB as shown below(Leave one row of 5 on each side of the header).

Header and PCB soldered together

Strip off a 1/8 inch off of each wire on one side of the glued connector and solder to the PCB. Keep your pinout the same and do not cross the wires.   Below, you can see that the first half of the PCB and the wires has been soldered.

Header with one side soldered.

Now comes the fun part.  Trying to solder the other side of the PCB without burning yourself or the other wires and without creating unnecessary solder bridges to other pins.  Below is a shot of my connector, partially soldered.

Second set of wires to solder

Protip: If you don’t already have a pair, I highly recommend you get a pair of Helping Hands for soldering like this. Available at Radio Shack and many other electronics outlets.  Below is a picture of the completely soldered PCB.

Completed PCB soldering

Now that the PCB is soldered, go ahead and check your wiring!  Don’t do any pin swaps, make sure that pin 1 on the 2.0mm connector is pin 1 on the header, pin2 on the 2.0mm connector is pin 2 on the header and so on. Also make sure that you didn’t bridge between pins on the PCB. Before you slip on the shrinkwrap, we’re going to reinforce the body of the adapter.  Get your hot glue gun ready and shoot a large bead of glue down the length of the wire. Once that is done, shoot some more hotglue around the connector to reinforce the wires coming out of the connector. Below is a picture of the hotglue process.

Wires hotglued together and header is wrapped in hotglue.

The hotglue on the wire-side of the plug will make sure that the wires don’t wiggle around inside the heatshrink tube and fail later on.  After you’ve properly applied the hot glue, put the tip of the hotglue gun over the two holes that we vacated earlier.  Keep consistent pressure on the hotglue gun and press the trigger.  This will inject hot glue into the holes left behind when the excess pins were extracted and ensure that the connector is “keyed” and will prevent a one-off connection (and prevent further headache).  This is what the hotglue injected connector looks like.

Key-glued header.

Take one moment and check your cable one last time.  Make sure that the pins are wired one to one.  Once you’re ready, get the heatshrink tube and cut it to a little bit less than the length of your adapter.  Below, you can see the heatshrink and adapter lengths I used. (This image was taken before the hot glue was applied.)

Header adapter and shrinkwrap.

Slip over the heatshrink wrap over the connector (it may not fit over the PCB) and leave just a little bit so that it overlaps the 2MM connector end.  Apply even heat to the 2MM connector end first so that it will shrink and hold the heatshrink wrap in place as you apply even heat to the rest of the connector. When completed, you should have a connector resembling the below image.

Heatshrink wrapped adapter.

Now take the hotglue gun and fill in the gap between the heatshrink wrap and the bottom of the PCB. If your gluegun has a fine tip, also shoot some hot glue into the open end of the shrinkwrap.  This will further harden the connector and ensure that it doesn’t flex and damage the connections.  You may have something looking like the below image.

Header Top with glue bead.

For a final touch, wrap and distribute hot glue around the wiring from a little bit over the heatshrink wrap all the way to the black part of the header wiring.  It’s ok to use a large amount of glue as this will make sure that the connector is properly protected.  As a last step, connect it to the Dockstar and make sure it fits.  Once finished, you should have something resembling the below image.

Completed Smokestack adapter on Dockstar.

Now, you have a completed Smokestack adapter.  You can use this for any device that has 2.0MM connector pitch and for any purpose.  Since the header on top is a 1 to 1 representation of the connector on bottom, you can use this anywhere where you need to use breadboard connectors for a temporary connection to these headers.

Section 2: Wiring it all up.

With a completed smokestack adapter, now you can wire it all up together  but before we begin, it is highly recommended to solder in a ground pin.  This ground pin will be used to ensure that the ground used by the JTAG adapter’s reference ground will be the same as the ground used by the Dockstar.  While it may not be required, it is recommended as a difference in ground may end up corrupting data being sent and received as part of the update.  To do that, we can use any of the ground planes, shields or open spots on the PCB.  I preferred to use one of the three USB shields as the shield’s purpose is the same as the GND connection that we are trying to establish.  For this, we’ll use a jumper pin with no plastic on it.  Start off by applying a small bead of solder to the USB shield as shown below.

Dockstar USB shield pin prepped for header pin.

Apply the heat from the soldering iron to the bead again and drop in the jumper pin.  Remove heat and do not touch the jumper pin until the connector has cooled.  Do not apply heat for a long period of time otherwise you may damage the USB port itself.  Below is the completed ground pin installation:

Dockstar Ground pin installed.

Now, we have a properly installed Ground pin that is easy to connect and remove and we also have our smokestack JTAG adapter.  At this point, we can start wiring up the JTAG connector up and prepare for recovery of our dead dockstar.  If you went with my suggestion and ordered the TIAO Parallel JTAG adapter, you should have received the following items.  JTAG board (blue with DB25 connector), Short jumpers (left of  JTAG board) and Long Jumpers (above board) as shown in the picture below.

TIAO Parallel JTAG kit.

The below image is the entire wiring diagram for the Dockstar JTAG adapter.  As long as you keep pin 1 on the dockstar as pin 1 on the smokestack adapter, you should have no problems with the connection.  As mrbill and Klingon and several others pointed out in the PlugApps forums, the nSRST line (orange) and the DINT(purple) leads are both not connected.  Pin 1 on the Dockstar/Smokestack are also left unconnected as we will use the Dockstar’s power supply to power the board while it is connected to the JTAG adapter.  Additionally, it is crucial to plug the USB cable into the JTAG adapter and into a PC to power the onboard buffer chip.  Without the USB cable connected, the adapter will not function.  There is also an LED on the JTAG adapter that will light when the device has sufficient power. Click on the below image to get a much larger image.

Dockstar/TAIO JTAG connection table.

The Dockstar layout diagram on the right hand side of the image is bundled together to provide a reference.  Pin 1 of the JTAG port is on the LED side of the jumper and is towards the center of the board and is designated by a black dot in the image and a white triangle on the dockstar board itself as shown below.  The picture of the Dockstar is rotated 90 degrees clockwise to the layout diagram in the image above.

Dockstar JTAG port showing pin 1

You can use the following images as a reference that your dockstar is connected properly.  The below image is a picture of my CA-42 adapter’s serial header as discussed in the serial port post. Also, since the serial port post discussed soldering to the header, if you haven’t done so already, remove the existing serial port wires so that your smokestack adapter will fit.  In the image below, the three jumpers coming off of the pins are colored as they would be if you had just cut and stripped back the CA-42′s cable. Remember that your CA-42 cable may be different!

Serial Port jumpers from CA42 USB cable.

The below image shows the top of the smokestack adapter and the respective colors.  You can see that the black wire for GND is attached to the USB shield pin we installed earlier. Remember, pin 1 and pin 7 on the smokestack are left not connected!

Top of smokestack adapter with jumpers.

The below image shows the JTAG adapter, properly wired and ready to go.  You can see the device is powered by the USB connector and that the orange and purple wires have been spared off.   Although the flash from my camera drowned out the red power LED, you will need to make sure that your LED is lit.  Please note, the JTAG adapter does require power however it will not show up as anything in Windows as we are using the USB port strictly for the power lines for the JTAG buffer.

TIAO JTAG wired up and ready.

An aerial view of the whole mess.     Yes, I know my desk is still messy.

C:\Program Files\OpenOCD\0.4.0

Wow, what a rats nest.

Now that all of the required connections have been made, it’s time to get busy with the software. Plug in the power cable to your dockstar and proceed to the next section.

Step III: Software

If you haven’t already, go back up to the Parts list and download Kragorn’s dockstar.cfg, OpenOCD and the uBoot image.

Install the OpenOCD software and accept the defaults.  Once completed, unzip the dockstar.zip and copy dockstar.cfg to C:\Program Files\OpenOCD\0.4.0\board and then copy your uboot image to C:\Program Files\OpenOCD\0.4.0  It would be recommended to rename it to just “uboot.bin” so that way you won’t have to retype that complicated line later on.

Now that we have all the proper software in place let’s discuss what all is going to happen.  When you start OpenOCD in a DOS window, it will in turn start a telnet server on localhost, port 4444.  You will use PuTTY to connect to the telnet server process and issue commands to OpenOCD.   In conjunction with that, you will need a second PuTTY session established to COM1 (if your windows machine has the CA-42 cable plugged into it) or to SSH to the machine you have the cable connected to. The reason is that once you enter specific commands on the telnet window, you need visibility to the other window (serial or SSH) to see if your dockstar is booting. Timing is critical! From here on out, commands and things to look for in output are in bold with other important text in bold, italics and underline.

In my configuration, my windows computer is what will run OpenOCD and the telnet session, and a nearby Linux box will have the SSH session with an application called minicom.

Start off by opening a DOS window (Start -> Run -> “cmd” )

Type the following command in exactly as shown: 

openocd -f board/dockstar.cfg

You should get output similar to the below image.  If you get what I have, then you can proceed to the next step.  If you get any errors, check your wiring. Make sure only those pins shown in the above images are what you have hooked up. Also, you may get a  Windows Firewall exception error.  If you do, just hit “Allow” otherwise you won’t be able to talk to OpenOCD.

OpenOCD successful startup

If OpenOCD is running without errors, minimize the DOS box and start PuTTY. Use the below configuration to establish a connection to the telnet process that OpenOCD started.

PuTTY Telnet settings

When you connect, you should get a window that says “Open On-Chip Debugger” with a caret “>” prompt.  Before we continue, if you haven’t already pulled up your serial session to the dockstar, you will need to do that now.  The issue is that from here on out, we will either be communicating with OpenOCD via Telnet, or communicating with the Dockstar via serial.

Now that you’ve established your connection to OpenOCD, perform the next two steps.

• Type the command “init” into the telnet session and hit enter.
• Type the command “sheevaplug_init” into the telnet session and hit enter.

Now, here is the hard part. The routine sheevaplug_init from above will attempt to halt the processor.  The Marvell chip has two types of halt, one of which labelled “ARM” and one labelled “Thumb”.  If your output resembles the below output (processor halted in Thumb state), you will need to perform the next steps otherwise skip down to the next section. When in doubt,  continue with the instructions below.

Thumb State Halt is no good!

If you got “Target halted in Thumb State”: There is some additional trickery that must be performed.   The issue is that the processor must be halted in ARM state as this allows OpenOCD to communicate with the processor properly.

• Hit Ctrl-C in your OpenOCD session. Your PuTTY session will break and generate an error. Dismiss the error and restart OpenOCD.
• Hold down the reset button and keep it held down with one hand and with the other, type “sheevaplug_init” and hit enter.  Ignore the error messages.
• Type in the command “halt” . DO NOT HIT ENTER YET!
• Release the RESET switch and simultaneously hit Enter.
• You should see that the processor was halted in ARM state.
• Type in “sheevaplug_init” and hit enter. No output should be generated from this command.

Check your telnet session output with my output in the screenshot below.  Make sure your output matches the screenshot before proceeding.

Properly halted dockstar

Now for the ultimate test.  We need to probe the NAND flash to make sure that the processor can communicate with it. Type in “nand probe 0” (zero) and hit enter.  If everything is correct, you should get text returned similar to “NAND flash device ‘NAND 256MiB 3,3V 8-bit’ found“.  If you get any other message ESPECIALLY anything about Unknown Manufacturer, restart OpenOCD and try again.  Here is my output so far:

Nand Probe Successful!

Now that the processor has been correctly identified by OpenOCD and the processor has properly identified the flash memory, we can now load the image into the Dockstar’s RAM and tell the processor to execute it. Type in load_image uboot.bin 0×800000 (zero, letter x, 8 and five zeros). If you renamed your uboot file something other than “uboot.bin” then substitute as needed.  This will take a couple of minutes as the image is transferred. Here is the output of what I have after the image loaded into RAM:

Load_Image successful!

When you get the caret prompt back “>”, type in the command “resume 0×800200” and check your serial connection for activity.  At this point, you can minimize the telnet session.  Now we will be dealing expressly with the serial connection.  Depending on your connection method, you may have a different window, but the text is the same.  As soon as you hit enter on the resume command, you should notice that the LED on your once dead dockstar is now blinking. Immediately switch over to the serial connection and hit a key to disrupt the boot process. If you did it right, you should see that the command prompt now shows Marvell>> as shown in the screenshot below:

Interrupted boot sequence

DO NOT DISCONNECT POWER FROM THE DOCKSTAR YET! WE ARE NOT DONE. The Dockstar has successfully loaded and ran the uboot commands in RAM however if we hit the reset switch or powercycle the dockstar, the device will return to it’s zombie state, and we will have to do it all over again. The only thing left to do is to prepare and write the image to flash.

If you were like me and you accidentally typed in ‘nand erase” and bricked your dockstar, you will need to re-erase the flash to reload it.  If you bricked your dockstar by another method, skip this step and go on to the next paragraph. To do this, type in “nand erase“.  This will erase the entire flash chip.  Now to write the working uboot to flash, use the command “nand write.e 0×800000 0×0 0×80000“  (zero x eight then 5 zeroes, zero x zero, then zero x eight then four zeros). You should get a message that the nand write was successful similar to the below screenshot.

Successful flash write.

If you did not brick your dockstar by an errant nand erase command, you will want to use “nand erase 0 0×0 0xa0000” (zero, zero x zero, zero x a then four zeros).  The reason for this difference is that if you didn’t erase your flash, this command will preserve the u-boot environment variables, otherwise you would have to recreate them later on.

Now, it’s time for the moment of truth.  Don’t start disconnecting wires just yet, simply tap the reset switch to load the uboot from the flash and test your recovery.   You will notice two key things:  Your uboot will be stuck in a permanent loop (assuming you didn’t interrupt autoboot) and the LED on the dockstar will alternate between flashing green and flashing orange as uboot cycles through.  This is because the dockstar can’t find a valid kernel or filesystem to boot from.  If you used the same version of the uBoot I listed above then you will notice that this uboot will attempt to boot off of USB key drives unlike the original factory image which opens up a LOT of opportunity.

To clean up, simply exit the various windows you have open, and exit OpenOCD by hitting Ctrl-C.  Remove power from the Dockstar, then remove the smokestack adapter and the ground wire on the USB shield.  If you want to make sure (because you’re as paranoid as I am, reapply power after all the jumpers have been removed and make sure that the Dockstar’s LED continues to blink orange then blinks green and repeats.  This means that your dockstar is confirmed as running off it’s own flash.

Now get to hacking!

Section IV: Notes and Credits

This article was assembled using information and help from various sources.  I want to thank everyone listed below for your assistance in helping me with getting the Dockstar JTAG figured out.  It was definitely not easy for someone new to JTAG however it was an enjoyable learning experience once I got the bugs worked out,  even if I did scratch my head a lot.

From the PlugApps forums, I’d like to thank Admin, Kragorn, bzboi, klingon, ygator, mrbill, and jtagfun.

A special thanks to bzboi for the initial howto that most of the OpenOCD instructions were used from and to Admin for the starting post with the Dockstar’s JTAG diagram.

I’d also like to thank mrbill for getting me involved with these things. It’s all his fault that I even have a dockstar to break.

Thanks goes to Kragorn for finding out the proper settings in his dockstar.cfg so that all of us could unbrick after the inevitable “Oops…” moment.

Last, but not least, thanks goes out to Jeff Doozan for his work with uBoot and compiling in needed features into the bootloader so that we can use USB sticks as boot devices.

Where do we go from here?

The answer is “Where do you want to go?”  In my relatively short time with the Dockstar, I was working on getting OpenWRT compiled and installed on it.  OpenWRT is the same OS that they use for the Linksys and other branded routers and is pretty much it’s own distribution.  There are also processes on how to install Debian onto the dockstar, using a laptop drive and USB sled to run the OS.  There is a lot of people doing research and finding out other warranty voiding things to do with their dockstars so take a look around.

As far as me personally?  I have three of them and while one of them is going to be a small NAS fileserver, one of the more esoteric things I was planning on doing with mine is making it into a roving USB camera with wifi.  The idea is that the Dockstar’s mainboard would be the brains of the rover and could send commands to a Parallax BOE-BOT via a usb to serial converter.  Since the entire thing would be wireless off of a USB dongle, I could use the IP based connection to deliver video and commands via a custom written application.

I sincerely hope that you are able to recover your dockstar using the above process.  It’s no fun when you accidentally destroy something you have put so much work into however now you should be able to work on the Dockstar without fear that you’re going to damage it and prevent it from booting.  Also, if you decide to try custom boot loaders, you can do so worry free.

Happy Hacking!

FIRESTORM_v1