{"id":26792985,"url":"https://github.com/osbuild/nboci","last_synced_at":"2025-03-29T16:18:25.301Z","repository":{"id":223895724,"uuid":"761845478","full_name":"osbuild/nboci","owner":"osbuild","description":"OCI netboot artifacts CLI reference implementation","archived":false,"fork":false,"pushed_at":"2024-03-18T13:04:05.000Z","size":161,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-05-01T20:15:30.570Z","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":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osbuild.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}},"created_at":"2024-02-22T15:43:58.000Z","updated_at":"2024-03-08T12:43:34.000Z","dependencies_parsed_at":"2024-03-18T14:29:27.097Z","dependency_job_id":"ef0c26c6-57c3-40d4-be0b-36a0e22b35c9","html_url":"https://github.com/osbuild/nboci","commit_stats":null,"previous_names":["osbuild/oci-netboot"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fnboci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fnboci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fnboci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osbuild%2Fnboci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osbuild","download_url":"https://codeload.github.com/osbuild/nboci/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246207503,"owners_count":20740723,"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-03-29T16:18:24.531Z","updated_at":"2025-03-29T16:18:25.291Z","avatar_url":"https://github.com/osbuild.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OCI network boot files CLI tool\n\nThis tool helps to push and pull files required for network booting (PXE, BOOTP, HTTP-EFI) in order to install operating systems, images or bootable containers to and from OCI-compatible container registries. Artifacts can be signed and distributed in dedicated repositories or with bootable containers.\n\nFor a Linux installation, typically these files are:\n\n* Shim bootloader\n* A bootloader (e.g. grub2)\n* Linux kernel\n* Linux initramdisk\n\nThis is work in progress.\n\n## Building\n\nNo binaries are currently available, you need Go 1.21+ to build the CLI tool:\n\n    git clone https://github.com/osbuild/oci-netboot\n    cd oci-netboot\n    go build ./cmd/nboci/\n\n## Preparing boot files\n\nGetting boot files is different depending on the target operating system. Here is an example for Fedora installation ISO:\n\n    wget http://fedora/Fedora-netboot-XX.iso\n    7z x Fedora-netboot-XX.iso\n    sha256sum EFI/BOOT/BOOTX64.EFI EFI/BOOT/grubx64.efi images/pxeboot/vmlinuz images/pxeboot/initrd.img\n\nIn the examples below, these files will be pushed:\n\n    2b7918e408b5cce5e9df3018c55e426493d8327d68694ce0bc29802c05decadf  EFI/BOOT/BOOTX64.EFI\n    2db12e047966f19323f815da155d7bf39c4f832aa0b2fbe1f5dca38152c106a2  EFI/BOOT/grubx64.efi\n    63f6ee372f74353dd90ac5287a621d8a41694369ee6241f2bd980a3537d19789  images/pxeboot/vmlinuz\n    f0aed0be4c2f68c97c320717fc223ec6feb2688473a2785f3e09a53ed240d8db  images/pxeboot/initrd.img\n\nThe same files can be also found in RPM packages named `shim-x64` and `grub2-efi-x64`. Additionally, PXELinux bootloader for legacy (BIOS) systems can be only found in `syslinux-tftpboot` package.\n\nIt is recommended to copy them into single directory and rename `BOOTX64.EFI` to just `shim.efi`.\n\n## Pushing boot files\n\nEach push operation requires the following input:\n\n* Operating system name (lowercase, alphanum)\n* Operating system version (lowercase, alphanum, dots allowed)\n* Operating system architecture (lowercase, alphanum, underscore allowed)\n* Entrypoint: bootoader filename as the entrypoint (e.g. when SecureBoot is on on x86_64)\n* Alternate entrypoint: bootoader filename as the alternative entrypoint (e.g. when SecureBoot is off on x86_64)\n* Legacy entrypoint: bootoader filename for legacy systems (e.g. BIOS mode on x86_64) \n\nExample:\n\n    ./nboci push --repository ghcr.io/lzap/bootc-netboot-example \\\n        --osname rhel \\\n        --osversion 9.3.0 \\\n        --osarch x86_64 \\\n        --entrypoint shim.efi \\\n        --alt-entrypoint grubx64.efi \\\n        --legacy-entrypoint pxelinux.0 \\\n        shim.efi grubx64.efi pxelinux.0 vmlinuz initrd.img\n\nFiles are compressed via zstd and pushed, content is tagged with the following tag:\n\n    osname-osversion-osarch\n\nTag name can ve overriden with `--tag` argument.\n\nOther examples:\n\n    ./nboci --verbose push --repository ghcr.io/lzap/bootc-netboot-example --osname rhel --osversion 9.3.0 --osarch x86_64 --entrypoint shim.efi --alt-entrypoint grubx64.efi fixtures/rhel-9.3.0-x86_64/*\n\n    ./nboci --verbose push --repository ghcr.io/lzap/bootc-netboot-example --osname rhel --osversion 9.3.0 --osarch aarch64 --entrypoint shim.efi --alt-entrypoint grubaa64.efi fixtures/rhel-9.3.0-aarch64/*\n\n## Pulling boot files\n\nTo list all tags (including those which are not netboot artifacts):\n\n    ./nboci list ghcr.io/lzap/bootc-netboot-example\n\nTo pull all files from all tags:\n\n    ./nboci pull --destination /tmp/test ghcr.io/lzap/bootc-netboot-example\n\nTo pull a specific tag use `ghcr.io/lzap/bootc-netboot-example:rhel-9.3.0-x86_64`.\n\nThe utility will sychronize files and only download those files which checksums do not match. Entrypoint and alternate entrypoints will be installed as relative symbolink links named `boot` and `boot-alt`.\n\n    tree /tmp/test\n    /tmp/test\n    └── rhel\n        └── 9.3.0\n            └── x86_64\n                ├── shim.efi\n                ├── boot (-\u003e shim.efi)\n                ├── grubx64.efi\n                ├── boot-alt (-\u003e grubx64.efi)\n                ├── pxelinux.0\n                ├── boot-legacy (-\u003e pxelinux.0)\n                ├── initrd.img\n                └── vmlinuz\n\n## Signing files\n\nCommits can be digitally signed using [cosign](https://github.com/sigstore/cosign).\n\n```\ncosign generate-key-pair\ncosign sign --key cosign.key -y ghcr.io/lzap/bootc-netboot-example:rhel-9.3.0-x86_64\n```\n\nTo verify content before it is pulled, use `-k` or `--signature-key` option.\n\n    ./nboci pull --signature-key cosign.pub --destination /tmp/test ghcr.io/lzap/bootc-netboot-example\n\nIf key is incorrect or signature is missing from the repo, the utility does not download the content.\n\n## How files are stored\n\nThis is described in the [specification](https://github.com/ipanova/netboot-oci-specs). Here is an example:\n\n```\n{\n  \"schemaVersion\": 2,\n  \"mediaType\": \"application/vnd.oci.image.manifest.v1+json\",\n  \"artifactType\": \"application/vnd.unknown.artifact.v1\",\n  \"config\": {\n    \"mediaType\": \"application/vnd.oci.empty.v1+json\",\n    \"digest\": \"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\",\n    \"size\": 2,\n    \"data\": \"e30=\"\n  },\n  \"layers\": [\n    {\n      \"mediaType\": \"application/x-netboot-file+zstd\",\n      \"digest\": \"sha256:8c4db4474646a08e4a251e2c1055cf5cf2c1c21f159e9a3ba74a381414652ad9\",\n      \"size\": 377793,\n      \"annotations\": {\n        \"org.opencontainers.image.title\": \"shim.efi\",\n        \"org.pulpproject.netboot.src.digest\": \"sha256:32e77976ebbc915f77dd7f15d66a52cb177d5a9d2ee1794b173390b67495c047\",\n        \"org.pulpproject.netboot.src.size\": \"946736\"\n      }\n    },\n    {\n      \"mediaType\": \"application/x-netboot-file+zstd\",\n      \"digest\": \"sha256:8526a40f8b5aa92dd35b01c03f2e748912d56b84c8675fe2f21e36a39b8eb388\",\n      \"size\": 565332,\n      \"annotations\": {\n        \"org.opencontainers.image.title\": \"grubx64.efi\",\n        \"org.pulpproject.netboot.src.digest\": \"sha256:735284626212a6267c0e90dab2428e8f82c182af17aec567c80838d219d9fa42\",\n        \"org.pulpproject.netboot.src.size\": \"2532984\"\n      }\n    },\n    {\n      \"mediaType\": \"application/x-netboot-file+zstd\",\n      \"digest\": \"sha256:d50baa5d4bf3af0fabebc7871b884be83f368c83dbe0ce1733087615808a6c15\",\n      \"size\": 41637,\n      \"annotations\": {\n        \"org.opencontainers.image.title\": \"pxelinux.0\",\n        \"org.pulpproject.netboot.src.digest\": \"sha256:dfcdf626efa753db88de0bf513c4c2e1c4e46cf084371e294e5f6864f16c2e01\",\n        \"org.pulpproject.netboot.src.size\": \"42555\"\n      }\n    },\n    {\n      \"mediaType\": \"application/x-netboot-file+zstd\",\n      \"digest\": \"sha256:e0180821662f2072771ecfbe4a242b3d7782126d06e1fa965f61e1247485943d\",\n      \"size\": 13020437,\n      \"annotations\": {\n        \"org.opencontainers.image.title\": \"vmlinuz\",\n        \"org.pulpproject.netboot.src.digest\": \"sha256:0d7a9a3c4804334b23cd43ffc3aedad4620192d9c520e2f466f56b96aeb2a284\",\n        \"org.pulpproject.netboot.src.size\": \"13335480\"\n      }\n    },\n    {\n      \"mediaType\": \"application/x-netboot-file+zstd\",\n      \"digest\": \"sha256:98328929370bdce755daaba59003399e5554a169feaf3cd9734c3f398f2f5b1c\",\n      \"size\": 100870099,\n      \"annotations\": {\n        \"org.opencontainers.image.title\": \"initrd.img\",\n        \"org.pulpproject.netboot.src.digest\": \"sha256:4080a4d952d5145625d18b822214982a87ad981c254fcac671ca9ea245da5e3d\",\n        \"org.pulpproject.netboot.src.size\": \"102417772\"\n      }\n    }\n  ],\n  \"annotations\": {\n    \"org.pulpproject.netboot.entrypoint\": \"shim.efi\",\n    \"org.pulpproject.netboot.altentrypoint\": \"grubx64.efi\",\n    \"org.pulpproject.netboot.legacyentrypoint\": \"pxelinux.0\",\n    \"org.pulpproject.netboot.os.arch\": \"x86_64\",\n    \"org.pulpproject.netboot.os.name\": \"rhel\",\n    \"org.pulpproject.netboot.os.version\": \"9.3.0\"\n  }\n}\n```\n\n## LICENSE\n\nApache License 2.0\n\n## TODO\n\n* rename repo to nboci\n* cosign integration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosbuild%2Fnboci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosbuild%2Fnboci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosbuild%2Fnboci/lists"}