IllegalException

Monitoring a secure Wi-Fi network using Wireshark on macOS

2020-03-09T00:00:00+01:00

Do you have a secure Wi-Fi network and a computer running macOS? Do you want to monitor the traffic of the devices connected to this network? Look no further, here’s how to do this step by step using Wireshark!

Wireshark is a very popular network protocol analyzer which understands many different network protocols out of the box and shows their data packets in a powerful GUI. The following instructions are based on macOS Mojave 10.14.6 running Wireshark 3.2.2 and may not work without changes for other versions of these software.

Disclaimer: Monitoring other people’s network traffic is a very bad idea and may be forbidden or even illegal in your case! Therefore, you may only apply these instructions if you own the Wi-Fi network and all its connected devices and you are the only user and no legal impediments whatsoever apply!

Installing Wireshark

I recommend to use Homebrew for this step because it makes installing and updating Wireshark really simple. In case you don’t already use it, Homebrew is a very popular package manager for macOS. Follow the instructions on their home page for installation. Once Homebrew is installed, you can install Wireshark in Terminal using

brew cask install wireshark

Wireshark provides an integrated update feature via the menu item Help » Check for Updates.... However, this doesn’t work for me because nothing ever happens, so I simply upgrade it using

brew cask reinstall wireshark

If you ever need to uninstall Wireshark, you can do that using (you guessed it)

brew cask uninstall wireshark

Any configuration data is saved in your home directory and will be preserved on re-installation or un-installation.

Obtaining The Wi-Fi Secret

Assuming that your Wi-Fi network is secured using WPA-Personal alias WPA-PSK, it is protected by a pre-shared key or even a password from which the pre-shared key gets derived. You need to copy this secret into the clipboard from which you will paste it into the Wireshark configuration later.

Further assuming that your Mac is already connected to this network, its secret is stored in the keychain. Otherwise, please connect your Mac to this network first.

In Terminal, launch the keychain management GUI using

open -a 'keychain access'

In the search box on the top right of the keychain window, enter the name of your Wi-Fi network, i.e. its SSID. In my case it’s FRITZ!Box 7530 CT:

Right click on the list item, select Copy Password To Clipboard and enter your password in the upcoming dialog box.

Configuring The Wi-Fi Secret In Wireshark

In Terminal, launch Wireshark using

open -a wireshark

After startup, the main window shows you all the interfaces from which you may capture network traffic:

Ignore this for now and select the menu item Wireshark » Preferences... instead. In the dialog, unfold the Protocols item and scroll down to IEEE 802.11 for Wi-Fi:

Click on the Edit... button to launch the following dialog:

Click on the + button to start entering the secret. In the Key type column, select wpa-psk or wpa-pwd, depending on if your secret is a pre-shared key or a password, respectively. If you are not sure, select wpa-psk first, paste the secret in the clipboard into the form using command-v and check if the dialog accepts it. Otherwise, select wpa-pwd and repeat. You can enter secrets for multiple Wi-Fi networks, allowing you to monitor them all concurrently. Once done, close all dialogs.

Capturing The Wi-Fi Network Traffic

Now that you have configured the secret for your Wi-Fi network, you can start monitoring the traffic of all connected devices. Select the menu item Capture » Options... to launch the following dialog:

In here, select the list item representing your Wi-Fi interface and double click on the column Link-layer Header. In the popup menu, select the list item Per-Packet Information. This will prevent a lot of false positive network error messages later. Most importantly, make sure to check the box Monitor or otherwise you will only ever see network traffic which is intended for your local computer. After clicking Start, Wireshark starts monitoring all packets from all Wi-Fi networks on the current channel within the reach of your computer’s antenna - not just your network. In the following capture, the beacon packets are from three different Wi-Fi networks on the current channel:

Initially, Wireshark shows 802.11 protocol packets only, so you won’t see packets from other protocols like ICMP, TCP or HTTP. This is because with WPA2, the 802.11 protocol packets are actually encrypted with a session key which gets derived from the pre-shared key, which in turn may be derived from the password. Wireshark has to learn the session key first by observing the exchange of a sequence of packets known as the EAPOL handshake. It will do so automatically for any secure Wi-Fi network who’s secrets you have configured. So all you have to do is to trigger the EAPOL handshake between the access point and the connected device, and the easiest way to do this is to switch its Wi-Fi interface off and on again.

In the preceding capture, first I have set the display filter to eapol || http. Then I have switched the Wi-Fi interface of my iPad off and on again, which triggers the initial four EAPOL messages. Then I have used Safari on my iPad to browse my blog’s home page at http://illegalexception.schlichtherle.de.

Note that the iPad and the web server exchange HTTP packets using both IPv4 and IPv6 addresses. This is not very efficient because it implies that there is no persistent TCP connection between the two hosts. As you can see, Wireshark is a very effective tool for analyzing issues like this.

Caveats

Obviously, you will not be able to read the plain text of any encrypted network protocols like HTTPS or SSH.
You may need to trigger the EAPOL handshake several times before Wireshark will be able to decrypt all data packets.
Sometimes the monitoring computer may get disconnected from the Internet. You can easily fix this by stopping the monitoring and switching the Wi-Fi interface off and on again.

Summary

This mini tutorial showed you how to obtain the Wi-Fi secret from the keychain, configure Wireshark with it, start the monitoring and trigger the authentication handshake to make Wireshark learn about the session key for the connected devices.

When monitoring a secure Wi-Fi network, you need to configure the monitoring tool with the pre-shared key or the password for decrypting the data packets. This is because in monitor mode the interface driver will deliver the raw 802.11 packets to the application, leaving it to deal with all the necessary processing, including the decryption. In non-monitor mode however, it’s the interface driver’s responsibility to process each 802.11 packet which is intended for the local host, thereby filtering, decrypting and converting the packets to plain old Ethernet (802.3) packets before delivering them to the application.

Overclocking the Raspberry Pi 4

2019-09-22T00:00:00+02:00

The latest firmware for the Raspberry Pi 4 Model B allows you to individually overclock it’s CPU, GPU, SDRAM etc. This posting shows you how to do that.

