From b11f5c984b28b5ff6f5909db34a4e6b96d3e4880 Mon Sep 17 00:00:00 2001
From: davidegirardi <16451191+davidegirardi@users.noreply.github.com>
Date: Fri, 28 Jun 2024 15:39:54 +0200
Subject: [PATCH] Clarify `url_preview_url_blacklist` is a usability feature
 (#17356)

---
 changelog.d/17356.doc                         |  1 +
 .../configuration/config_documentation.md     | 21 +++++++++++--------
 2 files changed, 13 insertions(+), 9 deletions(-)
 create mode 100644 changelog.d/17356.doc

diff --git a/changelog.d/17356.doc b/changelog.d/17356.doc
new file mode 100644
index 0000000000..b393d8d147
--- /dev/null
+++ b/changelog.d/17356.doc
@@ -0,0 +1 @@
+Clarify `url_preview_url_blacklist` is a usability feature.
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 80a7bf9d21..65b03ad0f8 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -1976,9 +1976,10 @@ This will not prevent the listed domains from accessing media themselves.
 It simply prevents users on this server from downloading media originating
 from the listed servers.
 
-This will have no effect on media originating from the local server.
-This only affects media downloaded from other Matrix servers, to
-block domains from URL previews see [`url_preview_url_blacklist`](#url_preview_url_blacklist).
+This will have no effect on media originating from the local server. This only
+affects media downloaded from other Matrix servers, to control URL previews see
+[`url_preview_ip_range_blacklist`](#url_preview_ip_range_blacklist) or
+[`url_preview_url_blacklist`](#url_preview_url_blacklist).
 
 Defaults to an empty list (nothing blocked).
 
@@ -2130,12 +2131,14 @@ url_preview_ip_range_whitelist:
 ---
 ### `url_preview_url_blacklist`
 
-Optional list of URL matches that the URL preview spider is
-denied from accessing.  You should use `url_preview_ip_range_blacklist`
-in preference to this, otherwise someone could define a public DNS
-entry that points to a private IP address and circumvent the blacklist.
-This is more useful if you know there is an entire shape of URL that
-you know that will never want synapse to try to spider.
+Optional list of URL matches that the URL preview spider is denied from
+accessing.  This is a usability feature, not a security one. You should use
+`url_preview_ip_range_blacklist` in preference to this, otherwise someone could
+define a public DNS entry that points to a private IP address and circumvent
+the blacklist. Applications that perform redirects or serve different content
+when detecting that Synapse is accessing them can also bypass the blacklist.
+This is more useful if you know there is an entire shape of URL that you know
+that you do not want Synapse to preview.
 
 Each list entry is a dictionary of url component attributes as returned
 by urlparse.urlsplit as applied to the absolute form of the URL.  See