obs-network-tools

Autonomous OBS packaging pipeline for network diagnostic and benchmarking tools not commonly packaged by Linux distributions. Packages are built and published automatically when upstream releases a new version — install them with your native package manager (zypper, apt, dnf).

Packages

Package	Description	Upstream
nic-xray	Ethernet physical connectivity diagnostic tool, with the `nic-health` NIC health checks	ciroiriarte/nic-xray
nic-xray-fleet	Fleet sweep over SSH (`nic-sweep`) and multi-site reports (`nic-report`) for the operator host; built from the nic-xray source	ciroiriarte/nic-xray
switch-xray	Switch port diagnostics and documentation via SNMP	ciroiriarte/switch-xray
ttl	Traceroute/mtr-style TUI (requires Rust >= 1.88)	lance0/ttl
xfr	Network bandwidth testing TUI (requires Rust >= 1.88)	lance0/xfr
create-network-tshoot-livecd	Boot-only cabling-diagnostics LiveCD builder (live-build wrapper) — Debian/Ubuntu only	ciroiriarte/network-tshoot-livecd
live-build	Current live-build, co-packaged for Ubuntu whose stock 3.0~a57 is broken — Debian/Ubuntu only	Debian live-team

Supported Distributions

Distribution	Repository Alias	Arch	nic-xray	switch-xray	ttl	xfr
openSUSE Tumbleweed	`openSUSE_Tumbleweed`	x86_64, aarch64	✓	✓	✓	✓
openSUSE Slowroll	`openSUSE_Slowroll`	x86_64	✓	✓	✓	✓
openSUSE Leap 16.1	`openSUSE_Leap_16.1`	x86_64, aarch64	✓	✓	✓	✓
openSUSE Leap 16.0	`openSUSE_Leap_16.0`	x86_64, aarch64	✓	✓	✓	✓
openSUSE Leap 15.6	`openSUSE_Leap_15.6`	x86_64, aarch64	✓	✓	—	—
Rocky Linux 9	`Rocky_9`	x86_64, aarch64	✓	✓	✓	✓
Rocky Linux 10	`Rocky_10`	x86_64, aarch64	✓	✓	✓	✓
Debian 13	`Debian_13`	x86_64, aarch64	✓	✓	—	—
Ubuntu 22.04 LTS	`Ubuntu_22.04`	x86_64, aarch64	✓	✓	—	—
Ubuntu 24.04 LTS	`Ubuntu_24.04`	x86_64, aarch64	✓	✓	—	—

Note: ttl and xfr require Rust >= 1.88, which is not yet available in Leap 15.6, Debian 13 or Ubuntu repos. Builds will automatically succeed once a compatible Rust version ships.

Build tooling (Debian/Ubuntu only): create-network-tshoot-livecd and live-build are published for Debian 13, Ubuntu 22.04 and Ubuntu 24.04 only — not for openSUSE/Rocky. create-network-tshoot-livecd is a live-build wrapper, and live-build is a Debian-family tool that cannot build a Debian/Ubuntu live image from an openSUSE/Rocky host. live-build is co-packaged because Ubuntu 22.04/24.04 ship a broken 3.0~a57 fork; the epoch (1:) keeps our build ahead of it. On Debian 13 the distribution's own live-build already works.

create-network-tshoot-livecd

Builds a standalone, boot-only cabling-diagnostics live ISO. It boots a target host into a RAM-resident environment, identifies it from a CSV persona inventory (DMI serial → hostname, optional bonded-VLAN management IP), brings up every physical NIC, runs nic-xray --all --output csv plus lldpd, and prints a per-NIC cabling report to the VGA console and an auto-discovered serial console, then drops to a root shell. It writes nothing to local disks.

# On a Debian 13 / Ubuntu 22.04 / Ubuntu 24.04 build host (needs root for lb build):
sudo apt install create-network-tshoot-livecd     # pulls live-build from this repo
sudo create-network-tshoot-livecd -c hosts.csv -o /var/tmp/iso/
# CSV columns: serial,hostname,bond_members(:-separated),ip

Installation

openSUSE (zypper)

zypper addrepo https://download.opensuse.org/repositories/home:/ciriarte:/network-tools/openSUSE_Tumbleweed/ obs-network-tools
zypper refresh
zypper install nic-xray switch-xray ttl xfr

