prosody-modules: mod_s2s_v6mesh/README.md annotate

annotate mod_s2s_v6mesh/README.md @ 6562:5da6fb562df9 default tip

mod_unified_push: Fix push error handling (fixes #2000) Use the error object that send_iq() passes as an argument to it's reject callback instead of attempting and failing to do the parsing in the callback itself.

author	kmq
date	Mon, 06 Jul 2026 14:23:57 +0200
parents	771944f2a7c7
children

rev	line source
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	1 ---
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	2 labels:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	3 - Stage-Alpha
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	4 summary: "Federate using stable IPv6 addresses encoded as hostnames, e.g. in mesh networks"
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	5 rockspec:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	6 build:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	7 modules:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	8 mod_s2s_v6mesh.base32: base32.lib.lua
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	9 ---
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	10
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	11 ## Overview
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	12
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	13 There are various virtual network overlay projects which provide peers with
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	14 stable IPv6 addresses, including [Yggdrasil](https://yggdrasil-network.github.io/),
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	15 [CJDNS](https://github.com/cjdelisle/cjdns/), and others.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	16
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	17 One problem is that these systems are generally peer-to-peer, and there is
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	18 typically no standard DNS root for the private networks. Public DNS can be
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	19 used, but that adds a dependency on the public internet which can cause
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	20 problems, e.g. if the public internet becomes inaccessible.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	21
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	22 The "obvious" solution is to skip domain names, and just federate between IP
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	23 addresses directly. Unfortunately this brings a lot of problems, such as
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	24 the inability for IP addresses to have subdomains, which are used extensively
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	25 in XMPP to allow hosting multiple services on a single IP address.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	26
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	27 This module provides an alternative solution. For every possible IPv6 address,
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	28 it can generate an encoded hostname, which supports subdomains, and can be
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	29 resolved to an IPv6 address without any external DNS server infrastructure.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	30
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	31 The domain names end with `.v6.alt`. The `.alt` TLD was defined by [RFC 9476](https://www.rfc-editor.org/rfc/rfc9476.html)
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	32 specifically for non-DNS use cases such as this. `.v6.alt` is our own scheme.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	33
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	34 ## Usage
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	35
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	36 For this module to be useful for federation:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	37
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	38 - Both servers must have this module loaded
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	39 - Both servers must have stable IPv6 addresses (if the IP address changes, the
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	40 hostname changes, and your XMPP identity changes - a new hostname is like
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	41 starting fresh).
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	42
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	43 Although this module was designed with virtual/mesh networks in mind, it is
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	44 possible to use it between any two servers with IPv6 addresses (check the
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	45 section on connection security below if you are using it over unencrypted
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	46 networks such as the public internet).
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	47
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	48 Discover your hostname with the prosodyctl command (our example will use the
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	49 IP address `2a00:1098:3a0::1` but you should replace it with your own):
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	50
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	51 ```
6478 bd785f524fd2 mod_s2s_v6mesh: Fix various bugs, s2s auth policies now work as expected Matthew Wild <mwild1@gmail.com> parents: 6472 diff changeset	52 $ prosodyctl shell v6alt get_domain 2a00:1098:3a0::1
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	53 OK: Encoded hostname: fiabbgadu-e.v6.alt
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	54 ```
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	55
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	56 You can then use this domain name in your config file, for example:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	57
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	58 ```lua
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	59 VirtualHost "fiabbgadu-e.v6.alt" -- Main host, for user accounts
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	60
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	61 Component "groups.fiabbgadu-e.v6.alt" "muc" -- MUC on a subdomain
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	62 ```
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	63
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	64 ### Connection security
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	65
6490 771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	66 Prosody typically requires TLS for server-to-server connections. However, it
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	67 is not possible to obtain CA-issued certificates for `.v6.alt` domains. This
6490 771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	68 raises challenges around authentication of peers.
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	69
6490 771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	70 By default, this module treats all certificates as trusted for all `v6.alt`
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	71 domains where the IP address matches the domain name that the remote server is
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	72 claiming to be (the actual certificate contents are irrelevant and never
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	73 checked, so self-signed certificates are fine). This provides a decent balance
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	74 between convenience and security.
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	75
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	76 Connections using v6.alt are automatically safe from whole categories of
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	77 attacks such as DNS spoofing/poisoning (because such domains do not use DNS
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	78 resolvers). However, any attack which enables an attacker to route an IP
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	79 address to their own machine, for example, may be susceptible to a
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	80 machine-in-the-middle attack, which cannot be ruled out on the internet.
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	81
6490 771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	82 For ultimate security across untrusted networks, use self-signed certificates
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	83 and pin fingerprints in the configuration on both sides using
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	84 [mod_s2s_auth_fingerprint](https://modules.prosody.im/mod_s2s_auth_fingerprint).
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	85
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	86 If you do this, or if you only want v6.alt certificates to be trusted within
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	87 explicitly configured network ranges, you can disable the default certificate
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	88 trusting behaviour using `s2s_v6mesh_trust_all_certs = false`.
6478 bd785f524fd2 mod_s2s_v6mesh: Fix various bugs, s2s auth policies now work as expected Matthew Wild <mwild1@gmail.com> parents: 6472 diff changeset	89
6490 771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	90 You can configure connection security and trust settings per range, using the
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	91 `s2s_v6mesh_ranges` configuration option (more details below).
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	92
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	93 Regardless of any other options, we always recommend keeping Prosody's default
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	94 settings of `s2s_require_encryption = true` and `s2s_secure_auth = true` so
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	95 that connections not covered by this module are always encrypted and
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	96 authenticated properly.
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	97
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	98 ### Connecting from clients
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	99
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	100 Note that although Prosody supports `.v6.alt` domains for federation when this
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	101 module is loaded, this domain scheme is not (currently?) supported by clients,
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	102 and you'll need to specify the connection IP manually in order to connect.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	103
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	104 Your JID should always be entered as `<username>@<domain.v6.alt>`, and you
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	105 should specify the server's IPv6 address in your client's advanced connection
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	106 configuration screen.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	107
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	108 ### HTTP
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	109
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	110 Services that use HTTP such as file sharing, web clients, etc. will need to
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	111 use the IP address in the URL, as clients and browsers won't be able to
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	112 resolve the `.v6.alt` domain names. You will need to [configure Prosody's HTTP
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	113 server](https://prosody.im/doc/http) appropriately for your deployment, e.g.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	114
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	115 ```lua
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	116 http_external_url = "https://[2a00:1098:3a0::1]:5281"
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	117 ```
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	118
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	119 ## Configuration
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	120
6490 771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	121 \| Name \| Default \| Description
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	122 \|------------------------------\|-------- \|-------------------------------------------------------------------------
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	123 \| s2s_v6mesh_ranges \| `{}` \| A list of IP ranges and associated configuration (see below)
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	124 \| s2s_v6mesh_trust_all_certs \| `true` \| Whether to trust all certs from verified v6.alt addresses (even in unconfigured ranges)
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	125
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	126 ### Range configuration
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	127
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	128 By default, this module will use TLS, and trust any certificate from a v6.alt
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	129 domain if the IP address matches. You can override this behaviour on a
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	130 per-range basis:
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	131
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	132 ```lua
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	133 s2s_v6mesh_ranges = {
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	134 ["200::/7"] = {
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	135 -- disable TLS requirement for this IP range (overrides s2s_require_encryption)
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	136 use_tls = false;
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	137 -- trust all certificates (even self-signed) within this range (overrides s2s_secure_auth)
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	138 trust_all_certs = true;
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	139 };
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	140 }
771944f2a7c7 mod_s2s_v6mesh: Update configuration syntax and associated documentation Matthew Wild <mwild1@gmail.com> parents: 6478 diff changeset	141 ```
6472 9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	142
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	143 ## Compatibility
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	144
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	145 \|Prosody-Version\|Status
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	146 \|---------------\|----------------------
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	147 \|trunk \| Works
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	148 \|13.0 \| Works
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	149 \|0.12 \| Does not work
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	150
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	151
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	152 ## Developers
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	153
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	154 This section is for developers who want to encode/decode v6.alt addresses
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	155 in their own code.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	156
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	157 ### Encoding scheme
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	158
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	159 1. Take an IPv6 address as raw packed bytes
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	160 2. Encode it using base32 (RFC 4648), remove `====` padding from the end.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	161 3. Lowercase the output
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	162 4. Find the first longest sequence of 'a' characters that is:
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	163 1. Not at the start of the string (start scanning from second position)
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	164 2. Two or more characters in length
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	165 3. Not including the end character
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	166
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	167 If found, replace this sequence with a hyphen (`-`).
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	168
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	169 5. Append `.v6.alt`
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	170
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	171 ### Decoding scheme
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	172
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	173 1. Take a hostname ending with `.v6.alt`
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	174 2. Remove `.v6.alt`
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	175 3. Remove any '.' characters and all content before them (`foo.bar` -> `bar`)
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	176 4. If the string contains a hyphen, replace that hyphen with sufficient 'a' characters to make the string 26 characters in length. Strings with multiple hyphen characters are invalid and must be rejected.
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	177 5. Uppercase the string
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	178 6. Decode using base32
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	179
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	180 ### Test vectors
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	181
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	182 \| IP \| Domain \|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	183 \|-------------------------------------------\|------------------------------------\|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	184 \| `2001:db8::1` \| `eaaq3o-e.v6.alt` \|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	185 \| `0200::1` \| `ai-e.v6.alt` \|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	186 \| `200:cab8:deb4:ce60:4362:4492:e539:4b5` \| `aiamvog6wthgaq3cisjokoiewu.v6.alt`\|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	187 \| `::1` \| `a-e.v6.alt` \|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	188 \| `::` \| `a-a.v6.alt` \|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	189 \| `fe80::1` \| `72-e.v6.alt` \|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	190 \| `ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff` \| `77777777777777777777777774.v6.alt`\|
9f43226c7de1 mod_s2s_v6mesh: DNS-less federation for IPv6 networks Matthew Wild <mwild1@gmail.com> parents: diff changeset	191 \| `1111:0000:0000:1111::1111` \| `ceiqaaaaaairc-rce.v6.alt` \|
6478 bd785f524fd2 mod_s2s_v6mesh: Fix various bugs, s2s auth policies now work as expected Matthew Wild <mwild1@gmail.com> parents: 6472 diff changeset	192 \| `1111:0000:0000:0000:1111::1111` \| `ceiq-eiraaaaaaarce.v6.alt` \|

Mercurial > prosody-modules

annotate mod_s2s_v6mesh/README.md @ 6562:5da6fb562df9 default tip