220 lines
4.9 KiB
Markdown
220 lines
4.9 KiB
Markdown
# Fedora 42 Custom Live ISO Builder
|
|
|
|
A Makefile-based toolchain for building custom Fedora 42 live ISOs optimized for specific use cases like Point-of-Sale systems, kiosks, security workstations, and minimal servers.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install dependencies (requires Fedora)
|
|
sudo make deps
|
|
|
|
# Generate kickstart templates
|
|
make init-kickstarts
|
|
|
|
# Build minimal ISO
|
|
sudo make iso VARIANT=minimal
|
|
|
|
# Test in QEMU
|
|
make test-qemu
|
|
```
|
|
|
|
## Available Variants
|
|
|
|
| Variant | Description | Approx Size |
|
|
| ------------- | ---------------------------------------- | ----------- |
|
|
| `minimal` | Bare minimum bootable system with SSH | ~400MB |
|
|
| `kiosk` | Single-app kiosk/PoS with Cage + Firefox | ~800MB |
|
|
| `workstation` | Lightweight GUI with Sway | ~1.2GB |
|
|
| `security` | Security/forensics toolkit | ~1.5GB |
|
|
|
|
## Requirements
|
|
|
|
- Fedora 42 (or compatible) host system
|
|
- Root privileges for ISO creation
|
|
- ~10GB free disk space
|
|
- KVM support recommended (or use `iso-novirt`)
|
|
|
|
## Usage
|
|
|
|
### Build Commands
|
|
|
|
```bash
|
|
# Build with default (minimal) variant
|
|
sudo make iso
|
|
|
|
# Build specific variant
|
|
sudo make iso VARIANT=kiosk
|
|
sudo make iso VARIANT=workstation
|
|
sudo make iso VARIANT=security
|
|
|
|
# Use custom kickstart
|
|
sudo make iso KICKSTART=/path/to/custom.ks
|
|
|
|
# Build without KVM (slower, works in containers)
|
|
sudo make iso-novirt VARIANT=minimal
|
|
```
|
|
|
|
### Utility Commands
|
|
|
|
```bash
|
|
# Validate kickstart syntax
|
|
make validate KICKSTART=kickstarts/minimal.ks
|
|
|
|
# Test ISO in QEMU
|
|
make test-qemu
|
|
|
|
# Generate checksums
|
|
make checksum
|
|
|
|
# Show configuration
|
|
make info
|
|
|
|
# Clean build artifacts
|
|
make clean
|
|
sudo make distclean # Also removes output/
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Modifying Kickstarts
|
|
|
|
The kickstart files in `kickstarts/` control the entire OS configuration:
|
|
|
|
1. **Packages**: Add/remove packages in the `%packages` section
|
|
2. **Services**: Enable/disable systemd units in `%post`
|
|
3. **Users**: Configure users and authentication
|
|
4. **Partitioning**: Customize disk layout
|
|
|
|
### Adding Custom Files
|
|
|
|
1. Place files in `overlays/<variant>/`
|
|
2. Copy them in the `%post` section of your kickstart
|
|
|
|
Example:
|
|
|
|
```bash
|
|
%post
|
|
# Copy custom configs
|
|
cp -r /run/install/repo/overlays/* /
|
|
%end
|
|
```
|
|
|
|
### Creating New Variants
|
|
|
|
1. Create `kickstarts/myvariant.ks`
|
|
2. Build with `sudo make iso VARIANT=myvariant`
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
.
|
|
├── Makefile # Build system
|
|
├── README.md
|
|
├── kickstarts/ # Kickstart definitions
|
|
│ ├── minimal.ks
|
|
│ ├── kiosk.ks
|
|
│ ├── workstation.ks
|
|
│ └── security.ks
|
|
├── overlays/ # Files to include in ISO
|
|
├── build/ # Temporary build files
|
|
├── cache/ # Downloaded packages (preserved)
|
|
└── output/ # Final ISO files
|
|
└── fedora-42-custom-*.iso
|
|
```
|
|
|
|
## PoS/Kiosk Specific Notes
|
|
|
|
For Point-of-Sale or kiosk deployments:
|
|
|
|
### Security Hardening
|
|
|
|
```kickstart
|
|
%post
|
|
# Disable USB storage
|
|
echo "blacklist usb-storage" > /etc/modprobe.d/blacklist-usb.conf
|
|
|
|
# Disable Ctrl+Alt+Del reboot
|
|
systemctl mask ctrl-alt-del.target
|
|
|
|
# Read-only root filesystem (advanced)
|
|
# Add 'ro' to kernel cmdline and use overlayfs
|
|
%end
|
|
```
|
|
|
|
### Auto-start Application
|
|
|
|
The `kiosk` variant uses Cage (minimal Wayland compositor) to run Firefox in kiosk mode. Modify `/home/kiosk/.bash_profile` to launch your application:
|
|
|
|
```bash
|
|
# For a custom app
|
|
exec cage -- /usr/local/bin/my-pos-app
|
|
|
|
# For a web app
|
|
exec cage -- firefox --kiosk https://pos.example.com
|
|
|
|
# For Electron apps
|
|
exec cage -- /opt/myapp/myapp --kiosk
|
|
```
|
|
|
|
### Network Configuration
|
|
|
|
For static IP (common in PoS):
|
|
|
|
```kickstart
|
|
network --bootproto=static --ip=192.168.1.100 --netmask=255.255.255.0 \
|
|
--gateway=192.168.1.1 --nameserver=192.168.1.1 --device=link
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Build fails with "No space left on device"
|
|
|
|
The build uses `/var/tmp/lorax-build` by default. Either:
|
|
|
|
- Free space on that partition
|
|
- Change `TMP_DIR` in Makefile to a larger partition
|
|
|
|
### "Cannot find a valid baseurl"
|
|
|
|
Network issues or mirror problems. Try:
|
|
|
|
```bash
|
|
# Use a specific mirror
|
|
sudo make iso LORAX_REPO=https://mirror.example.com/fedora/42/Everything/x86_64/os/
|
|
```
|
|
|
|
### SELinux denials
|
|
|
|
If building in a container or restricted environment:
|
|
|
|
```bash
|
|
# Temporarily set permissive (not recommended for production)
|
|
sudo setenforce 0
|
|
sudo make iso
|
|
sudo setenforce 1
|
|
```
|
|
|
|
### ISO won't boot
|
|
|
|
1. Verify checksum: `make checksum`
|
|
2. Check implanted MD5: `checkisomd5 output/*.iso`
|
|
3. Review build log: `less build/livemedia.log`
|
|
|
|
## Advanced: Building in Containers
|
|
|
|
For reproducible builds in CI/CD:
|
|
|
|
```bash
|
|
podman run --rm -it --privileged \
|
|
-v $(pwd):/build:Z \
|
|
-v /dev:/dev \
|
|
registry.fedoraproject.org/fedora:42 \
|
|
bash -c "cd /build && make deps && make iso-novirt"
|
|
```
|
|
|
|
Note: Container builds require `--privileged` for loop devices and must use `iso-novirt`.
|
|
|
|
## License
|
|
|
|
MIT - Do whatever you want with this.
|