Upgrading Tor Relays to Happy Families

With David Goulet’s announcement yesterday about the availability of the first stable release of the Tor 0.4.9 series, we can finally begin upgrading the Tor network to use Happy Families. I’m writing this blog post as a summary of the upgrade process of the two Tor relays that I help to run on the production Tor network together with some of my colleagues.

What is Happy Families?

For people who do not know what Happy Families is: Tor relays currently have a configuration setting named MyFamily where the relay operator can specify that their relays are operated by the same entity (person, legal organization, etc.) and are therefore “somewhat related”. We use this information in Tor’s path selection algorithm to ensure that, when Tor picks a path, no two relays are ideally in the same family. Tor also has some additional checks we call the “extended family”, which ensures that no two relays in a chosen path are on the same /16 network for IPv4 or /32 network for IPv6. With the arrival of Conflux, we relaxed some of these requirements under certain conditions, but this is not covered in this blog post.

In 2020, Nick Mathewson wrote Proposal 321, named “Better performance and usability for the MyFamily option (v2)”. In daily speak, we call this system “Happy Families”. As the number of relays in the Tor network has grown significantly in the last couple of years, both thanks to our amazing Tor Relay Operator community, but unfortunately also due to the poor multi-core CPU scaling of the C Tor implementation (which we are working on fixing with Arti), we have seen a signicant increase in micro-descriptor size (the metadata clients downloads during the bootstrap process to the network) where over 82% of the downloaded data is MyFamily information. This overhead is due to how MyFamily works: each relay in a family lists all other relays in the family. The overhead, unfortunately, is significant enough to yield a problematic O($n^2$) space requirement, which was once tolerable but is now causing problems for low-memory systems accessing the Tor network. What Happy Families brings to the table is a way in which each relay family needs only to share a cryptographic key pair and upload proof of ownership of that key. The Directory Authorities and clients can now use the family public key for various “group by” operations when computing relay families, just like with the MyFamily system, but with significantly less overhead.

Upgrading our Relays

Some assumptions in the next part of this post may make it more or less relevant for you:

• You’re running your Tor relays on either Debian or Ubuntu. I’m on Debian, but Ubuntu should be the same.

• You’re using The Tor Project’s own apt mirror for your Tor-related packages. If you’re not, you are most likely running an outdated version of Tor. Read the documentation on installing Tor using The Tor Project’s apt mirror, and also please set up automatic updates, as this greatly helps with the network upgrade timeline when new Tor versions are out.

• You’re using Peter Palfrader’s excellent tor-instance-create(8) utility bundled with the Debian packages. If you’re not using this tool to maintain multiple isolated Tor services on a single host, the only impact this may have on the instructions here will likely be related to paths and permissions.

I encourage operators to check out the official documentation for Happy Families as well.

For relay operators using other tooling, such as the popular ansible-relaytor, please follow the instructions provided by the respective upstream maintainers. For ansible-relaytor specifically, nusenu recently provided an update on the Happy Families roadmap on the tor-relays mailing list.

The Setup

The two relays described in this post are Akka and Ukko. Both are running at Hetzner in one of their Finnish data centers. We will be setting up Akka first, and thereafter Ukko. If you are running more than two relays, you would have to follow the instructions for Akka once, and the instructions for Ukko once for each other relay you run.

Since Happy Families is only relevant for relay operators who are already running multiple relays, it’s important to remind operators to continue using the MyFamily system you likely already have set up in the Tor configuration files. The MyFamily system and Happy Families will have to co-exist for a while before we can deprecate MyFamily in the network. Running both systems in parallel avoids screwing over older Tor clients due to the lack of MyFamily entries, while also allowing us to handle any bugs in Happy Families without too much worry.

We start by checking which version of Tor we have installed on our system. We can do that using:

# apt show tor

If your Tor version isn’t at least 0.4.9.5 as of when you read this post, you should upgrade. In our case here, the automatic update hadn’t taken place since the release yesterday, so we have to upgrade our packages manually:

# apt upgrade -y
Upgrading:
  tor  tor-dbgsym  tor-geoipdb

Summary:
  Upgrading: 3, Installing: 0, Removing: 0, Not Upgrading: 0
  Download size: 10.7 MB
  Space needed: 609 kB / 424 GB available

Get:1 https://deb.torproject.org/torproject.org trixie/main amd64 tor-dbgsym
    amd64 0.4.9.5-1~d13.trixie+1 [5,851 kB]
Get:2 https://deb.torproject.org/torproject.org trixie/main amd64 tor-geoipdb
    all 0.4.9.5-1~d13.trixie+1 [2,722 kB]
Get:3 https://deb.torproject.org/torproject.org trixie/main amd64 tor
    amd64 0.4.9.5-1~d13.trixie+1 [2,081 kB]
