Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Summary: naming things is hard, but should at least be consistent. This policy documents how domain names are used, how to name machines, services, networks and might eventually document IP addressing as well.

Domain names

Tor uses two main domain names for things:

  • torproject.org
  • torproject.net

There might be other domains managed by us or registered in the DNS, but they should eventually point to one of those, generally torproject.org. Exceptions to this rule are the Tails nodes, which have their own naming scheme.

All TPA-managed machines and services on those machines should be under torproject.org. The naming scheme of the individual machines is detailed below. This is managed by TPA directly through service/dns.

External services and machines can be hosted under torproject.net. In that case, the only association is a CNAME or A record pointing to the other machine. To get such a record, contact TPA using the normal communication channels detailed in support.

Machine names

There are multiple naming schemes in use:

  • onion species
  • role-based
  • location-based
  • Tails names

We are trying to phase out the onion-based names, in favor of more descriptive names. It kind of takes the soul out of the infrastructure, but it makes things much easier to figure out for newcomers. It also scales better.

Onion species

Note that this naming scheme is deprecated. Favor role-based names, see below.

Wikipedia list of onion species, preferably picking a first letter matching purpose (e.g. "m" for monitoring, "b" for backups, "p" for puppet) and ideally not overlapping with existing machines at debian.org in the first three letters or at least the short hostname part

Example: monticola.torproject.org was picked as a "monitoring" ("mon") server to run the experimental Prometheus server. no machine is named "monticola" at Debian.org and no machine has "mon" or smaller as its first three letters there either.

Roles

Another naming scheme is role-ID, where:

  • role is what the server is for, for example gitlab, mon for monitoring, crm, etc. try to keep it short and abbreviate to at most three letters if role is longer than five. role might have a dash (-) in it to describe the service better (crm-ext vs crm-int)
  • ID is a two-character number, padded with zero, starting from one, to distinguish between multiple instances of the same server (e.g. mon-01, mon-02)

Some machines do include a location name, when their location is actually at least as important as their function. For example, the Ganeti clusters are named like gnt-LOC where LOC is the location (example, gnt-fsn is in Falkenstein, Germany). Nodes inside the cluster are named LOC-node-ID (e.g. fsn-node-01 for the first Ganeti node in the gnt-fsn cluster).

Other servers may be named using that convention, for example, dal-rescue-01 is a rescue box hosted near the gnt-dal cluster.

Location

Note that this naming scheme is deprecated. Favor role-based names, see above.

Another naming scheme used for virtual machines is hoster-locN-ID (example hetzner-hel1-01), where:

  • hoster: is the hosting provider (example hetzner)
  • locN: is the three-letter code of the city where the machine is located, followed by a digit in case there are multiple locations in the same city (e.g. hel1)
  • ID: is an two-character number, padded with zero, starting from one, to distinguish multiple instances at the same location

This is used for virtual machines at Hetzner that are bound to a specific location.

Tails names

Tails machines were inherited by TPA on mid-2024 and their naming scheme was kept as-is. We currently don't have plans to rename them, but we may give preference to the role-based naming scheme when possible (for example, when installing new servers or VMs for Tails).

Tails machines are named as such:

  • Physical machines are named after reptiles and use the tails.net TLD (eg. chameleon.tails.net, lizard.tails.net, etc).
  • VMs are names after their role and use the physical machine hostname as their (internal) TLD (eg. mta.chameleon, www.lizard, etc).

Network names

Networks also have names. The network names are used in reverse DNS to designate network, gateway and broadcast addresses, but also in service/ganeti, where networks are managed automatically for virtual machines.

Future networks should be named FUN-LOCNN-ID (example gnt-fsn13-02) where:

  • FUN is the function (e.g. gnt for service/ganeti)
  • LOCNN is the location (e.g. fsn13 for Falkenstein)
  • ID is a two-character number, padded with zero, starting from one, to distinguish multiple instances at the same function/location pair

The first network was named gnt-fsn, for Ganeti in the Falkenstein datacenter. That naming convention is considered a legacy exception and should not be reused. It might be changed in the future.

Deadline

Considering this documentation has been present in the wiki for a while, it is already considered adopted. The change to deprecate the location and onions names was informally adopted some time in 2020.

References