Default folder for onion services

The apache and nginx webservers have a predefined folders for sites configuration e.g. sites-available and sites-enabled. So you know where to put your custom configuration.
In the Tor current approach is to edit the torrc file but during and update you may lost your changes because they will be overwritten.
This becomes a bigger problem for OpenWrt firmware for routers where during a firmware sysupgrade all files from the /etc/ are cleared unless they clearly specified to be kept. The ClearLinux also use immutable configs design.

Likely the torrc file has a %include directive that can be somehow give the same behavior:

%include /etc/torrc.d/*.conf

So we can add hidden service configurations as a separate files into the directory /etc/torrc.d/ e.g. /etc/torrc.d/sshd.conf or /etc/torrc.d/nextcloud.conf.

Here I found few problems:

  1. The directive is commented out. But it should work out of the box so user don’t need to change the torrc file.
  2. On Ubuntu/Debian the line is not present at all. And the /etc/torrc.d/ is not created on the tor package install. Maintainers should fix this.

Each service also needs for it’s own folder to keep keys. To make a layout simpler we can put keys in the same folder where the conf file is located. But it may be parsed as a config so instead create a subfolder keys. I tried and made the following structure:

File with the onion service config /etc/torrc.d/sshd/sshd.conf with content:

HiddenServiceDir /etc/torrc.d/sshd/keys/
HiddenServicePort 22

And it has a /etc/torrc.d/sshd/keys/ folders with all files: authorized_clients, hostname, hs_ed25519_public_key, hs_ed25519_secret_key.

Now I included it with:
%include /etc/torrc.d/*

And it works according to manual e.g. folders are scanned for configs but not their subfolders.

This files layout is probably a simplest that is possible. And it’s easy to backup and understand. Or maybe I missing something?

Can we make this or some other default config layout for hidden onion services to simplify tutorials and to have a common understanding.

I found a related topic

1 Like

Your concern is valid, and I would say that in general systems should not break config files during upgrades, but that may be hard to follow on image-based system upgrades like what may be happening with OpenWrt.

I don’t see a way that Tor could standardize it’s default folders in a way that would work seamlessly without changes across all distributions and operating systems. That’s usually a concern for distribution and package maintainers to adapt configurations to their systems.

That said, I recommend the following:

  1. Try to specify your Tor configs to be kept during OpenWrt upgrades.
  2. If that’s not possible, you may try to have a minimalistic /etc/torrc with things like %include /some/persistent/path/etc/tor/*.conf and DataDirectory /some/persistent/path/var/lib/tor, so whenever an upgrade happen you can easily fix the main config file, and keep your full config, keys etc in a persistent folder.
  3. Try to advocate with the distro/package maintainer to ship a torrc with defaults suited for persistency.

Hope that this helps.


The torrc config in OpenWrt is based on /src/config/ from official source tarball
In there the #%include /etc/torrc.d/*.conf is commented.
So it would be much better if you uncomment the line in the mainline sources. Distro packages will follow this.

Similarly it would be great to add %include /var/run/tor/*.conf directive. This would be useful for some GUI tools that allows to configure the Tor by generating a temp file with directives. They can put their files into the in-memory folder and it will be automatically picked up.

The main issue remains: we need a pre-defined folder for onion services. In the OpenWrt there is a tor-hs package that declares it in /etc/tor/hidden_service. Each service has own folder:


The hidden_service probably should be renamed to onion_services but that’s not a big deal.

What I’m asking for is to make the tor to create the folder /etc/tor/onion_services/ on installation and look for a service.conf file inside. So users can easily copy\backup such folders and they don’t need to change anything in the torrc.
A NextCloud package can just put own config inside of the folder and it will start working.
As an additional improvement it would be great to have some hook to trigger when Tor creates an onion service and generates keys. The hook will update the NextCloud config and configure it for the new generated onion domain.

For example the OpenWrt tor-hs package has such a hook packages/net/tor-hs/files/ at master · openwrt/packages · GitHub

The hook may be a DBUS event but this won’t work on Windows and MacOS.

I created a PR to OpenWrt to preserve the /etc/torrc.d/ during a sysupgrade.

P.S. you may be interested: I created a plugin luci-app-tor for OpenWrt Luci admin panel that allows to create and configure onion services from GUI.

1 Like