Before you rush to this, a word of warning: Overclocking can void your warranty and irreparably damage your RPi. To use sustainable overclocking, you must apply active cooling to your RPi - a heatsink alone is not good enough! DON’T FOLLOW THESE INSTRUCTIONS unless you understand and agree to apply them at your own risk!

Technically speaking, overclocking the RPi is simple: All you have to do is edit the file /boot/config.txt to set certain variables for frequencies and voltages in the [all] section and reboot the device. For the full list of variables, please check this reference page.

For example, to set the frequency of the ARM CPU, you can set the variable arm_freq, which defines the frequency in MHz. The default value for the RPi 4 is 1500:

[all]
arm_freq=1500

Setting a higher frequency for a component generally requires a higher voltage to drive the component. For example, to set the voltage for the ARM CPU, you can set the variable over_voltage, which defines the voltage in steps of 25mV. The default value for the RPi 4 is 0:

[all]
over_voltage=0

For me, I’ve applied the PoE HAT to the RPi 4s in my Kubernetes cluster:

The PoE HAT has a built-in fan which allows me to overclock the ARM CPU like this:

[all]
arm_freq=1750
over_voltage=2

Setting a higher frequency causes the firmware to frequently throttle the CPU clock in order to protect it from overheating - throttling starts at 80’C. Setting a lower voltage causes the CPU to crash because there is not enough power to drive it. Setting a higher voltage causes the CPU to become hotter and thus, getting throttled more often. Of course, your mileage may vary based on your cooling solution and ambient temperature (mine is A/C controlled at 23’C).

Don’t forget to reboot the device:

$ sudo reboot

You can check the results using the vcgencmd command. Here’s what it shows for me on one of the cluster nodes:

$ vcgencmd measure_temp; vcgencmd measure_clock arm; vcgencmd get_throttled
temp=78.0'C
frequency(48)=1750412160
throttled=0x20000

Everything below 80’C is OK. If it’s significantly lower while the device is running a CPU intensive workload for a while already, then it means that you can increase the frequency, which in turn may require you to set a higher voltage, too.

The throttled property indicates if the CPU is currently throttled or was throttled at some point in the past: If the least significant digit is not zero, then the CPU is currently throttled for some reason. If the most significant digit is not zero, then the CPU was throttled for some reason in the past. In this example, the value 0x20000 indicates that the CPU has been set to a lower frequency at some point in the past. Ideally, the value should be 0x0, of course.

Since I’m running a cluster, I’m using Ansible to get this information from all my nodes. Here’s a sample reading:

$ ansible all --module-name=shell --args='vcgencmd measure_temp; vcgencmd measure_clock arm; vcgencmd get_throttled' --one-line | sort
node-0 | CHANGED | rc=0 | (stdout) temp=79.0'C\nfrequency(48)=1750412160\nthrottled=0x20000
node-1 | CHANGED | rc=0 | (stdout) temp=50.0'C\nfrequency(48)=1750412160\nthrottled=0x0
node-2 | CHANGED | rc=0 | (stdout) temp=79.0'C\nfrequency(48)=1750412160\nthrottled=0x20000
node-3 | CHANGED | rc=0 | (stdout) temp=76.0'C\nfrequency(48)=1750412160\nthrottled=0x20000
node-4 | CHANGED | rc=0 | (stdout) temp=77.0'C\nfrequency(48)=1750464896\nthrottled=0x20000
node-5 | CHANGED | rc=0 | (stdout) temp=73.0'C\nfrequency(48)=1750412160\nthrottled=0x0
node-6 | CHANGED | rc=0 | (stdout) temp=74.0'C\nfrequency(48)=1750412160\nthrottled=0x0

In case you wonder why node-1 is relatively cool at 50’C while all the others are sweating close to 80’C: This is because node-1 is the single master node in my Kubernetes cluster. It doesn’t run a real workload like the other nodes do - more on that in a separate posting.

Enjoy!

How To Upgrade Raspbian To A 64 Bit Kernel

2019-09-21T00:00:00+02:00

At the time of this writing, there is no 64 bit edition of Raspbian yet. This is particularly bad if you are running Docker (or Kubernetes) on the new Raspberry Pi Model 4, because you will not be able to run the many ARM64 images on Docker Hub, e.g. OpenJDK. Fear not, you can change this! Here is how.

It’ll be a long way before a 64 bit edition of Raspbian gets released. However, thanks to the recent work of the Raspberry Foundation, you can now upgrade to a beta version of a 64 bit Linux kernel. This upgrade will not change the installed executables in your system, but at least the upgraded 64 bit kernel can run new 64 bit executables as well as any old 32 bit executables.

Before, you would have to try third party OS images to get a 64 bit Linux kernel. I have tried some with mixed results. The best alternative I have found so far is an unofficial image for Ubuntu Server 18.04.3, which has been created and described in a blog posting by James A. Chambers. However, the new hardware of the RPi 4 is not yet fully supported, so I thought I should give Raspbian another try.

Before you do this, be warned: This is beta software, so things may break! Retain your current OS image so that you can revert anytime if there is trouble. Now, for the upgrade, login to your RPi and enter:

$ sudo rpi-update

This will initiate the upgrade operation. At some point, it will ask you to type a single y or n character to confirm the upgrade or not. For tools like Ansible etc, you can simply automate a positive answer like this:

$ echo -n y | sudo rpi-update

The 64 bit kernel will not be loaded upon boot until you also edit the file /boot/config.txt to contain the following line:

arm_64bit=1

When testing this, I found a problem which is specific to Kubernetes: Containers could not connect to the Internet anymore. This is because the upgrade breaks iptables. There is a trivial fix for this, however:

$ update-alternatives --set iptables /usr/sbin/iptables-legacy
$ update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Next, you need to reboot the system:

$ sudo reboot

Finally, you can check the upgraded kernel:

$ uname -r
Linux node-3 4.19.73-v8+ #1267 SMP PREEMPT Fri Sep 20 18:14:38 BST 2019 aarch64 GNU/Linux

aarch64 is a synonym for ARM64v8 - sweet!

Enjoy!

Provisioning a Kubernetes cluster on Raspberry Pi with Ansible

2019-09-12T00:00:00+02:00

