Tor relay family declarations are a configuration mechanism that lets a single operator tell the Tor network which of their relays belong together. Tor routes each connection through several volunteer-run relays, and the design depends on no single party controlling the whole path.
The idea is simple: if two relays are run by the same person or organization, the network should avoid placing them in the same circuit. Without that rule, one operator could observe both the entry and the exit of a connection and gain far more insight than the design intends.
Why Relay Families Exist in the Tor Network
Tor is built on the principle that a user’s traffic is split across several independent relays. Each relay sees only a small piece of the picture, which means no single relay knows both who is connecting and where the traffic ultimately goes.
That protection depends on the relays in a circuit being run by different parties who do not cooperate with one another.
Now imagine an operator who runs two relays and both end up in the same circuit. That operator could see the entry point and the exit point of the same traffic, undoing much of the separation the design provides. This is the risk that relay families are meant to prevent.
Relay family declarations allow an operator to tell the network that certain relays are controlled by the same entity. Clients and path-selection logic then treat those relays as a single unit when building a circuit, reducing the chance that related relays appear together in one path.
How Tor Relay Family Declarations Are Configured
A relay operator declares a family by listing the fingerprints of the relays they control in each relay’s configuration.
Every relay in the family carries a list of the other members’ identities, and those declarations should be mutual so that each relay confirms the relationship with the others. A one-sided claim is less reliable because it does not establish that the relationship is consistent across the group.
The fingerprint is the unique identifier that Tor assigns to each relay, and it is the value operators use when they list family members. The exact configuration keyword and format are described in the official Tor Project documentation, which should be consulted for the current syntax because it can change between software versions.
Operators should also confirm that the family list stays accurate over time. When a relay is retired, replaced, or transferred to someone else, the declaration should be updated on the remaining relays so the network does not hold a stale or misleading relationship.
What Relay Families Are Designed to Prevent
Relay family declarations address a specific set of concerns that affect how well Tor protects its users. Understanding these concerns helps operators see why declaring their relays matters even when they feel their setup is harmless. The main concerns include the following.
- Same-operator entry and exit: one party controlling the first and last hop of a circuit, which would let it link a user to a destination
- Correlated observation: multiple relays owned by one entity giving a fuller view of traffic patterns across the path
- Concentration risk: an operator running a large share of relays and increasing the odds that its nodes appear together
- Misleading capacity: several relays from one owner distorting how the network appears to be diverse and resilient
These risks are about structure rather than intent. An operator who never tries to watch traffic can still create them simply by running related relays without declaring them. Declarations are a way of making the real relationships visible to the software that builds circuits, so that the protection the design promises holds up in practice.
How Clients Use Family Information When Building Circuits
When a Tor client builds a circuit, it selects relays according to weighting rules, consensus data, and several other constraints. Family information is one of those constraints.
If two candidate relays are declared as family members, the client will not place both of them in the same circuit. This is applied during path selection so the restriction happens automatically without the user needing to do anything.
The effect is that the client treats a declared family as a single choice for the purposes of a given path.
It may still use one member of the family as the entry and a relay from a different operator as the exit, which preserves the separation that matters. The restriction limits how the family is combined rather than removing its relays from the network entirely.
Because this behavior happens inside the client’s path logic, a user does not need to understand the internal details to benefit from it. The protection is built into how circuits are assembled, which is one reason accurate declarations by operators are so important to the overall health of the network.
Common Mistakes Operators Make With Family Declarations
One of the most frequent problems is forgetting to update family lists when relays change. An operator may add a new relay to their setup but fail to declare it on the others, leaving the relationship incomplete.
The result is that the network may not recognize the family as a unit, which weakens the protection the declaration is supposed to provide.
Another mistake is declaring relationships that do not exist. Listing unrelated relays as family members can distort path selection and reduce the number of usable relays available to clients. Accuracy matters in both directions: a missing declaration leaves a real risk in place, while a false one harms the network’s flexibility.
A third issue is inconsistency between relays. If one relay lists a family member that does not list it back, the relationship is only partly established. Operators should review all of their relays together and confirm that each declaration matches the others, using the official documentation as the reference for correct configuration.
Setting Up Declarations Correctly for Your Relays
Setting up relay family declarations takes careful attention to identity, consistency, and maintenance. The steps below describe how a careful operator approaches the task and what to verify before and after making changes to a live relay.
Gathering the Right Identity Information
Before writing any declaration, collect the fingerprint of every relay you operate. The fingerprint is the identifier Tor uses, and it is the value other relays need in order to recognize the family. Keep a written record of each relay alongside its fingerprint so you can cross-check later without relying on memory.
Confirm that the list is complete. Include every relay you control, including those that are offline for maintenance, because an omitted relay still represents a real connection to your other nodes. A complete inventory is the foundation of an accurate declaration.
Applying Mutual Declarations Across All Relays
Once you have the full list, add the family configuration to each relay so that every member lists the others.
Apply the change to all relays in the group rather than only one, since mutual confirmation is what makes the relationship clear to the network. Follow the configuration syntax in the official Tor Project documentation and restart each relay as the documentation instructs.
After applying the changes, verify them. Review the configuration on each relay to confirm the list is correct and identical in content across the group. Checking the public network status information can also help you confirm that your relays appear as expected, though interpretation of that data is best done with the official guidance.
Maintaining Declarations Over Time
Family declarations are not a one-time task. Whenever you add a relay, retire one, or change the hardware or hosting arrangement, update the family list on every affected node. Schedule periodic reviews so the declarations reflect your current setup rather than the setup you had when you first configured them.
Keep records of every change, including the date and the reason. This makes it easier to diagnose problems later and demonstrates that your configuration was deliberate. A simple maintenance log, reviewed alongside your other relay checks, is usually enough to keep the declarations accurate over the long term.
Limits of Relay Family Declarations
Relay family declarations are a useful safeguard, but they do not solve every problem. They rely on operators being honest and accurate about their relationships.
The mechanism cannot independently verify that two relays are truly controlled by the same party, so it depends on the good faith of the people declaring them. Readers should understand this as a policy-level protection built on cooperation, not an enforced technical guarantee.
Declarations also do not prevent an operator from running many unrelated-looking relays that are in fact controlled together but never declared. Detecting such arrangements is a separate and harder problem. Tor’s broader design, including diverse relay selection and guard behavior, provides additional protection, but no single feature can eliminate every form of concentration.
Family declarations address structural risk within the relay network, not every threat a user might face. They do not change what a website or service learns about a user, and they do not replace the privacy practices a user chooses. The protection they offer is one layer among several that Tor combines.
Relay Family Declarations Compared With Other Safeguards
Relay family declarations sit alongside several other mechanisms that shape how Tor selects relays. Entry guards keep a client’s first hop stable over time, which limits how often a user’s entry point changes.
Bandwidth weighting influences how often each relay is chosen, so that high-capacity relays carry a fair share of traffic without dominating the network. Family declarations are a different kind of rule: they focus on the relationships between relays rather than on the individual relays themselves.
It helps to think of these safeguards as complementary. Guards reduce the exposure created by changing entry points, weighting spreads load, and family declarations prevent related relays from appearing in the same path. Each addresses a different aspect of how a circuit could be observed or manipulated, and the combination is stronger than any one of them alone.
Operators sometimes ask whether declarations can be used to gain an advantage on the network. They do not. A declaration only restricts how relays are combined; it does not increase how often a relay is selected. Its purpose is to protect the integrity of the path, which benefits users regardless of which operator makes the declaration.
Questions Operators Ask About Family Declarations
Relay operators often raise similar questions when they first consider family declarations. The answers below reflect the general behavior of the network, and operators should confirm details against the current official documentation before making changes.
- Do I need to declare relays that run on different hosting providers? Yes, if you control them, because the declaration reflects who operates the relays rather than where they are hosted.
- Does declaring a family make my relays less likely to be used? A declaration restricts pairing within a path, which can affect selection somewhat, but it is not a penalty and is intended to protect users.
- What happens if I forget to declare one relay? That relationship is not recognized, which leaves a gap the mechanism is meant to close, so correcting the omission is important.
- Can a relay belong to more than one family? A relay’s declared family should reflect the real relationships an operator maintains, so operators should review the arrangement carefully and consult the official guidance.
The best approach is to treat declarations as an honest description of your operation. If you control a group of relays, declare them consistently and keep the list current. If you are unsure how a particular arrangement should be represented, the Tor Project’s documentation and community resources are the appropriate places to clarify the correct approach for your situation.
Keeping Your Relay Declarations Accurate Going Forward
For operators who run relays, the practical priority is accuracy and upkeep. Build a routine that checks your family declarations whenever you change your setup, and make it part of your normal review of relay health. A short checklist covering fingerprints, mutual listings, and recent changes will catch most errors before they cause problems.
Readers who are not operators can still benefit from understanding this mechanism. It explains part of why Tor’s circuits are assembled the way they are, and it shows that the network relies on people being transparent about their own infrastructure. Knowing this helps set realistic expectations about what the network can and cannot guarantee.
Going forward, the most useful habit is to stay informed. Follow the official Tor Project documentation for current configuration details, since syntax and recommendations can change, and treat any change to your relays as an occasion to re-check every declaration.
Careful, consistent maintenance is what turns a simple configuration option into a meaningful protection for the people who rely on the network.