17 KiB
Aamsveen Audio Kiosk
Table of Contents
Prologue
This project is not primarily about building a Linux installation. It is about creating a simple, reliable and tamper-resistant music system for the Aamsveen Common Room.
The complete system (from the custom installation ISO and unattended partitioning, through the kiosk configuration and browser restrictions) is designed around five goals.
Project Goals
-
Create a fool-proof, tamper-resistant music system The computer is intended to have one clear purpose: controlling the music available in the Aamsveen Common Room. Users should not need to understand Linux, system administration, browsers, or computer security. The system deliberately restricts access to functions and websites that are not required for its purpose.
-
Make installation and re-installation easy If the computer ever needs to be replaced, its disk needs to be reset, or the installation becomes unusable, the system should be recoverable without manually configuring Linux from scratch. The custom ISO contains the necessary installation configuration and automation to reproduce the intended system.
-
Prevent unnecessary support questions The system is designed to eliminate as many things as possible that could go wrong during normal use. Configuration is automated, unnecessary options are hidden or disabled, access is restricted, and the intended user experience is deliberately simple. The objective is that people using the system should rarely need to ask someone how it works.
-
Assume little to no technical knowledge The intended operator should not have to know what Linux is, how partitions work, how Chromium policies work, or how a kiosk system is configured. Technical complexity belongs in the installation and maintenance scripts — not in the hands of the person using the music system.
-
Allow controlled administration when defaults need to change The installation creates a dedicated
av-adminadministrator account. This account provides an intentional and controlled way to adjust configuration when the default settings need to be changed — for example, when an approved music service or website needs to be added or removed.The normal kiosk user remains restricted and should not have access to these configuration mechanisms. Changes are therefore made by an administrator rather than by modifying the system from the public-facing kiosk environment.
Administrator Access
This creates a deliberate separation:
Normal user
│
▼
Restricted kiosk
│
│ no system configuration
│
▼
─────────────────────────────
│
│ administrator access
▼
av-admin
│
├── Adjust configuration
├── Change approved URLs
├── Refresh policies
└── Re-install / maintain system
In other words:
The technical complexity is intentional, but it should be invisible to the end user.
The project therefore treats the installation, configuration, security restrictions and kiosk interface as one complete system, rather than as separate scripts.
The desired end result is a computer that can essentially be:
Install → configure itself → lock itself down → present the music interface → keep doing its job.
When maintenance or recovery is required, the same principle applies:
Re-install → restore the known configuration → return the computer to service.
And when the default configuration needs to evolve:
av-admin → adjust configuration → refresh policies → return to normal kiosk operation.
This repository contains the automation required to make all of this possible.
Overview
The Aamsveen Audio Kiosk is a custom Linux Mint 22.3 Cinnamon 64-bit based system intended to provide a controlled music interface in the Aamsveen Common Room.
The project consists of three main layers:
┌─────────────────────────────────────────────┐
│ Custom Installation ISO │
│ │
│ Boot → Preseed → Automatic Installation │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Base Linux System │
│ │
│ Partitioning → Users → Packages → GRUB │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Kiosk Configuration │
│ │
│ Chromium → URL restrictions → Openbox │
│ LightDM → Auto-login → Kiosk environment │
└─────────────────────────────────────────────┘
The result is a reproducible, restricted workstation designed specifically for music control rather than general-purpose computer use.
Repository Structure
The repository contains the following important components:
.
├── build-aamsveen-iso.sh
├── install-kiosk-nl.sh
├── preseed.cfg
└── linuxmint-22.3-cinnamon-64bit.iso
build-aamsveen-iso.sh
Builds the final bootable Aamsveen installation ISO.
Its responsibilities include:
- Extracting the original Linux Mint ISO.
- Preserving the original UEFI boot image.
- Injecting the unattended installation configuration.
- Installing the kiosk configuration script into the live environment.
- Creating the custom installer launcher.
- Configuring the BIOS/ISOLINUX boot menu.
- Configuring the UEFI GRUB boot menu.
- Rebuilding the live filesystem.
- Creating the final hybrid BIOS/UEFI ISO.
- Verifying the resulting ISO.
The builder deliberately avoids modifying the original UEFI EFI image. The custom GRUB configuration is placed in the ISO filesystem and loaded through the existing EFI boot chain.
BIOS and UEFI Boot
The generated ISO supports both traditional BIOS and UEFI booting.
The boot structure is intentionally kept compatible with the original Linux Mint ISO while adding the custom unattended installation option.
BIOS
The BIOS/ISOLINUX menu provides:
Unattended Install Aamsveen Kiosk
This is configured as the default BIOS entry.
UEFI
The UEFI GRUB configuration provides the same unattended installation option while retaining access to the normal Linux Mint boot options.
The original efi.img is preserved byte-for-byte.
This reduces the risk of accidentally breaking the UEFI bootloader while modifying the installation media.
Hybrid ISO
The final ISO is built as a hybrid image supporting:
- BIOS boot
- UEFI boot
- GPT
- MBR
- Apple Partition Map compatibility where applicable
- USB installation media
The ISO is generated directly using xorriso.
No post-processing with isohybrid is required.
Unattended Installation
preseed.cfg
The preseed configuration controls the automated Linux installation.
Its purpose is to ensure that a fresh installation produces the same basic system every time.
It configures:
- Locale
- Keyboard
- Network
- Time zone
- User creation
- Disk selection
- Partitioning
- Filesystem creation
- Swap
- GRUB
- Ubiquity
- Installation behaviour
- Reboot behaviour
Automatic Disk Selection
The installation deliberately avoids the USB installation media when selecting the target disk.
This allows the same ISO to be used from removable installation media without accidentally selecting the installer USB as the installation target.
Warning: the selected target disk is intentionally erased during installation.
Partition Layout
The installation uses GPT with the partitions required for both BIOS and UEFI booting.
Conceptually:
GPT disk
│
├── BIOS Boot partition
│
├── EFI System Partition
│
├── Linux root filesystem
│
└── Swap
The BIOS Boot partition allows GRUB to operate correctly when a GPT disk is booted in legacy BIOS mode.
The EFI System Partition provides UEFI boot support.
Kiosk Configuration
install-kiosk-nl.sh
After Linux has been installed, this script converts the normal desktop installation into the Aamsveen Audio Kiosk.
It handles the majority of the post-install configuration.
The script:
- Creates the kiosk user.
- Configures user groups.
- Installs the kiosk desktop components.
- Installs Chromium.
- Applies Chromium enterprise policies.
- Configures the permitted websites.
- Restricts popups.
- Disables unnecessary browser functionality.
- Configures Openbox.
- Configures LightDM automatic login.
- Configures the kiosk browser launcher.
- Provides administrator access mechanisms.
- Installs the policy refresh script.
The result is a system where the user does not interact with a normal Linux desktop.
Browser Restrictions
Chromium is configured using managed enterprise policies.
The system uses a default-deny approach:
All websites
│
▼
BLOCKED
│
├── Approved music/control sites
│
└── Explicitly approved popup destinations
Only explicitly approved destinations are allowed.
The configuration also disables or restricts functionality that is unnecessary for the kiosk, including:
- Extensions
- Developer tools
- Incognito mode
- Guest mode
- Additional browser users
- Browser sign-in
- Synchronisation
- Password storage
- Autofill
- Notifications
- Geolocation
- Printing
- Translation
- Unrestricted downloads
This reduces both accidental misuse and the amount of functionality that needs to be supported.
Kiosk Desktop
The kiosk uses:
- LightDM for login management.
- Openbox as the lightweight desktop environment.
- Chromium as the user interface.
- Unclutter to hide the mouse cursor when appropriate.
- X11 configuration to restrict unwanted virtual-terminal switching.
LightDM automatically logs the kiosk user into the Openbox session.
Openbox then starts the kiosk browser.
The user therefore effectively sees:
Power on
│
▼
Automatic login
│
▼
Kiosk session
│
▼
Chromium
│
▼
Approved music interface
There is no requirement for the normal user to understand or interact with the underlying Linux desktop.
Administrator Access
The system distinguishes between the normal kiosk user and the administrator account.
The kiosk user is intended for everyday operation.
The av-admin account is intended for maintenance, configuration changes and recovery.
This separation allows the everyday interface to remain highly restricted without preventing authorised maintenance.
The administrator can, when necessary:
- Change the approved website list.
- Adjust kiosk configuration.
- Refresh Chromium policies.
- Perform maintenance.
- Reinstall or recover the system.
The intention is that changes to the system are made deliberately and centrally, rather than by allowing normal users to alter the kiosk environment.
Policy Refresh
The installer creates:
/etc/kiosk/refresh_policies.sh
and exposes it through the administrator's kiosk directory.
The purpose of this script is to allow the configured kiosk policies to be refreshed after changes to the approved URL configuration.
The intended workflow is:
Edit approved URLs
│
▼
Refresh kiosk policies
│
▼
Restart Chromium
│
▼
New policy takes effect
This avoids having to manually edit Chromium's managed policy files.
Re-installation
A major design objective of this project is reproducibility.
The system should not depend on undocumented manual configuration steps.
The desired recovery procedure is therefore:
Boot custom ISO
│
▼
Automatic installation
│
▼
Known partition layout
│
▼
Linux Mint installed
│
▼
Kiosk configuration applied
│
▼
Reboot
│
▼
Aamsveen Audio Kiosk
This makes the system practical to recover or deploy on replacement hardware without requiring extensive Linux knowledge.
Building the ISO
The ISO builder expects a Linux Mint 22.3 Cinnamon 64-bit ISO as its base image.
The build process requires tools such as:
xorrisounsquashfsmksquashfs- Standard filesystem and archive utilities
The builder performs validation before modifying the image and performs additional verification after the final ISO has been created.
The resulting ISO can then be tested in QEMU or written to USB installation media.
Testing
QEMU can be used to test the generated ISO before deploying it to physical hardware.
For example:
qemu-system-x86_64 \
-enable-kvm \
-cpu host \
-smp 4 \
-m 8G \
-boot order=d \
-cdrom ./non-aamsveen-audio-kiosk_v1.iso \
-drive file=./mint.qcow2,format=qcow2,if=ide \
-vga std \
-display gtk \
-usb \
-device usb-tablet
The -boot order=d option ensures that QEMU boots the CD-ROM image first.
Both BIOS and UEFI behaviour should be tested before using the ISO on production hardware.
Writing the ISO to USB
The final ISO can be written directly to a USB drive.
Be extremely careful when selecting the target device. Writing the ISO to the wrong device will overwrite it.
A typical workflow is:
lsblk
Unmount any mounted partitions on the target USB device and then write the ISO to the whole device, not to an individual partition.
For example:
sudo dd if=non-aamsveen-audio-kiosk_v1.iso \
of=/dev/sdX \
bs=4M \
status=progress \
conv=fsync
Replace /dev/sdX with the correct USB device.
Design Principles
The project intentionally follows a few simple principles.
Simple for the User
The person using the music system should not have to understand the computer.
Strict by Default
Anything that is not required for the kiosk should be unavailable.
Reproducible
A replacement machine should be installable from the same basic inputs.
Automated
Manual configuration steps should be avoided wherever possible.
Recoverable
If something goes wrong, reinstallation should be a practical recovery mechanism.
Minimal Support Burden
The system should prevent common configuration and usage problems rather than requiring someone to explain how to fix them afterward.
Separate Operation from Administration
Normal users receive a restricted kiosk environment. Administrative functionality remains available to authorised administrators through av-admin.
Important Warning
The installation is intentionally destructive.
The selected installation target disk is erased and repartitioned.
Always verify the target hardware before starting an installation.
The ISO should be tested thoroughly in a virtual machine before deployment to physical hardware.
Summary
The Aamsveen Audio Kiosk is intended to be more than a customised Linux desktop.
It is a controlled appliance.
The combination of:
- Automated installation
- Reproducible partitioning
- BIOS and UEFI boot support
- Restricted Chromium policies
- Controlled website access
- Automatic kiosk login
- A dedicated kiosk environment
- Administrator separation
- Automated policy management
- Easy reinstallation
is designed to produce a system that can be handed to someone with little or no technical knowledge and simply used for its intended purpose.
The underlying Linux system and scripts may be technically complex.
The experience of using the finished system should not be.