The new Raspberry Pi model 4B is out and it’s a significant upgrade: Among other improvements, the new model has up to 4GB, real Gigabit Ethernet (no more throttling to USB 2.0 bandwidth) and a quad core Cortex-A72 (ARM64v8) CPU running at 1.5 GHz - see specifications. With all this power, why not build a Kubernetes cluster with it? Well, here we go: This posting shows you how you can setup a multi-node Kubernetes cluster on an array of Raspberry Pi’s in minutes!

To automate the provisioning, I have created an Ansible playbook which sets up either original Kubernetes (subsequently called k8s) or k3s, which is a certified Kubernetes variant with a smaller memory footprint. The playbook even supports partitioning your nodes so that some may form a k8s cluster while others form a k3s cluster. This can be useful for testing purposes.

The minimum number of nodes in any cluster is one for a single master node, but you should have at least two nodes, one master node and one worker node. The more worker nodes you can add, the better of course. At the time of this writing however, the playbook only supports a single master node. If you want more than one master node, then you need to manually reconfigure the cluster post setup.

Regardless of the Kubernetes variant, the playbook installs Docker as the container runtime, so that you can take advantage of Docker-specific features. For example, the playbook supports configuring an external Docker registry mirror. This can be used to reduce network traffic as otherwise every worker node individually pulls the same Docker images. For the same reason, the playbook also supports configuring an external HTTP(S) proxy. This can be used to make the provisioning a lot faster and more robust as every network operation (e.g. installing packages) is effectively done at most once for the first node while subsequent nodes will be served from the proxy’s cache.

If you need a private Docker registry, then this can be configured using image pull secrets in a post-master-up event hook (see below). I recommend adding image pull secrets to a service account, so that you don’t have to configure this for each pod individually.

For container networking, the playbook configures Flannel. This is the only choice with k3s anyway.

I have also created another playbook to properly tear down individual nodes or even the entire cluster. This allows you to re-purpose your hardware, e.g. a worker node can leave one cluster and join another or you can use it for something else.

Prerequisites

Hardware

The playbooks have been designed so that they do not depend on a particular hardware: They should work on anything which runs a Debian based Linux distribution, including EC2 instances on AWS. As a proof-of-concept, I’m running Kubernetes on an array of six Raspberry Pi 4’s with 4 GB memory each. Actually, as little as 1 GB memory is enough to run Kubernetes, but then there is not enough free memory to run many interesting apps.

Also, for best performance, the Pi’s should be connected via Ethernet cable, not WiFi. There is a caveat, however: With Raspberry Pi 3 and earlier models, the Ethernet port is connected to the USB 2.0 controller, which effectively limits the available bandwidth to about 224 Mbps. In comparison, the Raspberry Pi 4 can sustain over 900 Mbps with adequate cooling. For my setup I have chosen the Power-over-Ethernet (PoE) HATs, which have a temperature-controlled fan.

All the performance is waisted if you go for a cheap switch: The problem with cheap switches is that their backplane often doesn’t provide enough bandwidth for full-duplex transmission on all ports in parallel - this is the same problem as with the Ethernet port on older Raspberry Pi models.
For best results, you need a switch with at least N + 1 ports (for N Pis’ plus an uplink to your router) and a backplane bandwidth of at least 2 * (N + 1) Gbps. For my setup I have chosen the TRENDnet TPE-TG80g, which is an unmanaged switch with 8 Gigabit Ethernet ports. Its backplane has a bandwidth capacity of 16 Gbps, so all its ports can transmit data at full bandwidth in parallel. The ports also feature Power-over-Ethernet Plus (PoE+) with up to 30 Watts per port and a power budget of 123 Watts. The Pi’s typically need less than ten Watts, so the 123 Watts power budget is perfectly fine. The little extra money I’ve spent for the switch (~115 USD on Amazon) I’ve probably saved on power supplies for the Pi’s - I don’t need any!

Last, but not least, all the performance is waisted again unless you also go for some high performance microSDXC card. I have chosen SanDisk Extreme PRO microSDXC UHS-I with a capacity of 64 GB. For storing application data, I use an external NAS, though.

Software

As said before, the playbooks have been designed to work on any Debian based Linux distribution. However, at the time of this writing, only Raspbian Buster (32 bit, ARMHF/ARM32/ARM architecture) and Ubuntu 18.04.3 LTS (64 bit, AARCH64/ARM64 architecture) have been tested.

$ kubectl --kubeconfig=build/k8s-config.yml get nodes -o wide
NAME    STATUS   ROLES    AGE   VERSION   INTERNAL-IP     EXTERNAL-IP   OS-IMAGE                         KERNEL-VERSION   CONTAINER-RUNTIME
node1   Ready    <none>   83m   v1.15.3   192.168.71.21   <none>        Ubuntu 18.04.3 LTS               4.19.71-v8+      docker://18.9.9
node2   Ready    <none>   83m   v1.15.3   192.168.71.22   <none>        Ubuntu 18.04.3 LTS               4.19.71-v8+      docker://18.9.9
node3   Ready    <none>   83m   v1.15.3   192.168.71.23   <none>        Ubuntu 18.04.3 LTS               4.19.71-v8+      docker://18.9.9
node4   Ready    <none>   83m   v1.15.3   192.168.71.24   <none>        Ubuntu 18.04.3 LTS               4.19.71-v8+      docker://18.9.9
node5   Ready    master   84m   v1.15.3   192.168.71.25   <none>        Raspbian GNU/Linux 10 (buster)   4.19.71-v7l+     docker://18.9.0
node6   Ready    <none>   83m   v1.15.3   192.168.71.26   <none>        Ubuntu 18.04.3 LTS               4.19.71-v8+      docker://18.9.9

As you can see, I’m running k8s version 1.15.3 on all nodes. You can also use k3s with my Ansible playbooks, but I figured that it may be not worth it unless you want to run a single node cluster: While k3s has a significantly smaller memory footprint on a master node, there’s hardly any difference on a worker node. On the other hand, there are subtle differences in the default setup, like k8s uses a self-signed certificate to authenticate users whereas k3s uses a username and a password. I don’t want to risk bad surprises later, so I went with the original. You may beg to differ, of course.