Replace openSUSE_Tumbleweed with your repository alias.

Debian / Ubuntu (apt)

echo "deb https://download.opensuse.org/repositories/home:/ciriarte:/network-tools/Debian_13/ ./" \
  | sudo tee /etc/apt/sources.list.d/obs-network-tools.list
curl -fsSL "https://download.opensuse.org/repositories/home:/ciriarte:/network-tools/Debian_13/Release.key" \
  | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/obs-network-tools.gpg
sudo apt update
sudo apt install nic-xray switch-xray

Replace Debian_13 with your repository alias (Ubuntu_24.04, Ubuntu_22.04, etc.).

Rocky Linux (dnf)

dnf config-manager --add-repo \
  https://download.opensuse.org/repositories/home:/ciriarte:/network-tools/Rocky_9/home:ciriarte:network-tools.repo
dnf install nic-xray switch-xray ttl xfr

Replace Rocky_9 with Rocky_10 for Rocky Linux 10.

Note: nic-xray depends on lldpd, available via EPEL:
dnf install epel-release

nic-xray-fleet (operator host)

The fleet nodes need only nic-xray (it carries nic-health). On the operator or jump host that sweeps them, also install nic-xray-fleet with the same package manager:

zypper install nic-xray-fleet     # openSUSE
sudo apt install nic-xray-fleet   # Debian / Ubuntu
dnf install nic-xray-fleet        # Rocky Linux (EPEL enabled, for lldpd)

It installs /usr/bin/nic-sweep, /usr/bin/nic-report, their man pages and bash completions, and the starter rule catalog /usr/share/nic-xray/nic-report-rules.json. It requires nic-xray of the same version, jq, an SSH client and Python 3.9 or newer (on Leap 15.6, whose python3 is 3.6, it uses python311). PDF reports need WeasyPrint (python3-weasyprint), which is only suggested.

How Auto-Update Works

All three packages are fully autonomous — when upstream pushes a new tag, the pipeline picks it up within 24 hours with no manual steps.

nic-xray and switch-xray

The GitHub Actions workflows (nic-xray, switch-xray) run daily and:

Query the GitHub API for the latest release tag on the upstream repo.
Compare with the current version in git (the .changes file; _service for create-network-tshoot-livecd).
If changed: update _service, changelogs, commit to this repo.

OBS then runs its source services (tar_scm + set_version + recompress) to fetch, package, and build.

ttl and xfr

Rust packages require pre-committed source and vendor tarballs because OBS build workers have no internet access. The GitHub Actions workflows (ttl, xfr) run daily and:

Query the GitHub API for the latest tag on lance0/ttl or lance0/xfr.
If changed: install Rust, clone at the new tag, run cargo vendor.
Build the source tarball and vendor archive (vendor.tar.zst).
Update spec, changelogs, commit to this repo.

Pushing to OBS (all workflows)