Fetched 10.7 MB in 0s (49.8 MB/s)
Reading changelogs... Done
(Reading database ... 65746 files and directories currently installed.)
Preparing to unpack .../tor-dbgsym_0.4.9.5-1~d13.trixie+1_amd64.deb ...
Unpacking tor-dbgsym (0.4.9.5-1~d13.trixie+1) over (0.4.8.20-1~d13.trixie+1) ...
Preparing to unpack .../tor-geoipdb_0.4.9.5-1~d13.trixie+1_all.deb ...
Unpacking tor-geoipdb (0.4.9.5-1~d13.trixie+1) over (0.4.8.20-1~d13.trixie+1) ...
Preparing to unpack .../tor_0.4.9.5-1~d13.trixie+1_amd64.deb ...
Unpacking tor (0.4.9.5-1~d13.trixie+1) over (0.4.8.20-1~d13.trixie+1) ...
Setting up tor (0.4.9.5-1~d13.trixie+1) ...
Setting up tor-geoipdb (0.4.9.5-1~d13.trixie+1) ...
Setting up tor-dbgsym (0.4.9.5-1~d13.trixie+1) ...
Processing triggers for man-db (2.13.1-1) ...

The tor-instance-create utility uses /var/lib/tor-instances/ for the Tor DataDir directories. This includes the keys/ directory, where Tor’s various cryptographic keys are stored.

Since the family keys we are about to create can be trivially rotated by the relay operator, we use a fairly simple naming scheme: the current year and month. If you have a better naming scheme, you can proceed with that.

We create the family keys using the Tor binary:

# cd /var/lib/tor-instances/akka/keys
# tor -f /etc/tor/instances/akka/torrc --keygen-family 2026-02

... logs removed ...

# Generated 2026-02.secret_family_key
FamilyId XXX

Save the FamilyId string from above elsewhere, since we’ll use it in the following steps. Your string will not be XXX, but instead a longer base64 encoded value.

Since we are logged in as root, and tor-instance-create creates specific Unix users for each of our Tor instances, we need to change the ownership of the newly created files, and at the same time, we can verify that only the owner can read and write to the file:

# ls -l 2026-02.*
-rw------- 1 root _tor-akka 44 Feb 13 15:07 2026-02.public_family_id
-rw------- 1 root _tor-akka 96 Feb 13 15:07 2026-02.secret_family_key
# chown _tor-akka 2026-02.*
# ls -l 2026-02.*
-rw------- 1 _tor-akka _tor-akka 44 Feb 13 15:07 2026-02.public_family_id
-rw------- 1 _tor-akka _tor-akka 96 Feb 13 15:07 2026-02.secret_family_key

The above permissions looks good. We can now add our FamilyId entry (saved from our previous step) to Akka’s torrc configuration file:

# echo -e "\nFamilyId XXX" >> /etc/tor/instances/akka/torrc

For Ukko, instead of generating a new family key, we reuse the one we generated for Akka. Again, if we ran more than two relays, the following steps would need to be repeated for each relay instance after the initially created family key for the first relay.

We start by copying over Akka’s family key files and changing the ownership of the files to match the Unix user for Ukko:

# cd /var/lib/tor-instances/ukko/keys
# cp /var/lib/tor-instances/akka/keys/2026-02.* .

This time, we need to change ownership to Ukko’s Unix user and verify the permissions once again:

# chown _tor-ukko 2026-02.*
# ls -l 2026-02.*
-rw------- 1 _tor-ukko _tor-ukko 44 Feb 13 15:07 2026-02.public_family_id
-rw------- 1 _tor-ukko _tor-ukko 96 Feb 13 15:07 2026-02.secret_family_key

We can now set our FamilyId entry in Ukko’s torrc:

# echo -e "\nFamilyId XXX" >> /etc/tor/instances/ukko/torrc

We are finally at the point where we can restart our two Tor relay processes:

# systemctl restart tor@akka.service tor@ukko.service

With these small changes, we have now upgraded our two relays to support Happy Families in addition to their already existing MyFamily configuration.

If anything went wrong while restarting our two Tor services, or we wanted to check if bootstrap was successful, we could check the logs from our two Tor services using:

# journalctl -xeu tor@akka.service

Next Steps

Since 0.4.9 was just stabilized, a couple of additional steps are needed before Happy Families is used by new Tor clients on the network.

For the family-ids key to appear in Tor’s micro-descriptors generated by the Directory Authorities, the authorities will first have to upgrade to Tor 0.4.9, and begin voting using consensus method 35. Currently, Roger Dingledine is the early adopter here with his moria1 relay, but I suspect the others will upgrade soon. Once they begin voting using consensus method 35 (or later), we will begin to see the family-ids sequence in the micro-descriptor documents clients download.

According to our Consensus Health page, the Directory Authorities currently vote as follows:

In addition to the relay upgrades, Tor’s Network Health team will add support for family-ids in the Onionoo interface. They are tracking this work under onionoo#40051.

Conclusion

Upgrading to Happy Families for a simple setup with two relays running on a single Debian instance took less than five minutes from logging in to logging out. Hopefully, this may encourage more relay operators to upgrade their relays sooner rather than later.

Thanks to everybody running relays, and to all the people who help test, provide packages, and report bugs when new versions of Tor are released!

Especially shout-out to omni, who packages Tor and Arti for the Alpine Linux distribution who discovered an issue just a few hours after we rolled the Tor 0.4.9.5 release. The issue, fortunately, only impacts Big Endian systems and was discovered on something as esoteric as an IBM s390x Linux installation as part of Alpine Linux’s Continuous Integration workflow for their packages. A fix for the issue will be out in Tor 0.4.9.6.