The worker nodes run on Ubuntu 18.04.3 LTS / 64 bit, so I can benefit from the bigger portfolio of Docker images for its ARM64 architecture. At the time of this writing, there is no official image from Canonical which supports the Raspberry Pi 4 yet, so I’m using an unofficial image which has been kindly provided by James A. Chambers on GitHub.

Choosing the right architecture for the worker nodes is critical: A lot of my software is written in Java, so I want to run an official OpenJDK image. Unfortunately, it’s not available for ARM32, so I choose ARM64 and hence, Ubuntu.

$ kubectl --kubeconfig build/k8s-config.yml run -it --restart=Never --image=openjdk:11-jdk test
If you don't see a command prompt, try pressing enter.
|  Welcome to JShell -- Version 11.0.4
|  For an introduction type: /help intro

jshell> /exit
|  Goodbye
$ kubectl --kubeconfig build/k8s-config.yml get pod test -o wide
NAME   READY   STATUS      RESTARTS   AGE    IP           NODE    NOMINATED NODE   READINESS GATES
test   0/1     Completed   0          2m6s   10.244.1.2   node4   <none>           <none>
$ kubectl --kubeconfig build/k8s-config.yml delete pod test
pod "test" deleted

Technically, ARM64 is not necessarily the best choice however: At the time of this writing, the Raspberry Pi 4 ships with max 4 GB, so a 32 bit image is good enough to address all of its memory. With 64 bit however, the Docker images just get bigger, more (cache) memory is consumed to hold the bigger pointers and more bandwidth is consumed to transfer them to CPU registers and back. Therefore, 32 bit images should save you some memory and perform slightly better on the current hardware.

EDIT: You can still run ARM32 binaries on an ARM64 architecture though, so choosing a 64 bit architecture gives you more options.

The master node runs on Raspbian Buster Lite / 32 bit, so its an ARM32 architecture. This is the official image from the Raspberry foundation. As said above, ARM32 images should perform slightly better and a master node normally doesn’t run any work load, so the different portfolio of Docker images is irrelevant.

EDIT: Unfortunately, this breaks the container networking (Flannel) for some reason, so CoreDNS complains that it can’t talk to the external DNS servers (I have one on my NAS and one on my router). After some hours of analysis and failed experiments, my successful resolution is to teardown and setup the whole cluster again with all nodes running on Ubuntu/ARM64!

As for the playbooks, I’m using Ansible 2.8.4 with Python 3.7.3 on macOS 10.14.6. Other versions may work, but haven’t been tested.

Preparing the Nodes

Kubernetes generally requires that the IP addresses of the nodes do not change. The easiest way to achieve this is to pin the IP addresses in your DHCP server. Also, before you can use the Ansible playbooks, you need to be able to login to all the nodes using SSH. The easiest way to achieve that is to use the command ssh-copy-id pi@$ip_address for all Raspbian nodes and ssh-copy-id ubuntu@$ip_address for all Ubuntu nodes, where $ip_address is the IP address of the respective node. No further preparations are required - the rest is handled by the Ansible playbooks.

Checking Out the Repository

First, you need to check out the Git repository with the Ansible playbooks:

git clone git@github.com:christian-schlichtherle/kalaxy.git
cd kalaxy

Configuring the Ansible Playbooks

Next, use your editor-of-choice to edit the YAML file inventory.yml. This is a local Ansible inventory which needs to reflect your environment and configuration choices. Here’s mine:

---
all:
  hosts:
    # Use only IP addresses here!
    node1:
      ansible_host: 192.168.71.21
    node2:
      ansible_host: 192.168.71.22
    node3:
      ansible_host: 192.168.71.23
    node4:
      ansible_host: 192.168.71.24
    node5:
      ansible_host: 192.168.71.25
    node6:
      ansible_host: 192.168.71.26
  children:
    k3s_master:
      hosts:
        # Only one master!
    k3s_worker:
      hosts:
    k8s_master:
      hosts:
        # Only one master!
        node5: {}
    k8s_worker:
      hosts:
        node1: {}
        node2: {}
        node3: {}
        node4: {}
        node6: {}
    raspberry_pi:
      hosts:
        node1: {}
        node2: {}
        node3: {}
        node4: {}
        node5: {}
        node6: {}
    raspbian:
      hosts:
        node5: {}
      vars:
        ansible_ssh_user: pi
        boot_directory: /boot
        docker_apt_repository: "deb https://download.docker.com/linux/raspbian stretch stable"
        docker_version: "5:18.09.0~3-0~raspbian-stretch"
    ubuntu:
      hosts:
        node1: {}
        node2: {}
        node3: {}
        node4: {}
        node6: {}
      vars:
        ansible_ssh_user: ubuntu
        boot_directory: /boot/firmware
  vars:
    ansible_python_interpreter: /usr/bin/python3
    #containerd_version: 1.2.6-3
    # Make sure to match the `no_proxy` pattern or otherwise expect Docker images to be proxied twice:
    #docker_registry_mirror_url: https://my-docker-registry-mirror.local/
    #docker_version: "5:18.09.9~3-0~{{ ansible_lsb.id.lower() }}-{{ ansible_lsb.codename }}"
    #k3s_version: v0.9.0-rc2 # https://github.com/rancher/k3s/releases
    #k8s_version: 1.15.3-00
    #kuberneted_cni_version: 0.7.5-00
    # Make sure to match all nodes and the `docker_registry_mirror_url`:
    #no_proxy: 10.0.0.0/8,127.0.0.0/8,192.168.0.0/16,*.local,localhost
    # Make sure to use an IP address, not a hostname, or otherwise expect the Kubernetes setup to fail:
    #proxy_url: http://10.0.0.1:3128/
    #remove_docker_directory: yes

At the bare minimum, you need to update the file as follows:

all.hosts maps all your node names (node1 - node6 for me) to their IP addresses. Don’t use host names instead of IP addresses!
all.children assigns nodes to groups: For example, all.children.k8s_worker.hosts lists all the worker nodes of the k8s cluster, all.children.raspbian.hosts lists all the nodes running on Raspbian, all.children.raspberry_pi.hosts lists all the nodes running on Raspberry Pi hardware etc.

A node can be a member of multiple groups: For example, node5 is a member of the groups k8s_master, raspbian and raspberry_pi to declare that this is a Raspberry Pi running Raspbian which shall become the master of a k8s cluster.

