Repository navigation
FreeSpeech Directory Server 1.2.0
A directory tells an application that knows no relay which relays accept new accounts, and distributes newcomers across them.
The application contacts the directory once, on its first connection. The directory responds with a signed list and keeps no information about clients. After that, it plays no part in their communications.
The directory's key is its identity. Applications already know this key, so it must never change.
What this directory does
- Lists the relays linked to it that are public, accept new accounts (
access open) and have available capacity. - Selects relays by country first, then randomly, weighted by their remaining capacity.
- Relays register using their keys and the agreement of both administrators (
requests/accept). No shared secret is exchanged. - Each relay sends a heartbeat every two minutes (country, available capacity, version).
- The directory checks each relay's address on its first heartbeat and every 30 minutes. Relays that remain silent or fail to authenticate with the accepted key are no longer offered.
- Private relays remain invisible and are never offered to new users.
- Monitors connectivity with each relay and raises an alert after three consecutive failed checks. The
peerscommand displays the status of each link and the country of each relay. - All configuration is handled through the
admincommand, without restarting the service, including e-mail notifications.
Who needs it?
Most relay administrators do not need to install their own directory.
Two public directories are available free of charge:
To make your relay available to new users, link it to these directories:
admin add directory https://directory1.rebisway.com
admin add directory https://directory2.rebisway.comThe directory administrator reviews incoming requests and approves them.
Running your own directory is intended for those who build the application with their own directory infrastructure.
Requirements
- Debian 12/13 or Ubuntu 22.04/24.04.
- A machine with
sudoaccess. - A permanent domain name pointing to the server.
- Ports 80 and 443 accessible from the Internet.
Installation
The archive includes:
- The directory application.
- A systemd service.
- An nginx configuration example.
- The
install.shinstallation script.
The .NET runtime is installed automatically by the script.
sha256sum -c --ignore-missing SHA256SUMS
tar -xzf freespeech-directory-1.2.0.tar.gz
cd freespeech-directory-1.2.0
sudo bash install.sh directory.example.org --email admin@example.org --contact admin@example.orgThe installation script:
- Installs the required packages.
- Configures the firewall (SSH, HTTP and HTTPS).
- Installs the systemd service.
- Creates
appsettings.Local.jsonwith a randomly generated administrator secret. - Configures nginx and the TLS certificate.
- Runs the configuration checks.
- Starts the service only if all checks pass.
--email specifies the address used by Let's Encrypt for certificate expiration notifications. Providing this address means accepting its subscriber agreement.
Additional options:
--contact: contact address for relay administrators.--no-certificate: skip automatic certificate installation.--no-firewall: skip firewall configuration.
Once installed, check the service:
fsdir status
fsdir helpAccepting a relay
On the relay server, request a link to the directory:
admin add directory https://directory.example.orgOn the directory server, review and accept the request:
fsdir requests
fsdir accept <id>Before accepting, compare the fingerprint displayed by the directory with the one provided by the relay administrator.
A relay is offered to applications only after it has connected successfully, responds at its advertised address, is public, accepts new accounts and has available capacity.
Updating
Run install.sh again with the newer archive, using the same domain name and e-mail address.
The application is replaced, while appsettings.Local.json is preserved and never overwritten.
Other operating systems
The installation script and documentation cover Debian and Ubuntu.
The application itself is portable .NET 10 and runs wherever the ASP.NET Core 10 runtime is available, including:
- Windows
- macOS
- Other Linux distributions
- x64 and ARM architectures
For these platforms, extract the publish directory, create appsettings.Local.json, and run:
dotnet FreeSpeech.Directory.dll checkThe directory must then run behind an HTTPS reverse proxy.
These alternative setups are not documented or tested.
Backup and identity key
The directory's key is its identity. Applications trust this key, so it must be backed up offline and must never change.
When moving the directory to another machine, preserve its identity key and update the DNS record accordingly.
Use the admin export and import commands to transfer the directory configuration and identity.
Documentation
- Step-by-step installation guide:
INSTALL_DIRECTORY.en.md - Directory administration commands:
cli-directory.en.md - Architecture and operation:
HOW_IT_WORKS.en.md - Protocol specification:
PROTOCOL.en.md
License
AGPL-3.0-or-later
Source code: https://git.rebisway.com/rebisway/freespeech