The git commit and the OBS upload are decided separately. Each run also reads the version currently on OBS (from the package's .changes, or _service for create-network-tshoot-livecd) and pushes whenever OBS is behind upstream. If an upload fails after the git commit (for example an OBS 503), the next daily run sees OBS still behind and pushes again, so nothing is left stale. If OBS cannot be read at all, the run falls back to the git comparison and logs a warning.

The push mirrors packages/<name>/ exactly into the OBS package: every packaging file (spec, .changes, .dsc, debian.*, _service, tarballs) is sent, and files no longer in git (old tarballs) are removed. The checkout-to-commit sequence gets 3 attempts, one minute apart, each from a fresh checkout. The package must already exist on OBS: the workflows do not create it.

To send a packaging-only change without a new version, run the workflow by hand with sync checked (gh workflow run update-nic-xray.yml -f sync=true; every workflow has the input). For the tar_scm packages, sync only works when the tag pinned in _service already contains every file the spec installs: publish the upstream release first.

Maintainer Guide

Prerequisites

Install and configure the osc CLI client:

# openSUSE
zypper install osc

# Ubuntu/Debian
apt install osc

# Configure credentials
osc config https://api.opensuse.org
# Enter your OBS username and password when prompted

Required GitHub secrets

Add these secrets to the repository (Settings > Secrets > Actions):

Secret	Value
`OBS_PASSWORD`	OBS account password for `ciriarte`

OBS project setup (one-time)

Create the OBS project and configure repositories:

osc meta prj -e home:ciriarte:network-tools

Use the following project metadata XML:

<project name="home:ciriarte:network-tools">
  <title>Network Tools</title>
  <description>Packaging pipeline for network diagnostic and benchmarking tools</description>
  <person userid="ciriarte" role="maintainer"/>
  <repository name="openSUSE_Tumbleweed">
    <path project="openSUSE:Factory" repository="snapshot"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="openSUSE_Slowroll">
    <path project="openSUSE:Slowroll" repository="standard"/>
    <arch>x86_64</arch>
    <!-- aarch64 omitted: openSUSE:Slowroll has no aarch64 path in OBS -->
  </repository>
  <repository name="openSUSE_Leap_16.1">
    <!-- devel:languages:rust provides Rust >= 1.88 for ttl and xfr -->
    <path project="devel:languages:rust" repository="16.1"/>
    <path project="openSUSE:Leap:16.1" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="openSUSE_Leap_16.0">
    <!-- devel:languages:rust provides Rust >= 1.88 for ttl and xfr -->
    <path project="devel:languages:rust" repository="16.0"/>
    <path project="openSUSE:Leap:16.0" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="openSUSE_Leap_15.6">
    <path project="devel:languages:rust" repository="15.6"/>
    <path project="openSUSE:Leap:15.6" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="Debian_13">
    <path project="Debian:13" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="Rocky_9">
    <path project="RockyLinux:9" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="Rocky_10">
    <path project="RockyLinux:10" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="Ubuntu_22.04">
    <path project="Ubuntu:22.04" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
  <repository name="Ubuntu_24.04">
    <path project="Ubuntu:24.04" repository="standard"/>
    <arch>x86_64</arch>
    <arch>aarch64</arch>
  </repository>
</project>

Deploying package changes to OBS

First-time setup (any package):

osc co home:ciriarte:network-tools
mkdir -p home:ciriarte:network-tools/<package>
cp packages/<package>/* home:ciriarte:network-tools/<package>/
cd home:ciriarte:network-tools/<package>
osc add *
osc commit -m "Initial package"

Updating an existing package:

cd home:ciriarte:network-tools/<package>
osc up
cp /path/to/obs-network-tools/packages/<package>/* .
osc commit -m "Update to version X.Y"

Manual version updates

Version updates are normally handled automatically by GitHub Actions. To trigger an update immediately, run the workflow manually from the Actions tab.

nic-xray (local alternative):

./scripts/update-nic-xray-version.sh --push

ttl / xfr (fully manual, e.g. without GitHub Actions):

# Example: updating ttl to v0.20.0
git clone --branch v0.20.0 https://github.com/lance0/ttl ttl-src
cd ttl-src && cargo vendor
mkdir -p .cargo
printf '[source.crates-io]\nreplace-with = "vendored-sources"\n\n[source.vendored-sources]\ndirectory = "vendor"\n' \
  > .cargo/config.toml
cd ..
tar -czf ttl-0.20.0.tar.gz --exclude='.git' --exclude='vendor' \
  --transform='s|^ttl-src|ttl-0.20.0|' ttl-src/
tar -I "zstd" -cf vendor.tar.zst -C ttl-src .cargo/config.toml vendor/
cp ttl-0.20.0.tar.gz vendor.tar.zst packages/ttl/
# Then update ttl.spec (Version, %changelog), ttl.dsc, ttl.changes, debian.changelog
# and commit to git + OBS

The same pattern applies to xfr (substitute xfr and github.com/lance0/xfr).

Verification

After pushing to OBS, verify the builds:

# Check build results
osc results home:ciriarte:network-tools nic-xray
osc results home:ciriarte:network-tools switch-xray
osc results home:ciriarte:network-tools ttl
osc results home:ciriarte:network-tools xfr

# Watch live build log (example: Tumbleweed x86_64)
osc buildlog home:ciriarte:network-tools nic-xray openSUSE_Tumbleweed x86_64

On each installed system:

# RPM (openSUSE / Rocky Linux)
rpm -qi nic-xray

# Deb (Ubuntu)
dpkg -s nic-xray

# Functional tests
sudo nic-xray
sudo switch-xray --help
ttl --help
xfr --help

Repository Structure

Click to expand

obs-network-tools/
├── CLAUDE.md                       # Project instructions for Claude Code
├── README.md                       # This file
├── .github/workflows/
│   ├── update-nic-xray.yml         # Daily: detect new tag, update changelogs, push to OBS when OBS is behind (or on request: sync)
│   ├── update-switch-xray.yml      # Daily: same as nic-xray
│   ├── update-create-network-tshoot-livecd.yml  # Daily: same as nic-xray (Debian/Ubuntu only)
│   ├── update-ttl.yml              # Daily: detect new tag, vendor deps, rebuild tarballs, push to OBS when OBS is behind
│   └── update-xfr.yml              # Daily: same as ttl
├── scripts/
│   └── update-nic-xray-version.sh  # Manual alternative to the nic-xray workflow above
└── packages/
    ├── nic-xray/
    │   ├── _service           # tar_scm: fetch pinned tag from github.com/ciroiriarte/nic-xray
    │   ├── nic-xray.spec      # RPM spec (openSUSE + Rocky Linux): nic-xray and nic-xray-fleet
    │   ├── nic-xray.changes   # openSUSE changelog
    │   ├── nic-xray.dsc       # Debian source package descriptor
    │   ├── debian.control     # Debian/Ubuntu package metadata: nic-xray and nic-xray-fleet
    │   ├── debian.changelog   # Debian/Ubuntu changelog
    │   └── debian.rules       # Debian build rules
    ├── switch-xray/
    │   ├── _service           # tar_scm: fetch pinned tag from github.com/ciroiriarte/switch-xray
    │   ├── switch-xray.spec   # RPM spec (openSUSE + Rocky Linux)
    │   ├── switch-xray.changes # openSUSE changelog
    │   ├── switch-xray.dsc    # Debian source package descriptor
    │   ├── debian.control     # Debian/Ubuntu package metadata
    │   ├── debian.changelog   # Debian/Ubuntu changelog
    │   └── debian.rules       # Debian build rules
    ├── ttl/
    │   ├── _service           # cargo_vendor (manual mode, documents vendoring requirement)
    │   ├── ttl-0.19.0.tar.gz  # Source tarball (committed)
    │   ├── vendor.tar.zst     # Vendored Rust dependencies (includes .cargo/config.toml)
    │   ├── ttl.spec           # RPM spec (openSUSE + Rocky Linux)
    │   ├── ttl.changes        # openSUSE changelog
    │   ├── ttl.dsc            # Debian source package descriptor
    │   ├── debian.control     # Debian/Ubuntu package metadata
    │   ├── debian.changelog   # Debian/Ubuntu changelog
    │   ├── debian.rules       # Debian build rules
    │   └── debian.postinst    # Post-install: setcap cap_net_raw+ep
    └── xfr/
        ├── _service           # cargo_vendor (manual mode, documents vendoring requirement)
        ├── xfr-0.9.6.tar.gz   # Source tarball (committed)
        ├── vendor.tar.zst     # Vendored Rust dependencies (includes .cargo/config.toml)
        ├── xfr.spec           # RPM spec (openSUSE + Rocky Linux)
        ├── xfr.changes        # openSUSE changelog
        ├── xfr.dsc            # Debian source package descriptor
        ├── debian.control     # Debian/Ubuntu package metadata
        ├── debian.changelog   # Debian/Ubuntu changelog
        └── debian.rules       # Debian build rules

License

This packaging pipeline is maintained by Ciro Iriarte. The packaged software is distributed under its respective upstream licenses.

Navigation Menu

Repository navigation

About

Repository files navigation

obs-network-tools

Table of Contents

Packages

Supported Distributions

create-network-tshoot-livecd

Installation

openSUSE (zypper)

Debian / Ubuntu (apt)

Rocky Linux (dnf)

nic-xray-fleet (operator host)

How Auto-Update Works

nic-xray and switch-xray

ttl and xfr

Pushing to OBS (all workflows)

Maintainer Guide

Repository Structure

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
packages		packages
scripts		scripts
CLAUDE.md		CLAUDE.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

obs-network-tools

Table of Contents

Packages

Supported Distributions

create-network-tshoot-livecd

Installation

openSUSE (zypper)

Debian / Ubuntu (apt)

Rocky Linux (dnf)

nic-xray-fleet (operator host)

How Auto-Update Works

nic-xray and switch-xray

ttl and xfr

Pushing to OBS (all workflows)

Maintainer Guide

Repository Structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages