feat: add support for multiple proxy jumps

Author: samidalouche

docs/concepts.md

@@ -70,7 +70,7 @@ To be considered active, a local volume must have a `.nbkp-vol` file in the root
 A reusable configuration for an SSH server that can be shared between multiple remote volumes.
 Provides the host, port, user, key, structured connection options, and optional proxy-jump.
 
-The `proxy-jump` field references another ssh-endpoint by slug, enabling connections through a bastion/jump host. This maps to SSH's `-J` flag and Fabric's `gateway` parameter. Circular proxy-jump chains are detected and rejected at config load time.
+The `proxy-jump` field references another ssh-endpoint by slug, enabling connections through a bastion/jump host. For multi-hop chains, use `proxy-jumps` (a list of endpoint slugs); the two fields are mutually exclusive. Both map to SSH's `-J` flag (comma-separated) and Fabric's nested `gateway` parameter. Circular proxy-jump chains are detected and rejected at config load time.
 
 The `location` field declares which network location this endpoint is accessible from (e.g. `home`, `office`, `travel`). Used with the `--location` CLI option for endpoint selection (see [Endpoint Filtering](#endpoint-filtering)).
 

nbkp/check.py

@@ -115,7 +115,7 @@ def _check_remote_volume(
     ep = resolved_endpoints[volume.slug]
     marker_path = f"{volume.path}/.nbkp-vol"
     result = run_remote_command(
-        ep.server, ["test", "-f", marker_path], ep.proxy
+        ep.server, ["test", "-f", marker_path], ep.proxy_chain
     )
     reasons: list[VolumeReason] = (
         [] if result.returncode == 0 else [VolumeReason.UNREACHABLE]
@@ -145,7 +145,7 @@ def _check_endpoint_marker(
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
             result = run_remote_command(
-                ep.server, ["test", "-f", rel_path], ep.proxy
+                ep.server, ["test", "-f", rel_path], ep.proxy_chain
             )
             return result.returncode == 0
 
@@ -162,7 +162,7 @@ def _check_command_available(
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
             result = run_remote_command(
-                ep.server, ["which", command], ep.proxy
+                ep.server, ["which", command], ep.proxy_chain
             )
             return result.returncode == 0
 
@@ -182,7 +182,7 @@ def _check_btrfs_filesystem(
             )
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
-            result = run_remote_command(ep.server, cmd, ep.proxy)
+            result = run_remote_command(ep.server, cmd, ep.proxy_chain)
     return result.returncode == 0 and result.stdout.strip() == "btrfs"
 
 
@@ -207,7 +207,7 @@ def _check_hardlink_support(
             )
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
-            result = run_remote_command(ep.server, cmd, ep.proxy)
+            result = run_remote_command(ep.server, cmd, ep.proxy_chain)
     if result.returncode != 0:
         return True  # Cannot determine; assume supported
     fs_type = result.stdout.strip()
@@ -234,7 +234,7 @@ def _check_directory_exists(
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
             result = run_remote_command(
-                ep.server, ["test", "-d", path], ep.proxy
+                ep.server, ["test", "-d", path], ep.proxy_chain
             )
             return result.returncode == 0
 
@@ -259,7 +259,7 @@ def _check_btrfs_subvolume(
             )
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
-            result = run_remote_command(ep.server, cmd, ep.proxy)
+            result = run_remote_command(ep.server, cmd, ep.proxy_chain)
     return result.returncode == 0 and result.stdout.strip() == "256"
 
 
@@ -279,7 +279,7 @@ def _check_btrfs_mount_option(
             )
         case RemoteVolume():
             ep = resolved_endpoints[volume.slug]
-            result = run_remote_command(ep.server, cmd, ep.proxy)
+            result = run_remote_command(ep.server, cmd, ep.proxy_chain)
     if result.returncode != 0:
         return False
     options = result.stdout.strip().split(",")

nbkp/config/protocol.py

@@ -105,9 +105,28 @@ class SshEndpoint(_BaseModel):
         default_factory=lambda: SshConnectionOptions()
     )
     proxy_jump: Optional[str] = None
+    proxy_jumps: Optional[List[str]] = None
     location: Optional[str] = None
     extends: Optional[str] = None
 
+    @model_validator(mode="after")
+    def validate_proxy_exclusivity(self) -> SshEndpoint:
+        if self.proxy_jump is not None and self.proxy_jumps is not None:
+            raise ValueError(
+                "proxy-jump and proxy-jumps are mutually exclusive"
+            )
+        return self
+
+    @property
+    def proxy_jump_chain(self) -> list[str]:
+        """Return the proxy-jump chain as a list of slugs."""
+        if self.proxy_jumps is not None:
+            return list(self.proxy_jumps)
+        elif self.proxy_jump is not None:
+            return [self.proxy_jump]
+        else:
+            return []
+
 
 class RemoteVolume(_BaseModel):
     model_config = ConfigDict(frozen=True)
@@ -265,6 +284,13 @@ def _resolve(slug: str, chain: list[str]) -> Any:
                 **parent,
                 **{k: v for k, v in ep.items() if k != "extends"},
             }
+            # If child sets proxy-jump or proxy-jumps, remove
+            # the other to avoid exclusivity clash with parent
+            proxy_keys = {"proxy-jump", "proxy-jumps"}
+            child_proxy_keys = proxy_keys & set(ep.keys())
+            if child_proxy_keys:
+                for k in proxy_keys - child_proxy_keys:
+                    merged.pop(k, None)
             resolved[slug] = merged
             return merged
 
@@ -379,34 +405,35 @@ def resolve_endpoint_for_volume(
         # Deterministic pick: first candidate in original order
         return self.ssh_endpoints[reachable[0]]
 
-    def resolve_proxy(self, server: SshEndpoint) -> SshEndpoint | None:
-        """Resolve the proxy-jump server, if any."""
-        if server.proxy_jump is not None:
-            return self.ssh_endpoints[server.proxy_jump]
-        else:
-            return None
+    def resolve_proxy_chain(self, server: SshEndpoint) -> list[SshEndpoint]:
+        """Resolve the proxy-jump chain as a list of SshEndpoints."""
+        return [self.ssh_endpoints[slug] for slug in server.proxy_jump_chain]
 
     @model_validator(mode="after")
     def validate_cross_references(self) -> Config:
         for slug, server in self.ssh_endpoints.items():
-            if server.proxy_jump is not None:
-                if server.proxy_jump not in self.ssh_endpoints:
+            chain = server.proxy_jump_chain
+            for hop in chain:
+                if hop not in self.ssh_endpoints:
                     raise ValueError(
                         f"Server '{slug}' references "
                         f"unknown proxy-jump server "
-                        f"'{server.proxy_jump}'"
+                        f"'{hop}'"
                     )
-                visited: set[str] = {slug}
-                current: str | None = server.proxy_jump
-                while current is not None:
-                    if current in visited:
-                        raise ValueError(
-                            f"Circular proxy-jump chain "
-                            f"detected starting from "
-                            f"server '{slug}'"
-                        )
-                    visited.add(current)
-                    current = self.ssh_endpoints[current].proxy_jump
+            # Circular detection via BFS through transitive
+            # proxy chains
+            visited: set[str] = {slug}
+            queue = list(chain)
+            while queue:
+                current = queue.pop(0)
+                if current in visited:
+                    raise ValueError(
+                        f"Circular proxy-jump chain "
+                        f"detected starting from "
+                        f"server '{slug}'"
+                    )
+                visited.add(current)
+                queue.extend(self.ssh_endpoints[current].proxy_jump_chain)
 
         for vol_slug, vol in self.volumes.items():
             match vol:

nbkp/config/resolution.py

@@ -4,6 +4,8 @@
 
 from pydantic import ConfigDict
 
+from pydantic import Field
+
 from .protocol import (
     Config,
     EndpointFilter,
@@ -14,11 +16,11 @@
 
 
 class ResolvedEndpoint(_BaseModel):
-    """Pre-resolved SSH endpoint with optional proxy."""
+    """Pre-resolved SSH endpoint with proxy chain."""
 
     model_config = ConfigDict(frozen=True)
     server: SshEndpoint
-    proxy: SshEndpoint | None = None
+    proxy_chain: list[SshEndpoint] = Field(default_factory=list)
 
 
 ResolvedEndpoints = dict[str, ResolvedEndpoint]
@@ -40,9 +42,9 @@ def resolve_all_endpoints(
                 server = config.resolve_endpoint_for_volume(
                     vol, endpoint_filter
                 )
-                proxy = config.resolve_proxy(server)
+                proxy_chain = config.resolve_proxy_chain(server)
                 result[vol.slug] = ResolvedEndpoint(
                     server=server,
-                    proxy=proxy,
+                    proxy_chain=proxy_chain,
                 )
     return result

nbkp/output.py

@@ -25,6 +25,7 @@
 )
 from .sync import PruneResult, SyncResult
 from .check import SyncReason, SyncStatus, VolumeReason, VolumeStatus
+from .remote.ssh import format_proxy_jump_chain
 
 
 class OutputFormat(str, enum.Enum):
@@ -223,13 +224,18 @@ def print_human_prune_results(
     console.print(table)
 
 
-def _ssh_prefix(server: SshEndpoint) -> str:
+def _ssh_prefix(
+    server: SshEndpoint,
+    proxy_chain: list[SshEndpoint] | None = None,
+) -> str:
     """Build human-friendly SSH command prefix."""
     parts = ["ssh"]
     if server.port != 22:
         parts.extend(["-p", str(server.port)])
     if server.key:
         parts.extend(["-i", server.key])
+    if proxy_chain:
+        parts.extend(["-J", format_proxy_jump_chain(proxy_chain)])
     host = f"{server.user}@{server.host}" if server.user else server.host
     parts.append(host)
     return " ".join(parts)
@@ -246,7 +252,8 @@ def _wrap_cmd(
             return cmd
         case RemoteVolume():
             ep = resolved_endpoints[vol.slug]
-            return f"{_ssh_prefix(ep.server)} '{cmd}'"
+            prefix = _ssh_prefix(ep.server, ep.proxy_chain)
+            return f"{prefix} '{cmd}'"
 
 
 def _endpoint_path(
@@ -343,12 +350,17 @@ def _print_marker_fix(
 def _print_ssh_troubleshoot(
     console: Console,
     server: SshEndpoint,
+    proxy_chain: list[SshEndpoint] | None = None,
 ) -> None:
     """Print SSH connectivity troubleshooting instructions."""
     p2 = _INDENT * 2
     p3 = _INDENT * 3
-    ssh_cmd = _ssh_prefix(server)
+    ssh_cmd = _ssh_prefix(server, proxy_chain)
     port_flag = f"-p {server.port} " if server.port != 22 else ""
+    proxy_opt = ""
+    if proxy_chain:
+        jump_str = format_proxy_jump_chain(proxy_chain)
+        proxy_opt = f"-o ProxyJump={jump_str} "
     user_host = f"{server.user}@{server.host}" if server.user else server.host
     console.print(f"{p2}Server {server.host} is unreachable.")
     console.print(f"{p2}Verify connectivity:")
@@ -360,7 +372,8 @@ def _print_ssh_troubleshoot(
         console.print(f"{p3}2. Copy it to the server:")
         _print_cmd(
             console,
-            f"ssh-copy-id {port_flag}" f"-i {server.key} {user_host}",
+            f"ssh-copy-id {proxy_opt}{port_flag}"
+            f"-i {server.key} {user_host}",
             indent=4,
         )
     else:
@@ -369,7 +382,7 @@ def _print_ssh_troubleshoot(
         console.print(f"{p3}2. Copy it to the server:")
         _print_cmd(
             console,
-            f"ssh-copy-id {port_flag}{user_host}",
+            f"ssh-copy-id {proxy_opt}{port_flag}" f"{user_host}",
             indent=4,
         )
     console.print(f"{p3}3. Verify passwordless login:")
@@ -393,7 +406,11 @@ def _print_sync_reason_fix(
             match src:
                 case RemoteVolume():
                     ep = resolved_endpoints[src.slug]
-                    _print_ssh_troubleshoot(console, ep.server)
+                    _print_ssh_troubleshoot(
+                        console,
+                        ep.server,
+                        ep.proxy_chain,
+                    )
                 case LocalVolume():
                     console.print(
                         f"{p2}Source volume"
@@ -405,7 +422,11 @@ def _print_sync_reason_fix(
             match dst:
                 case RemoteVolume():
                     ep = resolved_endpoints[dst.slug]
-                    _print_ssh_troubleshoot(console, ep.server)
+                    _print_ssh_troubleshoot(
+                        console,
+                        ep.server,
+                        ep.proxy_chain,
+                    )
                 case LocalVolume():
                     console.print(
                         f"{p2}Destination volume"
@@ -566,7 +587,11 @@ def print_human_troubleshoot(
                     match vol:
                         case RemoteVolume():
                             ep = re[vol.slug]
-                            _print_ssh_troubleshoot(console, ep.server)
+                            _print_ssh_troubleshoot(
+                                console,
+                                ep.server,
+                                ep.proxy_chain,
+                            )
 
     for ss in failed_syncs:
         console.print(f"\n[bold]Sync {ss.slug!r}:[/bold]")
@@ -621,7 +646,7 @@ def print_human_config(
                 str(server.port),
                 server.user or "",
                 server.key or "",
-                server.proxy_jump or "",
+                ", ".join(server.proxy_jump_chain) or "",
                 server.location or "",
             )
 

nbkp/remote/fabricssh.py

@@ -14,11 +14,11 @@
 from .ssh import format_remote_path as format_remote_path  # noqa: F401
 
 
-def _build_connection(
+def _build_single_connection(
     server: SshEndpoint,
-    proxy_server: SshEndpoint | None = None,
+    gateway: Connection | None = None,
 ) -> Connection:
-    """Build a Fabric Connection from server config."""
+    """Build a single Fabric Connection with optional gateway."""
     opts = server.connection_options
     connect_kwargs: dict[str, object] = {
         "allow_agent": opts.allow_agent,
@@ -36,10 +36,6 @@ def _build_connection(
     if server.key:
         connect_kwargs["key_filename"] = server.key
 
-    gateway: Connection | None = None
-    if proxy_server is not None:
-        gateway = _build_connection(proxy_server)
-
     conn = Connection(
         host=server.host,
         port=server.port,
@@ -56,14 +52,25 @@ def _build_connection(
     return conn
 
 
+def _build_connection(
+    server: SshEndpoint,
+    proxy_chain: list[SshEndpoint] | None = None,
+) -> Connection:
+    """Build a Fabric Connection with optional proxy chain."""
+    gateway: Connection | None = None
+    for proxy in proxy_chain or []:
+        gateway = _build_single_connection(proxy, gateway)
+    return _build_single_connection(server, gateway)
+
+
 def run_remote_command(
     server: SshEndpoint,
     command: list[str],
-    proxy_server: SshEndpoint | None = None,
+    proxy_chain: list[SshEndpoint] | None = None,
 ) -> subprocess.CompletedProcess[str]:
     """Run a command on a remote host via Fabric."""
     cmd_string = " ".join(shlex.quote(arg) for arg in command)
-    with _build_connection(server, proxy_server) as conn:
+    with _build_connection(server, proxy_chain) as conn:
         if server.connection_options.server_alive_interval is not None:
             conn.transport.set_keepalive(
                 server.connection_options.server_alive_interval