Installation on a headless host: Difference between revisions

Revision as of 09:40, 1 April 2025

This page documents an easy installation procedure for Alpine Linux on a headless host i.e a system without keyboard, mouse & display to interact with but otherwise available only through a network connection. This procedure applies to all platforms.

Note: These steps still require physical access to the headless host. Somebody has to insert the Install media and power up the headless host.

Headless bootstrap overlay file

The Headless bootstrap repo provides a ready-to-use overlay file to bootstrap a headless system.

While straightforward to use in default use-case, repo homepage provides details on many optional settings and advanced modes like unattended installs scripting, secured logon, ssh keys configuration, etc.

Note: The author of above repo macmpi also maintains a number of raspberrypi* packages for Alpine Linux.

To Install Alpine Linux on a headless host, just add headless.apkovl.tar.gz overlay file as-is (along with optional config files) at the root of the Alpine Linux Installation media, or custom side media.

If using wifi networking, create a file wpa_supplicant.conf in the same location as follows:

Contents of wpa_supplicant.conf

country=FR

network={
	key_mgmt=WPA-PSK
	ssid="mySSID"
	psk="myPassPhrase"
}

Alternately, wpa_passphrase utility from wpa_supplicant package can be used to create the encrypted version of the above file as follows:

$ wpa_passphrase 'mySSID' 'myPassPhrase' > wpa_supplicant.conf

The above encrypted version of the wpa_supplicant.conf file may be placed in the same location.

Boot the system with the above setup: usual Installation steps can then be performed remotely using ssh

To find the ip of your headless host, one may use the nmap tool from nmap package as follows: $ nmap -v -sn 192.168.1.0/24

Alternative custom install media preparation steps

A Custom-made headless apkovl file can be created as per the below process.

This material needs expanding ...

Please feel free to help us complete it.

Booting the install media on some computer with a display and keyboard attached, or in a virtual machine, and doing an intermediate "diskless" setup of just the boot media (more details below), i.e. using the offical setup-alpine to configure the system's network, possibly for dhcp if needed, a ssh server, and a login user.
Choosing "disks=none" for now, yet, configure to store configs on the boot media (if it is writable, otherwise on a separate storage media).
Use lbu commit to store the configs as local backup. Then your completed setup, including its securely created own private keys, will readily get (re)loaded on every subsequent (headless) boot from your custom-build <hostname>.apkovl.tar.gz stored on the boot media (or on an auxilary media or server location, in case the boot media is read-only).

