Alan Pearce

scriptura: a cozy corner for your scripts

2026-02-06T15:42:00Z

I’ve created a new little tool to help run and manage scripts in a folder tree, called scriptura. It is based on the idea behind sd and is made for fish users.

Given a script folder like so:

$ set -x SCRIPTURA_ROOT ~/scripts
$ tree ~/scripts
~/scripts
├── os
│   └── update
│       ├── linde
│       └── r5 -> linde
└── scriptura
    └── tree

If I type in scriptura run os update linde, it will run the script at ~/scripts/os/update/linde, whilst providing tab completion for each element. Pressing tab after a script has been resolved will first add -- to clearly show the end of the script part of the command line, then use the default shell filename completion.

$ scriptura run os update linde -- <tab>
bin/        flake.nix  LICENSES/  private/    scripts/  system/
flake.lock  lib/       packages/  REUSE.toml  secrets/  user/

The usage information gives more detail on what can be done.

$ scriptura
Usage: scriptura <subcommand> <script_name>
SCRIPTURA_ROOT: ~/scripts

Subcommands:

  run          Run a script
  help         Display help information
  new          Create new script
  edit         Edit existing script
  which        Display script path
  cat          Display script content
  cmd          Execute shell command from target directory

User Subcommands:

  tree         print a tree of files under $SCRIPTURA_ROOT

Scripts:

os ...       -- os commands

Typing shortcuts

To reduce the amount of typing required, I have set the following aliases.

alias sfm="scriptura"
alias sf="scriptura run"

The fish completion system handles these well: sf <tab> will show me scripts to be run, whereas sfm will show me the subcommands of the tool.

Documenting scripts

To aid documentation, scriptura will look in a couple of places:

an adjacent file with the .help extension
comments inside the script (currently only supports one comment syntax #) Additionally, folders can be documented by adding a file called help. This information is then provided during tab completion, via the help subcommand or when listing scripts (the default action if a the command line does not resolve to a script).

Language support

Whilst scriptura is written in fish, scripts don’t have to be; it’s just the default. scriptura new will create scripts with a fish shebang, which can be freely edited. I also plan to add a command-line option to set a different interpreter.

Changes from sd

The blog post version of sd and the version published to Github already differ in that the blog post version uses subcommands like sd new, whereas the Github version uses flags for actions that don’t involve running a script (e.g. sd --new). I prefer the subcommand style, at least when there is a short alias to the run subcommand.

Additionally, I’ve added some new features.

New features

Tab completion after `new`

The new subcommand invokes the underlying command’s tab-completion after a script name is given:

$ scriptura new mac svc restart -- launchctl k<tab>
kickstart  (Forces an existing service to start)
kill    (Sends a signal to the service instance)

Run ad-hoc commands in the script root

$ scriptura cmd tree

will run the tree command with the working directory set to $SCRIPTURA_ROOT.

Custom subcommands

One thing that I thought would be useful is a tree subcommand. However, I don’t want to force that on any other potential users. Whilst I could have settled with the cmd subcommand mentioned in the previous section, I decided I wanted it to be even easier. Scripts under the special scriptura subdirectory are exposed as subcommands, which pass flags to the underlying command and interpret positional arguments as script path components:

# create a new script at ~/scripts/scriptura/tree which just calls tree
$ scriptura new scriptura tree -- tree
$ scriptura tree
.
├── os
│   └── update
│       ├── linde
│       └── r5 -> linde
└── scriptura
    └── tree

4 directories, 3 files
$ scriptura tree -L1 os
os
└── update

2 directories, 0 files

Motivation

Recently, I found sd, which is designed to help run and manage scripts under a specific directory tree.

There are two reasons I’m not using this tool directly:

It’s called sd, which is a name that’s already taken on my system by another tool: sd (sed alternative).
It doesn’t ship with completions for the fish shell. There was a gist with these, but it seems to have disappeared. The completions are, in my opinion, the biggest feature.

Also, I expected a fish implementation to be easier to read and write, as well as not requiring so many external command calls.

In the introductory blog post, Ian writes It’s not really a thing. It’s more of an idea. You can implement it yourself in one sitting, if you want..

It took me more than one sitting, but I enjoyed it.

Try it out

Visit the repository for installation instructions, including a home-manager module:

Avoiding Linguistic Misunderstandings

2025-04-15T00:00:00Z

Recently, I’ve been noticing more linguistic misunderstandings and it prompted me to make changes to how I communicate in order to reduce the likelihood of such misunderstandings.

Spell out initialisms

Unless 100% sure that the other party knows the same initialisms I do, I try to avoid them. I recently saw someone mention ‘SA’ in a group as referring to social anxiety, which led to some confusion as other participants thought about other meanings. If I’m talking to a web developer, then of course CSS and HTML don’t need to be spelled out.

I would also like to suggest that anybody that likes to use internet or generational slang to have their device expand these into their full forms rather than assuming that the other party has the same expansion in mind. I have noticed more difficulty communicating with younger people because they know a different set of initialisms than I do.

Use generic names

It’s a phone, not an iPhone. Whilst in this case it’s not too unreasonable to assume that anyone reading this knows what an iPhone is, this isn’t always true. Not everyone has the same knowledge of brands and products. Worse yet, not every region has the same brand or product names for the same products. In the United Kingdom, I grew up knowing what a Pritt Stick was, but most people in other regions will have no idea (it’s a stick of paper glue).

Prefer layperson’s terms

I once worked in a company providing loans to businesses. Every month there was a company meeting to provide updates from the various departments and I would often hear terms like ‘deliquency’ or ‘origination’ that I am not used to. Since my work wasn’t particularly related to loans, I wasn’t familiar with the terms and would have to ask or look them up later. I think that it’s something that contributed to my feeling of not really being a part of the company and also meant that I wasn’t able to follow the content of the meetings very well, at least in the beginning. I see a little irony in this, because I believe that people often prefer to adopt the specialised terms to try to signal being part of a group, but it can have the opposite effect on people who are not familiar with such terms.

Announcing Searchix: Nix ecosystem search

2024-07-11T13:05:00Z

I decided to create a search tool for NixOS, nix-darwin and home-manager options and packages, potentially with more sources to come.

I called it Searchix

For NixOS options and packages, search.nixos.org already exists (and works better than Searchix), whereas for home-manager and nix-darwin, I couldn’t manage to find a web-based search tool that’s still online¹. So I wrote one.

What I’m happy about with it is that it doesn’t require JavaScript, but, if it’s enabled, makes things a little bit better. It’s only my second project in Golang, so I still have things to learn, but I definitely think I will enjoy using this language further.

It still has quite a bit of room for improvement, but I’ve been using it quite a lot recently, which leads me to think that other people might like to use it, too.

If anyone would like to contribute, raise an issue, or host an instance themselves, the project site and source code are on codeberg.

I found Home Manager Option Search after I started this project, but nothing for nix-darwin. ↩︎

When Tailscale MagicDNS isn’t

2024-06-23T08:57:00Z

On a router, I have dnsmasq and kresd as DNS servers. Dnsmasq is accessible on the LAN interface and forwards queries to kresd, which is accessible on the loopback interface. This has been working for a long time.

I recently set up Tailscale and was confused as to why MagicDNS wasn’t working on this one device (I have two other NixOS devices that didn’t have any problems). I’m no stranger to investigating these problems, after using and tinkering with networking on Linux/FreeBSD for many years and if there’s a problem, it’s always DNS.

My first look at /etc/resolv.conf suggested things should be fine, I thought.

# Generated by resolvconf
search my-network.ts.net
nameserver 127.0.0.1
nameserver ::1

‘why is this even generated by resolvconf?’, I ask myself: this is a router with a static networking configuration and custom upstream nameservers. I’ll investigate that later, I tell myself.

I eventually realised that it should be using 100.100.100.100 for two reasons.

A working machine’s /etc/resolv.conf contains:

# Generated by resolvconf
search my-network.ts.net
nameserver 100.100.100.100
options edns0

The Tailscale dashboard gives me a hint under the nameservers section:

Nameservers

Set the nameservers used by devices on your network to resolve DNS queries. Learn more ↗

my-network.ts.net ✨MagicDNS
100.100.100.100

The linked documentation (DNS in Tailscale) doesn’t even mention 100.100.100.100, nor does the documentation for MagicDNS. It is explained as part of a blog post under the heading ‘how MagicDNS works’, but that’s not the first place I’d look.

This led me to try to find what might be responsible for the nameserver 127.0.0.1 setting:

I checked for systemd-resolved, but it wasn’t that (the nameserver would have been 127.0.0.53 if it were).
I didn’t think it was anything to do with dnsmasq because that’s configured to use the LAN interface, not the loopback.
I didn’t think it was kresd either, since another device uses kresd, but does not have the problem. kresd is not listening on a loopback address on the default port 53 on either machine, meaning that if it were doing this, DNS resolution would have been broken on both machines for a long time.

Eventually I stumbled upon something that worked: setting networking.resolvconf.useLocalResolver = false. I then started to investigate in order to open an issue with NixOS, but found things got more confusing and I forgot why I was shaving a yak¹.

Unexpected behaviours

The NixOS kresd module blindly sets networking.resolvconf.useLocalResolver to default to true because someone ran into resolver loops and this was accepted on the grounds that it’s ‘good to be consistent’ (with pdns-recursor, for example).
- I consider this “spooky action at a distance”. I do not think it should do this, but I can see how it could be helpful. In enough cases, though? I’m not sure.
- In my case, kresd was never even listening on localhost port 53, meaning that this default setting would have led to a broken DNS setup, which at least would at least have led me to investigate the right thing at that time. :::{.aside} Why didn’t it, then? :::
The NixOS dnsmasq module sets networking.resolvconf.useLocalResolver = true if services.dnsmasq.resolveLocalQueries = true. This is at least less spooky and distant, but still faulty.
1. I had indeed set services.dnsmasq.resolveLocalQueries = true, because I would like to be able to ping foo.lan on the router and it made that possible.
2. My erroneous assumption was likely that this setting changes the system nameserver to match the listen address of dnsmasq, rather than setting networking.resolvconf.useLocalResolver. Setting resolveLocalQueries = false was one of the first things I tried and it didn’t make a difference, which was unexpected (because kresd was setting it).
  
  If that weren’t enough, services.dnsmasq.resolveLocalQueries sets networking.nameservers to include 127.0.0.1, which makes things more confusing, and is wrong because I haven’t configured dnsmasq to listen on this address.
3. dnsmasq’s --interface=<interface name> setting doesn’t work either as I expected or as it is documented.
  
  -i, –interface=<interface name>
  Listen only on the specified interface(s).
  
  I had this set to listen only on the LAN interface and I could see it nevertheless listening on *:53 in lsof, rather than the addresses of the LAN interface.
  1. This behaviour is mentioned, under a different option, --bind-interfaces:
    
    On systems which support it, dnsmasq binds the wildcard address, even when it is listening on only some interfaces. It then discards requests that it shouldn’t reply to. This has the advantage of working even when interfaces come and go and change address. This option forces dnsmasq to really bind only the interfaces it is listening on. About the only time when this is useful is when running another nameserver (or another instance of dnsmasq) on the same machine.
    
    I had enabled this setting when I set up kresd on the machine, because the last sentence applies to my case and interfaces are not ‘coming and going’². The naming is weird as it would suggest it works like --interface; namely that --bind-interfaces=<interface name> would be a reasonable use. Alas, it is a boolean flag and takes no value.
  2. Even when --interface and --bind-interfaces are set, dnsmasq decides to ignore my intent and explicitly listen on loopback. This is weird, but, guess what, documented back under --interface:
    
    Dnsmasq automatically adds the loopback (local) interface to the list of interfaces to use when the –interface option is used.
  This explains why enabling kresd didn’t break things before; dnsmasq was listening on 127.0.0.1, even though I thought I had told it not to.
The option name networking.resolvconf.useLocalResolver and its documentation are unclear.

Use local DNS server for resolving.

This sentence adds no additional data not present in the option name. Local to what? I’m on a Local Area Network and wish to use a DNS server on the LAN, should I enable this? No, that’s not what this option is for. It could mean local to this host, looking at its usage. (I deliberately avoided combining the words ‘local’ and ‘host’, for reasons below)
- Even if it had a clearer name like useLocalhostResolver, the inaccuracy would remain, as getent hosts localhost and getent ahosts localhost both prefer ::1 over 127.0.0.1, not the other way around.
- What would have happened if I had enabled this setting with a server listening on ::1 and not 127.0.0.1? It would work, but not be the best setting as applications would attempt to reach a nameserver that is not listening on 127.0.0.1.
- It might be confusing to reference a hostname when talking about nameserver reachability, since an IP address is required to reach a nameserver and a nameserver is could be required to resolve a hostname. Setting nameserver localhost in /etc/resolv.conf won’t work, I thought.
  - I tried it. Neovim didn’t highlight it as an error³ and it did not break name resolution, presumably because localhost is added to /etc/hosts and is a special case in nss-myhostname, the existence of which I might not have known had I not set up multicast DNS to resolve .local hostnames in /etc/nsswitch.conf in the past,
    
    The hostnames “localhost” and “localhost.localdomain” (as well as any hostname ending in “.localhost” or “.localhost.localdomain”) are resolved to the IP addresses 127.0.0.1 and ::1.
    
    Why is localhost added to /etc/hosts if it’s handled by nss-myhostname in /etc/nsswitch.conf?? The man page of nsswitch.conf (mirror) gives a small clue:
  /etc/nsswitch.conf is used by the GNU C Library and certain other applications⁴
  
  Why isn’t even the choice of a name resolution mechanism for localhost unified in 2024?
  - I tried on macOS and iOS. Both allow setting a named nameserver in the GUI, which surprised me. I remember that on earlier versions of Windows (at least on XP, Vista and 7) there were special input boxes that exclusively allowed an IPv4 address, although there was a separate dialogue to input IPv6 addresses. I wonder if that allows hostnames or not, but I don’t have Windows running at the moment to check.
Setting networking.resolvconf.enable = false doesn’t appear to do.. well.. anything.
- The generated by resolvconf comment in /etc/resolv.conf remains, as do the previous nameserver entries.
- /run/current-system/sw/bin/resolvconf is not removed.
- man resolvconf has content (because it’s a link to man resolvectl, which is part of systemd-resolved, which isn’t even enabled on this system)
- I was surprised that /etc/resolv.conf was writable at all, as ~~all~~ many files under /etc/ are symlinks to their namesakes under /etc/static, which itself is a symlink to a folder in the nix store which contains… more symlinks. Here I use resolvconf.conf as an example, i.e. the configuration of resolvconf, the program that manages resolv.conf.
```
 rwxrwxrwx 1 root root  27 May 26 23:14 /etc/resolvconf.conf -> /etc/static/resolvconf.conf
lrwxrwxrwx 1 root root  51 May 26 23:14 /etc/static -> /nix/store/pm0yi93ak5kcvfmidv5lckzfixrh2gck-etc/etc/
lrwxrwxrwx 4 root root  63 Jan  1  1970 /nix/store/pm0yi93ak5kcvfmidv5lckzfixrh2gck-etc/etc/resolvconf.conf -> /nix/store/kf0lrhiqqqrc6w96h4qm0sysffnccx2d-etc-resolvconf.conf
-r--r--r-- 3 root root 518 Jan  1  1970 /nix/store/kf0lrhiqqqrc6w96h4qm0sysffnccx2d-etc-resolvconf.conf
```
  That’s too much indirection for me. If ‘we can solve any problem by introducing an extra level of indirection’, this suggests that at least three problems have been solved here.
  
  Isn’t it odd that the symlinks are writable to all? I know that /nix/store is a read-only filesystem, but it looks odd. Upon searching the web for information, I was directed to the coreutils chmod documentation:
  
  chmod doesn’t change the permissions of symbolic links; the chmod system call cannot change their permissions on most systems, and most systems ignore permissions of symbolic links
  
  Most systems? What does this mean? Is it based on the filesystem used? I would assume that it doesn’t mean ’this is the case on Linux’ given the reference to the system call of the same name and that Linux was not mentioned. The man page for the system call mentions
  
  flags can either be 0, or include the following flag:
AT_SYMLINK_NOFOLLOW
If pathname is a symbolic link, do not dereference it: instead operate on the link itself. This flag is not currently implemented.
- The default value of networking.resolvconf.enable is !(config.environment.etc ? "resolv.conf"), which I understand as if the content of resolv.conf isn’t otherwise assigned.
- There are values in networking.nameservers, but these aren’t used as content for resolv.conf, which I thought would have been reasonable.
What is the point of networking.resolvconf.enable, then? And what about networking.nameservers? Where do its values even go? ⁵
This issue pushed me to drop flakes on the router so that nixos-option would help me as it does not support flakes⁶.
The Tailscale module adds resolvconf to its path conditionally. The commit adding this condition explains that ‘trying to use [resolvconf] always fails because /etc/resolvconf.conf contains an exit 1’, which sounds perfectly reasonable.
- If resolvconf weren’t in tailscaled’s path, Tailscale would fall back to overwriting resolv.conf, which I found out about because it is a common enough problem/question to warrant a heading and its own page.
  
  This document is the most concise and informative clarification of my original issue; the last paragraph tells me everything I needed to know:
  
  Even if you set --accept-dns=false, Tailscale’s MagicDNS server still replies at 100.100.100.100 (or fd7a:115c:a1e0::53), as long as MagicDNS is enabled on the tailnet. If you’d like to manually configure your DNS configuration, you can point *.ts.net queries at 100.100.100.100.
  
  Sadly I didn’t look at this page earlier as Tailscale isn’t the one overwriting /etc/resolv.conf: it would have set the nameserver to be 100.100.100.100 in that case. Its behaviour is reasonable as ‘there are an incredible number of ways to configure DNS on Linux’.
  - This blog post suggests that the upcoming (as of April 2021) Tailscale 1.8 will use/prefer using systemd-resolved to configure the system resolver
  - It convinced me that systemd-resolved would be the right choice even on a router as the nameserver should depend on the interface. Thanks Xe, I always like your posts!

This should be the end of my issues now then, right?

What happens when I enable systemd-resolved and disable resolvconf? The hilarity continues:

# resolv.conf(5) file generated by tailscale
# For more info, see https://tailscale.com/s/resolvconf-overwrite
# DO NOT EDIT THIS FILE BY HAND -- CHANGES WILL BE OVERWRITTEN
nameserver 100.100.100.100
search my-network.ts.net lan my-network.ts.net

I expected Tailscale not to overwrite resolv.conf in this scenario, but instead configure systemd-resolved (Adding the tailnet to the search domains without checking its presence is yet another issue). I think it’s a race condition that tailscaled won that might have been caused by NixOS starting the services at the same time, however tailscaled.service has After=systemd-resolved.service. Restarting systemd-resolved then tailscaled explicitly did the right thing:

# This is /run/systemd/resolve/stub-resolv.conf managed by man:systemd-resolved(8).
# Do not edit.
# [...]
nameserver 127.0.0.53
options edns0 trust-ad
search lan my-network.ts.net

DNS can be confusing sometimes!

Whilst checking to see if yak shaving was the right turn of phrase, Wiktionary suggested ‘when you’re up to your neck in alligators, it’s hard to remember that your initial objective was to drain the swamp’ which would be more fitting, but I first learned of this expression today and don’t think it’s as widely-known. ↩︎
Since the router has a dynamic ~~public~~ CGNAT IP address, it’s true that the addresses are changing, but that’s not relevant to dnsmasq given that it was not ever configured to listen on this interface. ↩︎
vim’s syntax highlighting in /etc/resolv.conf marks nameserver localhost as an error, which is neat, but somewhat inaccurate here, as this does not appear to be invalid. ↩︎
As a Wikipedia editor would ask, which? ↩︎
I searched nixpkgs on Github and found it amusing that all the results where it is set correctly are in tests, but the other results show hardcoded definitions. ↩︎
After reading through the issue, the title does not appear to be accurate given that there are workarounds, however, upon loading the page and seeing that the issue is open since 2020 and has a small scroll bar, indicating many comments, it’s easy to be drawn to the assumption that it continues to be an issue. ↩︎

Homesteading

2023-09-22T10:09:22.141Z

I switched away from Zola and made my own static site builder that uses only HTML templates. I’ve been wanting to do this since at least 2017, when I started to work on a homestead project, which I didn’t quite finish.

The recent release of Bun, which touts itself as an “all-in-one JavaScript toolkit” encouraged me to play around with it. I have to say, I am surprised by how energising it was; an antidote to the “JavaScript fatigue” I’ve read about and definitely experienced.

I decided that I’d start by serving my site using Bun’s web server, then I added site generation later. I have been intrigued by the idea of DOM templating ever since I read about it on Camen Design in 2012 and I’ve enjoyed putting it into practice.

Running NixOS on a NanoPi R5S

2023-07-30T08:51:46Z

I managed to get NixOS running on my NanoPi R5S (FriendlyElec Wiki).

Firstly, I flashed a pre-built stock Debian image from inindev to an SD card. This can be used as a rescue system later on.

From that SD card, I then flashed the same system onto the internal eMMC Storage. I only really needed to this to ensure UBoot was correctly installed; I think there will be an easier way to do it.

I had nix already installed on the NVMe SSD along with a home directory. I bind-mounted /nix and /home following the fstab I had previously set up:

UUID=replaceme  /mnt    ext4    relatime,lazytime   0 2
/mnt/nix        /nix    none    defaults,bind       0 0
/mnt/srv        /srv    none    defaults,bind       0 0
/mnt/home       /home   none    defaults,bind       0 0

I then created a user for myself using that home directory, I had full access to nix in the new Debian environment. This meant I had access to nixos-install.

I wanted to use the extlinux support in UBoot, so I made /mnt/boot point to /boot on the eMMC:

mkdir /mnt/{emmc,boot}
mount LABEL=rootfs /mnt/emmc
mount --bind /mnt/emmc /mnt/boot

One could probably delete everything else on the eMMC and move the contents of /mnt/emmc/boot to /mnt/emmc, thus obviating the need to bind-mount /boot

I ran nixos-generate-config as usual, which set up the mount points in hardware-configuration.nix correctly. configuration.nix needed a bit of tweaking. My first booting configuration was something like this, mostly borrowed from Artem Boldariev’s comment:

{ config
, pkgs
, lib
, ...
}:
let
  fsTypes = [ "f2fs" "ext" "exfat" "vfat" ];
in
{
  imports = [ ./hardware-configuration.nix ];
  boot = {
    kernelPackages = pkgs.linuxKernel.packages.linux_6_4;

    # partial Rockchip related changes from Debian 12 kernel version 6.1
    # Also, see here:
    # https://discourse.nixos.org/t/how-to-provide-missing-headers-to-a-kernel-build/11422/3
    kernelPatches = [
      {
        name = "rockchip-config.patch";
        patch = null;
        extraConfig = ''
          PHY_ROCKCHIP_PCIE Y
          PCIE_ROCKCHIP_EP y
          PCIE_ROCKCHIP_DW_HOST y
          ROCKCHIP_VOP2 y
        '';
      }
      {
        name = "status-leds.patch";
        patch = null;
        # old:
        # LEDS_TRIGGER_NETDEV y
        extraConfig = ''
          LED_TRIGGER_PHY y
          USB_LED_TRIG y
          LEDS_BRIGHTNESS_HW_CHANGED y
          LEDS_TRIGGER_MTD y
        '';
      }
    ];
    
    supportedFilesystems = fsTypes;
    initrd.supportedFilesystems = fsTypes;

    initrd.availableKernelModules = [
      ## Rockchip
      ## Storage
      "sdhci_of_dwcmshc"
      "dw_mmc_rockchip"

      "analogix_dp"
      "io-domain"
      "rockchip_saradc"
      "rockchip_thermal"
      "rockchipdrm"
      "rockchip-rga"
      "pcie_rockchip_host"
      "phy-rockchip-pcie"
      "phy_rockchip_snps_pcie3"
      "phy_rockchip_naneng_combphy"
      "phy_rockchip_inno_usb2"
      "dwmac_rk"
      "dw_wdt"
      "dw_hdmi"
      "dw_hdmi_cec"
      "dw_hdmi_i2s_audio"
      "dw_mipi_dsi"
    ];
    loader = {
      timeout = 3;
      grub.enable = false;
      generic-extlinux-compatible = {
        enable = true;
        useGenerationDeviceTree = true;
      };
    };
  };
  # this file is from debian and should be in /boot/
  hardware.deviceTree.name = "../../rk3568-nanopi-r5s.dtb";
  # Most Rockchip CPUs (especially with hybrid cores) work best with "schedutil"
  powerManagement.cpuFreqGovernor = "schedutil";
  
  boot.kernelParams = [
    "console=tty1"
    "console=ttyS2,1500000"
    "earlycon=uart8250,mmio32,0xfe660000"
  ];
  # Let's blacklist the Rockchips RTC module so that the
  # battery-powered HYM8563 (rtc_hym8563 kernel module) will be used
  # by default
  boot.blacklistedKernelModules = [ "rtc_rk808" ];

  # ... typical config omitted for brevity
}

Due to the custom kernel configuration, building takes a while. I set up a distributed build to speed things up, using a Hetzner Cloud CAX21 ARM64 instance (although I could have used an x86_64 system with one of the methods mentioned on the NixOS on ARM NixOS wiki page). This made for a very long nixos-install command line:

sudo env PATH=$PATH =nixos-install --root /mnt --no-channel-copy --channel https://nixos.org/channels/nixos-23.05 --option builders'ssh://my-host aarch64-linux /root/.ssh/id_pappel_nixpkgs 4 2 big-parallel' --option builders-use-substitutes true --max-jobs 0

I added setenv bootmeths "extlinux" to /boot/boot.txt and ran /boot/mkscr.sh as root to ensure that UBoot would search for the extlinux.conf file

Now on three continents

2023-07-02T07:55:35Z

This website is now hosted on three continents.

I recently changed the hosting for this site to fly, since I was rather intrigued by the idea of being able to run three small VMs (Virtual Machines) worldwide for free. I would gladly have paid a small amount for their services. If they didn’t have a free allowance for VMs then it would only be around $6 a month, so I’m not worried about them removing the free allowance.

Previously it was running on one Hetzner VM in Nuremberg, Germany that I set up and maintained myself. The maintenance wasn’t a problem for me, but rather the idea of slow loading times for anyone reading this outside of Europe.

American visitors should notice a definite speedup now, as there’s a server on the west coast and for the few visitors in the Asia-Pacific region, there’s also a server in Australia. I kept track of the response time before and after the change using the Online or not Do I need a CDN? tool, which you can see in the table below (measured in ms)

Region	Before	After
Europe (Frankfurt)	62	32
US East (N. Virginia)	348	185
US West (N. California)	503	61
Asia Pacific (Tokyo)	732	251
Asia Pacific (Sydney)	1114	76

I do find it rather amusing that I spend more time tinkering with the site than actually posting anything, but, for once, tinkering has actually led to me posting something (this post). I would like to think that this might encourage me to post more in the future, but only time will tell.

Postfix on a NixOS null client with external catch-all

2020-09-11T16:49:00Z

I wanted to set up a server so that any local email (e.g. generated by cron jobs/systemd timers) would be forwarded to an external address, regardless of the user. I also wanted the from address to keep the system hostname whilst not allowing any external use of the mailserver.

It took me a while to figure out how to this, so I thought I’d share my method.

Here’s the config that can be used to do this on any NixOS host, after redefining the first two variables.

services.postfix = let
  localUser = "example-user";
  forwardingAddress = "user@external.domain";
in
{
  enable = true;
  destination = [];
  domain = config.networking.domain;
  virtual = ''
    @${config.networking.hostName}.${config.networking.domain} ${localUser}
    ${localUser} ${forwardingAddress}
  '';
  config = {
    inet_interfaces = "loopback-only";
  };
};

Emails to any user without a domain part are all sent to the forwarding address with a clear from address (e.g. System administrator <root@host.example.com>).

Background

First, the basic setup for a null client can be found in the postfix documentation. The example config would be translated into NixOS like so:

services.postfix = {
  enable = true;
  destination = [];
  domain = config.networking.domain;
  origin = config.networking.domain;
  relayHost = config.networking.domain;
  lookupMX = true;
  config = {
    inet_interfaces = "loopback-only";
  };
};

However, this rewrites user@hostname.example.com to user@example.com (due to origin on line 5). I wanted to be able to see which host a mail concerns.

A simple, powerful self-hosted git setup

2017-06-04T10:33:02Z

I had been using gogs for about a year. It worked reasonably well, as it focuses on being a lightweight self-hosted GitHub replacement. However, that wasn’t really what I wanted. I just wanted to host my own projects, I didn’t need things like issues, pull requests or wikis.

I recently switched to gitolite and cgit, as they were even lighter on resources, don’t require another login and work without an external database. Gitolite is unusual in its configuration: it creates a git repository with its configuration file. I will describe how I use them, rather than how to set them up, as they both have enough documentation on that.

My gitolite configuration file looks like this:

repo gitolite-admin
    RW+     =   alan

repo dotfiles
    C   =   alan
    RW+ =   alan
    R   =   READERS
    option hook.post-update   =    github-mirror

repo [a-z].*
    C   =   alan
    RW+ =   CREATOR
    RW  =   WRITERS
    R   =   READERS

The first block just allows me to work with the configuration repository, as the initial setup only enables one specific public SSH key, whereas I have three keys that I configure gitolite with.

The second configures my dotfiles specifically. Naturally, I should be the only person with read/write access. The R = READERS line allows remote configuration of read permissions via ssh $DOMAIN perms (explained further below). The last line runs a mirror script (just git push --mirror…) so that my dotfiles repository on GitHub is updated when I push to my private version.

Wild (or magic) repositories

The third block is where things get interesting. gitolite has a feature called wildrepos, which allows configuring a set of repositories at once, using a regular expression to match the repository name.

The really nice thing here is that the repository need not exist before applying the configuration. Therefore, the line C = alan means that I can create a remote repository automatically by cloning a repository URL that doesn’t already exist. I can clone and create a new repo simultaneously like so:

cd ~/projects
git clone alanpearce.eu:some-new-repository

But with ghq, which I blogged about before, I don’t have to concern myself with where to put the repository:

$ ghq get alanpearce.eu:some-new-repository
     clone ssh://alanpearce.eu/some-new-repository -> /Volumes/Code/projects/alanpearce.eu/some-new-repository
       git clone ssh://alanpearce.eu/some-new-repository /Volumes/Code/projects/alanpearce.eu/some-new-repository
Cloning into '/Volumes/Code/projects/alanpearce.eu/some-new-repository'...
Initialized empty Git repository in /var/lib/gitolite/repositories/some-new-repository.git/
warning: You appear to have cloned an empty repository.

The nice URLs come from this piece of my SSH configuration:

Host alanpearce.eu
  HostName git.alanpearce.eu
  User gitolite

Configuring wild repositories

This repository would be private by default, but I can change that by an SSH command. Here’s how I would do it:

ssh alanpearce.eu perms some-new-repository + READERS gitweb
ssh alanpearce.eu perms some-new-repository + READERS daemon

The first command makes it visible in cgit, whilst the second makes it clonable via git:// url. I can make a repository publically-clonable, but invisible on cgit by only allowing the daemon user and not gitweb, if I wanted.

I can also add or change the description of a repository shown on cgit like so:

ssh alanpearce.eu desc some-new-repository 'A new repository'

All the remote commands exposed by gitolite are described in the help command e.g. ssh alanpearce.eu help

hello alan, this is gitolite@oak running gitolite3 (unknown) on git 2.12.2

list of remote commands available:

	D
	desc
	help
	info
	motd
	perms
	writable

Conclusion

I much prefer creating repositories in this way. It’s much simpler and allows me to get on with working on the repositories rather than going through a multi-step process in a web browser.

With cgit and gitolite, I have a minimal setup, that does exactly what I want, without consuming many system resources with daemons.

Repository management with ghq

2017-05-06T21:31:51Z

I recently encountered ghq, a tool for automatically organising VCS-backed projects automatically. Give it a repository URL, it will clone a project to your projects dir (set by $GHQ_ROOT) like so:

$ ghq get https://github.com/motemen/ghq
# Runs `git clone https://github.com/motemen/ghq ~/.ghq/github.com/motemen/ghq`

I don’t like the idea of having projects hidden away, so I set $GHQ_ROOT to $HOME/projects.

From there, the list and look subcommands allow listing repositories and visiting them in the shell (actually a subshell).

I wanted a nicer way to visit project directories. Since I’m using fzf as a fuzzy-finder, I thought it would be nice to use it for this. I created a simple function, fp (find project) to do that:

fp () {
  ghq look $(ghq list | fzf +m)
}

I ran into some issues with the subshell of ghq look and wondered whether it might be possible to create a zsh command to remove the need for a subshell.

I found that fzf includes a cd-widget function and created something similar that uses ghq instead of find:

cd-project-widget () {
  local cmd="ghq list"
  setopt localoptions pipefail 2> /dev/null
  local dir="$(eval "$cmd" | FZF_DEFAULT_OPTS="--height ${FZF_TMUX_HEIGHT:-40%} --reverse $FZF_DEFAULT_OPTS $FZF_ALT_C_OPTS" fzf +m)"
  if [[ -z "$dir" ]]; then
    zle redisplay
    return 0
  fi
  cd $(ghq list --full-path | grep "$dir")
  local ret=$?
  zle reset-prompt
  typeset -f zle-line-init >/dev/null && zle zle-line-init
  return $ret
}
zle -N cd-project-widget

It should be quite simple to modify it to work with other fuzzy-finders. The basic idea is to show the output of ghq list for selection, and use ghq list --full-path with the selected candidate to print the correct directory for cd.

What’s really nice about this, is that I can bind it to a key sequence:

bindkey '\es' cd-project-widget

Now I can press M-s in a shell, start typing “nixfiles” and press enter to cd to my nixfiles project. Pretty neat!

Back again

2017-05-06T14:55:57Z

I’ve not made any posts for quite some time. My life has changed quite a bit, I’ve emigrated from the UK and it’s only now that I’m starting to feel more settled.

I hope to start posting a bit more often. Hopefully this post, despite being light on content, will help me to get back into the sharing mindset.

Cedit and Paredit

2014-08-04T07:10:14Z

I recently discovered cedit, which provides some structural commands for editing c-like languages. (See this Emacs Rocks! episode if you’re not familiar with the concept: it introduces paredit, a structural editing mode for lisps).

So, it deals with curly braces and semicolons, keeping things balanced and correct as show in its screencast. It mentions that it integrates with paredit rather than duplicating all its functionality. After setting up cedit, I decided to try enabling paredit alongside cedit and disabling autopair. Once I did, however, I noticed an annoying formatting issue: If I were to type foo and then (, paredit would format this as foo (), which makes sense, considering that paredit is written for lisps — s-expressions are usually separated by spaces — but not so much for c-like languages.

I was thinking about disabling paredit and going back to autopair, when I decided to look through the configuration variables for paredit. Turns out it provides paredit-space-for-delimiter-predicates, which is a list of functions that control whether a space should be inserted. So, solving the formatting issue turned out to be pretty simple:

(defun ap/cedit-space-delimiter-p (endp delimiter)
"Don't insert a space before delimiters in c-style modes"
(not cedit-mode))
(add-to-list 'paredit-space-for-delimiter-predicates #'ap/cedit-space-delimiter-p)

Hopefully that saves someone some time if they try to use the two together.

Emacs Package Archive Statistics

2014-07-19T13:19:54Z

I use cask for managing the dependencies of my Emacs configuration. Whenever I opened my Cask file, I wondered if I really was using all the sources I had defined:

(source gnu)
(source marmalade)
(source melpa)
(source melpa-stable)
(source org)

It seemed quite strange that we have so many package repositories in the Emacs world and I’m not even using all of them. I find this state less than ideal, much as Jorgen Schäfer details. My ideal package repository would be once that works with VCS releases, mostly because it’s a much simpler process to work with than having to sign up to yet another website just to upload a package, then ensure it’s kept up-to-date on every release.

As such, I prefer the concepts behing MELPA and MELPA Stable to those of Marmalade. GNU ELPA doesn’t appear to allow any submissions and org is specific to org-mode. I’ve also noticed that many packages I find and use are on github and so work with the MELPA system. However, I don’t like MELPA’s versioning: it just gets the latest code and puts the build date in the version, meaning that packages could break at any time.

So, ideally I would use MELPA Stable as much as possible and reduce my usage of Marmalade and MELPA. GNU ELPA doesn’t appear to have many packages, but I wasn’t sure if I was using any. I couldn’t see the information listed in the *Packages* buffer, so I decided to try to figure out how to generate some usage statistics.

I found how to get a list of installed packages, but that just gives a list:

(ace-jump-mode ag auto-compile auto-indent-mode autopair ...)

I needed to get more information about those packages. I looked at where list-packages gets that information from. It seems that package-archive-contents is a list of cons cells:

(org-plus-contrib .
				  [(20140714)
				  nil "Outline-based notes management and organizer" tar "org"])

Then created a function to loop over the contents of package-activated-list, retrieving the corresponding contents of package-archive-contents:

(defun package-list-installed ()
  (loop for pkg in package-activated-list
        collect (assq pkg package-archive-contents)))

This generates a list of arrays from package-archive-contents. There are some helper functions in package.el such as package-desc-kind. package-desc-archive was exactly what I needed. I happened to be using a pretest version of Emacs at the time and didn’t know that it’s not in 24.3, so I just made sure it was defined:

(if (not (fboundp #'package-desc-archive))
    (defsubst package-desc-archive (desc)
      (aref desc (1- (length desc)))))

Weirdly, some of the arrays (seemingly the ones from the org archive) had a different length, but the repository/archive was always the last element, which is why I used (1- (length )) and not a constant, like the other package-desc-* functions.

To generate a list of statistics, I just needed to loop over the installed packages from package-list-installed and update a count for each archive:

(defun package-archive-stats ()
  (let ((archives (makehash))
        (assoc '()))
    (dolist (arc package-archives)
      (puthash (car arc) 0 archives))
    (maphash (lambda (k v)
               (setq assoc (cons (cons k v) assoc)))
             (dolist (pkg (-filter #'identity (package-list-installed)) archives)
               (let ((pkg-arc (package-desc-archive (cdr pkg))))
                 (incf (gethash pkg-arc archives)))))
    assoc))

Running this gives a list of cons cells:

(("gnu" . 0)
 ("org" . 1)
 ("melpa-stable" . 2)
 ("melpa" . 106)
 ("marmalade" . 1))

I wrapped it in an interactive function so that I could check the numbers quickly:

(defun package-show-archive-stats ()
  (interactive)
  (message "%s" (package-archive-stats)))

With that, I removed (source gnu) from my Cask file. Now I had another question. What package was installed from marmalade? In the lisp fashion, I created yet another function:

(defun package-show-installed-from-archive (archive)
  (interactive (list (helm-comp-read "Archive: " (mapcar #'car package-archives)
                                      :must-match t)))
  (let ((from-arc (mapcar #'car
                          (--filter (equalp (package-desc-archive (cdr it)) archive)
                                    (package-list-installed)))))
    (if (called-interactively-p)
        (message "%s" from-arc)
      from-arc)))

(Non-helm users can replace helm-comp-read with ido-completing-read or similar)

Running this with the argument "marmalade" gives:

(php-extras)

I checked on MELPA Stable and MELPA, but it’s not available there. Given that I use php-extras quite a bit at work, I can’t remove marmalade just yet. However, as it’s a git repository, it should be easy for me to create a recipe for MELPA. Then I can remove marmalade from my cask configuration. Hooray for simplification!

Hopefully, packaging in Emacs will become simpler in the future. There are some interesting things in 24.4 like pinning packages to a repository, which would allow MELPA Stable to be used even when MELPA defines the same package with a higher “version”.

Opening Projects with Projectile

2014-07-12T09:12:34Z

I use Projectile for working with projects in Emacs. It’s really good at finding files in projects, working with source code indexes (I use Global), and with its perspective support, it’s also great at separating projects into workspaces. However, I’ve always felt it lacking in actually opening projects. I tend to work on different projects all the time and projectile-switch-project only tracks projects once they’ve been opened initially (despite the name, it works across Emacs sessions).

With this in mind, I decided to try to add support for opening projects under a given subdirectory, e.g. ~/projects, regardless of whether or not I’ve visited them before.

I saw that projectile uses Dash.el in some places, and after reading about anaphoric macros, I decided that I’d try to use them to aid me.

(defun ap/subfolder-projects (dir)
  (--map (file-relative-name it dir)
         (-filter (lambda (subdir)
                    (--reduce-from (or acc (funcall it subdir)) nil
                                   projectile-project-root-files-functions))
                  (-filter #'file-directory-p (directory-files dir t "\\<")))))

First, this filters the non-special files under dir, filtering non-directories. Then it runs the list of projectile-project-root-files-functions on it to determine if it looks like a projectile project. To make the list more readable, it makes the filenames relative to the passed-in directory. It runs like this:

(ap/subfolder-projects "~/projects") =>
("dotfiles" "ggtags" …)

So, we’ve got ourselves a list, but now we need to be able to open the project that’s there, even though the folders are relative.

(defun ap/open-subfolder-project (from-dir &optional arg)
  (let ((project-dir (projectile-completing-read "Open project: "
                                     (ap/subfolder-projects from-dir))))
    (projectile-switch-project-by-name (expand-file-name project-dir from-dir) arg)))

By wrapping the call to ap/subfolder-projects in another function that takes the same directory argument, we can re-use the project parent directory and expand the selected project name into an absolute path before passing it to projectile-switch-project-by-name.

We get support for multiple completion systems for free, since projectile has a wrapper function that works with the default system, ido, grizzl and recently, helm.

Then I defined some helper functions to make it easy to open work and home projects.

(defvar work-project-directory "~/work")
(defvar home-project-directory "~/projects")

(defun ap/open-work-project (&optional arg)
  (interactive "P")
  (ap/open-subfolder-project work-project-directory arg))

(defun ap/open-home-project (&optional arg)
  (interactive "P")
  (ap/open-subfolder-project home-project-directory arg))

I could probably simplify this with a macro, but I’m not sure that there’s much advantage in it. I only have two project types right now, after all.

With this all set up, whenever I want to start working on a project I just type M-x home RET to call up the list.

I also considered trying to add all the projects under a directory to the projectile known project list. I didn’t find it quite as easy to use, but it’s available below if anyone would prefer that style.

(defun ap/-add-known-subfolder-projects (dir)
  (-map #'projectile-add-known-project (--map (concat (file-name-as-directory dir) it) (ap/subfolder-projects dir))))

(defun ap/add-known-subfolder-projects ()
  (interactive)
  (ap/-add-known-subfolder-projects (ido-read-directory-name "Add projects under: ")))

Cloning Similar Git Repositories

2014-06-22T08:35:24Z

With multiple similar git repositories, for example where a base repository contains a framework or base system installation and other repositories are created from that repository, it’s possible to save some time when cloning down another repository by using the reference option to git-clone:

git clone git@github.com/my/repo --reference another-repo

(Where another-repo points to a local version of a repository.)

The reference here doesn’t have to be the base repository itself, it could just be another variant of it. The speedup can be quite dramatic if the repositories have megabytes of shared history, from minutes to seconds.

On a related note, I’m surprised that GitHub doesn’t allow for multiple renamed forks, which would be very useful in this scenario. BitBucket does support this, however. It even has a ‘sync’ button for pulling updates from the base into the child repositories, which is very useful, especially for those who prefer GUIs over CLIs.

A New Site

2014-06-07T20:16:16Z

I finally got around to making a website. I decided to use Hugo with a slightly-modified Hyde theme

Someday I’ll make my own theme, probably using Stylus for CSS processing. But for now, this will do. The more important thing is just to create some content.

Alan Pearce

scriptura: a cozy corner for your scripts

Typing shortcuts

Documenting scripts

Language support

Changes from sd

New features

Tab completion after new

Run ad-hoc commands in the script root

Custom subcommands

Motivation

Try it out

Avoiding Linguistic Misunderstandings

Spell out initialisms

Use generic names

Prefer layperson’s terms

Announcing Searchix: Nix ecosystem search

When Tailscale MagicDNS isn’t

Nameservers

Unexpected behaviours

Homesteading

Running NixOS on a NanoPi R5S

Now on three continents

Postfix on a NixOS null client with external catch-all

Background

A simple, powerful self-hosted git setup

Wild (or magic) repositories

Configuring wild repositories

Conclusion

Repository management with ghq

Back again

Cedit and Paredit

Emacs Package Archive Statistics

Opening Projects with Projectile

Cloning Similar Git Repositories

A New Site

Tab completion after `new`