Mind you that the groups k3s_master and k8s_master can contain at most one host - multi-master setup is not supported!
Optional: You can configure to use an external HTTP(S) proxy by uncommenting and setting the variables all.vars.no_proxy and all.vars.proxy_url. Make sure to use an IP address, not a hostname in the proxy URL, or otherwise expect the Kubernetes setup to fail for some reason.
Optional: You can configure to use an external Docker registry mirror by uncommenting and setting the variable all.vars.docker_registry_mirror_url. Make sure to match the no_proxy pattern or otherwise expect Docker images to be double proxied.
Optional: You can override the versions for Docker, k3s and k8s by uncommenting and setting the respective variables in all.vars and all.children.raspbian.vars. The playbooks will install and pin these particular versions, then.

Mind you that Kubernetes generally doesn’t support the latest Docker release, so it’s not always advisable to select the latest version.

Verifying Your Configuration

Run ansible all -m ping to verify your configuration. For my setup, it shows:

$ ansible all -m ping
node1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
node4 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
node3 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
node5 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
node2 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
node6 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

With this command, all refers to the same-named group in the inventory. You should repeat this command for all other groups to verify their members, i.e. k3s_master, k3s_worker, k8s_master, k8s_worker etc.

Configuring Event Hooks

An event hook is a custom Kubernetes resource manifest which gets supplied to the kubectl apply command whenever a playbook triggers a certain event. This feature can be used to configure the cluster during setup, for example to create an image pull secret for accessing a private Docker registry and applying it to the service account default.

The playbooks trigger the following events:

post-master-up: Triggered after the master node has been setup, but before the worker nodes join the cluster
pre-master-down: Triggered after the worker nodes left the cluster, but before the master node gets teared down

The following event hook files will be tried in order in response to a post-master-up event (changed in v0.2.3):

hooks/k3s-post-master-up.yml (only on k3s)
hooks/k8s-post-master-up.yml (only on k8s)
hooks/post-master-up.yml

The following event hook files will be tried in order in response to a pre-master-down event (changed in v0.2.3):

hooks/pre-master-down.yml
hooks/k8s-pre-master-down.yml (only on k8s)
hooks/k3s-pre-master-down.yml (only on k3s)

Like Ansible tasks, event hooks need to be idempotent. This requirements is ensured by Kubernetes.

Provisioning Your Cluster(s)

Setup

Finally, you are ready to setup your k3s or k8s cluster:

$ make # or `make up`
[...]

This takes some minutes, mostly depending on your Internet bandwidth and the storage throughput. As a side effect, unless the k8s_master group is empty, this command creates the file build/k8s-config.yml. Likewise, unless the k3s_master group is empty, this also creates the file build/k3s-config.yml. You need these configuration files to connect to your respective cluster. For example, to talk to the k8s cluster:

$ export KUBECONFIG="$PWD/build/k8s-config.yml"
$ kubectl get nodes
NAME    STATUS   ROLES    AGE     VERSION
[...]

This lists all your nodes in the k8s cluster. Watch out for the STATUS column - it should eventually show READY for all the nodes in the cluster. If not, you can use kubectl describe node $node_name and check the shown events.

Teardown

To tear down your entire cluster(s):

$ make down
[...]

This is rarely useful unless you want to do something completely different with all your nodes. Typically, you will want to limit this command to a single node, e.g. if you want to re-purpose or upgrade the node. You can do this by providing the OPTS variable to the make command:

make OPTS=--limit=node1 down

The option --limit=node1 is passed down to the ansible-playbook command which subsequently tears down node1 only, properly draining and deleting it from the cluster first.

Installing the Kubernetes Dashboard

Now that you have a working cluster, you can install the Kubernetes dashboard like this:

$ kubectl apply --filename https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta4/aio/deploy/recommended.yaml
namespace/kubernetes-dashboard created
serviceaccount/kubernetes-dashboard created
service/kubernetes-dashboard created
secret/kubernetes-dashboard-certs created
secret/kubernetes-dashboard-csrf created
secret/kubernetes-dashboard-key-holder created
configmap/kubernetes-dashboard-settings created
role.rbac.authorization.k8s.io/kubernetes-dashboard created
clusterrole.rbac.authorization.k8s.io/kubernetes-dashboard created
rolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
clusterrolebinding.rbac.authorization.k8s.io/kubernetes-dashboard created
deployment.apps/kubernetes-dashboard created
service/dashboard-metrics-scraper created
deployment.apps/dashboard-metrics-scraper created

Next, follow these ~~painful~~standard instructions to get an access token. Once you’ve passed this surgery, you can access the Kubernetes Dashboard at http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/ and browse your cluster.

Summary

In this post, I have shown how to provision a Kubernetes cluster on an array of Raspberry Pi’s using Ansible playbooks. The built cluster(s) support HTTP(S) proxies, a Docker registry mirror and a private Docker registry via a post-master-up event hook. By configuring the Ansible inventory, the same playbooks can be reused for a variety of Kubernetes variants and Linux distributions. Last, but not least, the same playbooks can be used with any hardware which runs a Debian based Linux distribution, not just the Raspberry Pi.

If you have been encountering any issues with the Ansible playbooks, kindly refer to the issue tracker on GitHub.

Blog Relaunch

2018-06-02T15:43:00+02:00

Welcome to my relaunched blog!

After years of laying dormant, I finally allocated the time to migrate my old blog from Wordpress with MySQL to Jekyll with Webpack and Bootstrap. Finally, good riddance to a slow, non-responsive web site with potentially lots of security issues, and a sincere welcome to a fast, responsive and secure web site.

The new design is a lot cleaner than the old one, but it’s far from perfect yet. I hope to find some more time eventually for updating this blog not only with new content, but also with design improvements.

Enjoy!

TrueLicense 2.4 released

2015-04-02T17:22:15+02:00

I am very proud to announce the release of TrueLicense version 2.4!

So what is so special about this release?

