{"id":50465370,"url":"https://github.com/threefoldtech/zos_bootstrap","last_synced_at":"2026-06-01T07:02:43.925Z","repository":{"id":84223068,"uuid":"142880311","full_name":"threefoldtech/zos_bootstrap","owner":"threefoldtech","description":"Zero-OS Bootstrap Webservice","archived":false,"fork":false,"pushed_at":"2026-05-27T14:04:56.000Z","size":339,"stargazers_count":1,"open_issues_count":8,"forks_count":2,"subscribers_count":15,"default_branch":"development-v3","last_synced_at":"2026-05-27T16:07:04.067Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/threefoldtech.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":"2018-07-30T13:36:13.000Z","updated_at":"2026-05-27T14:06:47.000Z","dependencies_parsed_at":"2024-04-27T00:24:17.027Z","dependency_job_id":"bb72d0a1-1347-4cec-8d41-9531e2431e06","html_url":"https://github.com/threefoldtech/zos_bootstrap","commit_stats":null,"previous_names":["threefoldtech/zos_bootstrap"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/threefoldtech/zos_bootstrap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fzos_bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fzos_bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fzos_bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fzos_bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threefoldtech","download_url":"https://codeload.github.com/threefoldtech/zos_bootstrap/tar.gz/refs/heads/development-v3","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fzos_bootstrap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33763655,"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-01T02:00:06.963Z","response_time":115,"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":[],"created_at":"2026-06-01T07:02:43.381Z","updated_at":"2026-06-01T07:02:43.917Z","avatar_url":"https://github.com/threefoldtech.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZOS Bootstrap\n\nA network bootstrapping webservice that generates dynamic iPXE scripts, bootable ISO images, USB images, UEFI loaders, and kernel images for bare-metal node provisioning.\n\n## What this is\n\nZOS Bootstrap provides network bootstrapping capabilities for Zero-OS nodes. It delivers initial configuration and boot images over the network, enabling automated operating system provisioning without manual intervention. The service generates custom boot configurations based on node identity and network parameters.\n\nThe webservice is built with Flask and serves as the entry point for nodes joining the infrastructure, producing iPXE scripts, ISO files, USB images, UEFI bootloaders, and directly-bootable kernels on demand.\n\n## What this repository contains\n\n- `bootstrap.py` — Flask web service that handles boot image generation\n- `config.py` — Service configuration (networks, paths, ports)\n- `setup/template.sh` — Pre-compilation script for iPXE templates\n- `db/schema.sql` — SQLite schema for runtime provisioning database\n- `kernel/` — Directory for kernel images (`zero-os-BRANCH-ARCH.efi`)\n\n## Role in the stack\n\n## ZOS / Zero-OS\n\nZOS, also known as Zero-OS, is the operating system layer used to run and manage nodes. It provides the low-level runtime environment for workloads, networking, storage, and automation.\n\nZOS Bootstrap is the first service a bare-metal node contacts when joining the network. It produces the correct boot artifacts so that ZOS can be fetched and started automatically. The service supports multiple environments (production, test, development, QA) via configurable network profiles.\n\n## Relation to ThreeFold\n\nThis technology is used within the ThreeFold ecosystem and was first deployed on the ThreeFold Grid. The component itself is designed as reusable infrastructure technology and should be understood by its technical function first, independent of any specific deployment.\n\n## Ownership\n\nThis repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.\n\n## Endpoints\n\nThe most simple endpoint is the plain text version:\n- `/ipxe/`: generate an iPXE plain text script to boot\n\nYou can generate a bootable image with a bundle boot-script via:\n- `/iso/`: generate a bootable ISO file\n- `/usb/`: generate a bootable USB image file\n- `/uefi/`: generate a UEFI bootloader file\n- `/uefimg/`: same as above, but an image to be dd'd to a USB stick for UEFI boxes\n- `/krn/`: generate a directly-bootable kernel\n\nStatic targets:\n- `/krn-generic`: build a generic iPXE kernel, with SSL certificates authorized\n- `/uefi-generic`: build a generic iPXE UEFI bootable image, with SSL certificates authorized\n- `/krn-provision`: build a generic iPXE kernel, calling the provisioning endpoint with NIC MAC address\n- `/uefi-provision`: build a generic iPXE UEFI bootable, calling the provisioning endpoint with NIC MAC address\n- `/kernel/[name]`: provide the kernel (static file)\n\n### Arguments\n\nAll endpoints (except `/krn-generic/` and `/kernel/` which are static) accept optional arguments:\n\n```\n...endpoint/target/[farmer-id]/[extra-arguments]\n```\n\nTarget can be one of the following to specify the environment:\n- `prod`: production environment\n- `test`: testnet environment\n- `dev`: devnet environment\n- `qa`: quality-assurance special dedicated network\n\nThese networks are configurable via `config.py`. The dictionary pointed to by `runmode` should contain a short keyword and define a long pretty name.\n\nBy default, these networks have links inside the `kernel-net-path` config location. This directory should contain files called `prod.efi`, `test.efi`, `dev.efi`, and `qa.efi`. These files are used as the default kernel per network.\n\nThis provides flexibility for kernel updates and allows different kernels to serve different networks, so testnet can use a test kernel while production stays stable. Using symlinks is recommended (`prod.efi` can be a symlink to the current kernel version).\n\nAny `[argument]` is optional, but arguments are ordered and dependent (you cannot provide extra arguments without providing the farmer-id and network).\n\nValid endpoint examples:\n- `/ipxe/prod`\n- `/ipxe/test/1234`\n- `/ipxe/dev/5550/console=ttyS0`\n\n### Extra Arguments\n\nEverything set in the last argument is forwarded as-is to the kernel argument line.\n\n## Installation\n\nTo speed up ISO and USB image creation, the script uses an iPXE template directory containing a pre-compiled version of the sources.\n\nTo pre-compile, run the `setup/template.sh` script. This prepares the template and places it at `/opt/ipxe-template`.\n\nBuild dependencies (Ubuntu): `build-essential syslinux liblzma-dev libz-dev genisoimage isolinux wget dosfstools udev`\n\n### Database\n\nClients can be provisioned at runtime using a database. You need to create the database, even if it is empty:\n\n```bash\ncat db/schema.sql | sqlite3 db/bootstrap.sqlite3\n```\n\n## Run\n\nThis is a Flask web service. Run the `bootstrap.py` server file. On Ubuntu you will need `python3-flask`.\n\nKernel images are served from the `kernel` directory. Images are in the form: `zero-os-BRANCH-ARCH.efi`\n\n## Configuration\n\nYou can customize the service by editing `config.py`:\n- `base-host`: HTTP web address (e.g., `https://bootstrap.grid.tf`)\n- `ipxe-template`: iPXE template path (default: `/opt/ipxe-template`)\n- `ipxe-template-uefi`: iPXE UEFI template path (default: `/opt/ipxe-template-uefi`)\n- `kernel-path`: path where to find kernels\n- `http-port`: HTTP listen port\n- `debug`: enable (`True`) or disable (`False`) Flask debug mode\n\n## License\n\nThis project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Fzos_bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreefoldtech%2Fzos_bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Fzos_bootstrap/lists"}