Introduction

This page contains instructions for using the Skunk Gigabit Ethernet switch / tap.

What's included?

Upon receiving your Skunk, the package should contain the following:

• Skunk (main board)
• Plastic case
• 5V 1A power supply
• USB power cable
• 0.3M USB cable
• 4x Cat6 cable (1m)
• Some stickers :)

Basics

The diagram below presents the main physical features of the Skunk. The port numbering represented here is the one used for all configuration commands.

Getting Started

The Skunk requires a 5V power source capable of supplying at least 1A of current. Plug in the included wall adapter to power on the Skunk.

Once plugged in, a few seconds are needed to initialize.

Alternatively, the included USB power cable can be used to power the Skunk from a USB source. This allows fun things like powering from a USB power bank to keep the Skunk mobile.

Keep in mind however that some very old or "weak" sources such as old laptops may not be able to reliably power the Skunk.

As soon as it is ready, the Skunk will blink all LEDs in sequence as shown below.

That's it! You can now use the Skunk as a standard switch.

To use any of the more advanced features, follow the sections below to discover how to use the USB interface to fully configure the Skunk.

USB communication

Connect the the Skunk to your computer via the included USB cable. The USB micro-B connector is located on the back of the Skunk, next to the power connector.

This should make the Skunk appear as a standard serial port in most modern operating systems.

If you are using Windows and the Skunk does not appear as a standard serial port (COM port), your system may be missing the appropriate driver. You can download it from here: https://ftdichip.com/drivers/vcp-drivers/

Use your favorite terminal emulator to open a session at 19200 baud on the device. Note that the Skunk appears as "COM9" in the picture below - this may be different on your system.

From there the help command will give a list of possible commands, as shown below:

The sections below will detail the various commands.

Configuration management - skconf

The 'skconf' command allows saving and loading the configuration (as well as reloading the factory defaults).

The 'skconf show' command is useful for getting a quick overview of the entire configuration. The picture below gives an example of this:

The current configuration can be saved at any time by entering the 'skconf save' command as shown below:

VLAN details - skvlan

The 'skvlan' command allows accessing some VLAN-related details. Specifically, it allows controlling the use of full trunking, double tagging, as well as reading the VLAN table information. The actual VLANs and their switch port assignments are managed through the 'skport' command described further down.

Use on-demand trunking when you don't need trunks to carry more than the VLANs assigned with your access ports. When you really need your trunks to carry all VLANs regardless of which are assigned to your access ports, enable full trunking for maximum power.

Note: full trunking requires writing to the entire VLAN table when applying the configuration, which is why you may notice a delay (~4 seconds) when applying settings with this enabled. Since full trunking is not required for most use cases, it is disabled by default.

Switch port management - skport

This is probably the most important command of all - skport allows configuring individual switch ports for VLAN access or trunking as well as sniffing.

In its most basic usage, 'skport show' displays the status and configuration of all ports. Information for a single port can also be displayed by using 'skport PORT_NUM show' (where PORT_NUM is the port number).

Port attributes can be combined into a single command to simplify configuration.

For example, to configure port 2 as an access port in VLAN 50 while also enabling RX and TX sniffing, the following command can be used:

skport 2 access 50 sniff_rx sniff_tx

Note: RX traffic refers to packets entering the Skunk, whereas TX traffic refers to packets leaving the Skunk.

Get / set device name - skname

The Skunk can be given a name to help make it easier to identify it, especially when more than one are being used.

When used without any arguments, 'skname' just displays the device name. When given an argument, the 'skname' command will set the name to whatever was given. As with all configuration, this is not persisted unless 'skconf save' is used.

Usage example - sniffing some packets

Let's imagine a scenario where we wish to capture all packets going from a "victim" device to the upstream switch it's connected to. First, we need to disconnect the victim device and place the Skunk between it and the upstream network. Simply connect both the upstream network and the victim device to ports on the Skunk.

In this scenario, we will use port 0 for the victim device and port 1 for the upstream network. We also want to connect our "sniffer" laptop to any other port on the Skunk - let's use port 3 here.

Please note that some of the pictures below depict a different case design and color than the one included with your Skunk. Feel free to modify the case and/or print it in a different color - the STL files are available at the bottom of this page.

With all this setup, we can now enable sniffing from the USB interface as described previously. Again, for this example we wish to capture all packets transmitted by the victim device - this is RX traffic (inbound to the Skunk) on port 0. Let's use the skport command to accomplish this:

skport 0 sniff_rx
skport 3 sniff_out

This will cause all packets entering the Skunk on port 0 (packets sent by the victim device) to be mirrored to port 3, where our sniffer laptop can comfortably capture them with something like TCPdump or Wireshark.

If desired, we could also sniff RX and / or TX traffic on any other ports at the same time. The picture below should serve as a quick memo.

Sniffing status

At any moment, the current status of the sniffing configuration can be obtained with the 'skport show' command:

Disabling all sniffing

Whenever you are done having fun, all sniffing can be easily disabled with the 'sniff_off' argument. To disable all sniffing on the ports shown in the example above, the following commands can be used:

skport 0 sniff_off
skport 1 sniff_off
skport 3 sniff_off

Modifying / extending the firmware

The firmware included by default serves as an open-source reference for anyone looking to write their own, or even just a foundation that can be easily modified / extended. The official repository is available here: Skunk firmware repository.

Only the sniffing features and VLAN support are implemented in the reference firmware, serving as an example - other management features such as 802.1X are left open to custom implementation.

The firmware is built using the open-source Dooba SDK - if you are not familiar with it, the Discover Dooba tutorial is a good place to get started.

The switch engine inside the Skunk is the powerful KSZ9896 from Microchip. Be sure to check out the datasheet if you want to play with its advanced features.

Flashing the firmware

The Skunk is pre-loaded with a fork of Dooba's Kiwi bootloader. As such, you can flash it just like any other Dooba-style hardware: press the reset button and run the dflash utility.

The Skunk bootloader (Kiwi fork) is also available here: Skunk bootloader repository.

Again like most Dooba tech, the Skunk expects to communicate at 19200 baud. This is also the default baudrate for dflash, making it even easier to use.

For more information on what we mean by "bootloader" in this context and how this works under the hood, go check out the Kiwi & dflash explanation page on Dooba.

Schematic

For anyone looking to modify / extend the firmware or even build their own, the schematic is provided in PDF format here: Skunk PDF schematic.

Enclosure

The Skunk is shipped with a basic 3D-printed press-fit enclosure. This means you can easily remove the case and print your own, or even integrate the Skunk board directly into something else.

STL files for the included case are provided below, ready to be 3D-printed.

Two files are provided - one for the bottom of the enclosure and one for the top.

• skunk-enclosure-bottom.stl
• skunk-enclosure-top.stl