IPv6 Feature Matrix

This is a list of core tor network features, and their support for IPv6.


Because clients connect through Guard relays, we want to prioritise IPv6 features in this order:

  • More dual-stack Guard and Middle Relays
  • Automatic IPv4 and IPv6 on Clients, including Bridge Clients
  • IPv6-only Bridges

Here are our long-term goals:

  • IPv6-only Exit Relays
  • IPv6-only Guards and Middles
  • IPv6-only Authorities (Feature Parity)

IPv6 Extends

We want to deploy IPv6 extends in this order to make it harder to identify clients with IPv6 support:

  • IPv6 single onion services (in any order, because they only use IPv6 in create cells)
  • Relays discover their own IPv6 address #5940
    • IPv6 relay reachability (provides cover traffic for IPv6 client extends) #24403
      • IPv6 relay extends #4565
    • Automatic IPv6 entry connections #17835 and #29801

In the same release, to avoid version distinguishers:

  • IPv6 client extends for exit circuits #24451
  • IPv6 client extends for multi-hop onion service circuits #24181

Better support for exiting to IPv6 sites #26664 and children

Relay IPv6

We need to get more IPv6 guards, before we make IPv6 work automatically on clients.

Here's the short-term plan:

  • Relay IPv6 reachability checks
  • Auto relay IPv6 address
  • Relay IPv6 statistics

We also need to get more IPv6 guards and middles, before we allow IPv6-only bridges and exits.

Here's the longer-term plan:

  • IPv6-only Bridges
  • IPv6-only Exits

Client IPv6

