annet 0.16.12__tar.gz → 0.16.14__tar.gz

{annet-0.16.12/annet.egg-info → annet-0.16.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: annet
-Version: 0.16.12
+Version: 0.16.14
 Summary: annet
 Home-page: https://github.com/annetutil/annet
 License: MIT

{annet-0.16.12 → annet-0.16.14}/README.md

@@ -59,4 +59,4 @@ pip install -r requirements-doc.txt
 sphinx-build -M html docs docs-build
 ```
 
-3. Open rendered html in browser [docs-build/html/index.html](docs-build/html/index.html)
+3. Open rendered html in browser docs-build/html/index.html

{annet-0.16.12 → annet-0.16.14}/annet/adapters/netbox/common/storage_opts.py

@@ -5,10 +5,11 @@ DEFAULT_URL = "http://localhost"
 
 
 class NetboxStorageOpts:
-    def __init__(self, url: str, token: str, insecure: bool = False):
+    def __init__(self, url: str, token: str, insecure: bool = False, exact_host_filter: bool = False):
         self.url = url
         self.token = token
         self.insecure = insecure
+        self.exact_host_filter = exact_host_filter
 
     @classmethod
     def parse_params(cls, conf_params: Optional[dict[str, str]], cli_opts: Any):
@@ -19,4 +20,8 @@ class NetboxStorageOpts:
             insecure = insecure_env in ("true", "1", "t")
         else:
             insecure = bool(conf_params.get("insecure") or False)
-        return cls(url=url, token=token, insecure=insecure)
+        if exact_host_filter_env := os.getenv("NETBOX_EXACT_HOST_FILTER", "").lower():
+            exact_host_filter = exact_host_filter_env in ("true", "1", "t")
+        else:
+            exact_host_filter = bool(conf_params.get("exact_host_filter") or False)
+        return cls(url=url, token=token, insecure=insecure, exact_host_filter=exact_host_filter)

{annet-0.16.12 → annet-0.16.14}/annet/adapters/netbox/provider.py

@@ -27,10 +27,12 @@ def storage_factory(opts: NetboxStorageOpts) -> Storage:
 
 
 class NetboxProvider(StorageProvider, AdapterWithName, AdapterWithConfig):
-    def __init__(self, url: Optional[str] = None, token: Optional[str] = None, insecure: bool = False):
+    def __init__(self, url: Optional[str] = None, token: Optional[str] = None, insecure: bool = False,
+                 exact_host_filter: bool = False):
         self.url = url
         self.token = token
         self.insecure = insecure
+        self.exact_host_filter = exact_host_filter
 
     @classmethod
     def with_config(cls, **kwargs: Dict[str, Any]) -> T:

{annet-0.16.12 → annet-0.16.14}/annet/adapters/netbox/v37/storage.py

@@ -87,16 +87,19 @@ def extend_ip_address(
 
 class NetboxStorageV37(Storage):
     def __init__(self, opts: Optional[NetboxStorageOpts] = None):
-        ctx: ssl.con | ssl.SSLContext = None
-        if opts.insecure:
-            ctx = ssl.create_default_context()
-            ctx.check_hostname = False
-            ctx.verify_mode = ssl.CERT_NONE
-        self.netbox = NetboxV37(
-            url=opts.url,
-            token=opts.token,
-            ssl_context=ctx,
-        )
+        ctx: Optional[ssl.SSLContext] = None
+        url = ""
+        token = ""
+        self.exact_host_filter = False
+        if opts:
+            if opts.insecure:
+                ctx = ssl.create_default_context()
+                ctx.check_hostname = False
+                ctx.verify_mode = ssl.CERT_NONE
+            url = opts.url
+            token = opts.token
+            self.exact_host_filter = opts.exact_host_filter
+        self.netbox = NetboxV37(url=url, token=token, ssl_context=ctx)
         self._all_fqdns: Optional[list[str]] = None
 
     def __enter__(self):
@@ -147,7 +150,7 @@ class NetboxStorageV37(Storage):
 
         interfaces = self._load_interfaces(list(device_ids))
         neighbours = {x.id: x for x in self._load_neighbours(interfaces)}
-        neighbours_seen = defaultdict(set)
+        neighbours_seen: dict[str, set] = defaultdict(set)
 
         for interface in interfaces:
             device_ids[interface.device.id].interfaces.append(interface)
@@ -162,14 +165,18 @@ class NetboxStorageV37(Storage):
     def _load_devices(self, query: NetboxQuery) -> List[api_models.Device]:
         if not query.globs:
             return []
-        query = _hostname_dot_hack(query)
-        return [
-            device
-            for device in self.netbox.dcim_all_devices(
-                name__ic=query.globs,
-            ).results
-            if _match_query(query, device)
-        ]
+        if self.exact_host_filter:
+            devices = self.netbox.dcim_all_devices(name__ie=query.globs).results
+        else:
+            query = _hostname_dot_hack(query)
+            devices = [
+                device
+                for device in self.netbox.dcim_all_devices(
+                    name__ic=query.globs,
+                ).results
+                if _match_query(query, device)
+            ]
+        return devices
 
     def _extend_interfaces(self, interfaces: List[models.Interface]) -> List[models.Interface]:
         extended_ifaces = {

{annet-0.16.12 → annet-0.16.14}/annet/bgp_models.py

@@ -103,7 +103,7 @@ class PeerOptions:
     af_rib_group: Optional[str] = None
     af_loops: Optional[int] = None
     hold_time: Optional[int] = None
-    listen_network: Optional[bool] = None
+    listen_network: Optional[list[str]] = None
     remove_private: Optional[bool] = None
     as_override: Optional[bool] = None
     aigp: Optional[bool] = None
@@ -158,7 +158,7 @@ class Redistribute:
 @dataclass
 class FamilyOptions:
     family: Family
-    vrf_name: str
+    vrf_name: str = ""
     multipath: int = 0
     global_multipath: int = 0
     aggregate: Aggregate = field(default_factory=Aggregate)
@@ -213,7 +213,7 @@ class PeerGroup:
     af_rib_group: Optional[str] = None
     af_loops: int = 0
     hold_time: int = 0
-    listen_network: bool = False
+    listen_network: list[str] = field(default_factory=list)
     remove_private: bool = False
     as_override: bool = False
     aigp: bool = False
@@ -234,6 +234,12 @@ class PeerGroup:
 @dataclass
 class VrfOptions:
     vrf_name: str
+
+    ipv4_unicast: FamilyOptions
+    ipv6_unicast: FamilyOptions
+    ipv4_labeled_unicast: FamilyOptions
+    ipv6_labeled_unicast: FamilyOptions
+
     vrf_name_global: Optional[str] = None
     import_policy: Optional[str] = None
     export_policy: Optional[str] = None
@@ -244,23 +250,20 @@ class VrfOptions:
     route_distinguisher: Optional[str] = None
     static_label: Optional[int] = None  # FIXME: str?
 
-    ipv4_unicast: Optional[FamilyOptions] = None
-    ipv6_unicast: Optional[FamilyOptions] = None
-    ipv4_labeled_unicast: Optional[FamilyOptions] = None
-    ipv6_labeled_unicast: Optional[FamilyOptions] = None
     groups: list[PeerGroup] = field(default_factory=list)
 
 
 @dataclass
 class GlobalOptions:
+    ipv4_unicast: FamilyOptions
+    ipv6_unicast: FamilyOptions
+    ipv4_labeled_unicast: FamilyOptions
+    ipv6_labeled_unicast: FamilyOptions
+
     local_as: ASN = ASN(None)
     loops: int = 0
     multipath: int = 0
     router_id: str = ""
     vrf: dict[str, VrfOptions] = field(default_factory=dict)
 
-    ipv4_unicast: Optional[FamilyOptions] = None
-    ipv6_unicast: Optional[FamilyOptions] = None
-    ipv4_labeled_unicast: Optional[FamilyOptions] = None
-    ipv6_labeled_unicast: Optional[FamilyOptions] = None
     groups: list[PeerGroup] = field(default_factory=list)

{annet-0.16.12 → annet-0.16.14}/annet/implicit.py

@@ -135,9 +135,11 @@ def _implicit_tree(device):
             """
     elif device.hw.Cisco:
         text += r"""
-            !interface
+            !interface *Ethernet*
+                mtu 1500
                 no shutdown
-                no ip address
+
+
         """
         if device.hw.Cisco.Catalyst:
             # this configuration is not visible in running-config when enabled

{annet-0.16.12 → annet-0.16.14}/annet/mesh/__init__.py

@@ -8,9 +8,12 @@ __all__ = [
     "Left",
     "Right",
     "Match",
+    "VirtualLocal",
+    "VirtualPeer",
 ]
 
 from .executor import MeshExecutor
 from .match_args import Left, Right, Match
-from .registry import DirectPeer, IndirectPeer, MeshSession, GlobalOptions
-from .registry import MeshRulesRegistry
+from .registry import (
+    DirectPeer, IndirectPeer, MeshSession, GlobalOptions, MeshRulesRegistry, VirtualLocal, VirtualPeer,
+)

{annet-0.16.12 → annet-0.16.14}/annet/mesh/device_models.py

@@ -1,16 +1,30 @@
 from typing import Annotated, Optional, Union
 
-from annet.bgp_models import Family, Aggregate, Redistribute
+from annet.bgp_models import Family, Redistribute
 from .basemodel import BaseMeshModel, Concat, DictMerge, Merge, KeyDefaultDict
 from .peer_models import MeshPeerGroup
 
 
+class Aggregate(BaseMeshModel):
+    policy: str
+    routes: Annotated[tuple[str, ...], Concat()]
+    export_policy: str
+    as_path: str
+    reference: str
+    suppress: bool
+    discard: bool
+    as_set: bool
+
+
 class FamilyOptions(BaseMeshModel):
+    def __init__(self, **kwargs):
+        kwargs.setdefault("aggregate", Aggregate())
+        super().__init__(**kwargs)
     family: Family
     vrf_name: str
     multipath: int = 0
     global_multipath: int
-    aggregate: Aggregate
+    aggregate: Annotated[Aggregate, Merge()]
     redistributes: Annotated[tuple[Redistribute, ...], Concat()]
     allow_default: bool
     aspath_relax: bool
@@ -24,16 +38,26 @@ class FamilyOptions(BaseMeshModel):
 
 
 class _FamiliesMixin:
-    ipv4_unicast: Optional[FamilyOptions]
-    ipv6_unicast: Optional[FamilyOptions]
-    ipv4_labeled_unicast: Optional[FamilyOptions]
-    ipv6_labeled_unicast: Optional[FamilyOptions]
+    def __init__(self, **kwargs):
+        kwargs.setdefault("ipv4_unicast", FamilyOptions(family="ipv4_unicast"))
+        kwargs.setdefault("ipv6_unicast", FamilyOptions(family="ipv6_unicast"))
+        kwargs.setdefault("ipv4_labeled_unicast", FamilyOptions(family="ipv4_labeled"))
+        kwargs.setdefault("ipv6_labeled_unicast", FamilyOptions(family="ipv6_labeled"))
+        super().__init__(**kwargs)
+    ipv4_unicast: Annotated[FamilyOptions, Merge()]
+    ipv6_unicast: Annotated[FamilyOptions, Merge()]
+    ipv4_labeled_unicast: Annotated[FamilyOptions, Merge()]
+    ipv6_labeled_unicast: Annotated[FamilyOptions, Merge()]
 
 
-class VrfOptions(BaseMeshModel, _FamiliesMixin):
-    def __init__(self, **kwargs):
+class VrfOptions(_FamiliesMixin, BaseMeshModel):
+    def __init__(self, vrf_name: str, **kwargs):
+        kwargs.setdefault("ipv4_unicast", FamilyOptions(family="ipv4_unicast", vrf_name=vrf_name))
+        kwargs.setdefault("ipv6_unicast", FamilyOptions(family="ipv6_unicast", vrf_name=vrf_name))
+        kwargs.setdefault("ipv4_labeled_unicast", FamilyOptions(family="ipv4_labeled", vrf_name=vrf_name))
+        kwargs.setdefault("ipv6_labeled_unicast", FamilyOptions(family="ipv6_labeled", vrf_name=vrf_name))
         kwargs.setdefault("groups", KeyDefaultDict(lambda x: MeshPeerGroup(name=x)))
-        super().__init__(**kwargs)
+        super().__init__(vrf_name=vrf_name, **kwargs)
 
     vrf_name: str
     vrf_name_global: Optional[str]
@@ -48,7 +72,7 @@ class VrfOptions(BaseMeshModel, _FamiliesMixin):
     groups: Annotated[dict[str, MeshPeerGroup], DictMerge(Merge())]
 
 
-class GlobalOptionsDTO(BaseMeshModel, _FamiliesMixin):
+class GlobalOptionsDTO(_FamiliesMixin, BaseMeshModel):
     def __init__(self, **kwargs):
         kwargs.setdefault("groups", KeyDefaultDict(lambda x: MeshPeerGroup(name=x)))
         kwargs.setdefault("vrf", KeyDefaultDict(lambda x: VrfOptions(vrf_name=x)))

{annet-0.16.12 → annet-0.16.14}/annet/mesh/executor.py

@@ -1,15 +1,22 @@
 from dataclasses import dataclass
 from logging import getLogger
-from typing import Annotated, Callable, Optional
+from typing import Annotated, Callable, Optional, Union
 
 from annet.bgp_models import Peer, GlobalOptions
 from annet.storage import Device, Storage
 from .basemodel import merge, BaseMeshModel, Merge, UseLast, MergeForbiddenError
 from .device_models import GlobalOptionsDTO
 from .models_converter import to_bgp_global_options, to_bgp_peer, InterfaceChanges, to_interface_changes
-from .peer_models import PeerDTO
-from .registry import MeshRulesRegistry, GlobalOptions as MeshGlobalOptions, DirectPeer, MeshSession, IndirectPeer
-
+from .peer_models import DirectPeerDTO, IndirectPeerDTO, VirtualLocalDTO, VirtualPeerDTO
+from .registry import (
+    DirectPeer,
+    GlobalOptions as MeshGlobalOptions,
+    IndirectPeer,
+    MeshRulesRegistry,
+    MeshSession,
+    VirtualLocal,
+    VirtualPeer,
+)
 
 logger = getLogger(__name__)
 
@@ -28,11 +35,16 @@ class PeerKey:
 
 
 class Pair(BaseMeshModel):
-    local: Annotated[PeerDTO, Merge()]
-    connected: Annotated[PeerDTO, Merge()]
+    local: Annotated[Union[DirectPeerDTO, IndirectPeerDTO], Merge()]
+    connected: Annotated[Union[DirectPeerDTO, IndirectPeerDTO], Merge()]
     device: Annotated[Device, UseLast()]
 
 
+class VirtualPair(BaseMeshModel):
+    local: Annotated[VirtualLocalDTO, Merge()]
+    connected: Annotated[VirtualPeerDTO, Merge()]
+
+
 class MeshExecutor:
     def __init__(
             self,
@@ -93,14 +105,14 @@ class MeshExecutor:
                 rule.handler(peer_neighbor, peer_device, session)
 
             try:
-                neighbor_dto = merge(PeerDTO(), peer_neighbor, session)
+                neighbor_dto = merge(DirectPeerDTO(), peer_neighbor, session)
             except MergeForbiddenError as e:
                 raise ValueError(
                     f"Handler `{handler_name}` provided session data conflicting with "
                     f"peer data for device `{neighbor_device.fqdn}`:\n" + str(e)
                 ) from e
             try:
-                device_dto = merge(PeerDTO(), peer_device, session)
+                device_dto = merge(DirectPeerDTO(), peer_device, session)
             except MergeForbiddenError as e:
                 raise ValueError(
                     f"Handler `{handler_name}` provided session data conflicting with "
@@ -132,6 +144,42 @@ class MeshExecutor:
             neighbor_peers[peer_key] = pair
         return list(neighbor_peers.values())
 
+    def _execute_virtual(self, device: Device) -> list[VirtualPair]:
+        virtual_peers: list[VirtualPair] = []
+        for rule in self._registry.lookup_virtual(device.fqdn):
+            for order_number in rule.num:
+                handler_name = self._handler_name(rule.handler)
+                logger.debug("Running direct handler: %s", handler_name)
+                session = MeshSession()
+                peer_device = VirtualLocal(rule.match, device)
+                peer_virtual = VirtualPeer(num=order_number)
+
+                rule.handler(peer_device, peer_virtual, session)
+
+                try:
+                    virtual_dto = merge(VirtualPeerDTO(), peer_virtual, session)
+                except MergeForbiddenError as e:
+                    raise ValueError(
+                        f"Handler `{handler_name}` provided session data conflicting with "
+                        f"virtual peer data for device `{device.fqdn}` and num={order_number}:\n" + str(e)
+                    ) from e
+                try:
+                    device_dto = merge(VirtualLocalDTO(), peer_device, session)
+                except MergeForbiddenError as e:
+                    raise ValueError(
+                        f"Handler `{handler_name}` provided session data conflicting with "
+                        f"peer data for device `{device.fqdn}`:\n" + str(e)
+                    ) from e
+
+                if not hasattr(device_dto, "svi"):
+                    raise ValueError(
+                        f"Handler `{handler_name}` did not provide `svi` number. "
+                        "Virtual peer must be connected to SVI interface."
+                    )
+                pair = VirtualPair(local=device_dto, connected=virtual_dto)
+                virtual_peers.append(pair)
+        return virtual_peers
+
     def _execute_indirect(self, device: Device, all_fqdns: list[str]) -> list[Pair]:
         # we can have multiple rules for the same pair
         # we merge them according to remote fqdn
@@ -152,14 +200,14 @@ class MeshExecutor:
                 rule.handler(peer_connected, peer_device, session)
 
             try:
-                connected_dto = merge(PeerDTO(), peer_connected, session)
+                connected_dto = merge(IndirectPeerDTO(), peer_connected, session)
             except MergeForbiddenError as e:
                 raise ValueError(
                     f"Handler `{handler_name}` provided session data conflicting with "
                     f"peer data for device `{connected_device.fqdn}`:\n" + str(e)
                 ) from e
             try:
-                device_dto = merge(PeerDTO(), peer_device, session)
+                device_dto = merge(IndirectPeerDTO(), peer_device, session)
             except MergeForbiddenError as e:
                 raise ValueError(
                     f"Handler `{handler_name}` provided session data conflicting with "
@@ -193,7 +241,10 @@ class MeshExecutor:
         return list(connected_peers.values())  # FIXME
 
     def _to_bgp_peer(self, pair: Pair, interface: Optional[str]) -> Peer:
-        return to_bgp_peer(pair.local, pair.connected, pair.device, interface)
+        return to_bgp_peer(pair.local, pair.connected, pair.device.hostname, interface)
+
+    def _virtual_to_bgp_peer(self, pair: VirtualPair, interface: Optional[str]) -> Peer:
+        return to_bgp_peer(pair.local, pair.connected, "", interface)
 
     def _to_bgp_global(self, global_options: GlobalOptionsDTO) -> GlobalOptions:
         return to_bgp_global_options(global_options)
@@ -225,6 +276,9 @@ class MeshExecutor:
         target_interface.add_addr(changes.addr, changes.vrf)
         return target_interface.name
 
+    def _apply_virtual_interface_changes(self, device: Device, local: VirtualLocalDTO) -> str:
+        return device.add_svi(local.svi).name  # we check if SVI configured in execute method
+
     def execute_for(self, device: Device) -> MeshExecutionResult:
         all_fqdns = self._storage.resolve_all_fdnds()
 
@@ -239,6 +293,13 @@ class MeshExecutor:
             )
             peers.append(self._to_bgp_peer(direct_pair, target_interface))
 
+        for virtual_pair in self._execute_virtual(device):
+            target_interface = self._apply_virtual_interface_changes(
+                device,
+                virtual_pair.local,
+            )
+            peers.append(self._virtual_to_bgp_peer(virtual_pair, target_interface))
+
         for connected_pair in self._execute_indirect(device, all_fqdns):
             peers.append(self._to_bgp_peer(connected_pair, None))
 

{annet-0.16.12 → annet-0.16.14}/annet/mesh/models_converter.py

@@ -1,14 +1,18 @@
 from dataclasses import dataclass
 from ipaddress import ip_interface
-from typing import Optional
+from typing import Optional, Union
 
 from adaptix import Retort, loader, Chain, name_mapping
 
-from .peer_models import PeerDTO
-from ..bgp_models import GlobalOptions, VrfOptions, FamilyOptions, Peer, PeerGroup, ASN, PeerOptions
+from .peer_models import DirectPeerDTO, IndirectPeerDTO, VirtualPeerDTO, VirtualLocalDTO
+from ..bgp_models import Aggregate, GlobalOptions, VrfOptions, FamilyOptions, Peer, PeerGroup, ASN, PeerOptions
 from ..storage import Device
 
 
+PeerDTO = Union[DirectPeerDTO, IndirectPeerDTO, VirtualPeerDTO]
+LocalDTO = Union[DirectPeerDTO, IndirectPeerDTO, VirtualLocalDTO]
+
+
 @dataclass
 class InterfaceChanges:
     addr: str
@@ -46,6 +50,7 @@ retort = Retort(
         loader(GlobalOptions, ObjMapping, Chain.FIRST),
         loader(VrfOptions, ObjMapping, Chain.FIRST),
         loader(FamilyOptions, ObjMapping, Chain.FIRST),
+        loader(Aggregate, ObjMapping, Chain.FIRST),
         loader(PeerOptions, ObjMapping, Chain.FIRST),
         name_mapping(PeerOptions, map={
             "local_as": "asnum",
@@ -62,14 +67,13 @@ to_bgp_global_options = retort.get_loader(GlobalOptions)
 to_interface_changes = retort.get_loader(InterfaceChanges)
 
 
-def to_bgp_peer(local: PeerDTO, connected: PeerDTO, connected_device: Device, interface: Optional[str]) -> Peer:
+def to_bgp_peer(local: LocalDTO, connected: PeerDTO, connected_hostname: str, interface: Optional[str]) -> Peer:
     options = retort.load(local, PeerOptions)
-    # TODO validate `lagg_links` before conversion
     result = Peer(
         addr=str(ip_interface(connected.addr).ip),
         interface=interface,
         remote_as=ASN(connected.asnum),
-        hostname=connected_device.hostname,
+        hostname=connected_hostname,
         options=options,
     )
     # connected

{annet-0.16.12 → annet-0.16.14}/annet/mesh/peer_models.py

@@ -61,7 +61,7 @@ class _OptionsDTO(_SharedOptionsDTO):
     af_rib_group: Optional[str]
     af_loops: int
     hold_time: int
-    listen_network: bool
+    listen_network: list[str]
     remove_private: bool
     as_override: bool
     aigp: bool
@@ -77,17 +77,41 @@ class _OptionsDTO(_SharedOptionsDTO):
     mtu: int
 
 
-class PeerDTO(MeshSession, _OptionsDTO):
+class DirectPeerDTO(MeshSession, _OptionsDTO):
     pod: int
     addr: str
     description: str
+    update_source: str
 
     subif: int
     lag: Optional[int]
     lag_links_min: Optional[int]
     svi: Optional[int]
 
-    group_name: str
+
+class IndirectPeerDTO(MeshSession, _OptionsDTO):
+    pod: int
+    addr: str
+    description: str
+    update_source: str
+
+
+class VirtualLocalDTO(BaseMeshModel):
+    asnum: int
+    pod: int
+    addr: str
+    description: str
+
+    import_policy: str
+    export_policy: str
+    update_source: str
+
+    svi: int
+
+
+class VirtualPeerDTO(MeshSession, _OptionsDTO):
+    addr: str
+    description: str
 
 
 class MeshPeerGroup(_OptionsDTO):

{annet-0.16.12 → annet-0.16.14}/annet/mesh/registry.py

@@ -1,13 +1,13 @@
 from dataclasses import dataclass
-from typing import Callable, Any
+from typing import Callable, Any, Sequence
 
 from .match_args import MatchExpr, PairMatcher, SingleMatcher
 from .match_args import MatchedArgs
 from .device_models import GlobalOptionsDTO
-from .peer_models import PeerDTO, MeshSession
+from .peer_models import MeshSession, IndirectPeerDTO, VirtualLocalDTO, VirtualPeerDTO, DirectPeerDTO
 
 
-class DirectPeer(PeerDTO):
+class DirectPeer(DirectPeerDTO):
     match: MatchedArgs
     device: Any
     ports: list[str]
@@ -19,7 +19,7 @@ class DirectPeer(PeerDTO):
         self.ports = ports
 
 
-class IndirectPeer(PeerDTO):
+class IndirectPeer(IndirectPeerDTO):
     match: MatchedArgs
     device: Any
 
@@ -29,6 +29,20 @@ class IndirectPeer(PeerDTO):
         self.device = device
 
 
+class VirtualLocal(VirtualLocalDTO):
+    match: MatchedArgs
+    device: Any
+
+    def __init__(self, match: MatchedArgs, device: Any) -> None:
+        super().__init__()
+        self.match = match
+        self.device = device
+
+
+class VirtualPeer(VirtualPeerDTO):
+    num: int
+
+
 class GlobalOptions(GlobalOptionsDTO):
     match: MatchedArgs
     device: Any
@@ -50,6 +64,7 @@ class GlobalRule:
 
 DirectHandler = Callable[[DirectPeer, DirectPeer, MeshSession], None]
 IndirectHandler = Callable[[IndirectPeer, IndirectPeer, MeshSession], None]
+VirtualHandler = Callable[[VirtualLocal, VirtualPeer, MeshSession], None]
 
 
 @dataclass
@@ -66,6 +81,14 @@ class IndirectRule:
     handler: IndirectHandler
 
 
+@dataclass
+class VirtualRule:
+    __slots__ = ("matcher", "num", "handler")
+    matcher: SingleMatcher
+    num: Sequence[int]
+    handler: VirtualHandler
+
+
 @dataclass
 class MatchedGlobal:
     __slots__ = ("match", "handler")
@@ -95,11 +118,20 @@ class MatchedIndirectPair:
     match_right: MatchedArgs
 
 
+@dataclass
+class MatchedVirtualPair:
+    __slots__ = ("match", "num", "handler")
+    match: MatchedArgs
+    num: Sequence[int]
+    handler: VirtualHandler
+
+
 class MeshRulesRegistry:
     def __init__(self, match_short_name: bool = False):
         self.direct_rules: list[DirectRule] = []
         self.indirect_rules: list[IndirectRule] = []
         self.global_rules: list[GlobalRule] = []
+        self.virtual_rules: list[VirtualRule] = []
         self.nested: list[MeshRulesRegistry] = []
         self.match_short_name = match_short_name
 
@@ -142,6 +174,17 @@ class MeshRulesRegistry:
 
         return register
 
+    def virtual(
+            self, peer_mask: str, num: Sequence[int], *match: MatchExpr,
+    ) -> Callable[[VirtualHandler], VirtualHandler]:
+        matcher = SingleMatcher(peer_mask, match)
+
+        def register(handler: VirtualHandler) -> VirtualHandler:
+            self.virtual_rules.append(VirtualRule(matcher, num, handler))
+            return handler
+
+        return register
+
     def lookup_direct(self, device: str, neighbors: list[str]) -> list[MatchedDirectPair]:
         found = []
         device = self._normalize_host(device)
@@ -198,6 +241,20 @@ class MeshRulesRegistry:
             found.extend(registry.lookup_indirect(device, devices))
         return found
 
+    def lookup_virtual(self, device: str) -> list[MatchedVirtualPair]:
+        found = []
+        device = self._normalize_host(device)
+        for rule in self.virtual_rules:
+            if args := rule.matcher.match_one(device):
+                found.append(MatchedVirtualPair(
+                    handler=rule.handler,
+                    match=args,
+                    num=rule.num,
+                ))
+        for registry in self.nested:
+            found.extend(registry.lookup_virtual(device))
+        return found
+
     def lookup_global(self, device: str) -> list[MatchedGlobal]:
         found = []
         device = self._normalize_host(device)