Setting up Tailscale on KOReader

“KOReader is a document viewer for E Ink devices”, as they advertise it. I use it as an alternative UI on my Kobo e-reader as I find it nicer than the default UI. It’s easy to install and is compatible with Wallabag, my read-it-later service of choice.

Recently, I moved my self-hosted Wallabag instance to be only accessible from Tailscale, as I’m the only user. It was all good since all my devices are connected to the Tailnet. All but my e-reader.

Fortunately, user victoria-riley-barnett on GitHub had packaged Tailscale as a KOReader plugin.

Installing the plugin and joining the Tailnet was easy enough with the provided instructions, but I struggled to access services from the Kobo. It turns out that due to system limitations, the plugin can’t route all traffic natively but can only expose an HTTP proxy. It’s then the user’s responsibility to configure KOReader to use that proxy.

I didn’t find step by step instructions online, so I’m documenting the process here in case it helps someone (or future me):

1. Install the plugin, follow the instructions to configure it but don’t turn on Tailscale yet

2. Configure Tailscale to use the system’s CA bundle:

   1. Add export SSL_CERT_FILE=/mnt/onboard/.adds/koreader/data/ca-bundle.crt to tailscale.koplugin/bin/start_tailscale.sh

   2. This is required because apparently the HTTP CONNECT proxy handles TLS handshakes so Tailscale has to know which certs to trust.

   3. There’s an open PR to fix this in the plugin directly

3. Turn on wifi (required otherwise the plugin hangs forever)

4. Turn on Tailscale

5. Configure the HTTP proxy by long pressing on the option in KOReader and input http://localhost:1056

6. Enable the HTTP proxy

7. Restart KOReader to make sure the HTTP proxy is taken into account

Done! You should now be able to connect to services inside your Tailnet from KOReader.

A few rough edges:

• The plugin doesn’t automatically start the network, making the UI unresponsive if Tailscale is started while not connected: Github issue #25

• When tailscale is running, it prevents the USB storage from starting: Github issue #26

It’s not a very polished experience, but it works! For now that’ll suffice.

I sent a few PRs to improve the overall UX, including fixes for the two aforementioned issues. They’re available on a single integrated branch at my fork.