If you have tried TrueLicense before, then you sure have used the TrueLicense Maven Archetype. This is a code generator which generates a custom licensing schema for your software product. However, in previous versions, the generated licensing schema was fix and you had to edit the generated code to do even simple things like changing passwords. Also, the key stores were fix and so you had to edit them, too. Overall, the old archetype exploited only a very small fraction of the TrueLicense Core API and yet it was very cumbersome and error-prone to work with. Well, that’s how it was!

For version 2.4, the TrueLicense Maven Archetype has been completely rewritten in order to exploit the full power of the TrueLicense Core API and yet be as easy to work with as possible. As a result, there is now a set of thirty properties for customizing the generated licensing schema! Passwords and key stores are automatically obfuscated and generated from these properties when building the project, so no code editing is required anymore!

Isn’t configuring thirty properties cumbersome, too?!

You don’t need to worry about the number of properties. There are reasonable default values set wherever possible. As a result, you don’t need to configure more properties than before in order to generate a custom licensing schema for your software product. But this time, the generated project automatically generates unique key stores and so you can immediately use the JARs after running the build. Here’s a minimal, yet fully working example:

$ mvn archetype:generate -B \
    -DarchetypeArtifactId=truelicense-maven-archetype \
    -DarchetypeGroupId=net.java.truelicense \
    -DarchetypeVersion=2.4 \
    -DartifactId=license \
    -DcompanyName="Company Inc." \
    -DdefaultPassword=test1234 \
    -DgroupId=com.company.product \
    -DlicensingSubject="Product 1" \
    -Dversion=1.0-SNAPSHOT
[...]
$ cd license
$ mvn install
[...]
$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar wizard

The last command starts the internationalized license wizard GUI. You can see some screenshots in the documentation.

Did you update the documentation?

Sure! To help you fully exploit all options with my shiny new code generator, I completely rewrote the documentation for the TrueLicense Maven Archetype. There are now twelve pages explaining all the details, including the CLI, GUI, WSI, API and last, but not least the certification of your custom licensing schema.

Finally, if you followed any of these links, you sure noticed the new web site design. I have spend some time in order to make sure the new TrueLicense web site provides you with an improved experience, just as the TrueLicense API does.

Enjoy!

Modeling Wizard Dialogs

2013-07-04T18:40:36+02:00

Wizard dialogs are a very common design pattern for user interfaces, e.g. for the GUI of software installation tools. However, although wizard dialogs are so ubiquitious these days, component frameworks such as Swing or JSF do not provide any support for them, so you have to turn to a third party library or roll your own. In this blog posting, I am modeling an abstraction for internationalized wizard dialogs which is independent of the particular user interface technology and easy to implement and use, e.g. in Swing based desktop applications or JSF based server applications.

Concept

The basic idea of a wizard dialog is to to split a larger task into multiple small, navigatable steps:

The task may be to execute a parameterized batch job. Then each step would prompt the user for some parameters and the final step would submit the batch job for execution. Alternatively, the user may cancel the wizard dialog before the batch job gets executed.
The steps may depend on each other so that they represent the vertices in a directed graph of job states with the wizard dialog as its stateful engine.
For navigation, the wizard dialog displays user interface components which, if enabled, switch to the previous step or the next step. Depending on the user interface technology, a component to cancel the wizard dialog may need to be displayed, too.

Use Cases

A software installation wizard dialog may prompt the user to decide which components to install at which location and finally perform the software installation based upon these parameters.
A license management wizard dialog may prompt the user to decide if a license key for the software should get installed, displayed or (optionally) uninstalled. The next step may then depend not only on the user’s choice, but also whether a license key is currently installed or not and if it’s valid or not.

In either case, a Swing based wizard dialog may display three buttons which enable the user to switch to the previous step, the next step or cancel the wizard dialog altogether. In contrast, a JSF based wizard dialog need not display a cancel button because cancelling the dialog is simply done by leaving or closing the browser page.

Requirements

I am going to define an abstraction for wizard dialogs which, in addition to the use cases, must meet the following requirements:

The abstraction must not depend on a particular user interface technology so that there can be different implementations.
The abstraction must not depend on a particular language so that an implementation can be internationalized.
Each step should be represented by a state of a stateful engine which meets the following requirements:
- The engine must not depend on a particular type of state so that the implementation can freely choose it.
- The engine must maintain the current state.
- The previous and the next state should depend on the current state and user input so that the engine walks the user through a directed graph of steps.

Design

I am going to apply a variant of the Model-View-Controller (MVC) pattern because it’s a natural fit for the implementation of a stateful engine for a user interface. Im also going to define the core abstractions as Java interfaces, not classes, because interfaces are most versatile when implementing the abstraction using different user interface technologies.

As a simplification to the MVC pattern, I will not apply the Observer pattern. That’s because (a) it adds a lot of complexity and constraints to the design and (b) you can almost always substitute it with the more powerful and simpler Decorator pattern (although this discussion deserves another blog posting).

Model

The wizard model is nothing but a holder for the current state and a map of views for each state:

public interface WizardModel<S, V> {

    S currentState();
    void currentState(S state);

    V view(S state);
    void view(S state, V view);
}

The current state is basically a property of the type parameter S, although I didn’t use the typical getCurrentState/setCurrentState naming pattern because I think it’s a thing of the past. The type parameter value is completely opaque, that is, the model does not know anything about this type. As you’ll see below, it is good practice to use an enum class as the value of this type parameter.

The map of views is basically a property of the type parameter V which is indexed by states. Again, I didn’t use the typical getView/setView name pattern and the value of the type parameter V is completely opaque.

This interface is accompanied by a reusable basic implementation:

public class BasicWizardModel<S, V> implements WizardModel<S, V> {

    public static <S extends Enum<S>, V> WizardModel<S, V> create(final Class<S> clazz) {
        return new BasicWizardModel<S, V>(new EnumMap<S, V>(clazz), clazz.getEnumConstants()[0]);
    }

    private final Map<S, V> views;
    private S state;

    protected BasicWizardModel(final Map<S, V> views, final S state) {
        this.views = Objects.requireNonNull(views);
        this.state = Objects.requireNonNull(state);
    }

    @Override
    public V view(S state) { return views.get(state); }

    @Override
    public void view(S state, V view) {
        views.put(state, Objects.requireNonNull(view));
    }

    @Override
    public S currentState() { return state; }

