You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This web service will provides dynamic construction of iPXE scripts for booting and bootstrapping Zero-OS kernel images.
3
+
A network bootstrapping webservice that generates dynamic iPXE scripts, bootable ISO images, USB images, UEFI loaders, and kernel images for bare-metal node provisioning.
4
+
5
+
## What this is
6
+
7
+
0-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.
8
+
9
+
The 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.
10
+
11
+
## What this repository contains
12
+
13
+
-`bootstrap.py` — Flask web service that handles boot image generation
14
+
-`config.py` — Service configuration (networks, paths, ports)
15
+
-`setup/template.sh` — Pre-compilation script for iPXE templates
16
+
-`db/schema.sql` — SQLite schema for runtime provisioning database
17
+
-`kernel/` — Directory for kernel images (`zero-os-BRANCH-ARCH.efi`)
18
+
19
+
## Role in the stack
20
+
21
+
## ZOS / Zero-OS
22
+
23
+
ZOS, 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.
24
+
25
+
0-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.
26
+
27
+
## Relation to ThreeFold
28
+
29
+
This 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.
30
+
31
+
## Ownership
32
+
33
+
This repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.
4
34
5
35
## Endpoints
6
36
@@ -10,85 +40,81 @@ The most simple endpoint is the plain text version:
10
40
You can generate a bootable image with a bundle boot-script via:
11
41
-`/iso/`: generate a bootable ISO file
12
42
-`/usb/`: generate a bootable USB image file
13
-
-`/uefi/`: generate an UEFI bootloader file
14
-
-`/uefimg/`: same as above, but an image to be dd'd to an usb stick for UEFI boxes
15
-
-`/krn/`: generate directly-bootable kernel
16
-
17
-
Static target:
18
-
-`/krn-generic`: build a generic ipxe kernel, with our SSL certificates authorized
19
-
-`/uefi-generic`: build a generic ipxe uefi bootable image, with our SSL certificates authorized
20
-
-`/krn-provision`: build a generic ipxe kernel, calling our provisioning endpoint with nic mac address
21
-
-`/uefi-provision`: build a generic ipxe uefi bootable, calling our provisioning endpoint with nic mac address
43
+
-`/uefi/`: generate a UEFI bootloader file
44
+
-`/uefimg/`: same as above, but an image to be dd'd to a USB stick for UEFI boxes
45
+
-`/krn/`: generate a directly-bootable kernel
46
+
47
+
Static targets:
48
+
-`/krn-generic`: build a generic iPXE kernel, with SSL certificates authorized
49
+
-`/uefi-generic`: build a generic iPXE UEFI bootable image, with SSL certificates authorized
50
+
-`/krn-provision`: build a generic iPXE kernel, calling the provisioning endpoint with NIC MAC address
51
+
-`/uefi-provision`: build a generic iPXE UEFI bootable, calling the provisioning endpoint with NIC MAC address
22
52
-`/kernel/[name]`: provide the kernel (static file)
23
53
24
-
## Arguments
25
-
All endpoints (except `/krn-generic/` and `/kernel/` which are static) accepts more optional arguments:
54
+
### Arguments
55
+
56
+
All endpoints (except `/krn-generic/` and `/kernel/` which are static) accept optional arguments:
57
+
26
58
```
27
59
...endpoint/target/[farmer-id]/[extra-arguments]
28
60
```
29
61
30
-
Target can be one of the following, to specify in which environment kernel boots:
62
+
Target can be one of the following to specify the environment:
31
63
-`prod`: production environment
32
64
-`test`: testnet environment
33
65
-`dev`: devnet environment
34
66
-`qa`: quality-assurance special dedicated network
35
67
36
-
These networks are configurable via the `config.py` file. The dictionary pointed by `runmode` should contain
37
-
a short keyword and define a long pretty name.
68
+
These networks are configurable via `config.py`. The dictionary pointed to by `runmode` should contain a short keyword and define a long pretty name.
38
69
39
-
By default, theses default network have new links inside `kernel-net-path` config location. This directory should contains files
40
-
called `prod.efi`, `test.efi`, `dev.efi` and `qa.efi`. Theses files will be used as default kernel per network.
70
+
By 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.
41
71
42
-
> This introduce flexibility about kernel update and allow different kernel to serve differents network, so 'testnet' can use a test
43
-
kernel while 'prod' stay stable. In order to update kernel, it's easy when using symlinks (`prod.efi` can -and should- be a symlink to the
44
-
current kernel version).
72
+
This 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).
45
73
46
-
Any [argument] are optional, but are ordered and dependants (eg: you cannot provide extra argument without providing farmer-id network)
74
+
Any `[argument]` is optional, but arguments are ordered and dependent (you cannot provide extra arguments without providing the farmer-id and network).
47
75
48
-
Theses are valid endpoint example:
76
+
Valid endpoint examples:
49
77
-`/ipxe/prod`
50
78
-`/ipxe/test/1234`
51
79
-`/ipxe/dev/5550/console=ttyS0`
52
80
53
-
### Branches
54
-
55
-
### Extra Argument
56
-
57
-
Everything set on the last argument will be forwarded as-it to the kernel argument. You can set spaces, etc.
81
+
### Extra Arguments
58
82
83
+
Everything set in the last argument is forwarded as-is to the kernel argument line.
59
84
60
85
## Installation
61
86
62
-
To speedup ISO and USB images creation, the script will use a iPXE-template directory which contains a pre-compiled version of the sources.
87
+
To speed up ISO and USB image creation, the script uses an iPXEtemplate directory containing a pre-compiled version of the sources.
63
88
64
-
To pre-compile code, you can run the `setup/template.sh` script.
65
-
This will prepare the template and put it on `/opt/ipxe-template`.
89
+
To pre-compile, run the `setup/template.sh` script. This prepares the template and places it at `/opt/ipxe-template`.
66
90
67
-
In order to compile correctly the sources, you'll need (ubuntu): `build-essential syslinux liblzma-dev libz-dev genisoimage isolinux wget dosfstools udev`
0 commit comments