Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: add docs on DNS-based transfer whitelist #157

Merged
merged 2 commits into from
Jul 6, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions docs/developers/modules/transfer.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,58 @@ The transfer module allows you to transfer players from one server to another, w
When you combine the usage of the ping packet and transfer packet, you can do connection-based optimizing for your players.

<Callout type="warning">
Players are prompted with a confirmation screen, where they can accept or decline the transfer-packet.
Players are prompted with a confirmation screen, where they can accept or decline the transfer-packet. However, the prompt can be skipped via the transfer consent DNS record. See the section below for more info.
</Callout>

![Transfer Module Example](https://i.imgur.com/TjdBfYn.png#center)

<div style={{ textAlign: "center" }}>
<small>Attempt to transfer users from one server to another! (1.20.4 & lower)</small>
<small>Attempting to transfer users from one server to another! (Works on both modern & legacy versions)</small>
</div>

## Transfer Consent DNS Record

Instead of requiring users to click "Accept" on the transfer popup, transfers can also be auto-accepted by the target server. This produces a smoother user experience, without the friction of manually needing to accept.

The intent of the confirmation screen is to ensure users are aware they're changing to a third-party server. However, many use cases of the transfer
packet involve moving around the same server, or between IPs owned by the same party. In these cases, the confirmation can be skipped entirely if
the **target** server has whitelisted the **sender** server in a `mc_transfer_accept_from` TXT DNS record.

### Building the whitelist
When attempting to transfer to a server, Lunar Client first performs a DNS lookup for TXT records at the target server's IP. For example, if directed to connect to `na.lunar.gg`, the client will send a TXT DNS query for `na.lunar.gg`.

The results of this query are split by a comma (`,`), and added to the whitelist. The same query is then sent for any parent domains. For example, if the user is connecting to `foo.na.lunar.gg`, the effective whitelist of sender servers is the **combination** of the results for `foo.na.lunar.gg`, `na.lunar.gg`, and `lunar.gg`.

This hierarchy method is intended to allow transfering to dynamically generated subdomains, without requiring a TXT record be set on each of them.

For example, if the following DNS records are present in your DNS provider:

* na.lunar.gg `TXT mc_transfer_accept_from=*.hypixel.net`
* lunar.gg `TXT mc_transfer_accept_from=*.lunar.gg,lunar.gg`

When transfering to `na.lunar.gg`, the effective whitelist would be:
* `*.hypixel.net`
* `*.lunar.gg`
* `lunar.gg`

When transfering to `lunar.gg` (or any other subdomains, like `eu.lunar.gg`), the effective whitelist would be:
* `*.lunar.gg`
* `lunar.gg`

### Checking the whitelist
Once a whitelist of allowed sender IPs has been built, Lunar Client checks if the IP the user is currently connected to is in this whitelist. If it is, the transfer is accepted immediately. If it is not, the user receives a transfer popup.

Note that wildcards are accepted. For example, `*.lunar.gg` will allow `na.lunar.gg`, `eu.lunar.gg`, `sa.lunar.gg`, etc. to transfer to this server.

### Practical Examples

If you own `example.com` and want to auto-accept transfers between any subdomains, create the following records:
* `example.com` -> `TXT mc_transfer_accept_from=*.example.com,example.com`

If you own `example.com` and `server.net`, and want to auto-accept transfers between them, create the following records:
* `example.com` -> `TXT mc_transfer_accept_from=*.example.com,example.com,*.server.net,server.net`
* `server.net` -> `TXT mc_transfer_accept_from=*.example.com,example.com,*.server.net,server.net`

## Integration

### Using the Transfer Packet
Expand Down
Loading