{"id":13876031,"url":"https://github.com/westermo/netbox","last_synced_at":"2026-01-16T07:47:11.511Z","repository":{"id":37805602,"uuid":"250634621","full_name":"westermo/netbox","owner":"westermo","description":"The BusyBox of embedded network toolboxes","archived":false,"fork":false,"pushed_at":"2024-05-08T19:25:41.000Z","size":823,"stargazers_count":32,"open_issues_count":3,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-07T06:06:02.442Z","etag":null,"topics":["buildroot","buildroot-external","buildroot-external-tree","networking","toolbox"],"latest_commit_sha":null,"homepage":"https://westermo.github.io/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/westermo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/scripts/fitimage.sh","governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-27T20:01:18.000Z","updated_at":"2024-07-18T13:41:19.000Z","dependencies_parsed_at":"2023-01-20T23:16:21.977Z","dependency_job_id":"52e77a00-5aa2-4685-9715-f6055877f390","html_url":"https://github.com/westermo/netbox","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westermo%2Fnetbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westermo%2Fnetbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westermo%2Fnetbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westermo%2Fnetbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/westermo","download_url":"https://codeload.github.com/westermo/netbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226122303,"owners_count":17576920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["buildroot","buildroot-external","buildroot-external-tree","networking","toolbox"],"created_at":"2024-08-06T06:00:57.791Z","updated_at":"2024-11-24T03:31:39.945Z","avatar_url":"https://github.com/westermo.png","language":"Shell","funding_links":[],"categories":["Shell","networking"],"sub_categories":[],"readme":"NetBox - Like BusyBox but for Networking\n========================================\n\n[Westermo][] NetBox is a toolbox for embedded systems based on [Buildroot][].\n\n![NetBox Zero/OS booting up in Qemu](screenshot.png)\n\nNetBox provides easy access to all Westermo specific custimizations made to\nLinux and other [Open Source][] projects used in WeOS.  You can use it as\nthe base for any application, but is strongly recommended for all use cases\nfor container applications running in WeOS.  Official WeOS container\napplications will be based on NetBox.\n\nNetBox is built using the Buildroot *External Tree* facility.  This is a\nlayered approach which enables customizing without changing Buildroot.\nYou may use NetBox as NetBox use Buildroot, see the [App-Demo][] project\nfor an example -- click *Use this template* -- to create your own.\n\nTo contribute, see the file [HACKING][] for details.\n\n\nVersioning\n----------\n\nNetBox use the same versioning as Buildroot, with an appended `-rN` to\ndenote the *revision* of Buildroot with Westermo extensions.  E.g., the\nfirst release is 2020.02-r1.\n\n\nPlatforms\n---------\n\nThe NetBox project follows the Westermo product platform naming.  This to\nbe able to easily match what container image works on a Westermo device:\n\n| **Architecture** | **Platform Name** | **Nightly App** | **Nightly OS** |\n|------------------|-------------------|-----------------|----------------|\n| arm9             | Basis             | [basis.app][]   | [basis.os][]   |\n| powerpc          | Coronet           | [coronet.app][] | [coronet.os][] |\n| arm pj4          | Dagger            | [dagger.app][]  | [dagger.os][]  |\n| aarch64          | Envoy             | [envoy.app][]   | [envoy.os][]   |\n| aarch64          | Ember             | [ember.app][]   | [ember.os][]   |\n| x86\\_64          | Zero              | [zero.app][]    | [zero.os][]    |\n\n\u003e **Note:** the *Envoy* platform includes support also for the Marvell\n\u003e ESPRESSObin (Globalscale) and MACCHIATObin (Solidrun) boards.\n\n\nFlavor\n------\n\nIn addition to various NetBox platforms there are two major *flavors*\navailable.  The current first-class citizen is *apps*, but it is also\npossible to build an entire *operating system* image, including Linux\nkernel and the same userland already available to *apps*.  To select\na pre-configured NetBox flavor for a given platform:\n\n- `netbox_app_$platform`\n- `netbox_os_$platform`\n\n\nRequirements\n------------\n\nThe build environment requires the following tools, tested on Ubuntu\n21.04 (x86\\_64): make, gcc, g++, m4, python, and openssl development\npackage.\n\nOn Debian/Ubuntu based systems:\n\n```sh\n~$ sudo apt install build-essential m4 libssl-dev python\n```\n\nTo run in Qemu, either enable host-side build in `make menuconfig`, or\nfor quicker builds you can use the version shipped with your Linux host.\n\nOn Debian/Ubuntu based systems:\n\n```sh\n~$ sudo apt install qemu-system\n```\n\nFor smooth sailing, after install, add the following line to the file\n`/etc/qemu/bridge.conf` (add file if it does not exist):\n\n```ApacheConf\nallow all\n```\n\nFor network access to work out of the box in your Qemu system, install\nthe virt-manager package, this creates a host bridge called `virbr0`:\n\n```sh\n~$ sudo apt install virt-manager\n```\n\n\nBuilding\n--------\n\nFirst clone the repository, optionally check out the tagged release you\nwant to use.  The build system clones the submodule on the first build,\nbut you can also run the command manually:\n\n```sh\n~$ cd ~/src\n~/src$ git clone https://github.com/westermo/netbox.git\n~/src$ cd netbox\n~/src/netbox$ git submodule update --init\n```\n\nSecond, select your target `_defconfig`, see the `configs/` directory,\nor use `make list-defconfigs` to see all Buildroot and NetBox configs\navailable.  We select the defconfig for Zero (x86-64) NetBox app flavor:\n\n```sh\n~/src/netbox$ make netbox_app_zero_defconfig\n```\n\n\u003e **Note:** if you want to use the `gdbserver` on target, *this* is the\n\u003e point where you have to enable it in `make menuconfig`.  The setting\n\u003e you want is under Toolchain --\u003e \"Copy gdb server to the Target\".  You\n\u003e also want \"Build options\" --\u003e \"build packages with debugging symbols\"\n\nThird, type make and fetch a cup of coffee because the first time you\nbuild it will take some time:\n\n```sh\n~/src/netbox$ make\n```\n\nDone.  See the `output/images/` directory for the resulting SquasFS\nbased root file system: `netbox-app-zero.img`\n\n\u003e **Tip:** the same source tree can easily be used to build multiple\n\u003e   defconfigs, use the Buildroot `O=` variable to change the default\n\u003e   `output/...` to `O=/home/$LOGNAME/src/netbox/zero` in one terminal\n\u003e   window, and `O=/home/$LOGNAME/src/netbox/coronet` in another.  This\n\u003e   way, when working with packages, e.g. editing code, you can build\n\u003e   for multiple targets at the same time, without cleaning the tree.\n\n\nUpdating\n--------\n\nTo update your local copy of NetBox from git, you need to update both\nNetBox and the Buildroot submodule, like when you first cloned (above):\n\n```sh\n~/src/netbox$ git pull\n~/src/netbox$ git submodule update --init\n```\n\n\nRunning\n-------\n\nAll NetBox OS builds are supported by Qemu.  This is actually a corner\nstone in NetBox, and principal testing strategy at Westermo.  It can be\nhighly useful for quick turnarounds when developing and testing new\nfeatures. Make sure you have built one of the os images before running, e.g.:\n\n```sh\n~/src/netbox$ make netbox_os_zero_defconfig\n```\n\nAny feature targeting OSI layer 3, and above, need nothing else to run.\nFor more advanced test setups, with multiple networked Qemu nodes, we\nhighly recommend [Qeneth](https://github.com/wkz/qeneth).\n\nTo start a single node:\n\n```sh\n~/src/netbox$ make run\n```\n\n\u003e **Note:** you may need `sudo`, unless you have set up your system with\n\u003e capabilities https://troglobit.com/2016/12/11/a-life-without-sudo/\n\n\n### Basic Networking in Qemu\n\nBy default, this command starts the `utils/qemu` script and tries to\nconnect one interface to a host bridge called `virbr0`.  That bridge\nonly exists if you installed virt-manager (above), if not, you can have\na look at the `utils/qemu` script arguments and environment variables,\nor try:\n\n```sh\n~/src/netbox$ make QEMU_NET=tap run\n```\n\n### Persistent Storage in Qemu\n\nQemu nodes start from the same read-only SquasFS image as built for all\ntargets.  For persistent storage a disk image file on the host system is\nused.  This is controlled by the environment variable `$QEMU_MNT`, which\ndefaults to `VENDOR-config-PLATFORM.img`, provided `~/.cache` exists .\nE.g., for NetBox Zero OS: `~/.cache/netbox-config-zero.img`.  See the\nhelper script `utils/qemu` for more information.\n\nWhen persistent storage is enabled and working, the `/mnt` directory on\nthe target system is used to storing an OverlayFS of the target's\n`/etc`, `/root`, and `/var`, directories.  I.e., changing a file in\neither of these directories (exceptions in `/var` exist) is persistent\nacross reboots.\n\n\n### Sharing a Host Directory with Qemu\n\nNetBox support 9P file sharing between the host and Qemu targets.  Set\ndirectory to share, using the absolute path, in `QEMU_HOST`:\n\n```\n~/src/netbox$ make run QEMU_HOST=/tmp\n```\n\nWhen booting your target system with `make run`, the hosts' `/tmp`\ndirectory is available as `/host` on the target system.\n\n\n### Example\n\nHere is an example run of a Zero OS build, the persistent store for all\nyour configuration (in `/etc` or `/home`) is stored in a disk image file\nnamed `~/.cache/netbox-config-zero.img`:\n\n```sh\n~/src/netbox$ make distclean\n~/src/netbox$ make netbox_os_zero_defconfig\n~/src/netbox$ make\n~/src/netbox$ make run\n```\n\n\u003e **Note:** you may still need to call `sudo make run`, see the note on\n\u003e capabilities, above.\n\n\n### Debugging with `gdbserver`\n\nif you remembered \"Copy gdb server to the target\", above, we can debug\nfailing programs on our target (Qemu) system.  You also need to have the\n`gdb-multiarch` program installed on your host system, the regular `gdb`\nonly supports your host's architecture:\n\n    sudo apt install gdb-multiarch\n\nTo open the debug port in Qemu we start NetBox with `QEMU_GDB=1`, this\nopens `localhost:4712` as your debug port (4711 is used for kgdb):\n\n    $ make run QEMU_GDB=1\n\nWhen logged in, start the `gdbserver` service:\n\n    # initctl enable gdbserver\n    # initctl reload\n\nFrom your host, in another terminal (with the same `$O` set!) from the\nsame NetBox directory, you can now connect to your target and the attach\nto, or remotely start the program you want to debug.  NetBox has a few\nextra tricks up its sleeve when it comes to remote debugging.  The below\ncommands are defined in the [.gdbinit][] file:\n\n    $ make debug\n    GNU gdb (Ubuntu 9.2-0ubuntu1~20.04.1) 9.2\n    Copyright (C) 2020 Free Software Foundation, Inc.\n    \n    For help, type \"help\".\n    (gdb) user-connect\n    (gdb) user-attach usr/sbin/querierd 488\n    0x00007f5812afc425 in select () from ./lib64/libc.so.6\n    (gdb) cont\n    Continuing.\n\nFor more information on how to use GDB, see the manual, or if you want\nto know a little bit more behind the scenes, see the blog post about\n[Debugging an embedded system][debug].\n\n\n### Running in LXC or LXD\n\nThe NetBox app builds can be run in LXC, or LXD, on your PC.  With LXD\nit is even possible to run non-native archs, like Arm64 using the Linux\n\"binfmt misc\" mechanism, which runs all binaries through `qemu-aarch64`.\nThis is only documented in the predecessor to NetBox, [myrootfs]][].\n\nTo run a NetBox app in LXC, first install all dependencies (lxc-utils,\nlibvirt, etc.) and create the necessary directories:\n\n```sh\n$ sudo mkdir -p /var/lib/lxc/images/\n$ sudo mkdir -p /var/lib/lxc/foo/mnt\n```\n\nSince we are playing it safe, we've built the Zero (x86_64) NetBox app,\nimage, so let's install it in the `images/` directory.  Images can be\nshared with multiple LXC container apps:\n\n```sh\n$ sudo cp output/images/netbox-app-zero.img /var/lib/lxc/images/foo.img\n```\n\nThe LXC `config` file might need some tweaking, in particular if you use\ndifferent path to the `.img` file.  The host bridge you probably want to\nchange as well.  Here we have used `lxcbr0` only because it's the\ndefault in libvirt installs in Debian/Ubuntu and gives us NAT:ed access\nto the Internet from our app(s) via the host.  All this is already set\nup by libvirt, so we can focus on the LXC container `config`:\n\n```sh\n$ sudo sh -c \"cat \u003e\u003e/var/lib/lxc/foo/config\" \u003c\u003c-EOF\n\tlxc.uts.name = foo\n\tlxc.tty.max = 4\n\tlxc.pty.max=1024\n\t#lxc.hook.pre-mount = pre-mount.sh /var/lib/lxc/images/foo.img /var/lib/lxc/foo/rootfs\n\t#lxc.rootfs.path    = overlayfs:/var/lib/lxc/foo/rootfs:/var/lib/lxc/foo/delta0\n\t#lxc.rootfs.options = -t squashfs\n\tlxc.rootfs.path = loop:/var/lib/lxc/images/foo.img\n\tlxc.mount.auto = cgroup:mixed proc:mixed sys:mixed\n\t#lxc.mount.entry=run run tmpfs rw,nodev,relatime,mode=755 0 0\n\t#lxc.mount.entry=shm dev/shm tmpfs rw,nodev,noexec,nosuid,relatime,mode=1777,create=dir 0 0\n\tlxc.mount.entry=/var/lib/lxc/foo/mnt mnt none bind 0 0\n\tlxc.net.0.type = veth\n\tlxc.net.0.flags = up\n\tlxc.net.0.link = lxcbr0\n\t#lxc.init.cmd = /sbin/init finit.debug\n\t\n\t#lxc.seccomp.profile = /usr/share/lxc/config/common.seccomp\n\tlxc.apparmor.profile = lxc-container-default-with-mounting\nEOF\n```\n\nThe last two lines are needed on systems with Seccomp and/or AppArmor.\nUncomment the one you need, see the host's dmesg when `lxc-start` fails\nwith mysterious error messages.  For convenience the Debian/Ubuntu is\nuncommented already.\n\n\n\u003e **Note1:**\n\u003e You may have to create the directory where to mount the container rootfs\n\u003e as it is configured in /var/lib/lxc/foo/config on line 11\n\u003e ```sh\n\u003e $ sudo mkdir -p /var/lib/lxc/foo/mnt\n\u003e ```\n\n\u003e **Note2:** you may have to add the following two lines to your AppArmor\n\u003e profile to enable writable /etc, /var, /home, and /root directories.\n\u003e The file is in `/etc/apparmor.d/lxc/lxc-default-with-mounting`:\n\u003e ```\n\u003e mount fstype=tmpfs,\n\u003e mount fstype=overlay,\n\u003e ```\n\nReload AppArmor, or restart your system to activate the changes, then we\ncan start the container with:\n\n```sh\n$ sudo lxc-start -n foo\n```\n\nTo see what actually happens when it starts up, append `-F`.  Attach to\nthe container's `/dev/console` with:\n\n```sh\n$ sudo lxc-console -n foo -t 0 -e '^p'\n```\n\nThe last `-e '^p` remaps the control key sequence to detach from your\ncontainer and return to your host: Ctrl-p q\n\n\n[Westermo]:      https://www.westermo.com/\n[Buildroot]:     https://buildroot.org/ \n[HACKING]:       HACKING.md\n[App-Demo]:      https://github.com/westermo/app-demo\n[Open Source]:   https://en.wikipedia.org/wiki/Free_and_open-source_software\n[basis.app]:     https://nightly.link/westermo/netbox/workflows/build/master/netbox-app-basis.zip\n[coronet.app]:   https://nightly.link/westermo/netbox/workflows/build/master/netbox-app-coronet.zip\n[dagger.app]:    https://nightly.link/westermo/netbox/workflows/build/master/netbox-app-dagger.zip\n[envoy.app]:     https://nightly.link/westermo/netbox/workflows/build/master/netbox-app-envoy.zip\n[zero.app]:      https://nightly.link/westermo/netbox/workflows/build/master/netbox-app-zero.zip\n[basis.os]:      https://nightly.link/westermo/netbox/workflows/build/master/netbox-os-basis.zip\n[coronet.os]:    https://nightly.link/westermo/netbox/workflows/build/master/netbox-os-coronet.zip\n[dagger.os]:     https://nightly.link/westermo/netbox/workflows/build/master/netbox-os-dagger.zip\n[envoy.os]:      https://nightly.link/westermo/netbox/workflows/build/master/netbox-os-envoy.zip\n[zero.os]:       https://nightly.link/westermo/netbox/workflows/build/master/netbox-os-zero.zip\n[.gdbinit]:      https://github.com/westermo/netbox/blob/master/.gdbinit\n[debug]:         https://westermo.github.io/2022/02/18/debugging-embedded-systems/\n[myrootfs]:      https://github.com/myrootfs/myrootfs#lxd\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwestermo%2Fnetbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwestermo%2Fnetbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwestermo%2Fnetbox/lists"}