3 files changed, 35 insertions, 3 deletions
diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst
index 579fb913..8ee0b444 100644
--- a/sites/docs/api/config.rst
+++ b/sites/docs/api/config.rst
@@ -61,6 +61,14 @@ Paramiko releases) are included. A keyword by itself means no known departures.
 
 - ``Host``
 - ``HostName``: used in ``%h`` :ref:`token expansion <TOKENS>`
+- ``Match``: fully supported, with the usual caveat that connection-time
+  information is not present during config lookup, and thus cannot be used to
+  determine matching. This primarily impacts ``Match user``, which can match
+  against loaded ``User`` values but has no knowledge about connection-time
+  usernames.
+
+    .. versionadded:: 2.7
+
 - ``Port``: supplies potential values for ``%p`` :ref:`token expansion
   <TOKENS>`.
 - ``ProxyCommand``: see our `.ProxyCommand` class for an easy
@@ -94,7 +102,8 @@ OpenSSH, ``%L`` works in ``ControlPath`` but not elsewhere):
 - ``%n``
 - ``%p``
 - ``%r``
-- ``%u``
+- ``%u``: substitutes the configured ``User`` value, or the local user (as seen
+  by ``getpass.getuser``) if not specified.
 
 In addition, we extend OpenSSH's tokens as follows:
 
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst
index 23e9a567..67ba6554 100644
--- a/sites/www/changelog.rst
+++ b/sites/www/changelog.rst
@@ -2,9 +2,30 @@
 Changelog
 =========
 
+- :bug:`- major` ``ssh_config`` :ref:`token expansion <TOKENS>` used a
+  different method of determining the local username (``$USER`` env var),
+  compared to what the (much older) client connection code does
+  (``getpass.getuser``, which includes ``$USER`` but may check other variables
+  first, and is generally much more comprehensive). Both modules now use
+  ``getpass.getuser``.
+- :feature:`-` A couple of outright `~paramiko.config.SSHConfig` parse errors
+  were previously represented as vanilla ``Exception`` instances; as part of
+  recent feature work a more specific exception class,
+  `~paramiko.ssh_exception.ConfigParseError`, has been created. It is now also
+  used in those older spots, which is naturally backwards compatible.
+- :feature:`717` Implement support for the ``Match`` keyword in ``ssh_config``
+  files. Previously, this keyword was simply ignored & keywords inside such
+  blocks were treated as if they were part of the previous block. Thanks to
+  Michael Leinartas for the initial patchset.
+
+  .. note::
+    This feature adds a new :doc:`optional install dependency </installing>`,
+    `Invoke <https://www.pyinvoke.org>`_, for managing ``Match exec``
+    subprocesses.
+
 - :support:`-` Additional :doc:`installation </installing>` ``extras_require``
-  "flavors" (``ed25519`` and ``everything``) have been added to our packaging
-  metadata; see the install docs for details.
+  "flavors" (``ed25519``, ``invoke``, and ``everything``) have been added to
+  our packaging metadata; see the install docs for details.
 - :bug:`- major` Paramiko's use of ``subprocess`` for ``ProxyCommand`` support
   is conditionally imported to prevent issues on limited interpreter platforms
   like Google Compute Engine. However, any resulting ``ImportError`` was lost
diff --git a/sites/www/installing.rst b/sites/www/installing.rst
index 26637e16..ee57bdfc 100644
--- a/sites/www/installing.rst
+++ b/sites/www/installing.rst
@@ -33,9 +33,11 @@ There are also a number of **optional dependencies** you may install using
 `setuptools 'extras'
 <https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras>`_:
 
+.. TODO 3.0: tweak the invoke line to mention proxycommand too
 .. TODO 3.0: tweak the ed25519 line to remove the caveat
 
 - If you want all optional dependencies at once, use ``paramiko[everything]``.
+- For ``Match exec`` config support, use ``paramiko[invoke]``.
 - For GSS-API / SSPI support, use ``paramiko[gssapi]``, though also see
   :ref:`the below subsection on it <gssapi>` for details.
 - ``paramiko[ed25519]`` references the dependencies for Ed25519 key support.