{"id":50717488,"url":"https://github.com/gaetanlhf/lldpos","last_synced_at":"2026-06-09T20:00:54.238Z","repository":{"id":351764676,"uuid":"1081806718","full_name":"gaetanlhf/lldpOS","owner":"gaetanlhf","description":"Lightweight bootable Linux distribution for LLDP discovery and network diagnostics","archived":false,"fork":false,"pushed_at":"2026-04-16T10:48:12.000Z","size":45,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-16T12:38:17.882Z","etag":null,"topics":["bootable","bootable-live-cd","bootable-usb","lightweight","linux","live-os","lldp","lldpd","network","networking","small"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gaetanlhf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T10:10:40.000Z","updated_at":"2026-04-16T10:46:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gaetanlhf/lldpOS","commit_stats":null,"previous_names":["gaetanlhf/lldpos"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/gaetanlhf/lldpOS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaetanlhf%2FlldpOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaetanlhf%2FlldpOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaetanlhf%2FlldpOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaetanlhf%2FlldpOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gaetanlhf","download_url":"https://codeload.github.com/gaetanlhf/lldpOS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gaetanlhf%2FlldpOS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34123172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootable","bootable-live-cd","bootable-usb","lightweight","linux","live-os","lldp","lldpd","network","networking","small"],"created_at":"2026-06-09T20:00:53.348Z","updated_at":"2026-06-09T20:00:54.220Z","avatar_url":"https://github.com/gaetanlhf.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"center\"\u003elldpOS\u003c/h2\u003e\n\u003cp align=\"center\"\u003eA lightweight bootable Linux distribution for LLDP discovery and network diagnostics\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#about\"\u003eAbout\u003c/a\u003e •\n    \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n    \u003ca href=\"#building\"\u003eBuilding\u003c/a\u003e •\n    \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n    \u003ca href=\"#network-tools\"\u003eNetwork Tools\u003c/a\u003e •\n    \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nlldpOS is a minimal, bootable Linux distribution designed for network engineers and system administrators. It provides an intuitive TUI interface for LLDP neighbor discovery and a comprehensive set of network diagnostic tools. Boot from ISO or USB and instantly access your network infrastructure information.\n\n## Features\n\n- ✅ **LLDP Discovery** with interactive TUI interface\n- ✅ **Unique hostname generation** - automatically creates memorable hostnames (e.g., `brave-falcon-1234`) that are advertised via LLDP, making it easy to identify the server from switch CLI using `show lldp neighbors`\n- ✅ **Comprehensive network tools** - ping, traceroute, tcpdump, iperf3, mtr, and more\n- ✅ **Network configuration utilities** - DHCP, static IP, VLAN, bonding, bridging\n- ✅ **BIOS and UEFI boot support** for maximum hardware compatibility\n- ✅ **Small footprint** - minimal base system with essential networking packages\n- ✅ **Firmware support** - includes drivers for common network adapters (Intel, Realtek, Broadcom, QLogic)\n- ✅ **Interactive shell access** with built-in network configuration helpers\n- ✅ **Live system** - runs entirely from RAM, no installation required\n\n## Building\n\n### Prerequisites\n\nBuilding lldpOS requires a Debian-based system with the following packages:\n\n```bash\nsudo apt install wget xorriso grub-pc-bin grub-efi-amd64-bin grub-common mtools dosfstools cpio xz-utils\n```\n\nAlternatively, build inside Docker (see `docker-build.sh`) — no host packages required beyond Docker itself.\n\n### Build Process\n\nThe build script creates a bootable ISO with all required components:\n\n```bash\n# Clone or download the repository\ngit clone \u003crepository-url\u003e\ncd lldpOS\n\n# Build the ISO\nsudo ./build.sh\n```\n\nThe build process will:\n1. Fetch the Alpine Linux minirootfs and bootstrap it\n2. Install networking tools and firmware via `apk`\n3. Configure OpenRC services and `/etc/inittab` to launch the TUI on tty1\n4. Create a compressed initramfs\n5. Generate a hybrid BIOS/UEFI bootable ISO\n\nThe output will be `lldpOS-vYYYY.MM.DD.iso` with the build date as version.\n\n### Required Files Structure\n\n```\nlldpOS/\n├── build.sh\n├── scripts/\n│   ├── generate-hostname.sh\n│   ├── shell-welcome\n│   ├── welcome\n│   ├── keyconf\n│   ├── dns-config\n│   ├── nethelp\n│   ├── dhcp-config\n│   ├── static-ip\n│   ├── vlan-create\n│   ├── bond-create\n│   ├── bridge-create\n│   └── lldp-display.sh\n└── openrc/\n    ├── generate-hostname\n    └── inittab\n```\n\n## Usage\n\n### Booting\n\nlldpOS can be booted through multiple methods:\n\n1. **USB Boot** (for physical hardware):\n   ```bash\n   sudo dd if=lldpOS-vYYYY.MM.DD.iso of=/dev/sdX bs=4M status=progress\n   ```\n\n2. **Remote Management Interface** (recommended for data centers):\n   - **Dell iDRAC** - Virtual Console → Virtual Media → Map ISO\n   - **HP iLO** - Virtual Media → Mount ISO/CDROM\n   - **Supermicro IPMI** - Virtual Media → CD-ROM Image\n   - **Lenovo XCC** - Remote Control → Virtual Media\n   \n   This allows you to boot lldpOS remotely without physical access, perfect for troubleshooting remote servers.\n\n3. **Virtualization Platforms**:\n   - VMware ESXi / vSphere - Mount as virtual CD/DVD\n   - Proxmox VE - Upload ISO to storage, attach to VM\n   - KVM/QEMU - Use `-cdrom` option\n   - Hyper-V - Attach ISO to virtual DVD drive\n\n4. **PXE Boot** (advanced):\n   - Extract `vmlinuz` and `initramfs.img` from the ISO\n   - Configure your PXE server to chainload these files\n\n**Boot Process:**\n\nOnce booted, the system will automatically:\n- Generate a unique hostname (e.g., `brave-falcon-1234`)\n- Bring up all network interfaces\n- Start LLDP daemon and discover neighbors\n- Display the main TUI interface\n\n### Main Interface\n\nUpon boot, you'll see the main menu with four options:\n\n```\n┌─────────────────────────────────┐\n│      lldpOS v2025.10.28         │\n├─────────────────────────────────┤\n│ Hostname: brave-falcon-1234     │\n│                                 │\n│ 1. View LLDP Neighbors          │\n│ 2. Shell Access                 │\n│ 3. Reboot System                │\n│ 4. Shutdown System              │\n└─────────────────────────────────┘\n```\n\n#### Navigation\n\n- Use **arrow keys** or **number keys** to select options\n- Press **Enter** to confirm\n- In LLDP view, press **Refresh** button to rescan neighbors\n- Select a neighbor to view detailed LLDP information\n\n### Hostname Generation\n\nlldpOS automatically generates a unique, memorable hostname on each boot using the format:\n```\n\u003cadjective\u003e-\u003canimal\u003e-\u003cnumber\u003e\n```\n\nExamples: `brave-falcon-1234`, `calm-leopard-5678`, `wise-eagle-9012`\n\n**Why this matters for LLDP:**\n\nThis hostname is immediately advertised via LLDP to all connected switches. This means you can:\n\n1. **Boot lldpOS** on a server\n2. **Check from the switch** which port the server is connected to\n3. **Identify the server** easily without needing to label cables or track MACs\n\nThis is particularly useful during:\n- Rack and stack operations\n- Cable verification in dense environments\n- Troubleshooting in data centers\n- Pre-deployment port mapping\n\n### LLDP Discovery\n\nThe LLDP interface displays all discovered neighbors showing:\n- Local interface name\n- Remote switch/device name\n- Remote port identification\n\nSelecting a neighbor shows detailed information including:\n- Chassis ID and description\n- Port ID and description\n- System capabilities\n- Management addresses\n- VLAN information (if available)\n\n## Network Tools\n\n### Shell Access\n\nPress **2** from the main menu to access the shell.  \nThe first time you enter the shell, you'll be prompted to configure your keyboard layout.\n\n### Available Commands\n\n#### Network Configuration\n- `nethelp` - Display comprehensive network configuration guide\n- `dhcp-config` - Configure DHCP on an interface\n- `static-ip` - Configure static IP address\n- `vlan-create` - Create VLAN interface (802.1Q)\n- `bond-create` - Create bonded interface (LACP/bonding)\n- `bridge-create` - Create bridge interface\n- `dns-config` - Configure DNS resolvers\n\n#### Diagnostic Tools\n- `ping` - ICMP echo requests\n- `traceroute` - Trace network path to destination\n- `mtr` - Combined ping and traceroute (interactive)\n- `tcpdump` - Packet capture and analysis\n- `iperf3` - Network bandwidth testing\n- `ethtool` - Network interface configuration and statistics\n- `dig` / `host` - DNS lookup tools\n- `curl` / `wget` - HTTP/HTTPS requests\n\n#### Network Information\n- `ip` - Show/manipulate routing, devices, tunnels\n- `ifconfig` - Configure network interfaces (legacy)\n- `lldpctl` - Query LLDP daemon directly\n- `ss` / `netstat` - Socket statistics\n\n### Configuration Examples\n\n**Configure DHCP:**\n```bash\ndhcp-config eno1\n```\n\n**Configure Static IP:**\n```bash\nstatic-ip eno1 192.168.1.100/24 192.168.1.1\n```\n\n**Create VLAN:**\n```bash\nvlan-create eno1 100  # Creates eno1.100\n```\n\n**Create Bond:**\n```bash\nbond-create bond0 eno1 eno2\n```\n\n**Create Bridge:**\n```bash\nbridge-create br0 eno1 eno2\n```\n\n**Configure DNS:**\n```bash\ndns-config 8.8.8.8 8.8.4.4\n```\n\n### Keyboard Configuration\n\nIf you need to reconfigure the keyboard layout:\n```bash\nkeyconf\n```\n\n## Technical Details\n\n### Base System\n- **Distribution**: Alpine Linux (minirootfs)\n- **Kernel**: `linux-lts` from Alpine repository\n- **Init System**: OpenRC + busybox init\n- **Shell**: bash\n\n### Included Packages\n- Network tools: `iproute2`, `net-tools`, `iputils`, `traceroute`, `mtr`, `tcpdump`, `ethtool`, `iperf3`\n- DNS tools: `bind-tools`\n- HTTP tools: `curl`, `wget`\n- LLDP: `lldpd`\n- Network configuration: `dhcpcd` (VLAN/bond/bridge via `iproute2`)\n- Editors: `nano`, `less`\n- Interface: `dialog` (for TUI)\n- Keyboard: `kbd`, `kbd-bkeymaps`\n\n### Firmware Support\n- Realtek adapters\n- Broadcom (bnx2, bnx2x)\n- QLogic (qlogic + qed)\n- Myricom\n- Netronome\n\n### Boot Process\n1. GRUB loads kernel and initramfs\n2. busybox init reads `/etc/inittab` and runs OpenRC sysinit/boot/default\n3. `generate-hostname` OpenRC service creates a unique hostname\n4. Network interfaces are brought up automatically\n5. `lldpd` starts and begins neighbor discovery\n6. `inittab` respawns the main TUI on tty1\n\n### System Characteristics\n- **Read-only root**: Entire system runs from RAM\n- **No persistence**: All changes are lost on reboot\n- **Stateless**: Perfect for diagnostic purposes\n- **Secure**: No passwords, no open services by default\n\n## Use Cases\n\nlldpOS is designed for:\n\n- **Data center diagnostics** - Quick LLDP verification during rack and stack\n- **Network troubleshooting** - Boot from USB to diagnose connectivity issues\n- **Infrastructure mapping** - Discover network topology without configuration\n- **Pre-deployment testing** - Verify cabling and switch configuration before OS installation\n- **Training and labs** - Consistent network diagnostic environment\n- **Emergency recovery** - Network access when the installed OS is unavailable\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaetanlhf%2Flldpos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaetanlhf%2Flldpos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaetanlhf%2Flldpos/lists"}