diff --git a/changelog.d/11561.feature b/changelog.d/11561.feature
index 19dada883b..3d4f2159c0 100644
--- a/changelog.d/11561.feature
+++ b/changelog.d/11561.feature
@@ -1 +1 @@
-Add `track_puppeted_user_ips` config flag to track puppeted user IP addresses. This also includes them in monthly active user counts.
+Add `track_puppeted_user_ips` config flag to record client IP addresses against puppeted users, and include the puppeted users in monthly active user counts.
diff --git a/changelog.d/11749.feature b/changelog.d/11749.feature
index 19dada883b..3d4f2159c0 100644
--- a/changelog.d/11749.feature
+++ b/changelog.d/11749.feature
@@ -1 +1 @@
-Add `track_puppeted_user_ips` config flag to track puppeted user IP addresses. This also includes them in monthly active user counts.
+Add `track_puppeted_user_ips` config flag to record client IP addresses against puppeted users, and include the puppeted users in monthly active user counts.
diff --git a/changelog.d/11757.feature b/changelog.d/11757.feature
new file mode 100644
index 0000000000..3d4f2159c0
--- /dev/null
+++ b/changelog.d/11757.feature
@@ -0,0 +1 @@
+Add `track_puppeted_user_ips` config flag to record client IP addresses against puppeted users, and include the puppeted users in monthly active user counts.
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 4d4f6a6948..5908f262e5 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -1503,10 +1503,18 @@ room_prejoin_state:
#additional_event_types:
# - org.example.custom.event.type
-# By default when puppeting another user, the user who has created the
-# access token for puppeting is tracked. If this is enabled, both
-# requests are tracked. Implicitly enables MAU tracking for puppeted users.
-# Uncomment to also track puppeted user IP's.
+# We record the IP address of clients used to access the API for various
+# reasons, including displaying it to the user in the "Where you're signed in"
+# dialog.
+#
+# By default, when puppeting another user via the admin API, the client IP
+# address is recorded against the user who created the access token (ie, the
+# admin user), and *not* the puppeted user.
+#
+# Uncomment the following to also record the IP address against the puppeted
+# user. (This also means that the puppeted user will count as an "active" user
+# for the purpose of monthly active user tracking - see 'limit_usage_by_mau' etc
+# above.)
#
#track_puppeted_user_ips: true
diff --git a/synapse/config/api.py b/synapse/config/api.py
index f8e52150a2..8133b6b624 100644
--- a/synapse/config/api.py
+++ b/synapse/config/api.py
@@ -61,10 +61,18 @@ class ApiConfig(Config):
#additional_event_types:
# - org.example.custom.event.type
- # By default when puppeting another user, the user who has created the
- # access token for puppeting is tracked. If this is enabled, both
- # requests are tracked. Implicitly enables MAU tracking for puppeted users.
- # Uncomment to also track puppeted user IP's.
+ # We record the IP address of clients used to access the API for various
+ # reasons, including displaying it to the user in the "Where you're signed in"
+ # dialog.
+ #
+ # By default, when puppeting another user via the admin API, the client IP
+ # address is recorded against the user who created the access token (ie, the
+ # admin user), and *not* the puppeted user.
+ #
+ # Uncomment the following to also record the IP address against the puppeted
+ # user. (This also means that the puppeted user will count as an "active" user
+ # for the purpose of monthly active user tracking - see 'limit_usage_by_mau' etc
+ # above.)
#
#track_puppeted_user_ips: true
""" % {
|