    @Override
    public void currentState(final S state) {
        this.state = Objects.requireNonNull(state);
    }
}

When subclassing this class, you need to provide the map for the views and the initial current state.

For convenience, a static constructor is provided which accepts an enum class as its sole parameter. It then passes an enum map and the first ordinal enum to the protected constructor. For example, with the following enum class for license management…

enum LicenseWizardState {
    welcome, install, display, uninstall;
}

… you could use the static constructor like this:

WizardModel<LicenseWizardState, MyView> model = BasicWizardModel.create(LicenseWizardState.class);

The static constructor saves you from typing the generic type parameters twice and the protected constructor retains the ability to use non-enum type states with this class if you want to.

View

The wizard view is another simple interface:

public interface WizardView<S> {

    S backState();
    S nextState();

    void onBeforeStateSwitch();
    void onAfterStateSwitch();
}

The (back|next)State methods enable the view to dynamically resolve the previous and next state, which is modeled as an opaque type parameter S again. If switching to a previous or next state is not available, e.g. because the user needs to provide some input first, then they need to return the current state.

The on(before|after)Switch methods are event methods which get called by the controller to indicate state change. A typical implementation may initialize and/or hide/display this view.

The wizard view is completely agnostic to the user interface technology. This enables you to use this abstraction with Swing, JSF or any other user interface technology, even a command line interface. Because of this and for the sake of brevity, there is no basic implementation provided here.

Controller

Last, but not least, the wizard controller interface looks like this:

public interface WizardController {

    boolean switchBackEnabled();
    boolean switchNextEnabled();

    void switchBack();
    void switchNext();
}

The boolean switch(Back|Next)Enabled method return true if and only if the respective (back|next)State method of the WizardView interface returns a different state than the current state. This may be used to enable or disable the respective button of the user interface.

Finally, the switch(Back|Next) methods switch the state of the engine from the current state to the previous or next state respectively. Calling these methods cause the on(Before|After)StateSwitch methods of the WizardView interface to be called.

In a typical implementation, the switch methods are the actions for the “back” and “next” buttons. You may wonder then why there is no action for a “cancel” button. This is because whether or not a “cancel” button is displayed is an implementation detail: In a desktop user interface (e.g. Swing based), it’ll most likely exist, whereas in a web app (e.g. JSF based), this wouldn’t make sense because cancelling the dialog is simply done by abandoning the browser session.

Although the contract for this interface implicitly depends on the WizardModel and WizardView interfaces, it doesn’t have an explicit dependency on these interfaces. Hence it also doesn’t know about their type parameters, that is it doesn’t know anything about the type of the wizard states or wizard views.

Again, this interface is accompanied by a reusable basic implementation:

public abstract class BasicWizardController<S, V extends WizardView<S>> implements WizardController {

    public static <S, V extends WizardView<S>> WizardController create(final WizardModel<S, V> model) {
        return new BasicWizardController<S, V>() {

            @Override
            protected WizardModel<S, V> model() { return model; }
        };
    }

    protected abstract WizardModel<S, V> model();

    @Override
    public final boolean switchBackEnabled() {
        return !backState().equals(currentState());
    }

    @Override
    public final void switchBack() { switchTo(backState()); }

    @Override
    public final boolean switchNextEnabled() {
        return !nextState().equals(currentState());
    }

    @Override
    public final void switchNext() { switchTo(nextState()); }

    private void switchTo(final S newState) {
        if (!newState.equals(currentState())) {
            fireBeforeStateSwitch();
            currentState(newState);
            fireAfterStateSwitch();
        }
    }

    protected final void fireBeforeStateSwitch() {
        currentView().onBeforeStateSwitch();
        onBeforeStateSwitch();
    }

    protected void onBeforeStateSwitch() { }

    protected final void fireAfterStateSwitch() {
        onAfterStateSwitch();
        currentView().onAfterStateSwitch();
    }

    protected void onAfterStateSwitch() { }

    protected final V currentView() { return view(currentState()); }

    protected final V view(S state) { return model().view(state); }
    protected void view(S state, V view) { model().view(state, view); }

    protected final S currentState() { return model().currentState(); }
    private void currentState(S state) { model().currentState(state); }

    protected final S backState() { return currentView().backState(); }
    protected final S nextState() { return currentView().nextState(); }
}

BasicWizardController is an abstract class because its model property method needs to be implemented in a subclass. For convenience, there is again a static constructor which accepts a generic wizard model as it’s sole parameter and implements a subclass for it.

Note that this time the type parameter V needs to extend WizardView<S>. This is required because the controller needs to ask the view for the previous and next states of the current state. This is a deviation from the pure MVC pattern where the controller would have to turn to the model to figure this. However, for this use case the deviation is simpler to implement.

The remainder of this class is pretty straightforward. The on(Before|After)StateSwitch methods are empty templates which mean to do the same thing as the equal named methods of the WizardView interface, yet they are called on the controller, not the view. Depending on the user interface technology, this may be more convenient. E.g. in a Swing based wizard, the onAfterStateSwitch method may be overridden to switch the tab of the CardPanel which hosts the JPanels for the different views.

Conclusions

That’s it, just three interfaces with just four methods each and two basic implementation classes! Given such a leightweight (or thin) abstraction, you may ask why you would want to use it? Here are some benefits:

Reusability: The abstraction is agnostic to the user interface and language, so it can be applied to many different problem domains.
Simplicity: The interfaces have just four methods each and the rather complex Observer pattern has been carefully avoided.
Don’t-repeat-yourself: The basic implementation classes save you from repeating and testing essential functionality.
Proven Practice: The abstraction has been used to implement wizard dialogs for license management based on Swing and JSF in my TrueLicense product.

Enjoy!

Guice Demo and Alternative DSL

2013-06-19T19:59:12+02:00

I just created a demo for Guice, Google’s popular dependency injection framework. The Guice Demo is a bit more complex and realistic than the samples in the Guice Wiki. The documentation discusses some general aspects of applying the Dependency Inversion Principle.

As an aftermath of this demo, I’ve also created Guicer, an alternative Domain Specific Language (DSL) for configuring a Guice Injector which is simpler and more concise than the original Guice DSL. The documentation introduces you to the DSL.

Enjoy!

