{"id":25649796,"url":"https://github.com/openchami/coresmd","last_synced_at":"2026-06-04T12:31:39.540Z","repository":{"id":257823391,"uuid":"870931852","full_name":"OpenCHAMI/coresmd","owner":"OpenCHAMI","description":"A CoreDHCP plugin with a pull-through cache that communicates with SMD","archived":false,"fork":false,"pushed_at":"2024-10-25T19:27:50.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-26T03:25:50.536Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/OpenCHAMI.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":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-10T23:56:27.000Z","updated_at":"2024-10-25T19:26:54.000Z","dependencies_parsed_at":"2024-10-26T04:16:07.400Z","dependency_job_id":"7749365e-2ba3-422a-b319-03272a4e8493","html_url":"https://github.com/OpenCHAMI/coresmd","commit_stats":null,"previous_names":["synackd/coresmd","openchami/coresmd"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fcoresmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fcoresmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fcoresmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Fcoresmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCHAMI","download_url":"https://codeload.github.com/OpenCHAMI/coresmd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240329443,"owners_count":19784452,"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":[],"created_at":"2025-02-23T14:33:55.116Z","updated_at":"2026-06-04T12:31:39.532Z","avatar_url":"https://github.com/OpenCHAMI.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: © 2024-2025 Triad National Security, LLC.\nSPDX-FileCopyrightText: © 2026 OpenCHAMI a Series of LF Projects, LLC\n\nSPDX-License-Identifier: MIT\n--\u003e\n\n# CoreSMD - Connect CoreDHCP/CoreDNS to SMD\n\n## Contents\n\n- [CoreSMD - Connect CoreDHCP/CoreDNS to SMD](#coresmd---connect-coredhcpcoredns-to-smd)\n  - [Contents](#contents)\n  - [Introduction](#introduction)\n    - [CoreDHCP](#coredhcp)\n    - [CoreDNS](#coredns)\n  - [Overview](#overview)\n  - [Configuration](#configuration)\n  - [Build](#build)\n    - [Build with GoReleaser](#build-with-goreleaser)\n      - [Using Make Targets](#using-make-targets)\n      - [Running Goreleaser Manually](#running-goreleaser-manually)\n    - [Build Binaries with Make](#build-binaries-with-make)\n    - [Build Container with Make](#build-container-with-make)\n  - [Testing](#testing)\n    - [CoreDHCP](#coredhcp-1)\n    - [CoreDNS](#coredns-1)\n  - [Running](#running)\n    - [Configuration](#configuration-1)\n    - [Preparation: SMD and BSS](#preparation-smd-and-bss)\n    - [Preparation: TFTP](#preparation-tftp)\n    - [Running](#running-1)\n      - [CoreDHCP](#coredhcp-2)\n      - [CoreDNS](#coredns-2)\n  - [More Reading](#more-reading)\n\n---\n\n## Introduction\n\nCoreSMD provides plugins for both [CoreDHCP](https://github.com/coredhcp/coredhcp) and [CoreDNS](https://github.com/coredns/coredns) that allow DHCP requests and DNS lookups to use [SMD](https://github.com/OpenCHAMI/smd), the OpenCHAMI inventory service.\n\n### CoreDHCP\n\nCoreSMD provides two plugins. The first plugin, **coresmd**, uses SMD as a source of truth to provide DHCP leases for both DHCPv4 and DHCPv6. The second plugin, **bootloop**, dynamically assigns temporary IP addresses to unknown MACs until they can be updated in SMD.\n\nThis repository is part of the [OpenCHAMI](https://openchami.org) project. It extends CoreDHCP by integrating it with the SMD service so DHCP leases can be centrally managed. There are two primary plugins:\n\n1. **coresmd**\n   Provides DHCP leases (IPv4 and IPv6) based on data from SMD.\n\n2. **bootloop**\n   Assigns temporary IPv4 addresses to unknown nodes. It also returns a DHCPNAK if it sees a node that has become known to SMD since its last lease, forcing a full DHCP handshake to get a new address (from **coresmd**).\n\nThe goal of **bootloop** is to ensure unknown nodes/BMCs continually attempt to get new IP addresses if they become known in SMD, while still having a short, discoverable address for tasks like [Magellan](https://github.com/OpenCHAMI/magellan).\n\nSee [**examples/coredhcp/**](https://github.com/OpenCHAMI/coresmd/tree/main/examples/coredhcp) for configuration examples.\n\n### CoreDNS\n\nThe **coresmd** plugin allows hostnames/FQDNs for nodes and BMCs stored in SMD to be resolved to IP addresses (both IPv4 and IPv6). It supports A, AAAA, and PTR record lookups.\n\nSee [**examples/coredns/**](https://github.com/OpenCHAMI/coresmd/tree/main/examples/coredns) for configuration examples.\n\n---\n\n## Overview\n\nCoreSMD acts as a pull-through cache of DHCP and DNS information from SMD, ensuring that new or updated details in SMD can be reflected in DHCP lease assignments and DNS records. This facilitates more dynamic environments where nodes might be added or changed frequently, and also simplifies discovery of unknown devices via the **bootloop** CoreDHCP plugin.\n\n---\n\n## Configuration\n\nTake a look at [**examples/**](examples/). In there are configuration examples and documentation for both CoreDHCP and CoreDNS.\n\n## Build\n\nThe plugins in this repository can be built into CoreDHCP/CoreDNS either using a container-based approach (via the provided Dockerfile) or by statically compiling them into CoreDHCP/CoreDNS on bare metal. Additionally, this project uses [GoReleaser](https://goreleaser.com/) to automate releases and include build metadata.\n\nFor local build options, run:\n\n```bash\nmake help\n```\n\nFor a list of build targets.\n\n### Build with GoReleaser\n\n#### Using Make Targets\n\nIf Goreleaser is already installed, the `goreleaser-*` Make targets can be used and the below steps skipped.\n\nTo build the binaries only (binaries will be located in `dist/`):\n\n```bash\nmake GORELEASER_OPTS='--clean --snapshot --single-target' goreleaser-build\n```\n\nTo build the containers (all supported architectures):\n\n\u003e [!NOTE]\n\u003e Goreleaser, as of this writing, doesn't support building a container _only_ for the native architecture. If that is desired, see [**Build a Container with Make**](#build-a-container-with-make) below.\n\n```bash\nmake GORELEASER_OPTS='--clean --snapshot --skip publish' goreleaser-release\n```\n\n#### Running Goreleaser Manually\n\nIf running Goreleaser manually, ensure the following environment variables are set in order to include build metadata:\n\n- **BUILD_HOST**: The hostname of the machine where the build is performed.\n- **GO_VERSION**: The version of Go used for the build.\n- **BUILD_USER**: The username of the person or system performing the build.\n\nYou can set them with:\n\n```bash\nexport BUILD_HOST=$(hostname)\nexport GO_VERSION=$(go version | awk '{print $3}')\nexport BUILD_USER=$(whoami)\n```\n\nTo build binaries and containers for all supported architectures:\n\n```bash\ngoreleaser release --clean --snapshot --skip publish\n```\n\nTo build just the binaries for the native architecture:\n\n```bash\ngoreleaser build --clean --snapshot --single-target\n```\n\nCheck the `dist/` directory for the built binaries, which will include the embedded metadata.\n\n### Build Binaries with Make\n\nBoth binaries can be built with:\n\n```\nmake\n```\n\nThere are also Make targets for each separate binary:\n\n```\nmake coredhcp\nmake coredns\n```\n\nThese will put `coredhcp` and `coredns` binaries in the repository root which can be used for building a container in the next step.\n\nVerify that CoreDHCP contains the **coresmd** and **bootloop** plugins:\n\n```\n$ ./coredhcp --plugins | grep -E 'coresmd|bootloop'\nbootloop\ncoresmd\n```\n\n...and that CoreDNS contains the **coresmd** plugin:\n\n\n```\n$ ./coredns --plugins | grep coresmd\ncoresmd\n```\n\n### Build Container with Make\n\nTo build a container that contains both CoreDHCP and CoreDNS, run:\n\n```\nmake container\n```\n\n\u003e [!NOTE]\n\u003e The container runtime is Docker by default, but is configurable. For example, to use Podman:\n\u003e ```bash\n\u003e make CONTAINER_PROG=\"$(which podman)\" container\n\u003e ```\n\n\u003e [!NOTE]\n\u003e Container tags are also configurable. Use `make ... CONTAINER_TAG=$TAG container` to change it.\n\nThe container contains [`dhcping`](https://github.com/nean-and-i/dhcping) that can be used as a health check for CoreDHCP.\n\n---\n\n## Testing\n\n### CoreDHCP\n\nTo test the DHCP handshake, **iproute2** tools can be used to create a virtual interface in a separate network namespace that can be used to perform DORA.\n\n```bash\n# Create the network namespace called \"dhcptest\"\nsudo ip netns add dhcptest\n\n# Create veth pair\n# veth-srv: virtual interface in parent namespace (\"server\")\n# veth-cli: virtual interface in child namespace (\"client\")\nsudo ip link add veth-srv type veth peer name veth-cli\nsudo ip link set veth-cli netns dhcptest\n\n# Bring up both interfaces\nsudo ip link set veth-srv up\nsudo ip netns exec dhcptest ip link set lo up\nsudo ip netns exec dhcptest ip link set veth-cli up\n\n# Optionally set specific MAC address on test interface\nsudo ip netns exec dhcptest ip link set dev veth-cli address de:ad:c0:de:ca:fe\n```\n\nEnsure CoreDHCP can listen on **veth-srv**. If restricting the interfaces CoreDHCP listens on, ensure there's a proper entry under `listen`, e.g:\n\n```yaml\nserver4:\n  listen:\n    - '%veth-srv'\n```\n\nThen, monitor the interface for the DORA handshake:\n\n```bash\nsudo tcpdump -nnni veth-srv -vvv 'udp port 67 or udp port 68'\n```\n\nInitiate the DHCP handshake from the namespaced virtual network interface:\n\n```bash\n# Using dhclient\nsudo ip netns exec dhcptest dhclient -4 -v -d -i veth-cli\n\n# Using BusyBox udhcpc\nsudo ip netns exec dhcptest udhcpc -i veth-cli -f -vv\n```\n\nMonitor the output of `tcpdump` for the DORA handshake.\n\nCleaning up:\n\n```bash\n# OPTIONAL: Kill processes inside child network namespace\nsudo ip netns pids dhcptest | xargs -r sudo kill\n\n# OPTIONAL: Release lease if dhclient was used\nsudo ip netns exec dhcptest dhclient -4 -r veth-cli\n\n# Delete namespace and veth-cli interface inside it\nsudo ip netns del dhcptest\n\n# Delete parent namespace veth if it still exists\nsudo ip link del veth-srv\n\n# Ensure namespace and interfaces are gone (output should be empty)\nsudo ip netns list | grep dhcptest\nip link show | grep -e veth-srv -e veth-cli\n```\n\n### CoreDNS\n\nSee: \u003chttps://github.com/OpenCHAMI/coresmd/tree/main/examples/coredns#testing\u003e\n\n---\n\n## Running\n\n### Configuration\n\nCoreDHCP requires a config file to run. See [**examples/coredhcp/coredhcp.yaml**](examples/coredhcp-config.yaml) for an example with detailed comments on how to enable and configure **coresmd** and **bootloop**.\n\nCoreDNS similarly has a **Corefile** to use. See [**examples/coredns/**](examples/coredns/) for examples of Corefiles.\n\n### Preparation: SMD and BSS\n\nBefore running CoreDHCP/CoreDNS, ensure the [OpenCHAMI](https://openchami.org) services (notably **BSS** and **SMD**) are configured and running. Their URLs should match what you configure in the CoreDHCP config file.\n\n### Preparation: TFTP\n\nBy default, **coresmd** includes a built-in TFTP server with iPXE binaries for 32-/64-bit x86/ARM (EFI) and legacy x86. If you use the **bootloop** plugin and set the iPXE boot script path to `\"default\"`, it will serve a built-in reboot script to unknown nodes. Alternatively, you can point this to a custom TFTP path if different functionality is desired.\n\n### Running\n\nOnce all prerequisites are set, you can run CoreDHCP or CoreDNS.\n\n#### CoreDHCP\n\n- **Podman CLI**\n  Use host networking and mount your config file (this example mounts in system certificate bundle):\n  ```bash\n  podman run \\\n    --rm \\\n    --name=coresmd-coredhcp \\\n    --hostname=coresmd-coredhcp \\\n    --cap-add=NET_ADMIN,NET_RAW \\\n    --volume=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/root_ca/root_ca.crt:ro,Z \\\n    --volume=/etc/openchami/configs/coredhcp.yaml:/etc/coredhcp/config.yaml:ro,Z \\\n    --network=host \\\n    ghcr.io/openchami/coresmd:latest\n  ```\n\n  \u003e [!NOTE]\n  \u003e `--cap-add` may or may not be needed on some distros.\n\n- **Podman Quadlet**:\n  ```ini\n  [Unit]\n  Description=The CoreSMD CoreDHCP container\n\n  [Container]\n  ContainerName=coresmd-coredhcp\n\n  HostName=coresmd-coredhcp\n  Image=ghcr.io/openchami/coresmd:latest\n\n  AddCapability=NET_ADMIN\n  AddCapability=NET_RAW\n\n  Volume=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/root_ca/root_ca.crt:ro,Z\n  Volume=/etc/openchami/configs/coredhcp.yaml:/etc/coredhcp/config.yaml:ro,Z\n\n  Network=host\n\n  PodmanArgs=--http-proxy=false\n\n  [Service]\n  Restart=always\n   ```\n\n- **Bare Metal**\n  Execute the locally built binary:\n  ```bash\n  ./coredhcp -conf /path/to/config.yaml\n  ```\n\n#### CoreDNS\n\n- **Podman CLI**\n  Use host networking and mount your config file (this example mounts in system certificate bundle):\n  ```bash\n  podman run \\\n    --rm \\\n    --name=coresmd-coredns \\\n    --hostname=coresmd-coredns \\\n    --cap-add=NET_ADMIN,NET_RAW \\\n    --volume=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/root_ca/root_ca.crt:ro,Z \\\n    --volume=/etc/openchami/configs/Corefile:/etc/coredhcp/Corefile:ro,Z \\\n    --network=host \\\n    ghcr.io/openchami/coresmd:latest \\\n    /coredns\n  ```\n\n  \u003e [!NOTE]\n  \u003e `--cap-add` may or may not be needed on some distros.\n\n- **Podman Quadlet**:\n  ```ini\n  [Unit]\n  Description=The CoreSMD CoreDNS container\n\n  [Container]\n  ContainerName=coresmd-coredns\n\n  HostName=coresmd-coredhcp\n  Image=ghcr.io/openchami/coredns:latest\n\n  Exec=/coredns\n\n  AddCapability=NET_ADMIN\n  AddCapability=NET_RAW\n\n  Volume=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/root_ca/root_ca.crt:ro,Z\n  Volume=/etc/openchami/configs/Corefile\n\n  Network=host\n\n  PodmanArgs=--http-proxy=false\n\n  [Service]\n  Restart=always\n   ```\n\n- **Bare Metal**\n  Execute the locally built binary:\n  ```bash\n  ./cored-conf /path/to/config.yaml\n  ```\n\n---\n\n## More Reading\n\n- [CoreDHCP GitHub](https://github.com/coredhcp/coredhcp)\n- [CoreDNS GitHub](https://github.com/coredns/coredns)\n- [OpenCHAMI Project](https://openchami.org)\n- [SMD GitHub](https://github.com/OpenCHAMI/smd)\n- [GoReleaser Documentation](https://goreleaser.com/install/)\n- [Magellan (OpenCHAMI)](https://github.com/OpenCHAMI/magellan)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenchami%2Fcoresmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenchami%2Fcoresmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenchami%2Fcoresmd/lists"}