ms-split-router 0.1.0__tar.gz

ms_split_router-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Generated output
+output/

ms_split_router-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `--print-example-config` prints the annotated YAML bundled in the installed package without fetching data,
+  inspecting links or modifying system configuration.
+- `--ipv6`/`--no-ipv6` options that override `routes.ipv6` on every split link. With `--no-ipv6`, fetched data is
+  also collected with `--no-ipv6`.
+
+### Changed
+
+- The canonical example moved from `examples/config.yaml` to `src/ms_split_router/example_config.yaml` so it is
+  available in wheels and editable installations. It defaults to live fetching rather than a repository-relative
+  data file; use `--print-example-config` to create a configuration outside a checkout.
+- `routes.ipv6: true` (and `--ipv6`) also fails when the collector data was gathered with `--no-ipv6`
+  (`metadata.options.ipv6: false`), instead of writing no Microsoft IPv6 routes. With `auto`, that case is logged
+  at info level.
+
+## [0.1.0]
+
+### Added
+
+- `ms-split-router` command (also `python -m ms_split_router`) that renders per-link split-tunnel configuration for
+  WSL2 mirrored networking from [ms-cloud-endpoints](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-cloud-endpoints) data.
+- YAML configuration with any number of split links and default links, each matched by MAC address, alternative
+  name or interface name, rendered as a full `.network` file or a `.network.d` drop-in.
+- Route selection from Azure Service Tags (globs), Microsoft 365 endpoint sets (instance, service area, category,
+  required, ExpressRoute) and the "other endpoints" page, plus extra and excluded prefixes. Prefixes are collapsed.
+- Routing-domain derivation from Microsoft 365 URLs, Private Endpoint DNS zones and the "other endpoints" page, with
+  root-domain collapsing, a built-in third-party (CA/CDN) denylist and extra/excluded domains.
+- Gateway and on-link auto-detection from `ip -json`; IPv6 routes only when the link has an IPv6 gateway (`auto`).
+- Optional `.link` file that pins a stable alternative name to the split adapter's MAC address.
+- `networkd.conf.d` (`ManageForeignRoutes=no`, `ManageForeignRoutingPolicyRules=no`) and `resolved.conf.d`
+  (`DNSSEC=no`, extra keys) drop-ins.
+- Data from a collector file or by running `ms-cloud-endpoints` with arguments narrowed to the configuration.
+- `--output`, `--install`/`--root`, `--diff`, `--check`, `--prune`, `--reload` and `--show-links`.

