localnetwork match condition not supported in ssh_config

[tobast]

Hello,

It seems that the localnetwork condition for Match blocks in ssh_config, introduced in OpenSSH 9.4, is not supported by asyncssh. This triggers a ConfigParseError.

This prevents a user from using asyncssh at all if they have such a match block in their ssh config.

Reproducing

# ~/.ssh/config
match localnetwork 2001:db8::/32
	ProxyJump proxy.example.com

$ ssh example.com  # --> OK

import asyncssh
conn = await asyncssh.connect('example.com')
# --> ConfigParseError: /tmp/tmp.esuGL7jFvj/.ssh/config line 1: Invalid match condition localnetwork

[tobast]

Note: it seems to me that listing interfaces' addresses is non-trivial to do in a portable manner. If you are willing to introduce a dependency, ifaddr seems to me to be the best candidate (netifaces is lacking a maintainer – and releases – for now and is bulkier).

[ronf]

Thanks for reporting this! I missed this being added to OpenSSH.

I agree that ifaddr seems like a good choice for getting the interface information in a portable fashion. It seems fairly lightweight and it appears to be pure-Python, which is a major plus.

I'm currently thinking of treating this similar to other optional modules supported in AsyncSSH. If the module is present, the "Match localnetwork" feature will be available. However, if not, an attempt to use it will raise a ConfigParseError exception like it does now, but with an error message like "Local network matching requires ifaddr module". I'll also add ifaddr as an optional dependency.

[tobast]

I think I would actually believe it more useful to end-users if, when the dependency is absent, the Match block was ignored with a warning.

I expect that this error would mostly be faced by end-users of something that depends on asyncssh, not developers. Most often, the Match block with this rule would also be unrelated to the host they are trying to reach. In these cases, a crash would simply be annoying for the user.

I can try implementing this if you want!

[ronf]

Since AsyncSSH is a library, I avoid it printing anything to the console or otherwise trying to interact with the end user. I agree that an end user might be running something which depends on AsyncSSH, but it's really up to that application code to handle any warnings or errors, and decide how (if at all) to present that information to the end user.

Also, looking at the Python "warnings" framework, it appears not to be thread or async safe by default, and this behavior can only be changed using a command-line argument or setting an environment variable when launching the Python interpreter. This would have to be done by an application-provided wrapper script or by the end user and I can't really count on it being safe to use the "warnings" framework in AsyncSSH code.

Another issue is that the match type determines how many arguments to consume on the "Match" line. So, if the code doesn't know a match type, it would have difficulty parsing the rest of the line. It would be possible to simply mark the block as never matching in this case (until the next Host/Match directive), but it would be hard to "ignore" the unknown match type as if it wasn't present and still match on other arguments in the Match line.

Given the problems with "warnings", I think I'm going to stick to the exception for now, but once this is implemented I expect anyone who runs into this error to just install ifaddr if they can't easily avoid "Match localnetwork" showing up in the config file AsyncSSH is using.

I appreciate your offer to implement this, but I've got most of it worked out already. If all goes well, I should have something you can try in the next day or two.

[tobast]

Your point about warnings definitely make sense, I agree that an exception is probably best in this case.

This exceeds a bit the scope of this issue, but if the responsibility to handle the exception lies with the application, maybe providing a way to have a kind of "fuzzy" parsing of the configuration (eg. skipping a config option if it is unknown, skipping the whole Match/Host block on an unknown type) would be useful? I'm really not certain whether it's worth the effort of implementing it though.

In any case, thanks for your fast reply and ongoing work!

[ronf]

Here's something you can try:

--- a/asyncssh/config.py
+++ b/asyncssh/config.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2024 by Ron Frederick <ronf@timeheart.net> and others.
+# Copyright (c) 2020-2026 by Ron Frederick <ronf@timeheart.net> and others.
 #
 # This program and the accompanying materials are made available under
 # the terms of the Eclipse Public License v2.0 which accompanies this
@@ -29,14 +29,20 @@ import subprocess
 from hashlib import sha1
 from pathlib import Path, PurePath
 from subprocess import DEVNULL
-from typing import Callable, Dict, List, NoReturn, Optional, Sequence
-from typing import Set, Tuple, Union, cast
+from typing import Callable, Dict, Iterator, List, NoReturn, Optional
+from typing import Sequence, Set, Tuple, Union, cast

 from .constants import DEFAULT_PORT
 from .logging import logger
 from .misc import DefTuple, FilePath, ip_address
 from .pattern import HostPatternList, WildcardPatternList

+try:
+    import ifaddr
+    _ifaddr_available = True
+except ImportError: # pragma: no cover
+    _ifaddr_available = False
+

 ConfigPaths = Union[None, FilePath, Sequence[FilePath]]

@@ -52,6 +58,18 @@ def _exec(cmd: str) -> bool:
                           stdout=DEVNULL, stderr=DEVNULL).returncode == 0


+def _get_local_ips() -> Iterator[str]:
+    """Return local IP addresses of the system"""
+
+    for adapter in ifaddr.get_adapters():
+        for ip in adapter.ips:
+            if isinstance(ip.ip, tuple):
+                addr, _, scope_id = ip.ip
+                yield f'{addr}%{scope_id}' if scope_id else addr
+            else:
+                yield ip.ip
+
+
 class ConfigParseError(ValueError):
     """Configuration parsing exception"""

@@ -183,6 +201,9 @@ class SSHConfig:
             elif match == 'final':
                 result = cast(bool, self._final)
             else:
+                if match == 'localnetwork' and not _ifaddr_available:
+                    self._error('Local network match requires ifaddr module')
+
                 match_val = self._match_val(match)

                 if match != 'exec' and match_val is None:
@@ -201,6 +222,15 @@ class SSHConfig:
                         ip = ip_address(cast(str, match_val)) \
                             if match_val else None
                         result = host_pat.matches(None, match_val, ip)
+                    elif match == 'localnetwork':
+                        host_pat = HostPatternList(arg)
+
+                        for addr in cast(Iterator[str], match_val):
+                            if host_pat.matches(None, addr, ip_address(addr)):
+                                result = True
+                                break
+                        else:
+                            result = False
                     else:
                         wild_pat = WildcardPatternList(arg)
                         result = wild_pat.matches(match_val)
@@ -514,6 +544,8 @@ class SSHClientConfig(SSHConfig):
             return self._options.get('Hostname', self._orig_host)
         elif match == 'originalhost':
             return self._orig_host
+        elif match == 'localnetwork':
+            return _get_local_ips()
         elif match == 'localuser':
             return self._local_user
         elif match == 'user':

Regarding SSH config parsing, AsyncSSH already ignores directives it doesn't understand. It only errors out on arguments to directives it understands, like "Match". We could change that, but now that AsyncSSH will understand localnetwork, a setting to control strictness on unknown directives would no longer apply. I'm not sure I'd want it to, since that would prevent it from reporting that the "ifaddr" module needs to be installed.

I'm also not sure that it would ever make sense to have a "strict" mode that fails on all unknown directives, as there are a bunch of things in the OpenSSH config that really don't make sense to support in AsyncSSH. So, it's highly likely that parsing in strict mode there would cause failures with anything but trivial SSH config files.

That leaves doing something specific to unknown Match types, but that seems rather narrow. It would also only be useful for future match types that AsyncSSH hasn't added yet.

[ronf]

A slightly more polished version of this is now available in the "develop" branch as commit 0ffefb4, with a unit test and some changes to the project metadata and README to reflect the new "ifaddr" dependency. Let me know if you have any problems with it.

Thanks again for reporting that this was missing!