6.4 KiB
Executable file
Browsing and publishing Gemini on a... Kobo?!
published: 2021-01-07
I have a Kobo Libra H2O. It's a little e-ink tablet-like device. While the specs aren't great, it does run Linux, which means theoretically one can run whatever programs they want on it! ...As long as those programs are line-based command-line or written for Kobo's special flavor of Qt.
Getting shell access to your Kobo
The first step is getting KOReader on the Kobo. Not only is it a much better reading app than the Kobo's built-in Nickel, it also includes a terminal emulator, a text editor, and a SSH server. The install instructions are on the KOReader wiki. I personally recommend using the NickelMenu installation method halfway down the page.
After you have KOReader set up, plug your Kobo into a computer with a USB cable.
cd /path/to/your/kobo/
cd ./.adds/koreader/settings/SSH/
ssh-keygen -trsa -b 2048 -f ~/.ssh/kobo
cp ~/.ssh/kobo.pub ./authorized_keys
Safely disconnect your Kobo from your computer. Go into KOReader, then tap the gear icon on the top of the screen. Tap "Network". Connect to the same WiFi network your computer is on, then tap on "SSH server" and then "Start SSH server".
ssh -i ~/.ssh/kobo -p 2222 root@your_kobo_local_ip_address
Shell access should only be necessary for troubleshooting. For this guide, we are more interested in SFTP file transfer.
Setting up your environment
There are four programs you'll need:
- godown: an HTML to Markdown converter
- gemget: wget, but for the Gemini protocol
- kurly: cURL, but written in Golang (since the version of
wgetthat ships with KOReader's Dropbear doesn't support HTTPS for some reason) - dave: a simple WebDAV server
The first three we will install on your Kobo. The last one will go on the server that runs your Gemini site.
I specifically picked programs written in Golang because they compile to a single binary. This means no trying to manually resolve dependencies, since the Kobo doesn't have a package manager installed (that I could see). However, they still must be compiled for ARM. I compiled them on my Raspberry Pi 4 (which is also an ARM device) and copied the resulting binaries to my computer. If you want to cross-compile on your local computer instead, you're on your own.
The config file for dave needs to go in ~/.swd/config.yaml on the remote server. It should look something like this:
address: "domain.tld" # the bind address
port: "7778" # the listening port
dir: "/path/to/your/gemsite/files" # the provided base dir
prefix: "/" # the url-prefix of the original url
users:
# user: # with password 'foo' and jailed access to '/home/webdav/user'
# password: "HASHED_PASSWORD"
# subdir: "/user"
YOURUSERNAME: # with password 'foo' and access to '/home/webdav'
password: "HASHED_PASSWORD"
tls:
keyFile: gemini.key
certFile: gemini.crt
You can make a HASHED_PASSWORD by running davecli passwd and following the prompts.
After that, you need to get TLS certificates so kurly doesn't shit its pants complain about having no certificates.
On your local computer:
sftp -P 2222 -i ~/.ssh/kobo root@your_kobo_local_ip_address
cd /etc/
mkdir ssl && cd ssl
mkdir certs && cd certs
lcd /usr/share/ca-certificates/mozilla/
put -r *
This will put all the certificates installed on your computer onto your Kobo. If this is too much for you, you can instead just upload the public key you used for your WebDAV server above (Gemini uses TOFU for its TLS and thus doesn't require a certificate store). Just change the extension to .pem first before uploading.
Put your binary program files in /bin/.
At this point, you should be all set up. You can disconnect from the SFTP server and turn the SSH server on your Kobo off.
The fun commands
Next to the gear icon at the top of the KOReader menu is a tool icon. Press it and then press "More tools". There's a terminal emulator!
Except it's not interactive, only processing one command at a time, and it doesn't save the state of the terminal in between sessions. While vi is installed, curiously, it's really only for debugging over SSH and isn't usable here. Best case scenario, it'll only print a bunch of terminal control characters and then exit without letting you do anything.
To look at an HTTP/S site: /bin/kurly http://example.com | /bin/godown | grep -v -e '^$'
To look at a Gemini site: /bin/gemget -o - gemini://domain.tld
To upload a text file: /bin/kurly -T /path/to/file.txt -u 'username:password' "https://domain.tld:port/"
These are quite a lot to type every time. I recommend saving them as shortcuts so you only have to change the domain or the file path every time instead of retyping everything.
CC BY-NC-SA 4.0 © Vane Vander
</html>