tsiry-sandratraina.com
Simple script and config (type-safe) for building custom Linux kernels for Firecracker MicroVMs
1# vmlinux-builder
2
3[](https://github.com/tsirysndr/vmlinux-builder/actions/workflows/tests.yml)
4[](https://hub.docker.com/r/tsiry/vmlinux-builder)
5[](https://jsr.io/@tsiry/vmlinux-builder)
6
7[](https://github.com/tsirysndr/vmlinux-builder/actions/workflows/ci.yml)
8
9📦 **vmlinux-builder** is a lightweight TypeScript/Deno-based tool to fetch, configure, and build the Linux kernel `vmlinux` image for a given version — ideal for use with Firecracker microVMs or other kernel-related debugging/testing tasks.
10
11## ✨ Features
12
13- Builds any stable Linux kernel version (e.g., `6.1`, `6.1.12`, `6.1.y`)
14- Enhanced kernel configuration handling with customizable options
15- Uses a custom `.config` for reproducible builds
16- Outputs a ready-to-use `vmlinux-X.Y-[arch]` file
17- Written in TypeScript with Deno for better type safety and cross-platform compatibility
18- Colored output using Chalk for improved readability
19- Easily integrated into CI pipelines (e.g., GitHub Actions)
20
21## 🛠 Prerequisites
22
23### System Dependencies
24
25Ensure you have the following dependencies installed:
26
27```bash
28sudo apt-get install -y git build-essential flex bison libncurses5-dev \
29libssl-dev gcc bc libelf-dev pahole
30```
31
32### Deno Runtime
33
34Install Deno if you haven't already:
35
36```bash
37curl -fsSL https://deno.land/install.sh | sh
38```
39
40Or follow the [official Deno installation guide](https://docs.deno.com/runtime/getting_started/installation).
41
42## 🚀 Usage
43
44```bash
45deno run -A jsr:@tsiry/vmlinux-builder 6.17.7
46```
47
48Or with docker:
49
50```bash
51docker volume create linux-build
52docker run --rm -it -v linux-build:/app tsiry/vmlinux-builder:latest 6.17.7
53```
54
55### Supported Version Formats
56
57- `6.1` - Major.Minor version
58- `6.1.12` - Specific patch version
59- `6.1.y` - Latest from maintenance branch
60- `v6.1.12` - Version with 'v' prefix (automatically normalized)
61
62### Kernel Configuration
63
64The tool provides enhanced kernel configuration handling with:
65
66- Support for TUN and TUN_VNET_CROSS_LE
67- Various netfilter options enabled
68- Customizable configuration through environment variables
69- Reproducible builds with consistent config options
70
71### Example output
72
73```sh
74Building vmlinux for Linux kernel 6.16 (x86_64)
75vmlinux built successfully!
76You can find the vmlinux file in /path/to/linux-stable/vmlinux-6.16.x86_64
77```
78
79## 📦 GitHub Actions
80
81This repo includes a GitHub Actions workflow (`.github/workflows/ci.yml`) that:
82
83- Triggers on tag push (e.g. `git tag 6.16.y && git push origin 6.16.y`)
84- Builds the vmlinux for both x86_64 and aarch64 architectures
85- Publishes the resulting `vmlinux-X.Y-[arch]` files as GitHub Release assets
86- Includes SHA256 checksums for all released files
87
88## 🧩 Config API Usage
89
90The `config.ts` module provides a type-safe API for parsing, validating, extracting, and serializing Linux kernel `.config` files.
91
92### Parse a kernel config file
93
94```ts
95import { KernelConfigParser } from '@tsiry/vmlinux-builder';
96const content = await Deno.readTextFile('path/to/.config');
97const config = KernelConfigParser.parse(content);
98```
99
100### Extract config categories
101
102```ts
103import { KernelConfigParser } from '@tsiry/vmlinux-builder';
104const processor = KernelConfigParser.extractProcessorConfig(config);
105const security = KernelConfigParser.extractSecurityConfig(config);
106const networking = KernelConfigParser.extractNetworkingConfig(config);
107const filesystem = KernelConfigParser.extractFilesystemConfig(config);
108```
109
110### Serialize config to different formats
111
112```ts
113import { KernelConfigSerializer } from '@tsiry/vmlinux-builder';
114const asConfig = KernelConfigSerializer.toConfig(config); // .config format
115const asJSON = KernelConfigSerializer.toJSON(config);
116const asTOML = KernelConfigSerializer.toTOML(config);
117const asYAML = KernelConfigSerializer.toYAML(config);
118```
119
120### Validate a config
121
122```ts
123import { validateKernelConfig } from '@tsiry/vmlinux-builder';
124const result = validateKernelConfig(config);
125if (!result.success) {
126 throw new Error('Invalid kernel config');
127}
128```
129
130See `config.ts` for more advanced usage and options.
131
132The script is written in TypeScript and runs on Deno. Key features:
133
134- **Type-safe**: Full TypeScript support with type checking
135- **Modern**: Uses Deno's native APIs for file operations and process management
136- **Colored output**: Enhanced user experience with Chalk
137
138## 📄 License
139
140This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.