How To Use Markdown Syntax With The Maven Site Plugin

2013-06-17T15:14:53+02:00

At current, there is very little information about how to use Markdown syntax to author pages for a project site with the maven-site-plugin. With this blog posting, I am going to change this - at least a little bit. ;-)

First, you should use version 3.3 of the Maven Site Plugin because it already defines a dependency on the Doxia Module Markdown, version 1.4. In your POM, add the following lines:

<project ...>
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <artifactId>maven-site-plugin</artifactId>
                    <version>3.3</version>
                </plugin>
                ...
            </plugins>
        </pluginManagement>
        ...
    </build>
    ...
</project>

Next, in your project directory, create the directory src/site/markdown. This will host your Markdown files. Markdown files may end with a .md or .md.vm extension. In the latter case, it gets preprocessed with the Velocity template engine, so you can evaluate some macros or expressions like ${project.name} in your Markdown files.

Next, to exploit the power of the maven-site-plugin, create a file named index.md.vm in this directory. This is the start page of the project site. Note that you don’t need to create a site descriptor for this sample. Make the contents of the file look like this:

#set($h1 = '#')
#set($h2 = '##')
#set($h3 = '###')
#set($h4 = '####')
<head>
    <title>Welcome to ${project.name}</title>
</head>

$h1 Welcome to ${project.name}

Lorem ipsem dolor sit amet...

There needs to be some explanation here:

Because the file ends with a .vm extension, it gets processed by the Velocity template engine. Unfortunately, Velocity uses a single hash character # as the prefix for macros and two hash characters as the prefix for comments. To escape these, I have chosen to define a variable for each heading level: $h1, $h2, etc.
You sure want to define some title in an HTML head, don’t you? Unfortunately, Markdown doesn’t directly support this. However, it does support to embed HTML tags in a page. Fortunately, if the tag is <head> then the Doxia Module Markdown will put its contents into the HTML head.
In a Velocity template, the maven-site-plugin supports accessing the POM via ${project.X} expressions, where X is the element you want to access. I have used this vehicle to quote the project name in the HTML title and level one heading of the document.

Finally, to start your sample site, run the following command …

$ mvn site:run

… and point your browser to http://localhost:8080 to see the magic happening.

Enjoy!

On Domain Specific Languages in Java: Lambda Expressions

2013-06-06T21:01:11+02:00

In this final part of the series I am going to look into the Lambda Expressions pattern to define an internal DSL for constructing object graphs. I am also going to provide some conclusions for the three patterns.

Lambda Expressions are all the rage these days. The tide started to rise with the paradigm shift towards multi-threaded applications. It’s arguably simpler to create a thread-safe application if it’s solely composed of pure functions (i.e. methods without side effects) than the traditional way of composing and sharing potentially mutable objects. Although you can certainly write functional code in a non-functional language like Java 7, it gets a lot easier with Lambda Expressions in Java 8.

Let’s look at the following example code from Mohamed Sanaulla’s excellent blog posting again:

Graph(g -> {
    g.edge(e -> {
        e.from(a);
        e.to(b);
        e.weight(12.3);
    });
    g.edge(e -> {
        e.from(b);
        e.to(c);
        e.weight(10.5);
    });
});

First, the good parts: Like with the Method Chaining pattern (if done right), the order of statements is irrelevant: You can swap them at will and it will still construct virtually the same object graph.

Another advantage is that you can provide some context with configurable default values for some properties of the constructed object graph. Consider this example:

public class GraphBuilder {

    double defaultWeight = 1.0;

    ...

    public void edge(Consumer<EdgeBuilder> eConsumer){
        EdgeBuilder eBuilder = new EdgeBuilder();
        eBuilder.weight(defaultWeight); // configure default value
        eConsumer.accept(eBuilder);
        ...
    }
}

In this modified example from Mohamed Sanaulla, I have added the eBuilder.weight(defaultWeight) statement. The effect is that if the eConsumer does not call the weight(Double w) method, then defaultWeight will prevail. Note that because this is an instance field, I do not need to share mutable state with other threads (I am assuming that there is a getter and a setter method for defaultWeight).

As you can see, the Lambda Expressions pattern is pretty much on par with the Method Chaining pattern. My biggest grief about it is that it’s a lot more code to write and read. Compare the initial example to the equivalent expression with Method Chaining again (I am using my Builder and Injection interfaces again):

Graph()
    .edge()
        .from(a)
        .to(b)
        .weight(12.3)
        .inject()
    .edge()
        .from(b)
        .to(c)
        .weight(10.5)
        .inject()
    .build();

This code has the same number of lines (twelve), yet it doesn’t need the ugly function and method call notation.

Conclusion

Finally, let’s compare the three patterns Method Chaining, Nested Functions and Lambda Expressions for defining an internal DSL for constructing object graphs: Among the three, the Nested Functions pattern clearly wins the competition for conciseness. As a reminder, here is the equivalent expression using the Nested Functions pattern to construct the object graph:

Graph(
    edge(from(a), to(b), weight(12.3),
    edge(from(b), to(c), weight(10.5)
);

This is just four lines of code instead of twelve - hooray! However, the Nested Functions pattern has two serious disadvantages: First, it can’t disambiguate parameters of the same type, so it can’t help you to avoid mistakes in their ordering. Second, it can’t easily provide some configurable context to the construction procedure without sharing mutable state. Considering the shift of paradigm to multithreaded applications, the last point is probably the most important. Therefore, I would only choose this pattern if these points do not apply and I could be confident that they still don’t apply when considering foreseeable changes in future versions of my code.

The Method Chaining and Lambda Expressions pattern do much better in this respect. Though they are functionally equivalent, the Method Chaining pattern is more concise. And then there is another difference: The Method Chaining pattern naturally restricts you to do only object graph construction (anything else will not compile) and the IDE can easily guide you through this procedure with code completion. In contrast, there are no such constraints with the Lambda Expressions pattern. You may think this is an advantage of the Lambda Expressions pattern, but I consider this being a disadvantage: My argument is that the purpose is object construction here and anything else should be inhibited (e.g. compiling your claim for tax refunds).

So the winner is… (drum roll and fanfare): The Method Chaining pattern! (your mileage may vary)

Enjoy!