Stop calling SRV records 'delegation'

[turt2live]

https://github.com/matrix-org/synapse/blob/master/docs/delegate.md

This is not how delegation works. Delegation is only capable through the .well-known path. SRV records are pointers.

[clokep]

I suspect this to simplify the terminology for people who are just trying to get it to work. What's the actual difference between "delegation" and a "pointer"?

[turt2live]

Delegation is when the server is being operated by an entity where control of the domain cannot be given to that entity (mozilla.org delegates to mozilla.modular.im because the folks at *.modular.im aren't reasonably able to gain control of mozilla.org to run a homeserver off of it). SRV records more or less define which port and hostname to connect to rather than shift control of the domain elsewhere.

Part of the issue with calling SRV records delegation is that people often show up in support rooms asking why their delegation doesn't work - from a spec perspective, there's only one kind of delegation and so they automatically start receiving support for .well-known not working rather than their SRV records being malformed.

[Zenuncl]

I think turt2live is correct. At least I think using .well-known delegation is different than using SRV records pointers.
I am having issue that setting up SRV records point to a domain (for example matrix.example.com) but the federation actually resolve the DNS and try to communicate with the IP address. Not sure if .well-known path will act same way, but this quite mis-leading when I read the doc.

[sosnik]

Seconding this. There's a lot of weird documentation floating around.

For instance, the Federation Tester points to the 1.0.0 docs which state the following:

If you have an existing reverse proxy set up with correct TLS certificates for your domain, you can simply route all traffic through the reverse proxy by updating the SRV record appropriately (or removing it, if the proxy listens on 8448).

This (from Option 2) is very ambiguous and doesn't help in setting up federation. The most useful is the actual spec which says that, if you don't have a .well-known endpoint, your matrix server must respond with a valid certificate for the parent / root domain.

[richvdh]

the federation tester linking to old docs is a separate issue, for which I raised matrix-org/fed-tester-ui#29.

[richvdh]

According to https://matrix-org.github.io/synapse/latest/delegate.html:

Delegation is a Matrix feature allowing a homeserver admin to retain a server_name of example.com so that user IDs, room aliases, etc continue to look like *:example.com, whilst having federation traffic routed to a different server and/or port (e.g. synapse.example.com:443).

Accordingly, both .well-known and SRV records are methods of doing delegation. If you want to change the definition of delegation, we're going to need a new name for the feature described above.

In short, I don't agree with this issue.

[sosnik]

Accordingly, both .well-known and SRV records are methods of doing delegation.

In that case, should the delegation docs be updated to also include the certificate requirements?

My suggestion - instead of "However, that is considered an advanced topic since it's a bit complex to set up, and .well-known delegation is already enough in most cases." one possible option is

When using SRV Delegation, the delegated (target) server must present a TLS certificate for both the delegated and the delegating domain.

...or something of the sort.

[richvdh]

The delegation docs deliberately discourage the use of SRV records because they are hard to set up correctly. I would not be in favour of removing that warning, and I am not in favour of cluttering the document with long details about how to set up SRV records - as the documentation already says, if you really need it, you can go and read the spec.

However, as I wrote in matrix-org/fed-tester-ui#29, it might be helpful to add a short note explaining the most likely pitfall.

[richvdh]

I'm also coming around the view that @turt2live is right on this one. If you consider .well-known as delegation, and SRV as routing, it helps explain why we do a .well-known lookup first, and then a SRV lookup.