You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/engine/virsh_panel/remote_host.py

2596 lines
107 KiB
Python

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""Pin and manage one remote libvirt host without exposing its root SSH key.
The panel runs under the local service account. Its OpenSSH user
configuration points at ``current/config``; ``current`` is an atomically
replaced symlink to a tested generation. Failed scans/tests never switch it.
"""
from __future__ import annotations
import base64
import binascii
import hashlib
import ipaddress
import json
import logging
import os
import re
import secrets
import shutil
import stat
import subprocess
import threading
import time
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Callable, Mapping
from urllib.parse import quote
from .network_roles import (
PRIVATE_INTERFACE_ROLE,
PRIVATE_LIBVIRT_ALIAS,
PUBLIC_INTERFACE_ROLE,
PUBLIC_LIBVIRT_ALIAS,
)
from .ssh_agent import SSHAgentError, SSHAgentSession
SSH_ALIAS = "vp-managed"
LIBVIRT_URI = f"qemu+ssh://root@{SSH_ALIAS}/system?no_tty=1"
_DNS_LABEL = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\Z")
_FINGERPRINT = re.compile(r"SHA256:[A-Za-z0-9+/]{43}\Z")
_KEY_HEADER = re.compile(r"-----BEGIN (?:OPENSSH |RSA |EC |DSA )?PRIVATE KEY-----\Z")
_GEN_NAME = re.compile(r"gen-[0-9a-f]{32}\Z")
_POOL_PATH = re.compile(r"/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*\Z")
_BRIDGE_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,14}\Z")
_IFACE_NAME = re.compile(r"[A-Za-z0-9_.:-]{1,15}\Z")
PUBLIC_POOL_KEY = re.compile(r"[0-9a-f]{32}\Z")
PUBLIC_POOL_STATES = frozenset({"active", "draining", "disabled"})
MAX_PUBLIC_NETWORK_POOLS = 32
HOST_CAPABILITY_SCHEMA_VERSION = 5
WG_FABRIC_INTERFACE = "wg-fabric0"
WG_FABRIC_OWNERSHIP_MARKER = "virt-cloud-wg-fabric-v1"
_MAX_CAPABILITY_OUTPUT = 262144
_CAPABILITY_MARKER = "__VIRT_CLOUD_HOST_CAPABILITIES_V1__"
# Keep this command literal and independent of every value supplied by an
# administrator. The remote shell is used only to run this fixed probe; no
# selector, path, peer, or other request data is interpolated into it. The
# probe is deliberately read-only: it never installs packages, loads modules,
# changes links, or rewrites a firewall. AlmaLinux and Debian place the
# utilities in slightly different directories, so each known path is checked
# explicitly instead of using PATH or ``command -v``.
_CAPABILITY_PROBE_COMMAND = r'''/bin/sh -c '
set +e
printf "%s\n" "__VIRT_CLOUD_HOST_CAPABILITIES_V1__"
printf "%s\n" "__VCAP_OS_BEGIN__"
/usr/bin/cat /etc/os-release 2>/dev/null || /bin/cat /etc/os-release 2>/dev/null
printf "%s\n" "__VCAP_OS_END__"
printf "%s\n" "__VCAP_KERNEL_BEGIN__"
/usr/bin/uname -r 2>/dev/null || /bin/uname -r 2>/dev/null
printf "%s\n" "__VCAP_KERNEL_END__"
capability_ip_path=
capability_nft_path=
capability_modinfo_path=
probe_binary() {
name="$1"
shift
for path in "$@"; do
if test -x "$path"; then
case "$name" in
ip) capability_ip_path="$path" ;;
nft) capability_nft_path="$path" ;;
modinfo) capability_modinfo_path="$path" ;;
esac
printf "__VCAP_TOOL__%s=%s\n" "$name" "$path"
return 0
fi
done
printf "__VCAP_TOOL__%s=\n" "$name"
return 1
}
probe_binary wg /usr/bin/wg /usr/sbin/wg /bin/wg /sbin/wg
probe_binary wg_quick /usr/bin/wg-quick /usr/sbin/wg-quick /bin/wg-quick /sbin/wg-quick
probe_binary ip /usr/sbin/ip /usr/bin/ip /sbin/ip /bin/ip
probe_binary nft /usr/sbin/nft /usr/bin/nft /sbin/nft /bin/nft
probe_binary nmcli /usr/bin/nmcli /usr/sbin/nmcli /bin/nmcli /sbin/nmcli
probe_binary networkctl /usr/bin/networkctl /usr/sbin/networkctl /bin/networkctl /sbin/networkctl
probe_binary ifup /usr/sbin/ifup /usr/bin/ifup /sbin/ifup /bin/ifup
probe_binary ifdown /usr/sbin/ifdown /usr/bin/ifdown /sbin/ifdown /bin/ifdown
probe_binary ifquery /usr/sbin/ifquery /usr/bin/ifquery /sbin/ifquery /bin/ifquery
probe_binary ifreload /usr/sbin/ifreload /usr/bin/ifreload /sbin/ifreload /bin/ifreload
probe_binary flock /usr/bin/flock /usr/sbin/flock /bin/flock /sbin/flock
probe_binary systemctl /usr/bin/systemctl /usr/sbin/systemctl /bin/systemctl /sbin/systemctl
probe_binary modinfo /usr/sbin/modinfo /usr/bin/modinfo /sbin/modinfo /bin/modinfo
probe_binary dnf /usr/bin/dnf /usr/sbin/dnf /bin/dnf /sbin/dnf /usr/bin/dnf5 /usr/sbin/dnf5
probe_binary apt_get /usr/bin/apt-get /usr/sbin/apt-get /bin/apt-get /sbin/apt-get
if test -e /sys/module/wireguard; then
printf "%s\n" "__VCAP_MODULE__wireguard=loaded"
else
printf "%s\n" "__VCAP_MODULE__wireguard=not_loaded"
fi
printf "%s\n" "__VCAP_MODULE_FILE_BEGIN__"
if test -n "$capability_modinfo_path" &&
test -x "$capability_modinfo_path"; then
"$capability_modinfo_path" -F filename wireguard 2>/dev/null
else
printf "%s\n" ""
fi
printf "%s\n" "__VCAP_MODULE_FILE_END__"
printf "%s\n" "__VCAP_FABRIC_OWNER_BEGIN__"
if test -f /etc/virt-cloud/wg-fabric0.owner; then
/usr/bin/cat /etc/virt-cloud/wg-fabric0.owner 2>/dev/null || /bin/cat /etc/virt-cloud/wg-fabric0.owner 2>/dev/null
fi
printf "%s\n" "__VCAP_FABRIC_OWNER_END__"
probe_sysctl() {
name="$1"
key="$2"
value=""
if test -x /usr/sbin/sysctl; then
value=$(/usr/sbin/sysctl -n "$key" 2>/dev/null)
elif test -x /usr/bin/sysctl; then
value=$(/usr/bin/sysctl -n "$key" 2>/dev/null)
fi
printf "__VCAP_SYSCTL__%s=%s\n" "$name" "$value"
}
probe_sysctl ip_forward net.ipv4.ip_forward
probe_sysctl rp_filter net.ipv4.conf.all.rp_filter
probe_sysctl rp_filter_default net.ipv4.conf.default.rp_filter
# Linux computes the effective reverse-path policy as the maximum of the
# global and per-interface values (and uses ``default`` to initialize future
# interfaces). Read every bounded interface file so the panel can explain
# the effective policy for the selected underlay and an existing Fabric link.
for rp_file in /proc/sys/net/ipv4/conf/*/rp_filter; do
test -f "$rp_file" || continue
rp_iface=${rp_file%/rp_filter}
rp_iface=${rp_iface##*/}
case "$rp_iface" in
""|*[!A-Za-z0-9_.:-]*) continue ;;
esac
if test -x /usr/bin/cat; then
rp_value=$(/usr/bin/cat "$rp_file" 2>/dev/null)
else
rp_value=$(/bin/cat "$rp_file" 2>/dev/null)
fi
printf "__VCAP_RPF__%s=%s\n" "$rp_iface" "$rp_value"
done
probe_service() {
name="$1"
service="$2"
status="unknown"
if test -x /usr/bin/systemctl; then
status=$(/usr/bin/systemctl is-active "$service" 2>/dev/null)
elif test -x /bin/systemctl; then
status=$(/bin/systemctl is-active "$service" 2>/dev/null)
fi
case "$status" in
active|inactive|failed|activating|deactivating) ;;
*) status="unknown" ;;
esac
printf "__VCAP_SERVICE__%s=%s\n" "$name" "$status"
}
probe_service network_manager NetworkManager
probe_service networkd systemd-networkd
probe_service networking networking
probe_service firewall firewalld
probe_service nftables nftables
probe_service_enabled() {
name="$1"
service="$2"
status="unknown"
if test -x /usr/bin/systemctl; then
status=$(/usr/bin/systemctl is-enabled "$service" 2>/dev/null)
elif test -x /bin/systemctl; then
status=$(/bin/systemctl is-enabled "$service" 2>/dev/null)
fi
case "$status" in
enabled|enabled-runtime|disabled|static|indirect|masked|generated|transient|\
alias|linked|linked-runtime) ;;
*) status="unknown" ;;
esac
printf "__VCAP_SERVICE_ENABLED__%s=%s\n" "$name" "$status"
}
probe_service_enabled network_manager NetworkManager
probe_service_enabled networkd systemd-networkd
probe_service_enabled networking networking
probe_service_enabled firewall firewalld
probe_service_enabled nftables nftables
probe_service_load() {
name="$1"
service="$2"
status=unknown
if test -x /usr/bin/systemctl; then
status=$(/usr/bin/systemctl show -p LoadState --value "$service" 2>/dev/null)
elif test -x /bin/systemctl; then
status=$(/bin/systemctl show -p LoadState --value "$service" 2>/dev/null)
fi
case "$status" in loaded|not-found|masked) ;; *) status=unknown ;; esac
printf "__VCAP_SERVICE_LOAD__%s=%s\n" "$name" "$status"
}
probe_service_load firewall firewalld
probe_service_load nftables nftables
# Native nftables is the only supported firewall owner. firewalld service
# state remains in the probe solely as fail-closed migration evidence.
probe_legacy_firewall_path() {
name="$1"
path="$2"
state=absent
if test -e "$path" || test -L "$path"; then state=present; fi
printf "__VCAP_LEGACY_FIREWALL__%s=%s\n" "$name" "$state"
}
probe_legacy_firewall_path manifest /etc/virt-cloud/nftables.conf
probe_legacy_firewall_path fabric_transaction /etc/virt-cloud/.wg-fabric-txn
probe_legacy_firewall_path emergency_owner /run/virt-cloud/wg-fabric-emergency.owner
vpc_transaction_state=absent
for vpc_transaction in /etc/virt-cloud/.vpc-dataplane-*.txn; do
if test -e "$vpc_transaction" || test -L "$vpc_transaction"; then
vpc_transaction_state=present
break
fi
done
printf "__VCAP_LEGACY_FIREWALL__vpc_transaction=%s\n" \
"$vpc_transaction_state"
vpc_snapshot_state=absent
for vpc_snapshot in \
/etc/virt-cloud/vpc-dataplane/*.nft.inet.live \
/etc/virt-cloud/vpc-dataplane/*.nft.bridge.live \
/etc/virt-cloud/vpc-dataplane/*.nft.arp.live; do
if test -e "$vpc_snapshot" || test -L "$vpc_snapshot"; then
vpc_snapshot_state=present
break
fi
done
printf "__VCAP_LEGACY_FIREWALL__vpc_snapshot=%s\n" \
"$vpc_snapshot_state"
legacy_stat=
for legacy_tool in /usr/bin/stat /bin/stat /usr/sbin/stat /sbin/stat; do
if test -x "$legacy_tool"; then legacy_stat="$legacy_tool"; break; fi
done
nft_main_seen=0
nft_main_ready=0
for nft_main in /etc/nftables.conf /etc/sysconfig/nftables.conf; do
if test -e "$nft_main" || test -L "$nft_main"; then
nft_main_seen=$((nft_main_seen + 1))
fi
if test -n "$legacy_stat" && test -f "$nft_main" &&
! test -L "$nft_main" &&
test "$("$legacy_stat" -c "%u" "$nft_main" 2>/dev/null)" = 0; then
nft_main_mode=$("$legacy_stat" -c "%a" "$nft_main" 2>/dev/null)
case "$nft_main_mode" in
[0-7][0145][0145]) nft_main_ready=$((nft_main_ready + 1)) ;;
esac
fi
done
if test "$nft_main_ready" = 1; then
nft_main_state=ready
elif test "$nft_main_ready" -gt 1; then
nft_main_state=conflict
elif test "$nft_main_seen" = 0; then
nft_main_state=missing
else
nft_main_state=unsafe
fi
printf "__VCAP_NFT_PERSISTENCE__main=%s\n" "$nft_main_state"
legacy_awk=
for legacy_tool in /usr/bin/awk /bin/awk /usr/sbin/awk /sbin/awk; do
if test -x "$legacy_tool"; then legacy_awk="$legacy_tool"; break; fi
done
fabric_desired_state_legacy=absent
fabric_desired_state=/etc/virt-cloud/wg-fabric0.conf
if test -e "$fabric_desired_state" || test -L "$fabric_desired_state"; then
fabric_desired_state_legacy=unknown
if test -n "$legacy_stat" && test -n "$legacy_awk" &&
test -f "$fabric_desired_state" && ! test -L "$fabric_desired_state" &&
test "$("$legacy_stat" -c "%u:%g:%a" "$fabric_desired_state" 2>/dev/null)" = 0:0:600; then
fabric_desired_size=$("$legacy_stat" -c "%s" "$fabric_desired_state" 2>/dev/null)
case "$fabric_desired_size" in
""|*[!0-9]*) ;;
*)
if test "$fabric_desired_size" -le 65536 2>/dev/null; then
fabric_desired_state_legacy=$("$legacy_awk" -F"|" "
length(\$0)>4096 {unsafe=1}
\$1==\"firewall\" {firewall++; if (NF!=2 || \$2!=\"native_nftables\") legacy=1; next}
\$1==\"underlay\" || \$1==\"firewall_rule\" {legacy=1; next}
END {
if (legacy) print \"present\"
else if (unsafe || firewall>1) print \"unknown\"
else print \"absent\"
}
" "$fabric_desired_state" 2>/dev/null) || fabric_desired_state_legacy=unknown
fi ;;
esac
fi
fi
printf "__VCAP_LEGACY_FIREWALL__fabric_desired_state=%s\n" \
"$fabric_desired_state_legacy"
vpc_state_legacy=absent
vpc_state_count=0
for vpc_state_file in /etc/virt-cloud/vpc-dataplane/*.state; do
test -e "$vpc_state_file" || test -L "$vpc_state_file" || continue
vpc_state_count=$((vpc_state_count + 1))
if test "$vpc_state_count" -gt 256 || test -z "$legacy_stat" ||
test -z "$legacy_awk" || ! test -f "$vpc_state_file" ||
test -L "$vpc_state_file" ||
! test "$("$legacy_stat" -c "%u:%g:%a" "$vpc_state_file" 2>/dev/null)" = 0:0:600; then
vpc_state_legacy=unknown
break
fi
vpc_state_size=$("$legacy_stat" -c "%s" "$vpc_state_file" 2>/dev/null)
case "$vpc_state_size" in
""|*[!0-9]*) vpc_state_legacy=unknown; break ;;
esac
if ! test "$vpc_state_size" -le 65536 2>/dev/null; then
vpc_state_legacy=unknown
break
fi
vpc_state_result=$("$legacy_awk" -F"|" "
length(\$0)>4096 {unsafe=1}
\$1==\"firewall_mode\" {firewall++; if (NF!=2 || \$2!=\"native_nftables\") legacy=1; next}
\$1==\"nft_snapshot\" {legacy=1; next}
END {
if (legacy) print \"present\"
else if (unsafe || firewall>1) print \"unknown\"
else print \"absent\"
}
" "$vpc_state_file" 2>/dev/null) || vpc_state_result=unknown
case "$vpc_state_result" in
present) vpc_state_legacy=present; break ;;
absent) : ;;
*) vpc_state_legacy=unknown; break ;;
esac
done
printf "__VCAP_LEGACY_FIREWALL__vpc_state=%s\n" "$vpc_state_legacy"
# ifupdown ownership is represented by bounded facts only. The contents of
# interfaces files can include addresses, credentials, and arbitrary hooks;
# never return those contents through the capability endpoint.
if test -f /etc/network/interfaces; then
printf "%s\n" "__VCAP_FILE__interfaces=present"
else
printf "%s\n" "__VCAP_FILE__interfaces=absent"
fi
interfaces_d_configured=absent
if test -d /etc/network/interfaces.d; then
for interfaces_file in /etc/network/interfaces.d/*; do
if test -f "$interfaces_file"; then
interfaces_d_configured=present
break
fi
done
fi
printf "%s\n" "__VCAP_FILE__interfaces_d=$interfaces_d_configured"
interfaces_d_loaded=absent
if test -f /etc/network/interfaces &&
/usr/bin/grep -Eq "^[[:space:]]*(source|source-directory)[[:space:]]+/etc/network/interfaces[.]d" /etc/network/interfaces 2>/dev/null; then
interfaces_d_loaded=present
elif test -f /etc/network/interfaces &&
/bin/grep -Eq "^[[:space:]]*(source|source-directory)[[:space:]]+/etc/network/interfaces[.]d" /etc/network/interfaces 2>/dev/null; then
interfaces_d_loaded=present
fi
printf "%s\n" "__VCAP_FILE__interfaces_d_loaded=$interfaces_d_loaded"
# A disabled manager can still take over on the next restart when it has
# persistent profiles. Return presence markers only; profile contents may
# contain secrets and arbitrary operator configuration.
probe_config_files() {
name="$1"
shift
configured=absent
for config_pattern in "$@"; do
for config_file in $config_pattern; do
if test -f "$config_file"; then
configured=present
break 2
fi
done
done
printf "%s\n" "__VCAP_FILE__${name}=$configured"
}
probe_config_files networkmanager_profiles \
/etc/NetworkManager/system-connections/* \
/run/NetworkManager/system-connections/*
probe_config_files networkd_configs \
/etc/systemd/network/*.network /etc/systemd/network/*.netdev \
/etc/systemd/network/*.network.d/* \
/run/systemd/network/*.network /run/systemd/network/*.netdev \
/run/systemd/network/*.network.d/*
probe_ip_json() {
name="$1"
shift
printf "__VCAP_IP_BEGIN__%s\n" "$name"
status=127
if test -n "$capability_ip_path" && test -x "$capability_ip_path"; then
"$capability_ip_path" "$@" 2>/dev/null
status=$?
fi
printf "__VCAP_IP_END__%s=%s\n" "$name" "$status"
}
probe_ip_json links -j -d link show
# Fabric may use an operator-selected private underlay address instead of the
# SSH management address. Return only bounded iproute2 JSON inventory; the
# parser below projects normalized IPv4 literals and never exposes labels or
# other arbitrary interface metadata.
probe_ip_json addresses -j -4 address show up scope global
# Keep bridge discovery compatible with the iproute2 versions shipped by the
# two supported distributions; ``-d`` is unnecessary for this selector and is
# rejected by some older builds.
probe_ip_json bridges -j link show type bridge
probe_ip_json wireguard -j -d link show type wireguard
printf "%s\n" "__VCAP_NFT_BEGIN__"
status=127
if test -n "$capability_nft_path" && test -x "$capability_nft_path"; then
"$capability_nft_path" -j list tables 2>/dev/null
status=$?
fi
printf "__VCAP_NFT_END__%s\n" "$status"
printf "%s\n" "__VCAP_END__"
' '''
_RUNNER = Callable[..., subprocess.CompletedProcess[str]]
LOG = logging.getLogger(__name__)
def _uri_for_generation(path: Path) -> str:
command = quote(str(path / "ssh-wrapper"), safe="/")
return f"{LIBVIRT_URI}&command={command}"
class RemoteHostError(Exception):
"""A safe, user-facing connection/configuration error."""
def __init__(
self,
message: str,
status: int = 400,
error_code: str = "host_configuration_invalid",
) -> None:
super().__init__(message)
self.status = status
self.error_code = error_code
@dataclass(frozen=True)
class HostProfile:
host: str
port: int
private_key: str = field(repr=False)
host_key: str = field(repr=False)
private_key_passphrase: str = field(default="", repr=False)
storage_pool: str = "default"
iso_pool: str = "iso"
rescue_iso_pool: str = ""
default_network: str = "default"
region: str = ""
fabric_endpoint_ip: str = ""
public_pool_cidr: str = ""
public_gateway: str = ""
public_dns_servers: list[str] = field(default_factory=list)
public_reserved_ips: list[str] = field(default_factory=list)
public_vm_prefix: int | None = None
@dataclass
class StagedHost:
path: Path
metadata: dict[str, Any]
tested: bool = False
@property
def ssh_config_file(self) -> str:
return str(self.path / "config")
@property
def ssh_known_hosts_file(self) -> str:
return str(self.path / "known_hosts")
@property
def ssh_target(self) -> str:
return SSH_ALIAS
@property
def libvirt_uri(self) -> str:
# libvirt's ssh transport accepts ``command=`` as the executable to
# launch. The staged wrapper inserts -F so libvirt can be tested with
# the candidate config before the active ~/.ssh/config is switched.
return _uri_for_generation(self.path)
def _validate_host(host: str) -> str:
if not isinstance(host, str) or not host or len(host) > 253 or host != host.strip():
raise RemoteHostError("宿主机地址格式无效")
try:
ipaddress.ip_address(host)
return host
except ValueError:
pass
if not all(_DNS_LABEL.fullmatch(label) for label in host.split(".")):
raise RemoteHostError("宿主机地址必须是 IP 或 DNS 名称")
return host.lower()
def _validate_port(port: int) -> int:
if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
raise RemoteHostError("SSH 端口必须介于 1 到 65535")
return port
def _validate_name(value: str, label: str) -> str:
if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9_.-]{1,128}", value):
raise RemoteHostError(f"{label}名称格式无效")
if value.startswith("-") or value in {".", ".."}:
raise RemoteHostError(f"{label}名称格式无效")
return value
def _validate_pool_selector(value: str, label: str) -> str:
if isinstance(value, str) and value.startswith("/"):
if (
len(value) <= 4096
and _POOL_PATH.fullmatch(value)
and not any(part in {".", ".."} for part in value.split("/"))
):
return value
raise RemoteHostError(f"{label}必须是规范的绝对目录路径")
return _validate_name(value, label)
def _validate_network_selector(value: str) -> str:
if isinstance(value, str) and value.startswith("bridge:"):
if not _BRIDGE_NAME.fullmatch(value.removeprefix("bridge:")):
raise RemoteHostError("网桥名称格式无效;请填写 bridge:br0,网桥名最长 15 字符")
return value
return _validate_name(value, "网络")
def _validate_region(value: str) -> str:
# This is an operator-supplied display label, not a provider region ID.
if (not isinstance(value, str) or len(value) > 64 or value != value.strip()
or any(ord(char) < 32 or ord(char) == 127 for char in value)):
raise RemoteHostError("宿主机地区最多 64 字符,且不能包含控制字符或首尾空格")
return value
def _validate_fabric_endpoint_ip(value: str) -> str:
"""Validate an optional literal underlay address without DNS resolution."""
if value == "":
return ""
if (not isinstance(value, str) or value != value.strip()
or len(value) > 15):
raise RemoteHostError(
"Fabric 传输地址必须是安全的 IPv4 字面地址",
error_code="host_fabric_endpoint_invalid",
)
try:
address = ipaddress.IPv4Address(value)
except (ValueError, ipaddress.AddressValueError) as exc:
raise RemoteHostError(
"Fabric 传输地址必须是安全的 IPv4 字面地址",
error_code="host_fabric_endpoint_invalid",
) from exc
first, second = address.packed[:2]
if (first in {0, 127} or (first == 169 and second == 254)
or first >= 224):
raise RemoteHostError(
"Fabric 传输地址必须是安全的 IPv4 字面地址",
error_code="host_fabric_endpoint_invalid",
)
return str(address)
def _assert_fabric_endpoint_is_local(
profile: Mapping[str, Any],
capabilities: Mapping[str, Any],
) -> None:
"""Require fresh local-address evidence for an explicit underlay IP."""
endpoint = profile.get("fabric_endpoint_ip", "")
if endpoint == "":
return
network = capabilities.get("network")
addresses = (
network.get("local_ipv4_addresses")
if isinstance(network, Mapping) else None
)
if (not isinstance(addresses, list)
or endpoint not in addresses):
raise RemoteHostError(
"Fabric 传输地址不是宿主机当前本地 IPv4 地址",
error_code="host_fabric_endpoint_not_local",
)
def validate_public_pool(
public_pool_cidr: str,
public_gateway: str,
public_dns_servers: list[str],
public_reserved_ips: list[str],
host: str,
public_vm_prefix: int | None = None,
) -> dict[str, Any]:
"""Validate one host's public IPv4 pool without probing live network use.
The SSH host address is deliberately not persisted in the reserved list:
the allocator excludes a literal host IPv4 address while allocating, so
the operator can still distinguish explicit reservations from that rule.
A VM prefix override changes guest network configuration, never the set
of addresses this pool may allocate.
"""
if not isinstance(public_pool_cidr, str):
raise RemoteHostError(
"公网地址池格式无效",
error_code="host_public_pool_invalid",
)
if not isinstance(public_gateway, str):
raise RemoteHostError(
"公网网关格式无效",
error_code="host_public_gateway_invalid",
)
if not isinstance(public_dns_servers, (list, tuple)):
raise RemoteHostError(
"公网 DNS 必须是地址列表",
error_code="host_public_dns_invalid",
)
if not isinstance(public_reserved_ips, (list, tuple)):
raise RemoteHostError(
"保留 IP 必须是地址列表",
error_code="host_public_reserved_ip_invalid",
)
cidr = public_pool_cidr.strip()
gateway = public_gateway.strip()
dns_input = list(public_dns_servers)
reserved_input = list(public_reserved_ips)
if not any((cidr, gateway, dns_input, reserved_input)):
if public_vm_prefix is not None:
raise RemoteHostError(
"启用虚拟机网卡前缀前必须配置公网地址池",
error_code="host_vm_prefix_invalid",
)
return {
"public_pool_cidr": "",
"public_gateway": "",
"public_dns_servers": [],
"public_reserved_ips": [],
"public_vm_prefix": None,
}
if not cidr:
raise RemoteHostError(
"启用公网地址池时必须填写公网网段",
error_code="host_public_pool_invalid",
)
if not gateway:
raise RemoteHostError(
"启用公网地址池时必须填写公网网关",
error_code="host_public_gateway_invalid",
)
if not dns_input:
raise RemoteHostError(
"启用公网地址池时必须填写 DNS",
error_code="host_public_dns_invalid",
)
if len(reserved_input) > 254:
raise RemoteHostError(
"保留 IP 最多可填写 254 个地址",
error_code="host_public_reserved_ip_invalid",
)
try:
# Providers sometimes describe a routed block using its gateway (for
# example 123.123.123.113/28). Normalize that host/CIDR to its actual
# network before checking membership or allocating any addresses.
network = ipaddress.IPv4Network(cidr, strict=False)
except (ValueError, ipaddress.AddressValueError, ipaddress.NetmaskValueError) as exc:
raise RemoteHostError(
"公网地址池必须填写有效的 IPv4 地址/前缀",
error_code="host_public_pool_invalid",
) from exc
if (not 24 <= network.prefixlen <= 30
or not network.network_address.is_global
or not network.broadcast_address.is_global):
raise RemoteHostError(
"公网地址池必须是可路由的 IPv4 网段,前缀长度为 /24 至 /30",
error_code="host_public_pool_invalid",
)
if network.prefixlen == 24 and cidr.split("/", 1)[0] != str(network.network_address):
raise RemoteHostError(
"/24 地址池必须填写网段起始地址;如果实际只获配 /28,请填写 /28 而不是 /24",
error_code="host_public_pool_invalid",
)
if (public_vm_prefix is not None
and (isinstance(public_vm_prefix, bool)
or not isinstance(public_vm_prefix, int)
or not 24 <= public_vm_prefix <= network.prefixlen)):
raise RemoteHostError(
"虚拟机网卡前缀须介于 /24 和地址池前缀之间",
error_code="host_vm_prefix_invalid",
)
def parse_ipv4(value: str, label: str) -> ipaddress.IPv4Address:
error_code = {
"公网网关": "host_public_gateway_invalid",
"公网 DNS": "host_public_dns_invalid",
"保留 IP": "host_public_reserved_ip_invalid",
}.get(label, "host_public_pool_invalid")
if not isinstance(value, str) or not value or value != value.strip():
raise RemoteHostError(
f"{label}必须是 IPv4 地址",
error_code=error_code,
)
try:
return ipaddress.IPv4Address(value)
except (ValueError, ipaddress.AddressValueError) as exc:
raise RemoteHostError(
f"{label}必须是 IPv4 地址",
error_code=error_code,
) from exc
gateway_ip = parse_ipv4(gateway, "公网网关")
if gateway_ip not in network or gateway_ip in (
network.network_address, network.broadcast_address):
raise RemoteHostError(
"公网网关必须位于所配置的网段内",
error_code="host_public_gateway_invalid",
)
def unique_ips(values: list[str], label: str, *, in_pool: bool) -> list[str]:
normalized: list[str] = []
seen: set[str] = set()
for value in values:
address = parse_ipv4(value, label)
if in_pool:
if address not in network or address in (
network.network_address, network.broadcast_address):
raise RemoteHostError(
f"{label}必须位于所配置的网段内",
error_code="host_public_reserved_ip_invalid",
)
elif not address.is_global:
raise RemoteHostError(
f"{label}必须是可路由的公网 IPv4 地址",
error_code="host_public_dns_invalid",
)
address_text = str(address)
if address_text not in seen:
seen.add(address_text)
normalized.append(address_text)
return normalized
dns = unique_ips(dns_input, "公网 DNS", in_pool=False)
reserved = unique_ips(reserved_input, "保留 IP", in_pool=True)
if len(dns) > 4:
raise RemoteHostError(
"公网 DNS 最多可填写 4 个地址",
error_code="host_public_dns_invalid",
)
if not dns:
raise RemoteHostError(
"启用公网地址池时必须填写 DNS",
error_code="host_public_dns_invalid",
)
return {
"public_pool_cidr": str(network),
"public_gateway": str(gateway_ip),
"public_dns_servers": dns,
"public_reserved_ips": reserved,
"public_vm_prefix": public_vm_prefix,
}
def validate_public_network_pool(
value: Mapping[str, Any],
host: str,
*,
allow_legacy_key: bool = False,
) -> dict[str, Any]:
"""Validate one revisioned public pool stored outside the host profile.
The legacy host fields remain readable during the migration window, while
every new pool has a stable 32-character key. Keeping this normalization
beside :func:`validate_public_pool` ensures that host save, network
configuration, provisioning and restart-time restoration all enforce the same on-link
IPv4 constraints.
"""
if not isinstance(value, Mapping):
raise RemoteHostError(
"公网地址池配置必须是对象",
error_code="host_public_pool_invalid",
)
allowed = {
"pool_key", "revision", "state", "network_selector", "cidr",
"gateway", "dns_servers", "reserved_ips", "guest_prefix_length",
}
if set(value) - allowed:
raise RemoteHostError(
"公网地址池包含不支持的配置字段",
error_code="host_public_pool_invalid",
)
pool_key = value.get("pool_key")
if (not isinstance(pool_key, str)
or not (PUBLIC_POOL_KEY.fullmatch(pool_key)
or (allow_legacy_key and pool_key == "legacy-default"))):
raise RemoteHostError(
"公网地址池标识必须是 32 位小写十六进制",
error_code="host_public_pool_invalid",
)
revision = value.get("revision")
if (isinstance(revision, bool) or not isinstance(revision, int)
or not 1 <= revision <= (1 << 63) - 1):
raise RemoteHostError(
"公网地址池版本号无效",
error_code="host_public_pool_revision_invalid",
)
state = value.get("state")
if not isinstance(state, str) or state not in PUBLIC_POOL_STATES:
raise RemoteHostError(
"公网地址池状态无效",
error_code="host_public_pool_state_invalid",
)
network_selector = _validate_network_selector(value.get("network_selector"))
normalized = validate_public_pool(
value.get("cidr"),
value.get("gateway"),
value.get("dns_servers"),
value.get("reserved_ips"),
host,
value.get("guest_prefix_length"),
)
if not normalized["public_pool_cidr"]:
raise RemoteHostError(
"公网地址池不能是空配置",
error_code="host_public_pool_invalid",
)
return {
"pool_key": pool_key,
"revision": revision,
"state": state,
"network_selector": network_selector,
"cidr": normalized["public_pool_cidr"],
"gateway": normalized["public_gateway"],
"dns_servers": normalized["public_dns_servers"],
"reserved_ips": normalized["public_reserved_ips"],
"guest_prefix_length": (
normalized["public_vm_prefix"]
if normalized["public_vm_prefix"] is not None
else ipaddress.IPv4Network(normalized["public_pool_cidr"]).prefixlen
),
}
def validate_public_network_pools(
values: list[Mapping[str, Any]],
host: str,
*,
allow_legacy_key: bool = False,
) -> list[dict[str, Any]]:
"""Normalize a bounded, non-overlapping public-pool catalog."""
if not isinstance(values, list) or len(values) > MAX_PUBLIC_NETWORK_POOLS:
raise RemoteHostError(
f"一台宿主机最多配置 {MAX_PUBLIC_NETWORK_POOLS} 个公网地址池",
error_code="host_public_pool_invalid",
)
pools: list[dict[str, Any]] = []
keys: set[str] = set()
networks: list[tuple[str, ipaddress.IPv4Network]] = []
for value in values:
pool = validate_public_network_pool(
value, host, allow_legacy_key=allow_legacy_key)
if pool["pool_key"] in keys:
raise RemoteHostError(
"公网地址池标识重复",
error_code="host_public_pool_conflict",
)
network = ipaddress.IPv4Network(pool["cidr"], strict=True)
if any(network.overlaps(existing) for _key, existing in networks):
raise RemoteHostError(
"同一宿主机的公网地址池不能重叠",
error_code="host_public_pool_conflict",
)
keys.add(pool["pool_key"])
networks.append((pool["pool_key"], network))
pools.append(pool)
return sorted(pools, key=lambda item: item["pool_key"])
def _key_parts(line: str) -> tuple[str, str]:
if not isinstance(line, str) or len(line) > 4096 or any(c in line for c in "\r\n\x00"):
raise RemoteHostError("主机公钥格式无效")
fields = line.split()
if len(fields) == 2 and fields[0] == "ssh-ed25519":
key_type, encoded = fields
elif len(fields) == 3 and fields[1] == "ssh-ed25519":
key_type, encoded = fields[1:]
else:
raise RemoteHostError("目前只支持 Ed25519 SSH 主机公钥")
try:
blob = base64.b64decode(encoded, validate=True)
except (ValueError, binascii.Error) as exc:
raise RemoteHostError("主机公钥内容无效") from exc
if (
len(blob) != 51
or blob[:4] != b"\x00\x00\x00\x0b"
or blob[4:15] != b"ssh-ed25519"
or blob[15:19] != b"\x00\x00\x00\x20"
):
raise RemoteHostError("主机公钥内容无效")
return key_type, base64.b64encode(blob).decode("ascii")
def _fingerprint(key: str) -> str:
_key_type, encoded = _key_parts(key)
digest = hashlib.sha256(base64.b64decode(encoded)).digest()
return "SHA256:" + base64.b64encode(digest).decode("ascii").rstrip("=")
def _validate_private_key(value: str) -> bytes:
if not isinstance(value, str) or not 0 < len(value) <= 131072:
raise RemoteHostError(
"请提供现有 SSH 私钥,最大 128 KiB",
error_code="host_private_key_format_invalid",
)
value = value.replace("\r\n", "\n")
if "\x00" in value or "\r" in value:
raise RemoteHostError(
"SSH 私钥格式无效",
error_code="host_private_key_format_invalid",
)
header = value.split("\n", 1)[0]
if not _KEY_HEADER.fullmatch(header) or "-----END " not in value:
raise RemoteHostError(
"请提供 PEM 或 OpenSSH 格式的私钥",
error_code="host_private_key_format_invalid",
)
return (value.rstrip("\n") + "\n").encode("ascii", errors="strict")
def _write_private(path: Path, content: bytes) -> None:
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
descriptor = os.open(path, flags, 0o600)
try:
with os.fdopen(descriptor, "wb") as stream:
stream.write(content)
stream.flush()
os.fsync(stream.fileno())
except BaseException:
path.unlink(missing_ok=True)
raise
def _quoted_path(path: Path) -> str:
value = str(path)
if any(c in value for c in "\r\n\x00"):
raise RemoteHostError("面板数据路径包含不支持的字符")
return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
def _capability_section(output: str, begin: str, end: str) -> str | None:
"""Return one bounded probe section, or ``None`` for malformed output."""
start = output.find(begin)
if start < 0:
return None
start += len(begin)
finish = output.find(end, start)
if finish < 0 or finish - start > _MAX_CAPABILITY_OUTPUT:
return None
return output[start:finish]
def _capability_lines(output: str, prefix: str) -> dict[str, str]:
values: dict[str, str] = {}
for line in output.splitlines():
if not line.startswith(prefix):
continue
key, separator, value = line[len(prefix):].partition("=")
if (separator and re.fullmatch(r"[a-z_]{1,32}", key)
and len(value) <= 512):
values[key] = value
return values
def _capability_named_lines(output: str, prefix: str) -> dict[str, str]:
"""Parse bounded interface-name keyed probe lines."""
values: dict[str, str] = {}
for line in output.splitlines():
if not line.startswith(prefix):
continue
key, separator, value = line[len(prefix):].partition("=")
if (separator and re.fullmatch(r"[A-Za-z0-9_.:-]{1,15}", key)
and re.fullmatch(r"[0-9]+", value.strip())):
values[key] = value.strip()
return values
def _parse_os_release(section: str | None) -> dict[str, str]:
if section is None:
return {}
values: dict[str, str] = {}
for line in section.splitlines()[:128]:
key, separator, value = line.partition("=")
if (not separator or not re.fullmatch(r"[A-Z0-9_]{1,64}", key)
or len(value) > 512):
continue
value = value.strip()
if len(value) >= 2 and value[0] == value[-1] == '"':
value = value[1:-1].replace('\\"', '"').replace("\\\\", "\\")
elif len(value) >= 2 and value[0] == value[-1] == "'":
value = value[1:-1]
if "\x00" not in value and "\r" not in value and "\n" not in value:
values[key] = value
return values
def _parse_json_interfaces(section: str | None, status: str | None) -> list[str]:
if section is None or status != "0":
return []
try:
values = json.loads(section.strip())
except (TypeError, ValueError):
return []
if not isinstance(values, list) or len(values) > 4096:
return []
names: list[str] = []
for item in values:
if not isinstance(item, dict):
continue
name = item.get("ifname")
if isinstance(name, str) and _IFACE_NAME.fullmatch(name):
names.append(name)
return sorted(set(names))
def _valid_json_interfaces(
section: str | None,
status: str | None,
*,
allow_empty_placeholders: bool = False,
) -> bool:
"""Return whether an iproute2 JSON section is complete and well formed.
Debian 13's iproute2 6.15 emits one empty object per link when a typed
WireGuard query runs before that kernel module is loaded. Callers may
accept only those exact empty placeholders for that one known state;
every non-empty record still needs a valid interface name.
"""
if section is None or status != "0":
return False
try:
values = json.loads(section.strip())
except (TypeError, ValueError):
return False
if not isinstance(values, list) or len(values) > 4096:
return False
for item in values:
if allow_empty_placeholders and item == {}:
continue
if (not isinstance(item, dict)
or not isinstance(item.get("ifname"), str)
or _IFACE_NAME.fullmatch(item["ifname"]) is None):
return False
return True
def _parse_local_ipv4_addresses(
section: str | None,
status: str | None,
) -> tuple[bool, list[str], dict[str, list[str]]]:
"""Project a complete ``ip -j address`` response to IPv4 literals.
Interface labels and every other free-form field remain private. A
malformed record invalidates the whole section so a configured Fabric
endpoint can never be accepted from partial evidence.
"""
if section is None or status != "0":
return False, [], {}
try:
values = json.loads(section.strip())
except (TypeError, ValueError):
return False, [], {}
if not isinstance(values, list) or len(values) > 4096:
return False, [], {}
addresses: set[str] = set()
interfaces_by_address: dict[str, set[str]] = {}
address_count = 0
for item in values:
if (not isinstance(item, dict)
or not isinstance(item.get("ifname"), str)
or _IFACE_NAME.fullmatch(item["ifname"]) is None):
return False, [], {}
interface = item["ifname"]
address_info = item.get("addr_info")
if not isinstance(address_info, list) or len(address_info) > 4096:
return False, [], {}
address_count += len(address_info)
if address_count > 16384:
return False, [], {}
for record in address_info:
if not isinstance(record, dict):
return False, [], {}
family = record.get("family")
if not isinstance(family, str):
return False, [], {}
if family != "inet":
continue
raw_address = record.get("local")
if not isinstance(raw_address, str):
return False, [], {}
try:
address = ipaddress.IPv4Address(raw_address)
except (ValueError, ipaddress.AddressValueError):
return False, [], {}
normalized = str(address)
addresses.add(normalized)
interfaces_by_address.setdefault(normalized, set()).add(interface)
return (
True,
sorted(addresses, key=lambda value: ipaddress.IPv4Address(value)),
{
address: sorted(interfaces)
for address, interfaces in sorted(interfaces_by_address.items())
},
)
def _parse_integer(value: str | None) -> int | None:
if value is None or not re.fullmatch(r"[0-9]+", value.strip()):
return None
try:
return int(value.strip(), 10)
except ValueError:
return None
def _parse_nft_tables(
section: str | None,
status: str | None,
) -> tuple[bool, set[tuple[str, str]]]:
"""Parse the bounded native nft table inventory.
Table names are retained only to reject stale firewalld ownership and
retired emergency tables. The platform never reads or edits them.
"""
if section is None or status != "0":
return False, set()
try:
payload = json.loads(section.strip())
except (TypeError, ValueError):
return False, set()
if len(section) > _MAX_CAPABILITY_OUTPUT:
return False, set()
if isinstance(payload, dict):
records = payload.get("nftables")
elif isinstance(payload, list):
records = payload
else:
return False, set()
if not isinstance(records, list):
return False, set()
tables: set[tuple[str, str]] = set()
for record in records:
if not isinstance(record, dict):
return False, set()
table = record.get("table")
if table is None:
continue
if not isinstance(table, dict):
return False, set()
family = table.get("family")
name = table.get("name")
if not isinstance(family, str) or not isinstance(name, str):
return False, set()
tables.add((family, name))
return True, tables
def parse_host_capabilities(
output: str,
*,
public_network: str = "default",
) -> dict[str, Any]:
"""Parse the fixed remote probe into a fail-closed capability snapshot.
The returned object is a data contract for the future VPC/Fabric
reconciler. It is intentionally useful even when a command is missing:
``vpc_ready`` remains false and ``reasons`` names the missing evidence.
No raw command output is returned to callers.
"""
if not isinstance(output, str) or len(output) > _MAX_CAPABILITY_OUTPUT:
output = ""
required_sections = (
_CAPABILITY_MARKER,
"__VCAP_OS_BEGIN__\n", "__VCAP_OS_END__",
"__VCAP_KERNEL_BEGIN__\n", "__VCAP_KERNEL_END__",
"__VCAP_MODULE_FILE_BEGIN__\n", "__VCAP_MODULE_FILE_END__",
"__VCAP_FABRIC_OWNER_BEGIN__\n", "__VCAP_FABRIC_OWNER_END__",
"__VCAP_IP_BEGIN__links\n", "__VCAP_IP_END__links=",
"__VCAP_IP_BEGIN__addresses\n", "__VCAP_IP_END__addresses=",
"__VCAP_IP_BEGIN__bridges\n", "__VCAP_IP_END__bridges=",
"__VCAP_IP_BEGIN__wireguard\n", "__VCAP_IP_END__wireguard=",
"__VCAP_NFT_BEGIN__\n", "__VCAP_NFT_END__",
"__VCAP_NFT_PERSISTENCE__main=",
"__VCAP_SERVICE_LOAD__firewall=",
"__VCAP_SERVICE_LOAD__nftables=",
"__VCAP_LEGACY_FIREWALL__manifest=",
"__VCAP_LEGACY_FIREWALL__fabric_transaction=",
"__VCAP_LEGACY_FIREWALL__emergency_owner=",
"__VCAP_LEGACY_FIREWALL__vpc_transaction=",
"__VCAP_LEGACY_FIREWALL__vpc_snapshot=",
"__VCAP_LEGACY_FIREWALL__fabric_desired_state=",
"__VCAP_LEGACY_FIREWALL__vpc_state=",
"__VCAP_END__",
)
protocol_ok = all(section in output for section in required_sections)
os_values = _parse_os_release(
_capability_section(output, "__VCAP_OS_BEGIN__\n", "__VCAP_OS_END__"))
kernel_section = _capability_section(
output, "__VCAP_KERNEL_BEGIN__\n", "__VCAP_KERNEL_END__")
kernel = "" if kernel_section is None else kernel_section.strip()
tools = _capability_lines(output, "__VCAP_TOOL__")
modules = _capability_lines(output, "__VCAP_MODULE__")
sysctls = _capability_lines(output, "__VCAP_SYSCTL__")
services = _capability_lines(output, "__VCAP_SERVICE__")
service_enabled = _capability_lines(output, "__VCAP_SERVICE_ENABLED__")
service_load = _capability_lines(output, "__VCAP_SERVICE_LOAD__")
nft_persistence = _capability_lines(
output, "__VCAP_NFT_PERSISTENCE__")
legacy_firewall = _capability_lines(
output, "__VCAP_LEGACY_FIREWALL__")
files = _capability_lines(output, "__VCAP_FILE__")
rp_filter_interfaces = {
name: parsed for name, raw in _capability_named_lines(
output, "__VCAP_RPF__").items()
if (parsed := _parse_integer(raw)) is not None
}
ip_statuses: dict[str, str] = {}
ip_sections: dict[str, str | None] = {}
for name in ("links", "addresses", "bridges", "wireguard"):
begin = f"__VCAP_IP_BEGIN__{name}\n"
section_start = output.find(begin)
if section_start < 0:
ip_sections[name] = None
continue
section_start += len(begin)
end_prefix = f"__VCAP_IP_END__{name}="
end_start = output.find(end_prefix, section_start)
if end_start < 0 or end_start - section_start > _MAX_CAPABILITY_OUTPUT:
ip_sections[name] = None
continue
ip_sections[name] = output[section_start:end_start]
status_line = output[end_start:].splitlines()[0]
ip_statuses[name] = status_line[len(end_prefix):].strip()
nft_start = output.find("__VCAP_NFT_BEGIN__\n")
nft_end = output.find("__VCAP_NFT_END__", nft_start + 1)
nft_section: str | None = None
nft_status: str | None = None
if nft_start >= 0 and nft_end >= 0:
nft_start += len("__VCAP_NFT_BEGIN__\n")
if nft_end - nft_start <= _MAX_CAPABILITY_OUTPUT:
nft_section = output[nft_start:nft_end]
nft_status = output[nft_end + len("__VCAP_NFT_END__"):].splitlines()[0].strip()
bridge_names = _parse_json_interfaces(
ip_sections.get("bridges"), ip_statuses.get("bridges"))
wireguard_names = _parse_json_interfaces(
ip_sections.get("wireguard"), ip_statuses.get("wireguard"))
all_interfaces = _parse_json_interfaces(
ip_sections.get("links"), ip_statuses.get("links"))
addresses_valid, local_ipv4_addresses, local_ipv4_interfaces = (
_parse_local_ipv4_addresses(
ip_sections.get("addresses"), ip_statuses.get("addresses"))
)
ip_probe_valid = bool(
_valid_json_interfaces(
ip_sections.get("links"), ip_statuses.get("links"))
and _valid_json_interfaces(
ip_sections.get("bridges"), ip_statuses.get("bridges"))
and _valid_json_interfaces(
ip_sections.get("wireguard"), ip_statuses.get("wireguard"),
allow_empty_placeholders=(
modules.get("wireguard") == "not_loaded"),
)
and addresses_valid
)
tool_paths = {
name: value for name, value in tools.items()
if value and re.fullmatch(r"/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*", value)
}
tool_state = {
name: {"available": name in tool_paths, "path": tool_paths.get(name)}
for name in (
"wg", "wg_quick", "ip", "nft", "nmcli", "networkctl",
"ifup", "ifdown", "ifquery", "ifreload", "flock", "systemctl",
"modinfo", "dnf", "apt_get",
)
}
os_id = os_values.get("ID", "").lower()
version_id = os_values.get("VERSION_ID", "")
if os_id in {"almalinux", "rhel", "rocky", "centos"}:
family = "rhel"
package_manager = "dnf"
elif os_id in {"debian", "ubuntu"}:
family = "debian"
package_manager = "apt"
else:
family = "unknown"
package_manager = None
os_supported = family in {"rhel", "debian"}
package_tool = "dnf" if family == "rhel" else "apt_get" if family == "debian" else None
package_tool_ready = bool(package_tool and tool_state[package_tool]["available"])
# ``static``/``indirect``/``generated`` units can be present on a host
# without owning any links. Only states that cause a manager to start
# automatically count as takeover evidence; service readiness below may
# still accept a static ``networking.service`` when it is active.
manager_enabled_states = {"enabled", "enabled-runtime"}
service_ready_states = manager_enabled_states | {
"static", "indirect", "generated", "transient", "alias",
}
networkmanager_active = services.get("network_manager") == "active"
networkd_active = services.get("networkd") == "active"
networkmanager_enabled = service_enabled.get("network_manager") in manager_enabled_states
networkd_enabled = service_enabled.get("networkd") in manager_enabled_states
networkmanager_configured = files.get("networkmanager_profiles") == "present"
networkd_configured = files.get("networkd_configs") == "present"
networking_active = services.get("networking") in {"active", "activating"}
networking_enabled = service_enabled.get("networking") in service_ready_states
# The Fabric adapter uses ``ifquery`` for a bounded syntax/ownership
# check before calling ifup. Treat it as part of the supported contract;
# ifup/ifdown alone would make a host appear ready and then fail halfway
# through deployment.
ifupdown_tools_available = all(
tool_state[name]["available"]
for name in ("ifup", "ifdown", "ifquery")
)
ifupdown_configured = (
files.get("interfaces") == "present"
and (
files.get("interfaces_d") != "present"
or files.get("interfaces_d_loaded") == "present"
)
)
ifupdown_service_ready = networking_active or networking_enabled
# A configured interfaces file is ownership evidence even when the
# oneshot networking.service has already exited. A package's ifup/ifdown
# binaries alone are not ownership evidence: Alma hosts may carry the
# tools while NetworkManager remains authoritative. Require all three
# facts (tools, config, service state) before accepting ifupdown below.
ifupdown_detected = bool(ifupdown_configured or ifupdown_service_ready)
network_managers = {
# Enabled services are ownership evidence too: an inactive manager
# can still take the interface on the next boot. Treating it as
# absent would allow a second manager to be installed beside it.
"networkmanager": (
networkmanager_active or networkmanager_enabled
or networkmanager_configured
),
"systemd_networkd": (
networkd_active or networkd_enabled or networkd_configured
),
"ifupdown": ifupdown_detected,
}
active_network_managers = [name for name, active in network_managers.items() if active]
if len(active_network_managers) == 1:
network_manager = active_network_managers[0]
elif len(active_network_managers) > 1:
network_manager = "conflict"
else:
network_manager = "unknown"
if family == "rhel":
expected_network_manager = "networkmanager"
expected_deployment_mode = "networkmanager_nmcli"
elif family == "debian":
expected_network_manager = "ifupdown"
expected_deployment_mode = "ifupdown"
else:
expected_network_manager = None
expected_deployment_mode = None
manager_requirements_ready = False
if expected_network_manager == "networkmanager":
manager_requirements_ready = bool(
network_manager == "networkmanager"
and networkmanager_active
and networkmanager_enabled
and tool_state["nmcli"]["available"]
)
elif expected_network_manager == "ifupdown":
manager_requirements_ready = bool(
network_manager == "ifupdown"
and ifupdown_tools_available
and ifupdown_configured
and ifupdown_service_ready
)
network_manager_supported = bool(
expected_network_manager is not None
and network_manager == expected_network_manager
and manager_requirements_ready
)
if network_manager_supported:
network_deployment_mode = expected_deployment_mode
else:
network_deployment_mode = "unsupported"
firewalld_active = services.get("firewall") == "active"
nftables_active = services.get("nftables") == "active"
# Service state is retained as bounded diagnostic and conflict evidence.
# It is not native nftables capability evidence: the panel applies and
# restores its own tables directly through nft, while distro stock units
# may be inactive, disabled, masked, or absent.
firewalld_takeover_enabled = (
service_enabled.get("firewall") in manager_enabled_states)
nftables_takeover_enabled = (
service_enabled.get("nftables") in manager_enabled_states)
firewalld_enabled = service_enabled.get("firewall") == "enabled"
nftables_enabled = service_enabled.get("nftables") == "enabled"
firewalld_load = service_load.get("firewall", "unknown")
nftables_load = service_load.get("nftables", "unknown")
# ``disable`` only removes boot-time enablement. A D-Bus request or a
# systemd dependency may still activate the competing manager, so exclusive
# firewall ownership is proven only when the unit is absent or masked.
firewalld_cannot_take_over = bool(
firewalld_load == "not-found"
or (services.get("firewall") == "inactive"
and service_enabled.get("firewall") == "masked")
)
firewall_managers = {
# An enabled-but-currently-inactive service can take ownership after
# a reboot. Treat it as ownership evidence so Fabric never installs
# nft rules beside a firewalld instance that will start later.
"firewalld": firewalld_active or firewalld_takeover_enabled,
"nftables": nftables_active or nftables_takeover_enabled,
}
active_firewall_managers = [
name for name, active in firewall_managers.items() if active
]
ip_forward = _parse_integer(sysctls.get("ip_forward"))
rp_filter = _parse_integer(sysctls.get("rp_filter"))
rp_filter_default = _parse_integer(sysctls.get("rp_filter_default"))
module_loaded = modules.get("wireguard") == "loaded"
owner_section = _capability_section(
output, "__VCAP_FABRIC_OWNER_BEGIN__\n",
"__VCAP_FABRIC_OWNER_END__")
fabric_owner_marker = "" if owner_section is None else owner_section.strip()
fabric_owned = fabric_owner_marker == WG_FABRIC_OWNERSHIP_MARKER
module_file = None
module_section = _capability_section(
output, "__VCAP_MODULE_FILE_BEGIN__\n", "__VCAP_MODULE_FILE_END__")
if module_section:
module_lines = module_section.strip().splitlines()
if module_lines:
candidate = module_lines[0]
if re.fullmatch(r"/[A-Za-z0-9_.+@:-]+(?:/[A-Za-z0-9_.+@:-]+)*", candidate):
module_file = candidate
wireguard_kernel_ready = module_loaded or module_file is not None
wireguard_ready = bool(tool_state["wg"]["available"] and wireguard_kernel_ready)
# The reserved name must be free for the panel's own WireGuard device.
# A pre-existing link with the same name is a conflict even when it is
# not itself a WireGuard link (for example, an operator-created dummy or
# bridge). An ownership marker alone cannot convert the wrong link type
# into a safe fabric interface.
fabric_interface_present = WG_FABRIC_INTERFACE in all_interfaces
fabric_interface_is_wireguard = WG_FABRIC_INTERFACE in wireguard_names
nft_readable, nft_tables = _parse_nft_tables(nft_section, nft_status)
if len(active_firewall_managers) == 1:
firewall_manager = active_firewall_managers[0]
elif len(active_firewall_managers) > 1:
firewall_manager = "conflict"
elif (firewalld_cannot_take_over
and tool_state["nft"]["available"]
and nft_readable):
# Native nftables names the supported direct nft ownership contract,
# not the lifecycle state of the distro-provided nftables.service.
firewall_manager = "nftables"
elif (services.get("firewall") == "unknown"
and services.get("nftables") == "unknown"):
firewall_manager = "unknown"
else:
firewall_manager = "unmanaged"
legacy_firewalld_table_present = bool(
("inet", "firewalld") in nft_tables
or ("inet", "virt_cloud_fabric_emergency") in nft_tables
or ("bridge", "virt_cloud_fabric_emergency") in nft_tables
)
legacy_manifest_state = legacy_firewall.get("manifest", "unknown")
fabric_transaction_state = legacy_firewall.get(
"fabric_transaction", "unknown")
emergency_owner_state = legacy_firewall.get(
"emergency_owner", "unknown")
vpc_transaction_state = legacy_firewall.get(
"vpc_transaction", "unknown")
vpc_snapshot_state = legacy_firewall.get("vpc_snapshot", "unknown")
fabric_desired_state = legacy_firewall.get(
"fabric_desired_state", "unknown")
vpc_legacy_state = legacy_firewall.get("vpc_state", "unknown")
legacy_firewall_evidence_valid = all(
state in {"absent", "present"}
for state in (
legacy_manifest_state,
fabric_transaction_state,
emergency_owner_state,
vpc_transaction_state,
vpc_snapshot_state,
fabric_desired_state,
vpc_legacy_state,
)
) and all(
sum(
line.startswith(
f"__VCAP_LEGACY_FIREWALL__{name}=")
for line in output.splitlines()
) == 1
for name in (
"manifest", "fabric_transaction", "emergency_owner",
"vpc_transaction",
"vpc_snapshot",
"fabric_desired_state", "vpc_state",
)
)
protocol_ok = protocol_ok and legacy_firewall_evidence_valid
nft_main_state = nft_persistence.get("main", "unknown")
nft_persistence_evidence_valid = bool(
nft_main_state in {"ready", "missing", "unsafe", "conflict"}
and sum(
line.startswith("__VCAP_NFT_PERSISTENCE__main=")
for line in output.splitlines()
) == 1
)
protocol_ok = protocol_ok and nft_persistence_evidence_valid
legacy_manifest_present = legacy_manifest_state == "present"
legacy_vpc_snapshot_present = vpc_snapshot_state == "present"
legacy_emergency_owner_present = emergency_owner_state == "present"
legacy_desired_state_present = bool(
fabric_desired_state == "present"
or vpc_legacy_state == "present"
)
firewall_transaction_present = bool(
fabric_transaction_state == "present"
or vpc_transaction_state == "present"
)
# This is only a capability result: a later reconciler still has to create
# and own a dedicated private ACL table, then read it back before marking
# a VPC revision active. The stock nftables.service state is deliberately
# diagnostic-only; direct nft access and exclusive firewalld absence are
# the relevant capability and ownership facts.
native_nftables_ready = bool(
tool_state["nft"]["available"]
and nft_readable
and firewall_manager == "nftables"
and firewalld_cannot_take_over
and nft_persistence_evidence_valid
and nft_main_state == "ready"
and not legacy_firewalld_table_present
and legacy_firewall_evidence_valid
and not legacy_manifest_present
and not legacy_emergency_owner_present
and not legacy_vpc_snapshot_present
and not legacy_desired_state_present
and not firewall_transaction_present
)
firewall_mode = (
"native_nftables" if native_nftables_ready else "unsupported")
nft_ready = native_nftables_ready
forwarding_ready = ip_forward == 1
selector = public_network if isinstance(public_network, str) else ""
if selector.startswith("bridge:"):
bridge = selector.removeprefix("bridge:")
public_selector_kind = "bridge"
public_verified = bridge in bridge_names
public_reason = None if public_verified else "public_bridge_missing"
elif selector and _DNS_LABEL.fullmatch(selector):
bridge = None
public_selector_kind = "libvirt_network"
# The libvirt resource check remains authoritative for named virtual
# networks. This probe records the role without guessing its bridge.
public_verified = True
public_reason = None
else:
bridge = None
public_selector_kind = "invalid"
public_verified = False
public_reason = "public_network_selector_invalid"
# Linux accepts 0 (disabled), 1 (strict) and 2 (loose), and evaluates an
# interface with max(conf/all, conf/<interface>). Host readiness answers
# whether the administrator's automatic Fabric operation can safely
# converge the host; it must not demand that an existing public underlay
# already use the panel's preferred policy. The panel does not own that
# interface or the global/default sysctls. It does own ``wg-fabric0`` and
# the apply path is responsible for setting that interface explicitly.
# Consequently global/default values and any already-created Fabric link
# must be present and in the kernel's documented domain, while a legal
# value of 1 is not itself a readiness failure. The coordinator resolves
# the actual endpoint interface from its IP address; this generic parser
# must not guess that the public bridge selector is that underlay.
valid_rp_filter_values = {0, 1, 2}
rp_filter_ready = (
rp_filter in valid_rp_filter_values
and rp_filter_default in valid_rp_filter_values
)
rp_filter_default_effective = (
max(rp_filter, rp_filter_default)
if rp_filter in valid_rp_filter_values
and rp_filter_default in valid_rp_filter_values
else None
)
fabric_rp_filter_raw = (
rp_filter_interfaces.get(WG_FABRIC_INTERFACE)
if fabric_interface_present else None
)
fabric_rp_filter_effective = None
if fabric_interface_present:
if fabric_rp_filter_raw not in valid_rp_filter_values:
rp_filter_ready = False
elif rp_filter in valid_rp_filter_values:
fabric_rp_filter_effective = max(
rp_filter, fabric_rp_filter_raw)
reasons: list[str] = []
if not protocol_ok:
reasons.append("capability_probe_invalid")
if not os_supported:
reasons.append("unsupported_host_os")
if not tool_state["wg"]["available"]:
reasons.append("wireguard_tool_missing")
elif not wireguard_kernel_ready:
reasons.append("wireguard_kernel_unavailable")
if fabric_interface_present and (
not fabric_owned or not fabric_interface_is_wireguard):
# The first deployment owns this name exclusively. A pre-existing
# interface may belong to an operator or another tenant; without an
# ownership marker it is unsafe to overwrite keys, peers, or routes.
reasons.append("wireguard_fabric_interface_conflict")
if not tool_state["ip"]["available"]:
reasons.append("iproute2_missing")
elif not ip_probe_valid:
reasons.append("iproute2_probe_failed")
if not tool_state["flock"]["available"]:
reasons.append("flock_missing")
if not tool_state["nft"]["available"]:
reasons.append("nftables_tool_missing")
elif not nft_readable:
reasons.append("nftables_probe_failed")
if not nft_persistence_evidence_valid:
reasons.append("nftables_persistence_evidence_invalid")
elif nft_main_state != "ready":
reasons.append("nftables_persistence_not_ready")
if firewall_manager == "nftables":
if not firewalld_cannot_take_over:
reasons.append("firewalld_unsupported_requires_maintenance")
elif firewall_manager == "firewalld":
reasons.append("firewalld_unsupported_requires_maintenance")
elif firewall_manager == "conflict":
reasons.append("firewall_manager_conflict")
reasons.append("firewalld_unsupported_requires_maintenance")
else:
reasons.append("firewall_owner_unsupported")
if not firewalld_cannot_take_over:
reasons.append("firewalld_unsupported_requires_maintenance")
if legacy_firewalld_table_present:
reasons.append("legacy_firewalld_state_requires_cleanup")
if legacy_manifest_present:
reasons.append("legacy_firewalld_state_requires_cleanup")
if legacy_emergency_owner_present:
reasons.append("legacy_firewalld_state_requires_cleanup")
if legacy_vpc_snapshot_present:
reasons.append("legacy_firewalld_state_requires_cleanup")
if legacy_desired_state_present:
reasons.append("legacy_firewalld_state_requires_cleanup")
if firewall_transaction_present:
reasons.append("firewall_transaction_requires_recovery_or_cleanup")
if not legacy_firewall_evidence_valid:
reasons.append("legacy_firewall_evidence_invalid")
if firewall_mode == "unsupported":
reasons.append("firewall_mode_unsupported")
if firewall_mode == "unsupported" and firewall_manager != "nftables":
# Preserve the established coarse reason for older callers while the
# specific reasons above explain why firewalld/ownership was refused.
reasons.append("firewall_owner_not_nftables")
if not forwarding_ready:
reasons.append("ipv4_forwarding_disabled_or_unknown")
if not rp_filter_ready:
reasons.append("rp_filter_not_compatible")
if network_manager == "conflict":
reasons.append("network_manager_conflict")
elif network_manager == "unknown":
reasons.append("network_manager_unknown")
elif network_manager == "systemd_networkd":
# systemd-networkd remains observable for diagnostics, but the
# current deployment contract intentionally supports only nmcli on
# RHEL-family hosts and ifupdown on Debian-family hosts.
reasons.append("systemd_networkd_not_supported")
if expected_network_manager == "networkmanager":
if network_manager == "networkmanager":
if not tool_state["nmcli"]["available"]:
reasons.append("networkmanager_nmcli_missing")
if not networkmanager_active:
reasons.append("networkmanager_service_not_active")
if not networkmanager_enabled:
reasons.append("networkmanager_service_not_enabled")
elif network_manager not in {"networkmanager", "conflict", "unknown"}:
reasons.append("network_manager_policy_mismatch")
elif expected_network_manager == "ifupdown":
if network_manager == "ifupdown":
if not ifupdown_tools_available:
reasons.append("ifupdown_tools_missing")
if not ifupdown_configured:
reasons.append("ifupdown_configuration_missing")
elif (files.get("interfaces_d") == "present"
and files.get("interfaces_d_loaded") != "present"):
reasons.append("ifupdown_interfaces_d_not_included")
if not ifupdown_service_ready:
reasons.append("ifupdown_service_not_active_or_enabled")
elif network_manager not in {"ifupdown", "conflict", "unknown"}:
reasons.append("network_manager_policy_mismatch")
if expected_network_manager is not None and not network_manager_supported:
# A manager can be selected while one of its required facts is
# absent. Keep a stable policy reason in addition to the specific
# missing evidence above so callers need not infer readiness.
if network_manager not in {"conflict", "unknown"} and not any(
reason in reasons for reason in (
"network_manager_policy_mismatch",
"systemd_networkd_not_supported",
"networkmanager_nmcli_missing",
"networkmanager_service_not_active",
"networkmanager_service_not_enabled",
"ifupdown_tools_missing",
"ifupdown_configuration_missing",
"ifupdown_service_not_active_or_enabled",
)
):
reasons.append("network_manager_policy_mismatch")
if public_reason:
reasons.append(public_reason)
reasons = sorted(set(reasons))
private_ready = not any(reason in reasons for reason in (
"capability_probe_invalid", "unsupported_host_os", "wireguard_tool_missing",
"wireguard_kernel_unavailable", "iproute2_missing", "nftables_tool_missing",
"nftables_probe_failed", "firewall_owner_not_nftables",
"firewall_owner_unsupported", "firewall_mode_unsupported",
"firewall_manager_conflict",
"firewalld_unsupported_requires_maintenance",
"legacy_firewalld_state_requires_cleanup",
"firewall_transaction_requires_recovery_or_cleanup",
"legacy_firewall_evidence_invalid",
"nftables_persistence_evidence_invalid",
"nftables_persistence_not_ready",
"iproute2_probe_failed", "flock_missing",
"ipv4_forwarding_disabled_or_unknown", "rp_filter_not_compatible",
"network_manager_conflict", "wireguard_fabric_interface_conflict",
"network_manager_unknown", "network_manager_policy_mismatch",
"systemd_networkd_not_supported", "networkmanager_nmcli_missing",
"networkmanager_service_not_active", "networkmanager_service_not_enabled",
"ifupdown_tools_missing", "ifupdown_configuration_missing",
"ifupdown_interfaces_d_not_included",
"ifupdown_service_not_active_or_enabled",
))
vpc_ready = private_ready and public_verified
return {
"schema_version": HOST_CAPABILITY_SCHEMA_VERSION,
"probe_protocol": _CAPABILITY_MARKER,
"probe_valid": protocol_ok,
"os": {
"id": os_id,
"name": os_values.get("NAME", ""),
"version_id": version_id,
"family": family,
"package_manager": package_manager,
"supported": os_supported,
"package_tool": package_tool,
"package_tool_available": package_tool_ready,
},
"kernel": kernel,
"tools": tool_state,
"network": {
"network_manager": network_manager,
"network_manager_expected": expected_network_manager,
"network_manager_policy": expected_deployment_mode,
"network_manager_supported": network_manager_supported,
"network_manager_evidence": {
"networkmanager_active": networkmanager_active,
"networkmanager_enabled": networkmanager_enabled,
"networkmanager_configured": networkmanager_configured,
"systemd_networkd_active": networkd_active,
"systemd_networkd_enabled": networkd_enabled,
"systemd_networkd_configured": networkd_configured,
"ifupdown_detected": ifupdown_detected,
},
"networking_service": services.get("networking", "unknown"),
"networking_service_enabled": service_enabled.get(
"networking", "unknown"),
"ifupdown": {
"interfaces_file": files.get("interfaces") == "present",
"interfaces_d": files.get("interfaces_d") == "present",
"interfaces_d_loaded": files.get("interfaces_d_loaded") == "present",
"configured": ifupdown_configured,
"tools_available": ifupdown_tools_available,
"service_active": networking_active,
"service_enabled": networking_enabled,
"ready": bool(
ifupdown_tools_available and ifupdown_configured
and ifupdown_service_ready
),
},
"deployment_mode": network_deployment_mode,
"firewall_manager": firewall_manager,
"firewall_mode": firewall_mode,
"firewall_manager_evidence": {
"firewalld_active": firewalld_active,
"firewalld_enabled": firewalld_enabled,
"firewalld_load_state": firewalld_load,
"legacy_firewalld_table_present":
legacy_firewalld_table_present,
"legacy_manifest_state": legacy_manifest_state,
"fabric_transaction_state": fabric_transaction_state,
"emergency_owner_state": emergency_owner_state,
"vpc_transaction_state": vpc_transaction_state,
"vpc_snapshot_state": vpc_snapshot_state,
"fabric_desired_state": fabric_desired_state,
"vpc_state": vpc_legacy_state,
"nftables_active": nftables_active,
"nftables_enabled": nftables_enabled,
"nftables_load_state": nftables_load,
},
"ip_probe_valid": ip_probe_valid,
"bridges": bridge_names,
"interfaces": all_interfaces,
"local_ipv4_addresses": local_ipv4_addresses,
"local_ipv4_interfaces": local_ipv4_interfaces,
"wireguard_interfaces": wireguard_names,
"ip_forward": ip_forward,
# ``rp_filter`` is the established name for ``conf/all``. Keep it
# stable while exposing safe effective values separately.
"rp_filter": rp_filter,
"rp_filter_default": rp_filter_default,
"rp_filter_default_effective": rp_filter_default_effective,
"fabric_rp_filter_raw": fabric_rp_filter_raw,
"fabric_rp_filter_effective": fabric_rp_filter_effective,
"rp_filter_interfaces": rp_filter_interfaces,
},
"wireguard": {
"interface": WG_FABRIC_INTERFACE,
"tool_available": bool(tool_state["wg"]["available"]),
"kernel_module_loaded": module_loaded,
"kernel_module_file": module_file,
"ready": wireguard_ready,
"interface_present": WG_FABRIC_INTERFACE in wireguard_names,
"interface_name_reserved": fabric_interface_present,
"interface_is_wireguard": fabric_interface_is_wireguard,
"ownership_marker": fabric_owner_marker or None,
"owned_by_panel": fabric_owned,
# The reconciler selects a manager-specific lifecycle. An
# unsupported or ambiguous manager is never silently downgraded
# to direct ``ip`` mutation.
"deployment_mode": network_deployment_mode,
"wg_quick_available": bool(tool_state["wg_quick"]["available"]),
},
"nftables": {
"tool_available": bool(tool_state["nft"]["available"]),
"ruleset_readable": nft_readable,
"owner": firewall_manager,
"firewall_mode": firewall_mode,
"service": services.get("nftables", "unknown"),
"service_enabled": service_enabled.get("nftables", "unknown"),
"service_active": nftables_active,
"service_persistent": nftables_enabled,
"persistence_main_state": nft_main_state,
"ready": nft_ready,
},
"network_roles": {
"public": {
"cloud_init_key": PUBLIC_INTERFACE_ROLE,
"guest_alias": PUBLIC_LIBVIRT_ALIAS,
"selector": selector,
"selector_kind": public_selector_kind,
"bridge": bridge,
"verified": public_verified,
},
"private": {
"cloud_init_key": PRIVATE_INTERFACE_ROLE,
"guest_alias": PRIVATE_LIBVIRT_ALIAS,
"kind": "l3_wireguard",
"host_interface": WG_FABRIC_INTERFACE,
"separate_from_public": True,
"verified": private_ready,
},
},
"private_ready": private_ready,
"vpc_ready": vpc_ready,
"reasons": reasons,
}
class RemoteHostManager:
"""Prepare, test, and atomically select a root-key SSH generation."""
def __init__(
self,
data_dir: Path,
*,
ssh_user_config_path: Path | None = None,
ssh_binary: str = "ssh",
keyscan_binary: str = "ssh-keyscan",
keygen_binary: str = "ssh-keygen",
runner: _RUNNER | None = None,
agent_factory: Callable[[Path, Path, str], SSHAgentSession] = SSHAgentSession,
) -> None:
# Canonicalize once so staged paths, the active target and cleanup
# comparisons all use the same path. The final data directory itself
# must not be a symlink; a trusted parent may be one.
requested_data_dir = Path(data_dir).expanduser().absolute()
if requested_data_dir.is_symlink():
raise RemoteHostError("面板数据目录不能是符号链接", status=500)
self.data_dir = requested_data_dir.resolve(strict=False)
self.ssh_user_config_path = (
Path(ssh_user_config_path).expanduser().absolute()
if ssh_user_config_path is not None
else self.data_dir / ".ssh" / "config"
)
self.ssh_binary = ssh_binary
self.keyscan_binary = keyscan_binary
self.keygen_binary = keygen_binary
self._run = runner or subprocess.run
self._agent_factory = agent_factory
self._lock = threading.RLock()
self._pending: set[Path] = set()
self._agents: dict[Path, SSHAgentSession] = {}
self.cleanup_inactive()
self._schedule_cleanup()
@property
def libvirt_uri(self) -> str:
generation = self._current_generation()
return _uri_for_generation(generation) if generation is not None else LIBVIRT_URI
def _exec(
self,
argv: list[str],
*,
timeout: float,
input_text: str | None = None,
) -> subprocess.CompletedProcess[str]:
"""Run a bounded SSH command, optionally feeding a fixed script.
Fabric uses ``sh -s`` with a generated, strictly validated helper.
Existing callers keep the historical no-stdin behavior; the optional
argument is intentionally named so arbitrary shell commands cannot be
confused with the fixed remote operation boundary.
"""
try:
options = {
"check": False,
"capture_output": True,
"text": True,
"timeout": timeout,
}
if input_text is not None:
options["input"] = input_text
return self._run(
argv,
**options,
)
except (OSError, subprocess.TimeoutExpired) as exc:
raise RemoteHostError("SSH 命令超时或无法启动", status=502) from exc
def scan(self, host: str, port: int) -> dict[str, Any]:
"""Scan but do not trust the public key; the operator must verify it."""
host = _validate_host(host)
port = _validate_port(port)
result = self._exec(
[self.keyscan_binary, "-T", "8", "-p", str(port), "-t", "ed25519", host],
timeout=12,
)
found: set[str] = set()
for line in result.stdout.splitlines():
if not line or line.startswith("#"):
continue
try:
key_type, encoded = _key_parts(line)
except RemoteHostError:
continue
found.add(f"{key_type} {encoded}")
if result.returncode != 0 or len(found) != 1:
raise RemoteHostError("无法获取唯一的 Ed25519 主机公钥,请检查地址和端口", status=502)
host_key = found.pop()
return {
"host": host,
"port": port,
"key_type": "ssh-ed25519",
"fingerprint": _fingerprint(host_key),
"host_key": host_key,
"known_hosts_line": f"{SSH_ALIAS} {host_key}",
}
def _ensure_storage(self) -> None:
self.data_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
if self.data_dir.is_symlink():
raise RemoteHostError("面板数据目录不能是符号链接")
self.data_dir.chmod(0o700)
generations = self.data_dir / "generations"
generations.mkdir(mode=0o700, exist_ok=True)
if generations.is_symlink():
raise RemoteHostError("面板配置目录不能是符号链接")
generations.chmod(0o700)
def stage(
self,
profile: HostProfile | Mapping[str, Any],
confirmed_fingerprint: str,
) -> StagedHost:
"""Re-scan and write an inactive generation after explicit verification."""
if isinstance(profile, Mapping):
try:
profile = HostProfile(**profile)
except (TypeError, ValueError) as exc:
raise RemoteHostError("宿主机配置字段无效") from exc
if not isinstance(profile, HostProfile):
raise RemoteHostError("宿主机配置字段无效")
host = _validate_host(profile.host)
port = _validate_port(profile.port)
storage_pool = _validate_pool_selector(profile.storage_pool, "磁盘池")
iso_pool = _validate_pool_selector(profile.iso_pool, "ISO 池")
rescue_iso_pool = (
_validate_pool_selector(profile.rescue_iso_pool, "救援 ISO 池")
if profile.rescue_iso_pool != "" else ""
)
if rescue_iso_pool and rescue_iso_pool == iso_pool:
raise RemoteHostError("救援 ISO 池不能与安装 ISO 池相同")
default_network = _validate_network_selector(profile.default_network)
region = _validate_region(profile.region)
fabric_endpoint_ip = _validate_fabric_endpoint_ip(
profile.fabric_endpoint_ip)
public_pool = validate_public_pool(
profile.public_pool_cidr,
profile.public_gateway,
profile.public_dns_servers,
profile.public_reserved_ips,
host,
profile.public_vm_prefix,
)
if not isinstance(confirmed_fingerprint, str) or not _FINGERPRINT.fullmatch(confirmed_fingerprint):
raise RemoteHostError("请确认扫描得到的 SHA256 主机指纹")
try:
submitted_type, submitted_encoded = _key_parts(profile.host_key)
except RemoteHostError as exc:
raise RemoteHostError("提交的主机公钥格式无效") from exc
submitted_key = f"{submitted_type} {submitted_encoded}"
scanned = self.scan(host, port)
if scanned["host_key"] != submitted_key or scanned["fingerprint"] != confirmed_fingerprint:
raise RemoteHostError("主机公钥或指纹在扫描后发生变化,请重新核验", status=409)
self._ensure_storage()
generation = self.data_dir / "generations" / ("gen-" + secrets.token_hex(16))
generation.mkdir(mode=0o700)
try:
key_path = generation / "id_private"
if profile.private_key:
try:
key_bytes = _validate_private_key(profile.private_key)
except UnicodeEncodeError:
raise RemoteHostError(
"SSH 私钥必须是 ASCII PEM 文本",
error_code="host_private_key_format_invalid",
) from None
else:
current = self._current_generation()
if current is None:
raise RemoteHostError(
"首次连接必须提供现有 SSH 私钥",
error_code="host_private_key_required",
)
try:
key_bytes = (current / "id_private").read_bytes()
except OSError as exc:
raise RemoteHostError("已保存的 SSH 私钥无法读取", status=500) from exc
_write_private(key_path, key_bytes)
key_check = self._exec(
[self.keygen_binary, "-y", "-P", "", "-f", str(key_path)],
timeout=8,
)
# Successful ssh-keygen -y is authoritative here: unencrypted
# ECDSA keys produce an `ecdsa-sha2-*` public key, not `ssh-*`.
encrypted = key_check.returncode != 0 or len(key_check.stdout.split()) < 2
identity_path = key_path
identity_agent = "none"
if encrypted:
if not profile.private_key_passphrase:
raise RemoteHostError(
"私钥已加密或无效;请填写私钥口令后重试",
error_code="host_private_key_passphrase_required",
)
try:
agent = self._agent_factory(generation, key_path, profile.private_key_passphrase)
except SSHAgentError as exc:
raise RemoteHostError(
"私钥口令错误或私钥无效,无法解锁",
error_code="host_private_key_invalid",
) from exc
with self._lock:
self._agents[generation] = agent
identity_path = generation / "identity.pub"
_write_private(identity_path, (agent.public_key + "\n").encode("ascii"))
identity_agent = _quoted_path(agent.socket_path)
known_hosts = generation / "known_hosts"
_write_private(known_hosts, f"{SSH_ALIAS} {submitted_key}\n".encode("ascii"))
ssh_config = generation / "config"
config_text = (
f"Host {SSH_ALIAS}\n"
f" HostName {host}\n"
f" Port {port}\n"
" User root\n"
f" IdentityFile {_quoted_path(identity_path)}\n"
f" UserKnownHostsFile {_quoted_path(known_hosts)}\n"
" GlobalKnownHostsFile /dev/null\n"
f" HostKeyAlias {SSH_ALIAS}\n"
" HostKeyAlgorithms ssh-ed25519\n"
" StrictHostKeyChecking yes\n"
" VerifyHostKeyDNS no\n"
" BatchMode yes\n"
" IdentitiesOnly yes\n"
f" IdentityAgent {identity_agent}\n"
" PreferredAuthentications publickey\n"
" PasswordAuthentication no\n"
" KbdInteractiveAuthentication no\n"
" GSSAPIAuthentication no\n"
" ForwardAgent no\n"
" ProxyCommand none\n"
" ProxyJump none\n"
" CanonicalizeHostname no\n"
" ControlMaster no\n"
" ControlPath none\n"
" UpdateHostKeys no\n"
" RequestTTY no\n"
" ServerAliveInterval 15\n"
" ServerAliveCountMax 2\n"
" ConnectTimeout 10\n"
)
_write_private(ssh_config, config_text.encode("ascii"))
wrapper = generation / "ssh-wrapper"
wrapper_text = (
"#!/usr/bin/env python3\n"
"import os\n"
"import sys\n"
f"os.execvp({self.ssh_binary!r}, "
f"[{self.ssh_binary!r}, '-F', {str(ssh_config)!r}, *sys.argv[1:]])\n"
)
_write_private(wrapper, wrapper_text.encode("ascii"))
wrapper.chmod(0o700)
metadata = {
"host": host,
"port": port,
"key_type": "ssh-ed25519",
"fingerprint": confirmed_fingerprint,
"private_key_configured": True,
"private_key_encrypted": encrypted,
"storage_pool": storage_pool,
"iso_pool": iso_pool,
"rescue_iso_pool": rescue_iso_pool,
"default_network": default_network,
"region": region,
"fabric_endpoint_ip": fabric_endpoint_ip,
**public_pool,
}
_write_private(
generation / "profile.json",
json.dumps(metadata, ensure_ascii=False).encode("utf-8"),
)
with self._lock:
self._pending.add(generation)
return StagedHost(generation, metadata)
except BaseException:
with self._lock:
agent = self._agents.pop(generation, None)
if agent is not None:
agent.close()
shutil.rmtree(generation)
raise
def test(self, staged: StagedHost) -> dict[str, Any]:
"""Check SSH/libvirt and return a read-only host capability snapshot.
Capability gaps deliberately do not reject saving an existing public
host yet: the public VM path has a separate compatibility boundary.
VPC/Fabric callers must require ``capabilities.vpc_ready`` and treat a
false value as unsupported. This keeps the probe useful during the
staged rollout while preventing a future private-network operation
from guessing when bridge, WireGuard, or firewall evidence is absent.
"""
self._check_staged(staged)
result = self._exec(
[
self.ssh_binary,
"-F",
staged.ssh_config_file,
"-T",
"-o",
"ConnectTimeout=10",
SSH_ALIAS,
"/usr/bin/virsh -c qemu:///system list --all",
],
timeout=22,
)
if result.returncode != 0:
# Do not reflect stderr: SSH diagnostics can contain arbitrary
# remote data or paths, and never need to include the secret key.
raise RemoteHostError(
"SSH 或宿主机 libvirt 连接失败;请检查 root 密钥、端口、主机指纹和 virsh 服务",
status=502,
)
probe = self._exec(
[
self.ssh_binary,
"-F",
staged.ssh_config_file,
"-T",
"-o",
"ConnectTimeout=10",
SSH_ALIAS,
_CAPABILITY_PROBE_COMMAND,
],
timeout=22,
)
capabilities = parse_host_capabilities(
probe.stdout if probe.returncode == 0 else "",
public_network=staged.metadata.get("default_network", ""),
)
_assert_fabric_endpoint_is_local(staged.metadata, capabilities)
staged.metadata["capabilities"] = capabilities
staged.tested = True
return {
"ok": True,
"ssh": "connected",
"libvirt": "available",
"capabilities": capabilities,
}
def _check_staged(self, staged: StagedHost) -> None:
if not isinstance(staged, StagedHost) or staged.path.parent != self.data_dir / "generations":
raise RemoteHostError("暂存配置无效")
if staged.path.is_symlink() or not staged.path.is_dir():
raise RemoteHostError("暂存配置不存在")
def _current_generation(self) -> Path | None:
current = self.data_dir / "current"
if not current.is_symlink():
if current.exists():
raise RemoteHostError("已保存的宿主机配置损坏", status=500)
return None
target = current.resolve()
if target.parent != self.data_dir / "generations" or not target.is_dir():
raise RemoteHostError("已保存的宿主机配置损坏", status=500)
return target
def _ensure_user_ssh_config(self) -> None:
ssh_dir = self.ssh_user_config_path.parent
ssh_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
if ssh_dir.is_symlink():
raise RemoteHostError("服务账号 SSH 目录不能是符号链接", status=500)
ssh_dir.chmod(0o700)
destination = self.data_dir / "current" / "config"
user_config = self.ssh_user_config_path
if user_config.is_symlink():
if user_config.readlink() != destination:
raise RemoteHostError("服务账号已有其他 SSH 配置,请勿覆盖", status=409)
elif user_config.exists():
raise RemoteHostError("服务账号已有其他 SSH 配置,请勿覆盖", status=409)
else:
user_config.symlink_to(destination)
@staticmethod
def _replace_profile_metadata(staged: StagedHost) -> None:
"""Atomically persist probe metadata without following a symlink."""
profile_path = staged.path / "profile.json"
try:
info = profile_path.lstat()
except OSError as exc:
raise RemoteHostError("暂存宿主机配置损坏", status=500) from exc
if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
raise RemoteHostError("暂存宿主机配置权限无效", status=500)
temporary = staged.path / (".profile-" + secrets.token_hex(8))
try:
_write_private(
temporary,
json.dumps(staged.metadata, ensure_ascii=False).encode("utf-8"),
)
os.replace(temporary, profile_path)
finally:
temporary.unlink(missing_ok=True)
def commit(self, staged: StagedHost) -> dict[str, Any]:
"""Activate a previously tested generation with one atomic symlink swap."""
with self._lock:
self._check_staged(staged)
if not staged.tested:
raise RemoteHostError("保存前必须先测试宿主机连接", status=409)
# Persist only the normalized capability contract. Older staged
# generations may have no snapshot and remain valid for the
# public path.
if "capabilities" in staged.metadata:
self._replace_profile_metadata(staged)
self._ensure_user_ssh_config()
previous = self._current_generation()
link = self.data_dir / (".current-" + secrets.token_hex(8))
link.symlink_to(staged.path)
try:
os.replace(link, self.data_dir / "current")
finally:
link.unlink(missing_ok=True)
self._pending.discard(staged.path)
if previous is not None and previous != staged.path:
# Give in-flight API calls that obtained the old URI time to
# launch SSH before removing that generation's private key.
try:
os.utime(previous, None)
except OSError as exc:
LOG.warning("could not date retired SSH generation: %s", exc)
self._schedule_cleanup()
return self.current() or {}
def abort(self, staged: StagedHost) -> None:
with self._lock:
self._check_staged(staged)
if self._current_generation() == staged.path:
raise RemoteHostError("不能删除正在使用的宿主机配置", status=409)
self._pending.discard(staged.path)
agent = self._agents.pop(staged.path, None)
if agent is not None:
agent.close()
shutil.rmtree(staged.path)
def _schedule_cleanup(self) -> None:
timer = threading.Timer(65, self.cleanup_inactive)
timer.daemon = True
timer.start()
def cleanup_inactive(self, *, grace_seconds: float = 60) -> int:
"""Remove only retired generations owned by this manager's data tree."""
if grace_seconds < 0:
raise ValueError("grace_seconds must not be negative")
with self._lock:
root = self.data_dir / "generations"
if root.is_symlink():
raise RemoteHostError("面板配置目录损坏", status=500)
if not root.exists():
return 0
if not root.is_dir():
raise RemoteHostError("面板配置目录损坏", status=500)
active = self._current_generation()
now = time.time()
removed = 0
for entry in root.iterdir():
if (
not _GEN_NAME.fullmatch(entry.name)
or entry.is_symlink()
or not entry.is_dir()
or entry == active
or entry in self._pending
):
continue
try:
if now - entry.stat().st_mtime < grace_seconds:
continue
agent = self._agents.pop(entry, None)
if agent is not None:
agent.close()
shutil.rmtree(entry)
removed += 1
except OSError as exc:
LOG.warning("could not prune retired SSH generation: %s", exc)
return removed
def unlock_current(self, passphrase: str) -> dict[str, Any]:
"""Load the saved encrypted key into a process-local SSH agent."""
with self._lock:
generation = self._current_generation()
if generation is None:
raise RemoteHostError("请先配置宿主机", 409)
profile = self.current()
if profile is None or not profile["private_key_encrypted"]:
raise RemoteHostError("当前 SSH 私钥不需要解锁", 409)
if not profile["key_locked"]:
return profile
try:
agent = self._agent_factory(generation, generation / "id_private", passphrase)
except SSHAgentError as exc:
raise RemoteHostError(
"私钥口令错误或私钥无效,无法解锁",
error_code="host_private_key_invalid",
) from exc
try:
expected = (generation / "identity.pub").read_text(encoding="ascii").split()
actual = agent.public_key.split()
if len(expected) < 2 or actual[:2] != expected[:2]:
raise RemoteHostError("已保存的私钥与公钥不匹配", 500)
self._set_agent_socket(generation, agent.socket_path)
except BaseException:
agent.close()
raise
previous = self._agents.pop(generation, None)
if previous is not None:
previous.close()
self._agents[generation] = agent
return self.current() or {}
@staticmethod
def _set_agent_socket(generation: Path, socket_path: Path) -> None:
"""Atomically point the active SSH config at the newly unlocked agent."""
config = generation / "config"
info = config.lstat()
if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
raise RemoteHostError("已保存的 SSH 配置权限无效", 500)
lines = config.read_text(encoding="ascii").splitlines(keepends=True)
replacements = [index for index, line in enumerate(lines)
if line.startswith(" IdentityAgent ")]
if len(replacements) != 1:
raise RemoteHostError("已保存的 SSH 配置损坏", 500)
lines[replacements[0]] = f" IdentityAgent {_quoted_path(socket_path)}\n"
temporary = generation / (".config-" + secrets.token_hex(8))
try:
_write_private(temporary, "".join(lines).encode("ascii"))
os.replace(temporary, config)
finally:
temporary.unlink(missing_ok=True)
def close(self) -> None:
"""Stop all process-local agents on graceful panel shutdown."""
with self._lock:
agents = list(self._agents.values())
self._agents.clear()
for agent in agents:
agent.close()
def reprobe_current_snapshot(self) -> tuple[dict[str, Any], dict[str, Any]]:
"""Return a fresh capability snapshot bound to one SSH generation.
The profile and capability result are returned together while the
manager lock is held. Fabric can therefore not combine capabilities
from a newly committed generation with the SSH path of an older one.
The probe remains read-only and does not update the durable profile.
"""
with self._lock:
generation = self._current_generation()
if generation is None:
raise RemoteHostError(
"请先配置宿主机",
status=409,
error_code="host_not_configured",
)
profile = self.current()
if profile is None:
raise RemoteHostError(
"请先配置宿主机",
status=409,
error_code="host_not_configured",
)
if profile.get("key_locked"):
raise RemoteHostError(
"当前 SSH 私钥已锁定,请先解锁",
status=409,
error_code="host_private_key_locked",
)
ssh_config = generation / "config"
try:
config_info = ssh_config.lstat()
except OSError as exc:
raise RemoteHostError(
"已保存的 SSH 配置损坏", status=500,
) from exc
if (not stat.S_ISREG(config_info.st_mode)
or config_info.st_mode & 0o077):
raise RemoteHostError("已保存的 SSH 配置权限无效", status=500)
probe = self._exec(
[
self.ssh_binary,
"-F",
str(ssh_config),
"-T",
"-o",
"ConnectTimeout=10",
SSH_ALIAS,
_CAPABILITY_PROBE_COMMAND,
],
timeout=22,
)
if probe.returncode != 0:
raise RemoteHostError(
"宿主机能力重新探测失败;请检查 SSH 连接和宿主机状态",
status=502,
error_code="host_capability_probe_failed",
)
capabilities = parse_host_capabilities(
probe.stdout,
public_network=profile.get("default_network", ""),
)
if not capabilities["probe_valid"]:
raise RemoteHostError(
"宿主机能力探针返回无效结果",
status=502,
error_code="host_capability_probe_invalid",
)
_assert_fabric_endpoint_is_local(profile, capabilities)
return dict(profile), capabilities
def reprobe_current_capabilities(self) -> dict[str, Any]:
"""Read a fresh capability snapshot through the pinned generation."""
_profile, capabilities = self.reprobe_current_snapshot()
return capabilities
# Keep the shorter name available to Fabric callers while retaining the
# explicit name for other host-capability consumers.
def reprobe_current(self) -> dict[str, Any]:
return self.reprobe_current_capabilities()
def current(self) -> dict[str, Any] | None:
generation = self._current_generation()
if generation is None:
return None
try:
metadata = json.loads((generation / "profile.json").read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise RemoteHostError("已保存的宿主机配置损坏", status=500) from exc
fields = (
"host",
"port",
"key_type",
"fingerprint",
"private_key_configured",
"storage_pool",
"iso_pool",
"default_network",
)
if any(field not in metadata for field in fields):
raise RemoteHostError("已保存的宿主机配置损坏", status=500)
try:
region = _validate_region(metadata.get("region", ""))
fabric_endpoint_ip = _validate_fabric_endpoint_ip(
metadata.get("fabric_endpoint_ip", ""))
rescue_iso_pool = metadata.get("rescue_iso_pool", "")
if rescue_iso_pool != "":
rescue_iso_pool = _validate_pool_selector(rescue_iso_pool, "救援 ISO 池")
if rescue_iso_pool == metadata["iso_pool"]:
raise RemoteHostError("救援 ISO 池不能与安装 ISO 池相同")
public_pool = validate_public_pool(
metadata.get("public_pool_cidr", ""),
metadata.get("public_gateway", ""),
metadata.get("public_dns_servers", []),
metadata.get("public_reserved_ips", []),
metadata["host"],
metadata.get("public_vm_prefix"),
)
except RemoteHostError as exc:
raise RemoteHostError("已保存的宿主机配置损坏", status=500) from exc
has_capabilities = "capabilities" in metadata
capabilities = metadata.get("capabilities")
if has_capabilities and not isinstance(capabilities, dict):
raise RemoteHostError("已保存的宿主机能力快照损坏", status=500)
result = {
**{field: metadata[field] for field in fields},
"rescue_iso_pool": rescue_iso_pool,
"region": region,
"fabric_endpoint_ip": fabric_endpoint_ip,
**public_pool,
"private_key_encrypted": bool(metadata.get("private_key_encrypted", False)),
"key_locked": bool(metadata.get("private_key_encrypted", False)) and not (
generation in self._agents and self._agents[generation].alive
),
"libvirt_uri": _uri_for_generation(generation),
"ssh_target": SSH_ALIAS,
"ssh_config_file": str(generation / "config"),
"ssh_known_hosts_file": str(generation / "known_hosts"),
}
if has_capabilities:
result["capabilities"] = capabilities
return result
# A clearer name for callers that prefer "store" terminology.
RemoteHostStore = RemoteHostManager