Installation on a headless host: Difference between revisions

Latest revision as of 16:36, 4 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. Somebody has to insert the Install media and power up the headless host. This procedure applies to all platforms.

Headless bootstrap overlay file

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

While straightforward in default use-case, many optional settings and advanced modes are detailed on repo homepage (unattended installs scripting, secured logon, ssh keys configuration, gadget-modes, 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 customizable boot device, or of a 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 install media for a headless host can be created using a customizable boot device as per the below process.

Note: Instead of customizable boot device, if a read-only boot media is used, then storing the configs require either a separate storage media or server location.

Booting the customizable boot device 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 customizable boot device.
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 customizable boot device.

@@ 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. Somebody has to insert the Install media and power up the headless host. 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.]
-= Method 1: Proxy ARP =
+== Headless bootstrap overlay file ==
-These steps result in a working solution where hosts on the wired side and hosts on the wireless side are all in the same ip network. There are no frills added, such as dhcp or automatic route entries for the wired hosts. Each wired host needs to have a manually configured IP address and an entry manually added to the bridge host's routing table.
-Note: For your wired hosts, use IP addresses in the same IP range as the rest of your network but outside of the scope used by a local DHCP server, if applicable. You may need to reduce your DHCP scope to free up IP addresses for this purpose.
+The [https://github.com/macmpi/alpine-linux-headless-bootstrap Headless bootstrap] repo provides a ready-to-use overlay file to bootstrap a headless system.
-Configure the network interfaces on your bridge host:
+While straightforward in default use-case, many optional settings and advanced modes are detailed on repo homepage (unattended installs scripting, secured logon, ssh keys configuration, gadget-modes, etc).
-{{Cat|/etc/network/interfaces|
+{{Note|The author of above repo macmpi also maintains a number of {{pkg|raspberrypi*|arch=|maintainer=macmpi}} packages for Alpine Linux.}}
-auto lo
-iface lo inet loopback
-auto wlan0
+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 [[Create a Bootable Device|customizable boot device]], or of a side media.
-iface wlan0 inet dhcp
-	hostname wyse3030-3
-auto eth0
+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 eth0 inet manual
-	pre-up ifconfig $IFACE up
-	pre-down ifconfig $IFACE down
-}}
+network={
+	key_mgmt=WPA-PSK
+	ssid="mySSID"
+	psk="myPassPhrase"
+}</nowiki>}}
-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).
+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.
-Enable and create a local start-up script to add route entries at boot:
+Boot the system with the above setup: usual [[Installation#Installation_Step_Details|Installation steps]] can then be performed remotely using {{ic|ssh}}
-{{Cmd| # rc-update add local default
+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}}
- # touch /etc/local.d/RouteAdd.start
- # chmod +x /etc/local.d/RouteAdd.start
+== Alternative custom install media preparation steps==
-}}
+A Custom install media for a headless host can be created using a [[Create a Bootable Device|customizable boot device]] as per the below process.
+{{Note|Instead of [[Create a Bootable Device|customizable boot device]], if a read-only boot media is used, then storing the configs require either a separate storage media or server location.}}
+* Booting the [[Create a Bootable Device|customizable boot device]] 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 customizable boot device.
+* 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 customizable boot device.
+==See also==
+* [[Create a Bootable Device|Customizable boot device page]]
+* [[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]]