clanService/phonebox: global decentralized number directory over yggdrasil

Replace the static prefix+extension numbering with random 6 digit box
numbers (100000-999999) signed by the machine's yggdrasil key. A serf
gossip cluster on yggdrasil port 7946 exchanges the signed records;
phonebox-sync verifies key -> address derivation and the signature and
writes the number -> address map to /run/phonebox/numbers for the
asterisk dialplan. Any yggdrasil node running the service can reach any
other; clan-core's ygg-input filter is opened for SIP, RTP and gossip.

Drop the server-prefix-number and ata-local-number vars, add a two-node
VM test that proves directory convergence and a call over yggdrasil.
This commit is contained in:
2026-09-17 06:34:27 +00:00
parent 0906700ad6
commit d623ef8470
48 changed files with 554 additions and 345 deletions
+304 -256
View File
@@ -6,7 +6,7 @@
_class = "clan.service";
manifest.name = "phonebox";
manifest.description = "A peer to peer phone relay network built on top of yggdrasil.";
manifest.readme = "A peer to peer phone relay network built on top of yggdrasil.";
manifest.readme = builtins.readFile ./README.md;
manifest.categories = [ "System" ];
roles.default = {
@@ -19,11 +19,6 @@
description = "An Ethernet interface that connect to ATA box.";
default = "enp2s0";
};
options.ownerName = lib.mkOption {
type = lib.types.str;
description = "";
default = "";
};
options.extraClientNumbers = lib.mkOption {
type = with lib.types; listOf str;
description = "List of client suffix number.";
@@ -47,6 +42,7 @@
}
);
description = "Extra client to be added to pjsip config as a fixed IP auth";
default = { };
example = {
"01" = {
ip = "192.168.1.3";
@@ -54,6 +50,17 @@
};
};
};
options.extraPeers = lib.mkOption {
type = with lib.types; listOf str;
description = ''
Yggdrasil addresses of phonebox nodes outside this clan to bootstrap
the number directory from. Any single reachable node is enough; the
directory is gossiped from there and remembered across restarts.
'';
default = [ ];
example = [ "200:1234:5678:9abc:def0:1234:5678:9abc" ];
};
};
perInstance =
{
@@ -75,6 +82,7 @@
propagatedNativeBuildInputs = [ pkgs.spandsp3 ];
});
machineName = config.clan.core.settings.machine.name;
machines = lib.attrNames roles.default.machines;
user = "asterisk";
@@ -83,62 +91,72 @@
rtpPortTo = 20000;
ata-interface = settings.ata-ethernet-iface;
contactList = builtins.map (machineName: {
name = "${clanLib.getPublicValue {
flake = config.clan.core.settings.directory;
machine = machineName;
generator = "phonebox";
file = "owner-name";
default = null;
}}";
number = "${
# The ATA's own line. Remote callers reach it by dialing the 6
# digit box number alone or with this extension appended.
ataLine = "00";
sipPort = 5060;
# Well-known port of the phonebox directory gossip. Every phonebox
# node worldwide must agree on it, so it is not configurable.
directoryPort = 7946;
directoryRpc = "127.0.0.1:7373";
directoryUser = "phonebox";
directoryDir = "/run/phonebox";
phoneboxVars = config.clan.core.vars.generators.phonebox.files;
ownNumber = phoneboxVars.number.value;
ownerName = lib.trim phoneboxVars.owner-name.value;
getYggdrasilIP =
name:
lib.trim (
clanLib.getPublicValue {
flake = config.clan.core.settings.directory;
machine = machineName;
generator = "phonebox";
file = "server-prefix-number";
default = null;
machine = name;
generator = "yggdrasil";
file = "address";
default = "";
}
}${
clanLib.getPublicValue {
flake = config.clan.core.settings.directory;
machine = machineName;
generator = "phonebox";
file = "ata-local-number";
default = null;
}
}";
}) machines;
);
createContactListTiff =
let
contactTXT = lib.concatStringsSep "\n" (
builtins.map (contact: "${contact.number}\t\t: \t\t${contact.name}") contactList
);
in
pkgs.writeShellApplication {
name = "create-contact-tiff";
text = ''
magick -background white -fill black -pointsize 20 -font DejaVu-Sans label:"${contactTXT}" "$1"
magick "$1" -border 20x50 -bordercolor white "$1"
magick "$1" -resize 1728x -units PixelsPerInch -compress Group4 -density 204x196 -monochrome -depth 1 "$1"
'';
runtimeInputs = [ pkgs.imagemagick ];
};
ownYggdrasilIP =
if config.clan.core.vars.generators.yggdrasil.files ? address then
config.clan.core.vars.generators.yggdrasil.files.address.value
else
throw "clanService/yggdrasil is required";
genServerSIPEndpoint =
{ hostname, address }:
''
[${hostname}](internal_endpoint)
aors=${hostname}
seedPeers = lib.unique (
lib.filter (ip: ip != "") (map getYggdrasilIP (lib.remove machineName machines))
++ settings.extraPeers
);
[${hostname}](ip_auth)
endpoint=${hostname}
match=[${address}]
# Rebuilds the number -> yggdrasil address directory from the
# gossip membership. Every record is verified: the yggdrasil
# address is derived from the record's public key, so a node can
# only publish numbers for the address it actually owns, and the
# number is signed with the matching private key.
phoneboxSync = pkgs.writers.writePython3Bin "phonebox-sync" {
libraries = [ pkgs.python3Packages.cryptography ];
flakeIgnore = [ "E501" ];
} (builtins.readFile ./phonebox-sync.py);
[${hostname}](dynamiic_aor)
contact=sip:[${address}]
phoneboxSyncWrapped = pkgs.writeShellApplication {
name = "phonebox-sync";
runtimeInputs = [ pkgs.serfdom ];
text = ''
exec ${lib.getExe phoneboxSync} ${directoryRpc} ${directoryDir}
'';
};
createContactListTiff = pkgs.writeShellApplication {
name = "create-contact-tiff";
text = ''
magick -background white -fill black -pointsize 20 -font DejaVu-Sans label:"$(cat ${directoryDir}/contacts.txt)" "$1"
magick "$1" -border 20x50 -bordercolor white "$1"
magick "$1" -resize 1728x -units PixelsPerInch -compress Group4 -density 204x196 -monochrome -depth 1 "$1"
'';
runtimeInputs = [ pkgs.imagemagick ];
};
genLocalSIPEndpoint =
{ localNumber }:
@@ -151,7 +169,7 @@
username=${localNumber}
password=${localNumber}
[${localNumber}](dynamiic_aor)
[${localNumber}](dynamic_aor)
max_contacts=1
remove_existing=yes
'';
@@ -168,7 +186,7 @@
username=${localNumber}
password=${localNumber}
[${localNumber}](dynamiic_aor)
[${localNumber}](dynamic_aor)
max_contacts=1
'';
@@ -181,7 +199,7 @@
contact_deny=::/0
contact_permit=${settings.extraFixedIPClient.${number}.ip}/128
[${number}](dynamiic_aor)
[${number}](dynamic_aor)
max_contacts=1
remove_existing=yes
@@ -196,63 +214,58 @@
''
exten => ${localNumber},1,Dial(PJSIP/${localNumber},20)
'';
genExtentConf =
{
prefixNumber,
hostname,
localNumber,
}:
let
replaceWithX =
ln: builtins.concatStringsSep "" (builtins.genList (_: "X") (builtins.stringLength ln));
in
''
exten => _${prefixNumber}${replaceWithX localNumber},1,Dial(PJSIP/''${EXTEN:${builtins.toString (builtins.stringLength prefixNumber)}}@${hostname},30)
'';
getYggdrasilIP =
machineName:
if config.clan.core.vars.generators.yggdrasil.files.address ? value then
clanLib.getPublicValue {
flake = config.clan.core.settings.directory;
machine = machineName;
generator = "yggdrasil";
file = "address";
default = null;
}
else
throw "clanService/yggdrasil is required";
localNumbers = [
ataLine
]
++ settings.extraClientNumbers
++ lib.attrNames settings.extraFixedIPClient;
in
{
clan.core.vars.generators.phonebox = builtins.break {
assertions = [
{
assertion = !config.networking.nftables.enable;
message = "phonebox: opening the yggdrasil interface to non-clan nodes is only implemented for the iptables firewall backend";
}
];
clan.core.vars.generators.phonebox = {
files = {
server-prefix-number.secret = false;
ata-local-number.secret = false;
number.secret = false;
public-key.secret = false;
signature.secret = false;
owner-name.secret = false;
};
prompts = {
server-prefix-number = {
type = "line";
persist = true;
description = "Server prefix number: indicate server to connect to [10XX]";
};
ata-local-number = {
persist = true;
type = "line";
description = "Local suffix number: indicate local number on the server [XX00]";
};
owner-name = {
persist = true;
type = "line";
description = "The owner's name for this unit";
};
dependencies = [ "yggdrasil" ];
prompts.owner-name = {
persist = true;
type = "line";
description = "The owner's name for this unit";
};
runtimeInputs = with pkgs; [
coreutils
openssl
xxd
];
# A random 6 digit number (100000-999999), bound to this
# machine's yggdrasil identity by signing it with the yggdrasil
# private key. Other nodes accept the number only if the
# signature checks out and the key derives to the yggdrasil
# address the record is gossiped from. Regenerate to re-roll.
script = ''
cat $prompts/server-prefix-number > $out/server-prefix-number
cat $prompts/ata-local-number > $out/ata-local-number
cat $prompts/owner-name > $out/owner-name
shuf -i 100000-999999 -n 1 | tr -d '\n' > $out/number
openssl pkey -in $in/yggdrasil/privateKey -pubout -outform DER \
| tail -c 32 | xxd -p -c 64 | tr -d '\n' > $out/public-key
# openssl needs a regular file for one-shot ed25519 signing
printf 'phonebox:%s' "$(cat $out/number)" > $out/message
openssl pkeyutl -sign -rawin -inkey $in/yggdrasil/privateKey -in $out/message \
| base64 -w0 > $out/signature
rm $out/message
'';
};
@@ -312,188 +325,223 @@
networking.firewall.allowedUDPPorts = [
53
67
5060
sipPort
];
networking.firewall.allowedTCPPorts = [
53
];
networking.firewall.interfaces =
let
matchAll = if !config.networking.nftables.enable then "zt+" else "zt*";
in
{
"${matchAll}".allowedTCPPorts = [ 80 ];
networking.firewall.interfaces = {
"zt+".allowedTCPPorts = [ 80 ];
ygg = {
allowedTCPPorts = [ directoryPort ];
allowedUDPPorts = [ directoryPort ];
};
};
# clanService/yggdrasil drops everything on the ygg interface that
# does not come from a clan member. Phonebox is a global network,
# so let SIP, RTP and the directory gossip through from anyone.
networking.firewall.extraCommands = lib.mkAfter ''
if ip6tables -n -L ygg-input >/dev/null 2>&1; then
ip6tables -I ygg-input 1 -i ygg -p udp --dport ${toString sipPort} -j RETURN
ip6tables -I ygg-input 1 -i ygg -p udp --dport ${toString rtpPortFrom}:${toString rtpPortTo} -j RETURN
ip6tables -I ygg-input 1 -i ygg -p udp --dport ${toString directoryPort} -j RETURN
ip6tables -I ygg-input 1 -i ygg -p tcp --dport ${toString directoryPort} -j RETURN
fi
'';
users.users.${directoryUser} = {
isSystemUser = true;
group = directoryUser;
};
users.groups.${directoryUser} = { };
# Decentralized number directory: a serf gossip cluster over
# yggdrasil. Each node advertises its signed number record as
# tags; membership changes trigger phonebox-sync, which writes the
# verified number -> address map to ${directoryDir}/numbers/ for
# the dialplan. The snapshot lets a node rejoin from previously
# seen members, so seeds are only needed for the very first join.
systemd.services.phonebox-directory = {
description = "Phonebox number directory (serf gossip over yggdrasil)";
wantedBy = [ "multi-user.target" ];
wants = [ "network-online.target" ];
after = [
"network-online.target"
"yggdrasil.service"
];
serviceConfig = {
User = directoryUser;
Group = directoryUser;
RuntimeDirectory = "phonebox";
RuntimeDirectoryMode = "0755";
RuntimeDirectoryPreserve = "yes";
StateDirectory = "phonebox";
Restart = "always";
RestartSec = 5;
ExecStart = lib.concatStringsSep " " (
[
(lib.getExe pkgs.serfdom)
"agent"
"-node=${machineName}-${ownNumber}"
"-bind=[::]:${toString directoryPort}"
"-advertise=[${ownYggdrasilIP}]:${toString directoryPort}"
"-rpc-addr=${directoryRpc}"
"-profile=wan"
"-snapshot=/var/lib/phonebox/serf.snapshot"
"-rejoin"
"-retry-max=0"
"-retry-interval=30s"
"-tag number=${ownNumber}"
"-tag key=${phoneboxVars.public-key.value}"
"-tag sig=${phoneboxVars.signature.value}"
"-tag ${lib.escapeShellArg "owner=${ownerName}"}"
"-event-handler=member-join,member-leave,member-failed,member-update,member-reap=${lib.getExe phoneboxSyncWrapped}"
]
++ map (ip: "-retry-join=[${ip}]:${toString directoryPort}") seedPeers
);
};
};
services.asterisk = {
enable = lib.mkDefault true;
package = lib.mkDefault asterisk;
confFiles =
let
nodes = builtins.foldl' (
nodes: name:
nodes
++ [
{
hostname = name;
address = getYggdrasilIP name;
prefixNumber = clanLib.getPublicValue {
flake = config.clan.core.settings.directory;
machine = name;
generator = "phonebox";
file = "server-prefix-number";
default = null;
};
confFiles = {
"logger.conf" = ''
[general]
dateformat = %F %T.%3q ; ISO 8601 date format with milliseconds
use_callids = yes
appendhostname = no
queue_log = yes
queue_log_to_file = no
queue_log_name = queue_log
queue_log_realtime_use_gmt = no
rotatestrategy = rotate
exec_after_rotate=gzip -9 $\{filename\}.2
[logfiles]
console => notice,warning,error
security => security
messages => notice,warning,error
full => notice,warning,error,verbose,dtmf,fax
syslog.local0 => notice,warning,error
'';
localNumber = clanLib.getPublicValue {
flake = config.clan.core.settings.directory;
machine = name;
generator = "phonebox";
file = "ata-local-number";
default = null;
};
}
]
) [ ] machines;
in
{
"logger.conf" = ''
[general]
dateformat = %F %T.%3q ; ISO 8601 date format with milliseconds
use_callids = yes
appendhostname = no
queue_log = yes
queue_log_to_file = no
queue_log_name = queue_log
queue_log_realtime_use_gmt = no
rotatestrategy = rotate
exec_after_rotate=gzip -9 $\{filename\}.2
[logfiles]
console => notice,warning,error
security => security
messages => notice,warning,error
full => notice,warning,error,verbose,dtmf,fax
syslog.local0 => notice,warning,error
'';
"modules.conf" = ''
[modules]
autoload=yes
"modules.conf" = ''
[modules]
autoload=yes
load => res_fax_spandsp.so
'';
load => res_fax_spandsp.so
'';
# Dial plan config
"extensions.conf" = ''
[from-internal]
exten => 999,1,Answer()
same => n,Playback(hello-world)
same => n,Hangup()
# Dial plan config
"extensions.conf" =
let
serverConf = builtins.foldl' (
config: node:
config
+ (genExtentConf {
inherit (node) prefixNumber hostname localNumber;
})
) "" nodes;
in
''
[from-internal]
exten => 999,1,Answer()
same => n,Playback(hello-world)
same => n,Hangup()
exten => 000,1,Answer()
same => n,ReceiveFAX(${faxDir}/echo-''${UNIQUEID}.tiff)
same => n,Set(FAXFILE=${faxDir}/echo-''${UNIQUEID}.tiff)
same => n,Set(FAXECHO=true)
exten => 000,1,Answer()
same => n,ReceiveFAX(${faxDir}/echo-''${UNIQUEID}.tiff)
same => n,Set(FAXFILE=${faxDir}/echo-''${UNIQUEID}.tiff)
same => n,Set(FAXECHO=true)
exten => 888,1,Answer()
same => n,Set(FAXFILE=${faxDir}/contact.tiff)
same => n,System(${lib.getExe createContactListTiff} ''${FAXFILE})
same => n,Set(FAXECHO=true)
same => n,Playback(vm-goodbye)
same => n,Wait(3)
exten => 888,1,Answer()
same => n,Set(FAXFILE=${faxDir}/contact.tiff)
same => n,System(${lib.getExe createContactListTiff} ''${FAXFILE})
same => n,Set(FAXECHO=true)
same => n,Playback(vm-goodbye)
same => n,Wait(3)
exten => h,1,GotoIf($[''${FAXECHO}]?sendfax)
same => n,Hangup()
same => n(sendfax),Originate(PJSIP/${ataLine},app,SendFAX,''${FAXFILE})
same => n,Set(FAXECHO=false)
exten => h,1,GotoIf($[''${FAXECHO}]?sendfax)
same => n,Hangup()
same => n(sendfax),Originate(PJSIP/00,app,SendFAX,''${FAXFILE})
same => n,Set(FAXECHO=false)
; 6 digit box number, optionally followed by a 2 digit line
exten => _[1-9]XXXXX,1,Goto(to-yggdrasil,''${EXTEN},1)
exten => _[1-9]XXXXXXX,1,Goto(to-yggdrasil,''${EXTEN},1)
''
+ (genLocalExtenConf {
localNumber = config.clan.core.vars.generators.phonebox.files.ata-local-number.value;
})
+ lib.concatStringsSep "\n" (
builtins.map (number: genLocalExtenConf { localNumber = number; }) settings.extraClientNumbers
)
+ lib.concatStringsSep "\n" (
lib.mapAttrsToList (
number: _: genLocalExtenConf { localNumber = number; }
) settings.extraFixedIPClient
)
+ serverConf;
''
+ lib.concatMapStrings (number: genLocalExtenConf { localNumber = number; }) localNumbers
+ ''
"rtp.conf" = ''
[general]
rtpstart=${builtins.toString rtpPortFrom}
rtpend=${builtins.toString rtpPortTo}
'';
; Outbound: resolve the box number through the directory and
; send the call to that node over yggdrasil.
[to-yggdrasil]
exten => _[1-9]X.,1,Set(PEER=''${FILE(${directoryDir}/numbers/''${EXTEN:0:6})})
same => n,GotoIf($["''${PEER}" = ""]?unknown)
same => n,Set(CALLERID(num)=${ownNumber}''${CALLERID(num)})
same => n,Set(CALLERID(name)=${ownerName})
same => n,Dial(PJSIP/yggdrasil/sip:''${EXTEN}@[''${PEER}]:${toString sipPort},30)
same => n,Hangup()
same => n(unknown),Playback(ss-noservice)
same => n,Hangup()
"pjsip.conf" =
let
serverConf = builtins.foldl' (
conf: node:
conf
+ (genServerSIPEndpoint {
hostname = node.hostname;
address = node.address;
})
) "" nodes;
in
''
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0
[transport-udp6]
type=transport
protocol=udp
bind=::
; Inbound from any yggdrasil node: only our own number is served.
[from-yggdrasil]
exten => ${ownNumber},1,Dial(PJSIP/${ataLine},20)
exten => _${ownNumber}XX,1,Dial(PJSIP/''${EXTEN:6},20)
'';
[base_endpoint](!)
type=endpoint
disallow=all
allow=ulaw,alaw,g722,gsm
direct_media=no
"rtp.conf" = ''
[general]
rtpstart=${toString rtpPortFrom}
rtpend=${toString rtpPortTo}
'';
[internal_endpoint](!,base_endpoint)
context=from-internal
"pjsip.conf" = ''
[global]
type=global
; Local lines authenticate by username; everything else from
; the yggdrasil range is a remote phonebox node.
endpoint_identifier_order=username,ip,anonymous
[userpass_auth](!)
type=auth
auth_type=userpass
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0
[transport-udp6]
type=transport
protocol=udp
bind=::
[ip_auth](!)
type=identify
endpoint=external
[base_endpoint](!)
type=endpoint
disallow=all
allow=ulaw,alaw,g722,gsm
direct_media=no
[dynamiic_aor](!)
type=aor
[internal_endpoint](!,base_endpoint)
context=from-internal
''
+ (genLocalSIPEndpoint {
localNumber = config.clan.core.vars.generators.phonebox.files.ata-local-number.value;
})
+ lib.concatStringsSep "\n" (
builtins.map (number: genLocalSIPEndpointV6 { localNumber = number; }) settings.extraClientNumbers
)
+ lib.concatStringsSep "\n" (
lib.mapAttrsToList (number: _: genLocalSIPIPEndpoint number) settings.extraFixedIPClient
)
+ serverConf;
};
[userpass_auth](!)
type=auth
auth_type=userpass
[dynamic_aor](!)
type=aor
[yggdrasil](base_endpoint)
transport=transport-udp6
context=from-yggdrasil
[yggdrasil]
type=identify
endpoint=yggdrasil
match=200::/7
''
+ (genLocalSIPEndpoint { localNumber = ataLine; })
+ lib.concatMapStrings (
number: genLocalSIPEndpointV6 { localNumber = number; }
) settings.extraClientNumbers
+ lib.concatMapStrings genLocalSIPIPEndpoint (lib.attrNames settings.extraFixedIPClient);
};
};
environment.systemPackages = [
createContactListTiff
phoneboxSyncWrapped
];
systemd.tmpfiles.rules = [