ms_split_router-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Radux Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ms_split_router-0.1.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.5
+Name: ms-split-router
+Version: 0.1.0
+Summary: Generate systemd-networkd and systemd-resolved per-link split-tunnel configuration for Microsoft 365, Entra and Azure from ms-cloud-endpoints data.
+Project-URL: Homepage, https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter
+Project-URL: Source, https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-split-router
+Project-URL: Documentation, https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-split-router/blob/main/README.md
+Project-URL: Issues, https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-split-router/issues
+Project-URL: Changelog, https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-split-router/blob/main/CHANGELOG.md
+Author-email: Jayonics <jameshopwood1998@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: azure,entra,microsoft-365,office-365,routing,split-tunnel,systemd-networkd,systemd-resolved,wsl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# ms-split-router
+
+Generate **systemd-networkd** and **systemd-resolved** per-link split-tunnel configuration for **Microsoft 365,
+Microsoft Entra and Azure** on a WSL2 VM that uses
+[mirrored mode networking](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking).
+
+It is the rendering stage of
+[Azure-O365-DNS-UDR-SplitRouter](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter). It reads the
+document written by [`ms-cloud-endpoints`](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-cloud-endpoints) (or runs that command for you) and writes:
+
+| File | Purpose |
+|------|---------|
+| `/etc/systemd/network/10-ms-split-<id>.network` (or a `.network.d` drop-in) | Split link: `Domains=~…` routing-only domains, `DNS=`, `DNSDefaultRoute=no` and one `[Route]` per Microsoft prefix |
+| `/etc/systemd/network/10-ms-split-<id>.link` (optional) | Gives the split adapter a stable alternative name, matched by MAC address |
+| `/etc/systemd/network/20-ms-default-<id>.network` (or a drop-in) | Default links: `Domains=~.`, `DNSDefaultRoute=yes`, `DNS=` |
+| `/etc/systemd/networkd.conf.d/10-ms-split-router.conf` | `ManageForeignRoutes=no`, `ManageForeignRoutingPolicyRules=no` so networkd keeps WSL's routes |
+| `/etc/systemd/resolved.conf.d/10-ms-split-router.conf` | Global resolved settings (`DNSSEC=no` by default, plus any extra keys) |
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Options](#options)
+- [How the output is built](#how-the-output-is-built)
+- [Notes and limitations](#notes-and-limitations)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- Any number of **split links**, each with its own routes, domains and DNS servers (for example Microsoft 365 over a
+  VPN adapter and Azure over an ExpressRoute adapter). Overlapping prefixes or domains between links are allowed.
+- Links are matched by **MAC address**, **alternative name** or interface name. An optional `.link` file pins an
+  alternative name (for example `msvpn`) to the adapter's MAC.
+- **Full `.network` files or `.network.d` drop-ins** on top of a `.network` file you already own.
+- **Routes** from Azure Service Tags (case-insensitive globs, default `AzureCloud`), Microsoft 365 endpoint sets
+  (instance, service area, category, required, ExpressRoute), the "other endpoints" page, extra prefixes, and
+  excluded prefixes. Prefixes are widened (IPv6 to `/48` by default) and collapsed so they stay within networkd's
+  limit.
+- **Routing domains** derived from the Microsoft 365 URLs and the Private Endpoint DNS zones, reduced to their root
+  domains. Certificate authority and CDN domains (`digicert.com`, `akamaihd.net`, …) are dropped by default.
+- The **gateway and on-link flag are auto-detected** from the link's current default route (`ip -json route`).
+  IPv6 routes are only written when the link has an IPv6 gateway. `--ipv6`/`--no-ipv6` require them or leave them
+  out on every split link.
+- Output is **deterministic** (no timestamps), so `--check`, `--diff` and only-if-changed installs are reliable.
+  Every file carries a marker header, which lets `--prune` remove stale files safely.
+- The only runtime dependency is [PyYAML](https://pypi.org/project/PyYAML/). It doesn't import `ms-cloud-endpoints`.
+
+## Requirements
+
+- Python 3.12 or later (tested on 3.12, 3.13 and 3.14)
+- Linux with iproute2 (`ip -json`) for auto-detection, `--show-links` and `--reload`
+- On the target VM: systemd ≥ 249 with `systemd-networkd` and `systemd-resolved`, and WSL mirrored networking with
+  `dnsTunneling=false` (see [docs/configuration.md](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter/blob/main/docs/configuration.md#prerequisites))
+- To fetch data live: the `ms-cloud-endpoints` command on `PATH`
+
+## Installation
+
+From a clone of the [parent project](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter) with submodules
+(`git clone --recurse-submodules`), at its root:
+
+```bash
+pipx install ./ms-cloud-endpoints ./ms-split-router   # both commands, isolated
+# or
+pip install ./ms-split-router
+```
+
+Directly from GitHub:
+
+```bash
+pipx install "git+https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter.ms-split-router.git"
+```
+
+Both install the `ms-split-router` command. `python -m ms_split_router` works too.
+
+For a version-pinned deployment once both releases exist on PyPI (pipx >= 1.5):
+
+```bash
+sudo pipx install --global "ms-cloud-endpoints==0.1.0"
+sudo pipx install --global "ms-split-router==0.1.0"
+ms-cloud-endpoints --version
+ms-split-router --version
+```
+
+The collector is a separate executable, not an automatically installed Python dependency. Install both for
+live fetching; the router alone can read an existing data file. The annotated example is bundled in the installed
+package: print it with `ms-split-router --print-example-config`. For older pipx and explicit upgrade/rollback
+commands, see the parent's
+[pinned deployment guide](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter/blob/main/USAGE.md#version-pinned-deployment-from-pypi).
+Avoid `pipx upgrade`/`upgrade-all` for pinned deployments; application pins do not lock transitive dependencies.
+
+## Quick start
+
+```bash
+# 1. Find the split adapter: name, MAC, altnames, addresses and default gateways of every link
+ms-split-router --show-links
+
+# 2. Print the bundled example, then set the split adapter's MAC and DNS servers
+ms-split-router --print-example-config > split-router.yaml
+$EDITOR split-router.yaml
+
+# 3. Preview: print every file to stdout, or render into a directory tree
+ms-split-router -c split-router.yaml
+ms-split-router -c split-router.yaml -o output/
+
+# 4. Install into /etc, remove stale generated files, and reload what changed
+sudo ms-split-router -c split-router.yaml --install --prune --reload
+
+# Later, from cron or a timer: refresh only when the data or gateway changed
+sudo ms-split-router -c split-router.yaml --fetch --install --prune --reload
+```
+
+Use `--diff` to see the changes against `/` (or `--root`) first. `--check` exits with code 4 when the installed
+files are out of date.
+
+`--print-example-config` works without a configuration file, collector, root access or network connection.
+It prints and exits without inspecting links or installing/reloading anything. Shell redirection (`>`) replaces
+an existing file, so create the example only on first setup or redirect it to a new filename.
+
+## Configuration
+
+A YAML file. The [bundled example](src/ms_split_router/example_config.yaml) lists every key with its default.
+It defaults to fetching live data; uncomment `data.file` to use an existing document. The full reference
+with explanations is in [docs/configuration.md](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter/blob/main/docs/configuration.md#generator-configuration-ms-split-router).
+
+```yaml
+data:
+  file: output/ms-cloud-endpoints.json   # omit to run ms-cloud-endpoints instead
+
+split_links:
+  - id: corp-vpn
+    match: {mac: "04:92:26:8a:8f:98"}    # or {altname: msvpn} / {name: eth1}
+    altname_link: {name: msvpn}          # optional .link file
+    dns: [10.10.0.4, 10.10.0.5]
+    routes:
+      azure: {service_tags: [AzureCloud]}
+      m365: {service_areas: [Common, Exchange, SharePoint, Skype]}
+      extra_prefixes: [10.20.0.0/16]     # e.g. the vNet that holds your Private Endpoints
+
+default_links:
+  - id: internet
+    match: {name: eth0}
+    dns: [1.1.1.1, 1.0.0.1]
+```
+
+Errors name the offending key, for example `split_links[0].routes.m365.service_areas[0]: unknown value 'Teams'`.
+
+## Options
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `-c`, `--config FILE` | required for generation | Generator configuration |
+| `--data FILE` | `data.file` | Collector JSON/YAML, overriding `data.file` |
+| `--fetch` | off | Run `ms-cloud-endpoints` even when `data.file` is set |
+| `--allow-partial` | off | Continue when the collector reports failed sources |
+| `--ipv6`, `--no-ipv6` | `routes.ipv6` | Override `routes.ipv6` on every split link. `--ipv6` fails if a link has no IPv6 gateway or the data was collected with `--no-ipv6`. `--no-ipv6` also fetches without IPv6 |
+| `-o`, `--output DIR` | | Write the files as a tree under `DIR` (`DIR/etc/systemd/...`) |
+| `--install` | off | Write the files under `--root` |
+| `--root DIR` | `/` | Target root for `--install`, `--diff` and `--check` |
+| `--prune` | off | Also remove generated files (marker header) that are no longer rendered |
+| `--reload` | off | After `--install` to `/`, run the reload commands for what changed (see below) |
+| `--diff` | off | Print a unified diff against the target |
+| `--check` | off | Write nothing. Exit 4 if the target is out of date |
+| `--show-links` | | List links (name, state, MAC, altnames, addresses, gateways) and exit |
+| `--print-example-config` | | Print the bundled annotated YAML and exit; mutually exclusive with `--show-links` |
+| `-v`, `-vv` | warnings | Info (per-link route and domain counts, excluded domains) or debug logging on stderr |
+| `--version` | | Print the version |
+
+Without `-o`, `--install`, `--diff` or `--check`, the files are printed to stdout.
+
+Only changed files are written, atomically (temporary file + rename, mode `0644`). `--reload` runs:
+
+| Changed | Command(s) |
+|---------|------------|
+| `.link` | `udevadm control --reload`, `udevadm trigger --action=add --subsystem-match=net --attr-match=address=<mac>`, `udevadm settle` |
+| `networkd.conf.d` | `systemctl restart systemd-networkd` |
+| `.network` / drop-ins (only) | `networkctl reload` |
+| `resolved.conf.d` | `systemctl try-reload-or-restart systemd-resolved` |
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success (or `--check`: up to date) |
+| `1` | Error: data, discovery, rendering, writing or a reload command failed |
+| `2` | Usage or configuration error |
+| `3` | The collector reported failed sources (use `--allow-partial` to continue). Nothing was written |
+| `4` | `--check`: the target is out of date |
+
+## How the output is built
+
+**Routes.** For each split link the selected prefixes are gathered, widened to `widen_to` (IPv6 `/48` by default),
+reduced by `exclude_prefixes`, and collapsed. Each prefix becomes one `[Route]` with the link's gateway, plus
+`GatewayOnLink=yes` when the detected default route is on-link (as it is on WSL mirrored links). Generation fails
+if a link would exceed **8192 routes**, because systemd-networkd silently ignores `[Route]` sections beyond that per
+`.network` file. With the defaults, `AzureCloud` plus Microsoft 365 renders roughly 1,000 IPv4 and 400 IPv6 routes.
+
+**Domains.** From the selected Microsoft 365 endpoint sets (the link's `routes.m365` filters, or all sets if
+`routes.m365` is off), the Private Endpoint zones (`privatelink.` stripped, plus their public forwarders) and,
+optionally, the "other endpoints" page:
+
+1. Wildcards and `{placeholder}` labels are cut to the suffix after the last wildcard (`*.blob.core.windows.net` →
+   `blob.core.windows.net`).
+2. With `collapse_to_root` (default) every name is reduced to its root domain (`windows.net`). Single-label results
+   are dropped.
+3. With `exclude_third_party` (default) CA/OCSP/CDN domains are dropped. `-v` lists them.
+4. `extra` is added, `exclude` removed, and names already covered by a shorter domain are dropped.
+
+They are written as routing-only domains (`~office.com`) across several `Domains=` lines. Without `dns` servers
+the DNS layer is skipped (with a warning), because the domains would have nowhere to go.
+
+**Gateways.** `gateway4`/`gateway6: auto` takes the lowest-metric default route of the matched link at render time.
+If no IPv4 default route exists, generation fails unless `gateway4` is set explicitly or to `none`. `onlink: auto`
+copies the `onlink` flag of the detected route when it uses the same gateway.
+
+**IPv6.** `routes.ipv6: auto` (default) writes IPv6 routes only when the link has an IPv6 gateway. `true` (or
+`--ipv6`) makes them mandatory: generation fails when the link has no IPv6 gateway, or when the data was collected
+with `ms-cloud-endpoints --no-ipv6` (recorded in `metadata.options.ipv6`). `false` (or `--no-ipv6`) leaves them out.
+When the data is fetched and no split link wants IPv6 routes, the collector runs with `--no-ipv6`.
+
+## Notes and limitations
+
+- **Render-time detection.** Routes carry a fixed gateway. Re-run the generator (for example with `--check` or from a
+  timer) when the Windows adapter's gateway changes.
+- **First match wins.** networkd uses the first `.network` file, in lexical order, whose `[Match]` fits. Your own
+  `10-eth1.network` sorts before `10-ms-split-…`. Either remove it, or use `style: dropin` with `base:` set to it.
+- **`.link` files** only apply on udev "add" events. `--reload` triggers one, but the most reliable way is
+  `wsl --shutdown`. The generated file keeps the naming and alternative-name policies of systemd's `99-default.link`,
+  which it supersedes for that device, and sets `MACAddressPolicy=none` so the mirrored MAC is never changed.
+- **Third-party denylist.** It is built in (`domains.THIRD_PARTY_DOMAINS`). To route one of those domains anyway,
+  set `exclude_third_party: false` or add it to `extra`.
+- **Root-domain collapsing** routes whole Microsoft domains (for example `~live.com`, `~bing.com`) to the split
+  link. Set `collapse_to_root: false` for the exact suffixes instead (longer list).
+- **Validated with systemd 259.** The generated files were loaded by systemd-networkd 259 against a link set up
+  like a WSL mirrored link: all routes installed, foreign addresses and routes kept, DNS and domains handed to
+  resolved.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e . --group dev      # pip >= 25.1
+
+pytest                            # offline: fixtures/collector.json, fake `ip -json` output, golden files
+ruff check . && ruff format --check .
+python -m build
+```
+
+Golden files in `tests/fixtures/golden/` hold the exact expected output. Regenerate them deliberately when the
+rendering changes and review the diff.
+
+### Releases
+
+The existing workflow also runs on `v*` tag pushes. Stable tags such as `v0.1.0` must exactly match the version
+in the built wheel (sourced from `src/ms_split_router/__init__.py`); prerelease or mismatched tags fail.
+After lint, tests and build checks pass, the `pypi` environment gates PyPI Trusted Publishing. A subsequent
+job creates a GitHub Release with the same wheel and source distribution. Pull requests, branch pushes and
+manual runs never publish.
+
+Before tagging, configure this repository's `pypi` GitHub environment to allow deployments only from `v*`
+tags (optionally with required reviewers, where the GitHub plan supports them). Register a PyPI Trusted Publisher for project `ms-split-router`,
+owner `Jayonics`, repository `Azure-O365-DNS-UDR-SplitRouter.ms-split-router`, workflow
+`ms-split-router.yml`, environment `pypi`. No PyPI API token is required. Optionally restrict release-tag
+creation and mutation with a tag ruleset.
+
+Commit the version and changelog first, then release the reviewed commit:
+
+```bash
+git tag -a v0.1.0 -m "Release 0.1.0"
+git push origin main
+git push origin v0.1.0
+```
+
+Pushing the tag publishes automatically once checks pass (or after approval, if reviewers are required). Never move a published tag or reuse an uploaded PyPI
+version. If GitHub release creation fails after PyPI succeeds, re-run only failed jobs, not the whole workflow.
+See the parent's [release procedure](https://github.com/Jayonics/Azure-O365-DNS-UDR-SplitRouter/blob/main/USAGE.md#publishing-releases)
+for the complete setup and coordinated deployment process.
+
+### Layout
+
+```
+src/ms_split_router/
+  cli.py        command line, exit codes
+  config.py     YAML -> validated dataclasses
+  data.py       collector document loading / ms-cloud-endpoints subprocess
+  select.py     per-link prefix selection
+  domains.py    routing-domain derivation, third-party denylist
+  discover.py   `ip -json` link and gateway discovery
+  generate.py   combines the above into rendered files, route-limit check
+  render.py     INI rendering of every file type
+  install.py    plan/diff/atomic write/prune/reload
+  netutil.py    prefix and domain helpers
+```
+
+## License
+
+[MIT](LICENSE) © Radux Technologies