We need to get more IPv6 guards, before we make IPv6 work automatically on clients.

  • Clients try IPv4 and IPv6 automatically to guards
  • Clients try IPv4 and IPv6 automatically to bridges
    • (If they are configured with both IPv4 and IPv6 bridges)
  • BridgeDB reliably distributes IPv4 and IPv6 bridges
  • Tor Browser and other apps have IPv4 and IPv6 bridges
    • (Tor Browser has some IPv6 bridges already, but we don't know how well they work)


  • Auto: this works automatically in the default configuration.
  • Manual: this requires manual config on the client or relay.
  • Workaround: this works, but we could make it work much better.
  • Broken: this should work, but it doesn't.
  • Never: this can't work, or we won't implement it any time soon.

Each manual, workaround, or broken feature should also have a ticket.

Entry Nodes

What does an entry node need to do to use each IP version for its ORPort? (There are no IPv6 DirPorts.)

Authorities, Relays and Bridges set:

  • Address IPv4 and ORPort Port
  • ORPort [IPv6]:Port

If they do not set Address, Relays and Bridges will automatically detect their IPv4 address. But IPv6 addresses require manual configuration.

Entry Node IPv4 Only Dual-Stack IPv6 Only
Publicly Routable IPv4 Publicly Routable IPv6 Publicly Routable Publicly Routable
Authority Manual Manual Manual Needs Research #4565
Relay Auto Auto Manual #5940 Needs Research #4565
Bridge Auto Auto Manual #5940, Private/NAT IPv4 #4847 Broken #23824

Client Connection to Entry Nodes

What does a client need to do to bootstrap off or connect to an entry node?

Clients can set these options:

  • Default: Use IPv4 only
  • ClientUseIPv6 1: Use IPv6 occasionally
  • ClientPreferIPv6ORPort 1: Use IPv6 whenever they can
  • ClientUseIPv4 0: Only use IPv6
Entry Node IPv4 Only Dual-Stack IPv6 Only
IPv4 IPv6
Authority Dir Auto Auto Manual #17835 Manual #17835
Fallback Dir Auto Auto Manual #17835 Manual #17835
Guard Dir Auto Auto Manual #17835 Manual #17835
Guard microdesc Auto Auto Workaround #19610, #20916 Workaround #19610, #20916
Guard OR Auto Auto Manual #17835, #17217 Manual #17835, #17217

Bridge clients set UseBridges 1, and configure bridge lines using Bridge .... They will use the configured addresses of their bridges, including IPv6 addresses. They can also set ClientPreferIPv6ORPort 1 to prefer IPv6 bridge addresses.

Entry Node IPv4 Only Dual-Stack IPv6 Only
IPv4 IPv6
Bridge Auth Dir Auto Auto Unknown Unknown
Bridge Dir Auto Auto Auto Auto
Bridge OR Auto Auto Auto Auto
Bridge PT Auto Auto Workaround #7961 Workaround #7961

Reachability Checks

Authorities do reachability checks automatically on relay IPv4 ORPorts, and do IPv6 ORPort reachability checks when AuthDirHasIPv6Connectivity is set.

Authorities assume that their own IPv6 ORPorts are reachable (#24338).

Relays do reachability checks automatically on their IPv4 ORPort and DirPort, but don't IPv6 ORPort reachability checks (#24403):

  1. Declare Relay protover 3, in which relays with IPv6 ORPorts start attempting to connect to IPv6 ORPorts in response to EXTEND2 cells containing IPv6 addresses. Relays should choose between IPv4 and IPv6 when extending (how? at random?). (proposal: #24404, code: #24405)
  2. Relays with IPv6 ORPorts check the reachability of their IPv6 ORPort via a multi-hop path using an EXTEND2 cell with their own IPv4 and IPv6 ORPorts for the final hop (#6939, #22781), using a relay that supports protover Relay >= 3 as the second-last hop, and making sure that relay is not in the same IPv4 or IPv6 address block (?) (#24393, #15518).
  3. When a CREATED cell is received on an origin connection, and it contains one of our our ORPort addresses, we know we are reachable at that address (#13112, #17782 (IPv4)).
  4. If we don't confirm ourselves reachable within 20 minutes (this can happen because relays will use existing canonical connections to another relay, rather than making a new one to a different address), use a fallback mechanism (see #24406 for details). Using saved NETINFO from incoming connections is probably the best way forward here.
  5. Authorities do IPv6 reachability checks, and warn if their ORPort is unreachable (but still publish the address: #24338). If an authority publishes an unreachable IPv6 address, it will be marked not running as long as a majority of authorities (that does not include that authority) are on IPv6.

The Bridge Authority may do reachability checks automatically on bridge IPv4 ORPorts and IPv6 ORPorts (#24264).

Exit Connections

IPv4 and IPv6 mostly work, exits handle literal addresses and DNS.

IPv6-only DNS resolves should send a hint to the client, so it tries an IPv6 Exit #26664

IPv6 editing can be unreliable, see the children of #26664

Onion Service Protocol

v2 only supports IPv4, which only matters for single onion services, as long as all relays have IPv4.

v3 only supports IPv4 in 0.3.2. In 0.4.2 we added IPv6 addresses to the v3 onion service implementation, which mainly affects single onion services (#23588). We still need to do multi-hop fallback on failure (#23493), and a few other minor changes.

When we put IPv6 addresses in EXTEND cells for onion services (#24181), we should also put them in normal client extend cells (#24451), so we don't split the anonymity set of v3 onion service circuits and other client circuits. (Hiding v2 onion service circuits is a lost cause, they are the only circuits that use TAP for the final client intro and service rend hops.)


Consensus health has a ReachableIPv6 pseudo-flag for authority to relay IPv6 ORPort reachability checks (#24287):

Metrics reports relay IPv6 ORPorts and IPv6 Exit policies (#23761, #24218):

Reporting IPv6 traffic on ORPorts and Exits needs Core Tor to report these statistics (ticket?).

Tor Browser

Tor Browser shows IPv4 addresses for dual-stack relays, even if the client connects over IPv6 (#14939). We might need to modify the Tor control protocol to fix this issue.

Draft Long-Term Transition Plan

Here is one possible way to transition between IPv4 and IPv6. We need more research to know if this is a good plan.

Automatically detect and use IPv6 on relays:

  1. Release a tor version that automatically detects IPv6 on relays, and uses it if it works. But turn it off by default, and have an option and a consensus parameter to turn it on.
  2. Ask relay operators to test the new feature in the alphas and release candidates.
  3. Once the feature has had enough testing, turn it on for all relays using the consensus parameter.
  4. Encourage relay operators to configure IPv6 on their relay's network stack and upstream connection

Reduce the consensus weight for IPv4-only relays:

  1. Wait until we have enough dual-stack relays, that we can afford to send them more traffic. (We need metrics for IPv6 traffic, which we don't have right now.)
  2. Add a consensus parameter and consensus method that reduces the consensus weight for IPv4-only relays by a percentage.
  3. Gradually reduce the weight of IPv4 relays.
  4. Encourage relay operators to configure IPv6 on their relay's network stack and upstream connection

Wait until we have seen some good research on non-clique anonymity networks, or remove IPv4 and allow IPv6 at the same time.

Allow IPv6-only guards:

  1. Add automatic IPv6 support to clients, so clients use IPv4 and IPv6 when available
  2. Optional: add automatic IPv6 support to bridges, so bridges use IPv4 and IPv6 when available
  3. Wait until we have enough dual-stack middle relays, and dual-stack or IPv6 clients and bridges
  4. Allow IPv6-only guards
  5. Optional: allow IPv6-only bridges

Allow IPv6-only exits:

  1. Improve Tor client and Tor exit support for IPv6 exit connections, allowing clients to discover and remember whether a site is IPv4-only, dual-stack, or IPv6-only
  2. Wait until we have enough dual-stack middle relays, and enough internet sites that support IPv6
  3. Allow IPv6-only exits

Allow IPv6-only middles:

  1. Wait until we have enough dual-stack guards and exits
  2. Allow IPv6-only middles

Remove IPv4-only relays:

  1. Wait until the proportion of IPv4-only guards, middles, or exits is small enough
  2. Remove IPv4-only relays from that role (we can turn guards and exits into middles)

Related Tickets

This is a list of all open IPv6 tickets:

Results (1 - 20 of 156)

1 2 3 4 5 6 7 8
Ticket Summary Keywords Status Owner Type Priority
#4565 Enable relays to talk to other relays via IPv6 ipv6 tor-relay needs-design assigned ln5 project Medium
#4806 Detect and warn when running IPv6-using client without IPv6 address privacy ipv6, tor-client, nickm-patch, intro, privacy needs_revision enhancement High
#4847 Fix IPv6 bridges with a private/dynamic IPv4 address ipv6, tor-bridge assigned ln5 defect Medium
#5298 Relay does not pick the right IP addr of local node when multiple interfaces are available tor-relay, ipv6, reachability, 034-triage-20180328, 034-removed-20180328 new defect Medium
#5532 Reconstruct and merge 4561 leftover code that adds wrappers for address-access functions tor-relay ipv6 multihome addressing needs_revision task Medium
#5788 Add support for relays without an IPv4 address ipv6, tor-relay non-clique new ln5 enhancement Medium
#5940 Figure out own IPv6 address ipv6, tor-relay, 044-deferred new enhancement Medium
#6772 Fall back to alternative OR or Dir port if the current fails ipv6 tor-client tor-hs single-onion robustness address-handling new enhancement Medium
#6878 Make outbound DNS requests honor IPv6 OutboundBindAddress ipv6, exit, tor-relay dns needs-libevent-change new enhancement Medium
#6939 Missing IPv6 ORPort reachability check ipv6, tor-relay, ipv6-relay, self-test, 034-triage-20180328, 034-removed-20180328 needs_revision defect High
#7193 Tor's sybil protection doesn't consider IPv6 ipv6, intro, tor-dirauth, security, sybil, network-health, outreachy-ipv6, network-team-roadmap-2020Q1, 044-must needs_revision enhancement Medium
#7478 Allow routersets to include/exclude nodes by IPv6 address tor-client, ipv6 needs_revision enhancement High
#7482 Discard nonsense in address.c about v4-mapped addresses tor-client, ipv6 refactor code-removal needs_revision defect Medium
#7961 Publish transports that bind on IPv6 addresses tor-bridge, pt, ipv6 anticensorship needs-spec refactor needs_information defect Medium
#11211 Multiple ServerTransportListenAddr entries should be allowed per transport. tor-bridge, pt, needs-spec, tor-pt, bridgedb-parsers, ipv6, triaged-out-20170124 new enhancement Medium
#11360 Listen on IPv6 by default for SocksPort *:Port tor-client, ipv6, torrc, ui, intro new enhancement Medium
#11625 Tor DNSPORT returns NXDOMAIN for AAAA records? tor-client, dns, exit-node-choice, ipv6 new defect Medium
#12138 No IPv6 support when suggesting a bindaddr to a PT tor-pt, tor-bridge ipv6 new enhancement Medium
#13112 Some things are probably broken when we advertise multiple ORPorts and only some are reachable tor-relay, reachability, self-testing, needs-design, ipv6, tor-bridge, 034-triage-20180328, 034-removed-20180328, teor-unreached-2019-03-08, teor-backlog-revise needs_revision defect Medium
#17011 chutney doesn't verify using IPv6 addresses outreachy-ipv6, testing, ipv6, tor-tests-integration assigned defect High
1 2 3 4 5 6 7 8

Last modified 9 months ago Last modified on Jan 21, 2020, 5:29:26 AM