@@ Line 1: / Line 1: @@
-{{Draft}}
+This page documents an easy installation procedure for Alpine Linux on a headless host i.e a system without keyboard, mouse & display to interact with but otherwise available only through a network connection. This procedure applies to '''all''' platforms.
-{{TOC right}}
-= Introduction =
-This wiki describes a modified version of the original method I posted for [https://wiki.alpinelinux.org/wiki/Raspberry_Pi_-_Headless_Installation Headless installation on a Raspberry Pi.] While the original version worked for other architectures, like x86_64, it was targeted at and posted in the Raspberry Pi section since that was my primary focus at the time. Revisions to that page by other authors removed the mention of x86_64 altogether so this version will be more generally written in the hopes that it will be easier to find and that it's applicability will be clearer.
-Additionally, this version improves upon the original (in my opinion) by automatically logging in the root user and optionally running a shell script. This provides a means to perform unattended installations or other scripted tasks and does not require modification of the stock Alpine installation media / files.
+{{Note| These steps still require physical access to the headless host. Somebody has to insert the Install media and power up the headless host.}}
-The following functionality is provided:
+== Headless bootstrap overlay file ==
-* Automatic DHCP configuration of a network interface, either wired or wireless
-* Automatic configuration of sshd with password-less root login enabled
-* Automatic login of the root user on tty7
-* Automatic script execution (optional)
-[http://www.sodface.com/repo/headless.apkovl.tar.gz Download a pre-built overlay file here.]
+The [https://github.com/macmpi/alpine-linux-headless-bootstrap Headless bootstrap] repo provides a ready-to-use overlay file to bootstrap a headless system.
-= Basic Use =
+While straightforward to use in default use-case, repo homepage provides details on many optional settings and advanced modes like unattended installs scripting, secured logon, ssh keys configuration, etc.
-For Alpine supported Raspberry Pi models:
-# Download the applicable [https://alpinelinux.org/downloads/ Alpine installation tarball] and extract it to an SD card formatted with a single FAT partition.
-# Copy the [http://www.sodface.com/repo/headless.apkovl.tar.gz headless.apkovl.tar.gz] file to the root of the SD card.
-# Optionally, create a file named '''wifi.txt''' in the root of the SD card. See below for file format.
-# Optionally, create a file named '''unattended.sh''' in the root of the SD card. See below for an example.
-# Boot the Pi with the SD card.
-For other architectures (tested on various x86_64 hardware and a Qemu VM)
+{{Note|The author of above repo macmpi also maintains a number of {{pkg|raspberrypi*|arch=|maintainer=macmpi}} packages for Alpine Linux.}}
-# Download the applicable [https://alpinelinux.org/downloads/ Alpine installation file] and write it to usb stick or other media as needed.
-# Copy the [http://www.sodface.com/repo/headless.apkovl.tar.gz headless.apkovl.tar.gz] file to a second usb stick or other media separate from the installation media.
-# Optionally, create a file named '''wifi.txt''' in the root of second media. See below for file format.
-# Optionally, create a file named '''unattended.sh''' in the root of the second media. See below for an example.
-# Boot the device with both the installation and the secondary media connected.
-{{Cat|/etc/network/interfaces|
+To Install Alpine Linux on a headless host, just add [https://github.com/macmpi/alpine-linux-headless-bootstrap  headless.apkovl.tar.gz] overlay file as-is (along with optional config files) at the root of the Alpine Linux [[Installation#Preparing_installation_media|Installation media]], or custom side media.
-auto lo
-iface lo inet loopback
-auto wlan0
+If using wifi networking, create a file {{Path|wpa_supplicant.conf}} in the same location as follows:{{Cat|wpa_supplicant.conf|<nowiki>country=FR
-iface wlan0 inet dhcp
-	hostname wyse3030-3
-auto eth0
+network={
-iface eth0 inet manual
+	key_mgmt=WPA-PSK
-	pre-up ifconfig $IFACE up
+	ssid="mySSID"
-	pre-down ifconfig $IFACE down
+	psk="myPassPhrase"
+}</nowiki>}}
-}}
+Alternately, <code>wpa_passphrase</code> utility from {{pkg|wpa_supplicant}} package can be used to create the encrypted version of the above file as follows:{{Cmd|$ wpa_passphrase 'mySSID' 'myPassPhrase' > wpa_supplicant.conf}}
+The above encrypted version of the {{Path|wpa_supplicant.conf}} file may be placed in the same location.
-Notice that the wireless interface (wlan0) uses dhcp from the home network as usual and that an IP address is not used at all on the wired interface (eth0).
+Boot the system with the above setup: usual [[Installation#Installation_Step_Details|Installation steps]] can then be performed remotely using {{ic|ssh}}
-Enable and create a local start-up script to add route entries at boot:
+To find the ip of your headless host, one may use the {{ic|nmap}} tool from {{pkg|nmap}} package as follows: {{Codeline|$ nmap -v -sn 192.168.1.0/24}}
-{{Cmd| # rc-update add local default
+== Alternative custom install media preparation steps==
- # touch /etc/local.d/RouteAdd.start
- # chmod +x /etc/local.d/RouteAdd.start
+A Custom-made headless [[Diskless Mode#Apkovl|apkovl]] file can be created as per the below process.
-}}
+{{Expand}}
+* Booting the install media on some computer with a display and keyboard attached, or in a virtual machine, and doing an intermediate "diskless" setup of just the boot media (more details below), i.e. using the offical <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> to configure the system's network, possibly for dhcp if needed, a ssh server, and a login user.
+* Choosing "disks=none" for now, yet, configure to store configs on the boot media (if it is writable, otherwise on a separate storage media).
+* Use <code>[[Alpine_local_backup|lbu commit]]</code> to store the configs as local backup. Then your completed setup, including its securely created own private keys, will readily get (re)loaded on every subsequent (headless) boot from your custom-build <code><hostname>.apkovl.tar.gz</code> stored on the boot media (or on an auxilary media or server location, in case the boot media is read-only).
+==See also==
+* [[Diskless Mode#Apkovl|Diskless page with information on apkovl]]
+* [[Alpine local backup]]
+* [https://github.com/macmpi/alpine-linux-headless-bootstrap/ Bootstrap Alpine Linux on a headless system] using pre-built <code>apkovl</code> overlay file.
+[[Category:Installation]]