Access rules and names
Decide who can reach what in your network, give your services names, connect an office network, and help members reach each other through a relay.
How access rules work
Joining a network doesn't open everything on it. Each device checks the rules for traffic arriving at it, and refuses anything no rule allows.
A new network starts with one rule that lets every member reach everything. Narrow it when you're ready. Rules are written in a file and loaded from the command line.
For access someone needs for a while, they can ask for it in the app, and you approve it for a set time, up to 30 days, or decline it. Approving adds a rule that ends by itself. Requests for access
An example, explained
A small network: a file server, an intranet, and some servers. The front desk can use the files, everyone can open the intranet, and a contractor can work on the servers until the end of a job.
{
"groups": { "front-desk": ["user:dana", "user:lee"] },
"rules": [
{ "from": ["group:front-desk"], "to": ["device:files"], "ports": ["tcp/445"] },
{ "from": ["*"], "to": ["device:intranet"], "ports": ["tcp/443", "icmp"] },
{ "from": ["user:alex"], "to": ["tag:servers"], "ports": ["tcp/22"],
"until": "2027-03-31T18:00:00Z" }
]
}
Dana, at the front desk
- files, for shared folders (
tcp/445): she (dana) is in the groupfront-desk, which the first rule lets in. - intranet, for its website (
tcp/443) and to check it answers (icmp): the second rule lets in every member. - Nothing else. The servers refuse her: no rule names her.
Alex, a contractor
- intranet, as every member can.
- Every device tagged
servers, by SSH (tcp/22), until 18:00 on 31 March 2027 (UTC). Then the third rule ends by itself. - Not files: Alex (
alex) isn't infront-desk.
Sam, the administrator
- intranet, as every member can.
- Nothing else. Looking after a network doesn't open its devices to you: only the rules do. Add yourself to a rule if you need to.
from,to*(every member),user:USERNAME,service:NAME,device:NAME,group:NAMEortag:NAME.tocan also belan:GATEWAY, a gateway's office network. Auser:term never matches a service's devices: name them withservice:,device:ortag:. Servicesports*,icmp, ortcp/orudp/with a port or a range, such astcp/8000-8100.until- Optional. The rule ends by itself then.
groups- Up to 64. A group holds people and devices, not other groups.
Write and load your rules
Rules are loaded from the command line. Loading replaces all the rules at once.
- Write the rules in a file, such as
rules.json, as in the example. - Load it, below. Names are checked as it loads, and stored as IDs. An unknown name is refused, so a typo can't open or close everything.
- Check the rules now in force with
devices.
& $mt set-rules $st northwind rules.jsonsudo multitunnel set-rules /var/lib/multitunnel northwind rules.json- A person, service or tag named in a rule can't be removed until the rules change.
- On a Windows device, Windows' own firewall still applies: a rule can't open what it blocks.
- Loading replaces approved requests in force too. To keep one, copy it into the file as
devicesshows it, with its"request"number. What approving does
See the rules in force
On Windows, in Terminal (Admin), once you have set $mt and $st. On Linux, in a terminal. Before you start
& $mt devices $st northwindsudo multitunnel devices /var/lib/multitunnel northwindNames for your services
Give a name, such as intranet.northwind.example, to a device in the network. Every member then reaches that device by that name while connected.
- Open Administer, then Names.
- Under Give a name, type the full name in lower case, choose the device it Reaches, and choose Give this name…. Giving a name that is already given moves it to the device you choose.
- To remove one, choose Stop giving this name beside it, then Stop giving with the name, such as Stop giving intranet.northwind.example…. Devices then look it up on the internet again.
Every device can also be reached by its own name, such as files.northwind.multitunnel.
Give each service its full, exact name. A short name such as northwind.example or db.internal, or a name a cloud gives every customer's servers, is one other networks are likely to give too, and on a computer in both, neither answers it. MultiTunnel says so before you give one: in the app, the PIN window starts with Careful: and suggests a better name, and at the command line it asks you to add -broad-ok.
Command line
On Windows, in Terminal (Admin), once you have set $mt and $st. On Linux, in a terminal. Before you start
& $mt set-name $st northwind intranet.northwind.example intranetsudo multitunnel set-name /var/lib/multitunnel northwind intranet.northwind.example intranet& $mt set-name $st northwind intranet.northwind.example nonesudo multitunnel set-name /var/lib/multitunnel northwind intranet.northwind.example noneGateways to office and cloud networks
A gateway is a Linux device in an office or a cloud network that lets members reach that network's own servers, printers and databases through MultiTunnel. It is a paid feature. Gateways are set up from the command line: the app has no screen for them. A gateway runs under a service, such as Office gateway: it joins for the service, with -service. Set up a server as a service
- On the Linux device, install MultiTunnel with
-gatewayand the interface for the network behind it, such aseth0, then join it for its service. - Make it the gateway: give the ranges members reach through it, and the names they look up through it.
- Allow it in the rules with
lan:and the device's name.
sudo ./multitunnel install -yes -gateway eth0sudo multitunnel join /var/lib/multitunnel auto office-gw "<paste the invite here>" -service& $mt set-route $st northwind office-gw 10.0.20.0/24,10.0.30.0/24 -names db.northwind.example,vault.northwind.examplesudo multitunnel set-route /var/lib/multitunnel northwind office-gw 10.0.20.0/24,10.0.30.0/24 -names db.northwind.example,vault.northwind.exampleThe ranges it reaches
A gateway reaches up to 8 private ranges, separated by commas, each one whole and at most a /16: within 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16, none overlapping another. Only these ranges go through the gateway; everything else stays on each member's own connection.
Where a range is this network's alone on a computer, members reach it by its own addresses, so a server keeps the address it has. Where it isn't, they reach it by name, at stand-in addresses of MultiTunnel's own, without anyone setting anything: names work as usual, and only the address differs, on that device alone. The gateway and the other members see nothing different. Pick a case to see what happens:
Only this network has it here
db.northwind.exampleleads to10.0.20.5, its own address, through the gateway.- An address someone gives you, such as
10.0.20.7, works as it is.
The computer's own network uses it
- The computer's own network keeps its addresses in the range: its Wi-Fi or office network, its router and its DNS server. It always comes first.
db.northwind.exampleleads to a stand-in, such as198.18.44.5, and so to the database, through the gateway.- A bare address in the part of the range the computer's own network uses reaches that network, not the gateway's.
Another network here has it too
- Each network's names lead to stand-ins of its own, so both work by name, at once.
- A bare address in the range reaches neither network, so an address someone quotes never reaches the wrong one.
- Connections already open when the other network arrived carry on; new ones go by name.
Another VPN routes it
- If the other VPN routes a wider range, such as all of
10.0.0.0/16, the narrower10.0.20.0/24goes through MultiTunnel by its own addresses. - If it routes the same range or a narrower one, or on Linux looks its own routes up first (as Tailscale does with routes accepted), MultiTunnel reaches the range by name at stand-ins, and says so. To use its own addresses there, list narrower ranges, or turn that VPN's route acceptance off on that device.
On a phone
- A phone reaches every gateway range by name, at stand-ins, as it can't tell a range from its own Wi-Fi's.
- Bare addresses in the gateway's ranges don't reach the gateway from a phone: use names.
- Stand-ins stay put. They stay the same while the network is connected, and usually after it reconnects or the computer restarts too. When another network arrives with the same range, connections already open carry on by their own addresses until the network next connects. Only the computer's own network, a DNS server it uses or another VPN's route coming into a range changes it at once, so traffic never goes the wrong way.
- Shown where it matters. On a computer, the network's page in the app says, for example,
10.0.20.x is reached at 198.18.44.x
, anddevicessays the same. Programs that use names need nothing; one set up with a bare address in such a range needs the name instead. - Keep ranges small.
10.0.20.0/24,10.0.30.0/24rather than all of10.0.0.0/16keeps more of them reached by their own addresses.set-routesays when a range overlaps what home routers often use. - Blocked while MultiTunnel runs. While MultiTunnel runs on a member's device, traffic for a network's ranges leaves only through MultiTunnel: while the network is disconnected or can't connect, or if another network, another VPN or a Wi-Fi tries to route part of them elsewhere, it is dropped. Only the part of a range the computer's own network is on is let through. While MultiTunnel is stopped, or before it starts, the ranges aren't blocked. MultiTunnel's own addresses are blocked whatever runs.
- Idle connections stay open. A connection with nothing to send, such as a database pool or an SSH session, stays open for 2.5 hours without traffic. One never answered, or already ended, is forgotten after 2 minutes, and UDP after 5.
- Only the person who joined. On a computer several people use, only the account the network belongs to reaches its ranges. On Windows, that also keeps out what Windows itself does as the system account, such as opening a file share by its server's address or printing to a printer in the ranges.
The names it answers
Your services may already have names, such as a cloud database's. Give them to the gateway with -names, and members look them up as they are. MultiTunnel sends exactly these names to the gateway, which asks its own DNS servers (in a cloud network, the cloud's, which knows its private names). Programs that check a server's certificate by its name, such as database clients, work as they do inside that network. Phones look them up the same way.
- An exact name
- Such as
db.northwind.example: only that name goes to the gateway. Prefer these: list each service's own name. - Part of a domain, starting with a dot
- Such as
.internal.northwind.example: that name and every name under it go to the gateway. It must be part of a domain, never a whole one: not.northwind.example. Use one only for a part that is entirely yours and private. - Azure private endpoints
- List the public name, such as
mydb.postgres.database.azure.com. Azure's DNS answers it with its private address, and the gateway passes the whole answer on. List theprivatelinkname too only if programs use it.
- Up to 32 names, separated by commas. Nothing else a member looks up goes to the gateway, and an answer outside the gateway's ranges is dropped, so a name can't lead anywhere else.
- The computer's own names come first. A name at or under a domain the member's own network uses isn't looked up through the gateway there.
- Not allowed: wildcards (
*), MultiTunnel's own domains, shared public domains such asazurewebsites.netorco.uk, a domain under a cloud provider's shared zone such as.postgres.database.azure.comor anyprivatelinkzone (other customers' names live there too: list your own exact names), and a name the network already gives to one of its devices. - Broad names need
-broad-ok. A name other networks are likely to give too is answered by neither on a device in both: a name of two parts (northwind.example,db.internal), a cloud's zone itself (postgres.database.azure.com), a cloud's default server name (ip-10-0-1-5.eu-west-2.compute.internal), or a part of a domain under a cloud's default private zone (.eu-west-2.compute.internal).set-routesays so, for examplenorthwind.example is short, so another network may use it too: list the exact names under it instead
, and gives the name only if you run it again with-broad-ok. Names the network already gives are never asked about again. - A name two networks give. If two networks on someone's computer both give a name, neither answers it there until that person chooses which one does, on the network's page in the app on a computer, or from the command line. Names from a network
- While the network is on but can't connect on a member's device, its gateway's names get no answer there: they never go to the device's own DNS instead. When the person turns the network off there, its names go to the device's own DNS, as if MultiTunnel weren't running, except a name another of their networks also gives, which still gets no answer.
- The gateway answers these lookups itself, on its own address in the network. Run no other DNS server on that address.
A name with a fixed address
Some sites have a private address that no DNS server the gateway can ask knows: the cloud's DNS gives their public address, and only a line written by hand on a server gave the private one. Give such a name its address in the list, after =. The gateway then answers that name itself, with that address, and never asks its DNS servers.
& $mt set-route $st northwind cloud-gw 10.0.20.0/24,10.0.30.0/24 -names .app.northwind.example=10.0.30.10,staff.northwind.example=10.0.30.10,mydb.postgres.database.azure.comsudo multitunnel set-route /var/lib/multitunnel northwind cloud-gw 10.0.20.0/24,10.0.30.0/24 -names .app.northwind.example=10.0.30.10,staff.northwind.example=10.0.30.10,mydb.postgres.database.azure.comHere app.northwind.example, every name under it, and staff.northwind.example lead to 10.0.30.10 through the gateway, and the database's name is looked up as usual.
- The address is an IPv4 address inside one of the gateway's ranges, not a range's first or last address. A range of one address, such as
10.0.30.10/32, is fine. - It works for an exact name or a part of a domain, and counts towards the 32 names. Where more than one entry covers a name, the closest decides:
staff.northwind.example=…keeps its own address beside a part of a domain that covers it. - It answers IPv4 lookups only.
- Members and phones reach the address through the gateway like any other address there, at a stand-in where they need one.
devicesand the network's page in the app show each one asname → address. - Fixed addresses need every device in the network on an up-to-date MultiTunnel. Until then,
set-routesays which devices to update.
Changing it
Run set-route again with the gateway's whole setup: its ranges, and its names or domain. Anything you leave out is removed. Members follow within seconds.
Whole ranges and names need every device in the network to have an up-to-date MultiTunnel: until then, MultiTunnel says which devices to update. A single /24 range works on every version. A gateway set up with a range larger than a /24 before then reaches only its first /24 until you run set-route again.
More set-route examples
On Windows, in Terminal (Admin), once you have set $mt and $st. On Linux, in a terminal. Before you start
One office network, with the office's own name suffix:
& $mt set-route $st northwind office-gw 192.168.50.0/24 office.northwind.examplesudo multitunnel set-route /var/lib/multitunnel northwind office-gw 192.168.50.0/24 office.northwind.exampleA cloud network, a database's private endpoint and a key vault's:
& $mt set-route $st northwind cloud-gw 10.0.20.0/24,10.0.30.0/24 -names mydb.postgres.database.azure.com,mykv.vault.azure.netsudo multitunnel set-route /var/lib/multitunnel northwind cloud-gw 10.0.20.0/24,10.0.30.0/24 -names mydb.postgres.database.azure.com,mykv.vault.azure.netTell your apps who is asking
A gateway can put MultiTunnel's identity proxy in front of a web app in its network. Each request then reaches the app with a signed statement of who sent it, so the app can decide for itself whom to let in. It is set up on the gateway, from the command line.
- What the app learns
- The network, the device and its person (or the service it runs for), by ID and by name; the device's groups and tags; and until when it is a member. People are known by their ID, so a renamed person is the same person. After a merge or a new ID, the app sees the new one. One person under two names, or a new ID
- How it is signed
- By the gateway's own keys, twice: with ECDSA P-256 and with ML-DSA-65, a post-quantum signature. The app accepts a statement only if both verify. Each one lasts a minute, and names the request it came with: its method, host, path and query.
- The host name
- The request reaches the app under the name the person asked for, so an app that serves several names gets each one. The proxy serves only the names you list, and refuses any other.
- On the gateway, put
identity.jsonin MultiTunnel's state folder: the app's address, the names the proxy serves, and their certificate. Keep the certificate and its key together in one file,proxy.pem, and name that file as both, so a renewal replaces the two at once. It must be readable by the proxy's own account,multitunnel-gw, alone. - Restart MultiTunnel on the gateway. The proxy runs as a service of its own, under its own account, and starts and stops with MultiTunnel. A device installed without
-gatewayneeds the install run again with it first. - Give the app the gateway's key record, which
devicesprints. It is valid for 90 days: print it again before then, and replace the old one. - Give the names the proxy serves to the gateway, so members reach the app through it. Names for your services
- A statement a client sends itself is replaced, never passed on.
- The proxy reaches the app directly, and checks the app's certificate.
- When the certificate is renewed, reload the proxy, and it takes the new one without a restart: people's open connections carry on. If the new certificate fails a check, the proxy keeps serving the one it had and says why. After each renewal, check the certificate the proxy serves.
- Your app checks both signatures with the gateway's key record, the statement's time, the network's ID and the request, and accepts each statement once only.
Command line
On Windows, in Terminal (Admin), once you have set $mt and $st. On Linux, in a terminal. Before you start
On the gateway, after adding identity.json:
sudo systemctl restart multitunnelAfter renewing the certificate in proxy.pem, with no restart:
sudo systemctl reload multitunnel-gatewayThe certificate the proxy serves for a name, to compare with the file's (put the proxy's address and the name in):
echo | openssl s_client -connect <proxy address>:443 -servername <name> 2>/dev/null | openssl x509 -noout -serial -enddateThe gateway's key record, for the app:
& $mt devices $st northwind -pin office-gwsudo multitunnel devices /var/lib/multitunnel northwind -pin office-gwRelays
Two members at two different homes sometimes can't reach each other directly. A relay passes their traffic between them, still encrypted, so it can't read it. Choose a device that's always on and can be reached from anywhere, such as a small cloud server.
- Run it under a service, such as Relay: join it for the service, or move its device to one. Services
- Open Administer, then Devices, and choose Manage beside the device.
- Under Relay, choose Make it a relay…. As for other changes, Windows asks for permission, MultiTunnel says what the change does, and Windows asks for your admin PIN.
It starts relaying as soon as it has the change: there's nothing to set on the device itself. Its page in the app then says Relaying for Northwind Clinic. To stop, choose Stop relaying… in the same place.
Only services' devices relay, because a relay carries other people's traffic. A person's own computer is never made one: for it, the app explains this instead of offering the button. A gateway, too, is always a service's device: move one that is a person's to a service first.
On a cloud server, open UDP ports 49000 to 59999 in the provider's firewall too. On Windows, MultiTunnel's own firewall rule already lets them in.
Members on older versions of MultiTunnel can't use a relay behind its provider's one-to-one address, as most cloud servers are, until they're updated. A relay with an internet address of its own works for everyone.
Command line
On Windows, in Terminal (Admin), once you have set $mt and $st. On Linux, in a terminal. Before you start
& $mt set-relay $st northwind relay-1 onsudo multitunnel set-relay /var/lib/multitunnel northwind relay-1 on& $mt set-relay $st northwind relay-1 offsudo multitunnel set-relay /var/lib/multitunnel northwind relay-1 offStill stuck?
Email us and a person will reply. For a security problem, write to security@multitunnel.co.uk instead.