Alpine Linux - User contributions [en]

Wi-Fi

2025-04-13T06:12:03Z

Cos: Update dead link to its new location

Alpine Linux supports two wireless daemons i.e [[#wpa_supplicant|wpa_supplicant]] and [[iwd]]. This page describes how to set up a wireless network connection using the default daemon [[#wpa_supplicant|wpa_supplicant]]. The [[iwd]] daemon is also fully supported in Alpine Linux. {{Note|Do not use both wireless daemons i.e [[#wpa_supplicant|wpa_supplicant]] and [[iwd]] simultaneously, as it leads to conflicts.}}

== Prerequisites ==

Working wireless drivers. To list your available network interfaces use the commands {{ic|ip link}} or {{ic|ip a}}. Refer to [[#Troubleshooting|Troubleshooting]] section if you don't see any wireless interfaces (e.g. {{Path|wlan0}}).

== Setup-interfaces ==

The [[Configure_Networking#setup-interfaces|setup-interfaces]] script automates the installation and configuration of
<code>wpa_supplicant</code> daemon to use Wi-Fi. [[NetworkManager]] can then be used to manage your Wi-Fi using various gui/tui tools.

== Manual configuration ==

To get started install {{Pkg|wpa_supplicant}} package: {{Cmd|# apk add wpa_supplicant}}

Use this command to add your Wi-Fi network to wpa_supplicant: {{Cmd|# wpa_passphrase 'ExampleWifiSSID' 'ExampleWifiPassword' > /etc/wpa_supplicant/wpa_supplicant.conf}}
''(Access point not broadcasting its SSID requires additional line <code>scan_ssid=1</code> in the file {{Path|/etc/wpa_supplicant/wpa_supplicant.conf}})''

{{Note|the Wi-Fi SSID and password are case sensitive and the single quote before and after the SSID and password need to be there}}

Start wpa_supplicant in the foreground to check if wireless connection succeeds.{{Cmd|# wpa_supplicant -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf}}

'''Optional security precaution:'''

By default {{Pkg|wpa_supplicant}} will store your Wi-Fi password in plain text:{{Cat|/etc/wpa_supplicant/wpa_supplicant.conf|<nowiki>network={
ssid="<YourSSIDShouldBeHere>"
#psk="<YourPasswordShouldBeHereInPlainText>"
psk=<RandomLettersAndNumbersShouldBeHere>
}</nowiki>}}
If you dont want your stored password in plain text just delete the line with <code>#psk="<YourPasswordShouldBeHereInPlainText>"</code> on it.

If all is well, run it as a daemon in the background by setting the {{Path|-B}} option. {{Cmd|# wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf}}

Configure the interface with an IP address.{{Cmd|# udhcpc -i wlan0}}

Sanity check: the interface should have a {{Path|inet}} address. {{Cmd|$ ip addr show wlan0}}

Add a entry for the desired interface (e.g. <code>wlan0</code>) in the file as follows:{{Cat|/etc/network/interfaces|auto lo
auto wlan0
iface wlan0 inet dhcp}}

{{Warning|Don't remove or comment out the '''auto lo''' entry}}

Sanity check: Make sure {{Path|/etc/wpa_supplicant/wpa_supplicant.conf}} is the correct configuration for the wireless access point you want to connect to.

Bring the interface down. {{Cmd|# ip link set wlan0 down}}

Manually restart (or '''start''') '''networking'''.{{Cmd|# rc-service networking --quiet restart &}}

Perform [[Configure_Networking#Connectivity_testing|sanity checks]]. For issues related to name resolution, refer [[Configure_Networking#Configuring_DNS|Networking]] section.

=== Service configuration ===
{{Seealso|NetworkManager}}

Proceed to configure wpa_supplicant service to start automatically on boot, if networking works properly: {{Cmd|# rc-update add wpa_supplicant boot}}
Also ensure that '''networking''' is set to automatically start on boot: {{Cmd|# rc-update add networking boot}}

Manage wpa_supplicant service using the standard '''start''', '''stop''' and '''restart''' options. For eg: to start wpa_supplicant service: {{Cmd|# rc-service wpa_supplicant start}}

=== Launching udhcpc through wpa_cli actions ===

With the above configuration, udhcpc will only run once at boot. If the Wifi isn't available then, or the network changes after booting, udhcpc needs to be notified. You can automatically notify udhcpc of network changes by using a wpa_cli action file, such as the one installed by default at {{Path|/etc/wpa_supplicant/wpa_cli.sh}}.

To manually start a wpa_cli daemon with an action file, use the `-a` option: {{Cmd|# wpa_cli -a /etc/wpa_supplicant/wpa_cli.sh}}

To do this automatically, use the `wpa_cli` service included in {{Pkg|wpa_supplicant-openrc}}: {{Cat|/etc/conf.d/wpa_cli|<nowiki>WPACLI_OPTS="-a /etc/wpa_supplicant/wpa_cli.sh"</nowiki>}}
Add the service to start at boot: {{Cmd|# rc-update add wpa_cli boot}}

== Troubleshooting ==

If the commands {{ic|ip link}} or {{ic|ip a}} do not show any {{Path|wlan0}} interface, you probably need to load and/or install drivers/firmware. In most cases installing {{Pkg|linux-firmware}} should get you the required drivers. Installation of this package can produce errors on diskless or data disk modes. If such errors occur, switch to system disk mode.

If you are using a '''Broadcom chipset''', see the [[#Broadcom_Wi-Fi_Chipset_Users|Broadcom Wi-Fi section]].

Bring up the desired interface: {{Cmd|# ip link set wlan0 up}}

=== Check dmesg ===

Run dmesg and check for errors related to the wireless interface. Usually, dmesg gives maximum information related to network and all other hardware.
{{Cmd|# dmesg}}

=== checking network cards ===

{{Cmd|$ cat /proc/net/dev }} lists the network interfaces that are detected. If the expected interfaces are not available, Check what network hardware chip you have using lspci or lsusb:

{{Cmd|$ lspci -nn }}
{{Cmd|$ lsusb }}

Refer [[How to get regular stuff working#Hardware_Management|hardware management]], if the above output lacks sufficient information.

Check what driver the card uses and modprobe it. Check that the card is in master mode.
Check what driver you need on the [https://wireless.docs.kernel.org/en/latest/en/users/drivers/b43.html#list-of-hardware b43 compatibility page]

=== Broadcom Wi-Fi Chipset Users ===

The Broadcom chipset is quite popular among older computers. The b43 driver is included in the linux-lts or linux-edge kernel packages. However, you might need to compile the firmware manually for this chipset as it is not included in linux-firmware for some cards.

To check what broadcom chip you have using lspci:

{{Cmd|$ lspci -nn -d 14e4:}}

====B43====

Download firmware cutter. {{Cmd|$ apk add b43-fwcutter}}

Now we have everything to download the proprietary driver and extract the firmware from it: {{Cmd|<nowiki># export FIRMWARE_INSTALL_DIR="/lib/firmware"
$ wget http://www.lwfinger.com/b43-firmware/broadcom-wl-5.100.138.tar.bz2
$ tar xjf broadcom-wl-5.100.138.tar.bz2
$ b43-fwcutter -w "$FIRMWARE_INSTALL_DIR" broadcom-wl-5.100.138/linux/wl_apsta.o</nowiki>}}

More information can be found [http://linuxwireless.sipsolutions.net/en/users/Drivers/b43/#Other_distributions_not_mentioned_above here].

Now you need to use modprobe so the device will show up: {{Cmd|# modprobe b43}}

Now continue with the normal instructions.

====wl ====

You can use APKBUILD from [https://codeberg.org/NeYurii/broadcom-wl here]. It uses [[Alpine kernel module support]] for automatic building and updating driver for new kernel versions. Instructions can be found in the [https://codeberg.org/NeYurii/broadcom-wl broadcom-wl repository].

Alternately, install the software to build a driver: {{Cmd|apk add git alpine-sdk linux-headers linux-lts-dev}}

Then install the driver build repo (this is archived, however it's legacy so that doesn't matter): {{Cmd|git clone https://github.com/antoineco/broadcom-wl
cd broadcom-wl
}}

Then follow the build instructions listed in the git repo: {{Cmd|make
doas make install
doas depmod -A
doas modprobe wl
}}

Reboot and you have a working wl driver. Now continue with the normal instructions.

=== Rfkill ===

An error message <code>ioctl 0x8914 failed: No error information</code>, is the <code>busybox ip</code>'s way of saying your wireless radio is rfkilled, which means the wireless card is blocked by kernel. This can be changed using rfkill. To show the current status of your Wi-Fi:
~'''$''' rfkill list
0: phy0: wlan
Soft blocked: no
Hard blocked: no


If the card is hard-blocked, use the hardware button or switch to unblock it. If the card is not hard-blocked but soft-blocked, use the following command: {{Cmd|# rfkill unblock wifi}}

== See also ==

* [[Configure_Networking| Networking in Alpine Linux]]
* [[Iwd|iwd]] - An alternate to wpa_supplicant
* [[NetworkManager]] - Front-end to Networking
* [https://wiki.postmarketos.org/wiki/WiFi PostmarketOS Wiki]
* [https://wiki.archlinux.org/title/Network_configuration/Wireless Archwiki]
* [https://wiki.gentoo.org/wiki/Wi-Fi Gentoo Wiki]
* [[Alpine kernel module support]] - A fully automated solution for building kernel modules
* [https://unix.stackexchange.com/questions/606073/how-to-build-kernel-modules-in-alpine-3-12 Build kernel modules manually]

[[Category:Networking]]

PXE boot

2021-07-15T16:35:31Z

Cos: Clarify that alpine_repo=auto does not work.

'''This functionality is still largely prototypal. Some things could still be broken.'''

=Guide to options=
; ip
: '''Required for PXE.'''
: Set <code>ip=dhcp</code> to get an IP via DHCP. (Requires af_packet.ko in the initrd, in addition to the modules needed for your NIC.)
: Set <code>ip=client-ip::gateway-ip:netmask::[device]:</code> to specify an IP manually. <code>device</code> is a device name (e.g. <code>eth0</code>). If one is not specified, one is chosen automatically.

; apkovl
: Valid forms include:
:* A HTTP, HTTPS or FTP URL to an apkovl.tar.gz file which will be retrieved and applied.
:* <code>device_name[:fs_type]:path</code>, where <code>device_name</code> does not include <code>/dev</code> (e.g., <code>sda</code>). <code>fs_type</code> is optional (e.g. <code>ext4</code>). <code>path</code> expresses the path on the device to the apkovl.tar.gz file.
:* A relative path, interpreted relative to the root of the <code>alpine_dev</code>.
:* If not specified, a file matching <code>*.apkovl.tar.gz</code> is searched for in the root of the <code>ovl_dev</code>. (If more than one exists in the root of a device, all are ignored.)

; alpine_dev (this parameter is no longer used)
: The <code>alpine_dev</code> specifies a device used for reference data which must reside on a filesystem; currently, this is only the case for kernel modules.
: This is also used to obtain APKs if a repository is not explicitly specified; see below.
: Valid forms include:
:* A device name, not including <code>/dev/</code>.
:* <code>UUID=filesystem-uuid</code>
:* <code>LABEL=filesystem-label</code>
:* <code>nfs:ip-address:path</code>, specifying an NFS export to use as the device. You may need to add modules to the initrd.

; ovl_dev (this parameter is no longer used)
: Valid forms include:
:* <code>device_name[:fs_type]</code>
:* If not specified, various devices are searched for a file matching <code>*.apkovl.tar.gz</code> in the root directory.
: This argument can contain the fields <code>{MAC}</code> and <code>{UUID}</code>, which will be substituted with the MAC address of the NIC used by Alpine and the system's DMI "Product UUID" respectively. If these substitutions are used, the value passed to ovl_dev must be enclosed in quotes. e.g. <code>ovl_dev="<nowiki>http://.../</nowiki>{MAC}.apkovl.tar.gz"</code>.

; alpine_repo
: '''Required.'''
: <code>/etc/apk/repositories</code> will be filled from this. May be a URL. Otherwise, try and find a directory containing the marker file <code>.boot_repository</code> on the <code>alpine_dev</code>. Please note that although "auto" might appear documented as a valid value, it will not work when PXE booting.

; modloop
: If the specified file is of http/ftp or https (if wget is installed), the modloop file will be downloaded to the /lib directory and will be mounted afterwards
: e.g. modloop=http://192.168.1.1/pxe/alpine/grsec.modloop.squashfs in the append section of your [[Bootloaders|bootloader]]

; console
: Examples:
:* <code>tty0</code>
:* <code>ttyS1 </code>
:* <code>ttyAMA0</code>

; acpi
: Valid forms include:
:* <code>force</code>

; ssh_key
: Valid forms include:
:* A HTTP, HTTPS or FTP URL to a public SSH key which will be retrieved and added to the list of authorized SSH keys.

; modules

=HOWTO=
Alpine can be PXE booted starting with Alpine 2.6-rc2. In order to accomplish this you must complete the following steps:

* Set up a DHCP server and configure it to support PXE boot.
* Set up a TFTP server to serve the PXE bootloader.
* Set up an HTTP server to serve the rest of the boot files.
* Set up an NFS server from which Alpine can load kernel modules.
* Configure mkinitfs to generate a PXE-bootable initrd.

This article describes a setup using gpxe as a PXE bootloader, but you could also use PXELINUX.

Standard setup of all involved services is not covered here; advice on setting up basic DHCP/TFTP/HTTP/NFS/etc. is widely available.

==Set up a DHCP server and configure it to support PXE boot==
If you use the ISC DHCP server (package "dhcp"), amend your <code>subnet</code> block like so:
next-server 10.0.0.1;
filename "gpxe.kpxe";

==Set up a TFTP server to serve the PXE bootloader==
Install a TFTP server (package "tftp-hpa"). You will need to place a gPXE image at <code>/var/tftproot/gpxe.kpxe</code>. You can generate an image online at [http://rom-o-matic.eu/ ROM-o-matic.eu]. Select the ".kpxe" output format and the "undionly" driver. You will need to specify a custom boot script. Select "Customize". The following boot script works well:
dhcp net0
chain http://${net0/next-server}/gpxe-script
You can include <code>${net0/mac}</code> and <code>${uuid}</code> in the URL for the interface MAC address and machine UUID respectively.

Note that as of writing, ROM-o-matic appears to produce a buggy image unless it is used with the "undionly" driver. If you require a different driver, consider building gPXE yourself, especially if you experience inexplicable connectivity issues. Common symptoms are a seemingly correctly configured, randomly functional network connection which appears to suffer from extreme packet loss.

==Set up an HTTP server to serve the rest of the PXE boot files==
Suppose you have an HTTP server configured to serve from <code>/srv/http</code>. Place an appropriate gPXE script, such as the following, at <code>/srv/http/prov/gpxe-script</code>:
#!gpxe
kernel http://${net0/next-server}/prov/grsec ip=dhcp alpine_dev=nfs:${net0/next-server}:/srv/nfs/depot alpine_repo=http://nl.alpinelinux.org/alpine/v2.5/main/
initrd http://${net0/next-server}/prov/pxerd
boot

<code>ip=dhcp</code> instructs the initrd to obtain an IP via DHCP. The NFS share specified by <code>alpine_dev</code> will be mounted. <code>alpine_repo</code> specifies an apk repository to use.

==Using lpxelinux instead of gPXE==

Since recent version of syslinux, pxelinux also has support to boot over ftp/http. 
The pxelinux.cfg/default file (or specific MAC address file name) should be in the same format as with regular syslinux. 
You will need to use a copy of the '''lpxelinux.0''' found when installing syslinux on alpine: /usr/share/syslinux/lpxelinux.0 and copy it to your tftp server. 
Don't forget to also copy ldlinux.c32, as its a dependency of syslinux variants (see documentation).

DEFAULT alpine
LINUX http://ipaddr/grsec
INITRD http://ipaddr/grsec.gz
APPEND ip=dhcp modules=loop,squashfs,sd-mod,usb-storage alpine_repo=http://repo-url modloop=http://ipaddr/grsec.modloop.squashfs apkovl=http://ipaddr/localhost.apkovl.tar.gz

==Using pxelinux instead of gPXE==

Since recent version of syslinux, pxelinux also has support to boot over tftp. 
The pxelinux.cfg/default file (or specific MAC address file name) should be in the same format as with regular syslinux. 
You will need to use a copy of the '''pxelinux.0''' found when installing syslinux on alpine: /usr/share/syslinux/pxelinux.0 and copy it to your tftp server. 
Don't forget to also copy ldlinux.c32, as its a dependency of syslinux variants (see documentation).

PROMPT 0
TIMEOUT 3
default alpine
LABEL alpine
LINUX alpine-vmlinuz-grsec
INITRD alpine-pxerd
APPEND ip=dhcp alpine_dev=nfs:192.168.1.1:/srv/boot/alpine modloop=http://192.168.1.1/modloop-grsec nomodeset quiet apkovl=http://192.168.1.1/localhost.apkovl.tar.gz

''vmlinuz-grsec'' is taken from a system running in memory from usb. 
''pxerd'' is generated on a system running in memory from usb. With network nfs and virtio_net added. 
''/srv/boot/alpine'' is a copy of /media/usb from a system running in memory from usb. 
''modules=loop,squashfs,sd-mod,usb-storage'' is not needed as loop and squashfs are hard coded into the init script and we do not use sd nor usb. 
''modloop=http://ipaddr/grsec.modloop.squashfs'' does not seems to work. Without neither...(*) 
''apkovl=http://ipaddr/localhost.apkovl.tar.gz''. 

(*) about the modloop problem: /etc/init.d/modloop tries to load the file from /media/nfs instead of /media/alpine and starts trying to mount it! (unsuccessfully) A fix to it is (a proposal) see http://bugs.alpinelinux.org/issues/4015

==Set up an NFS server from which Alpine can load kernel modules==

NOTE: by adding modloop with http support, this is no need for modules.

Set up an NFS share at <code>/srv/nfs/depot</code> and export it via /etc/exports:
/srv/nfs/depot *(ro,no_root_squash,no_subtree_check)

This export does not currently need to contain anything, unless you wish to use it to serve apks, in which case ensure that a file ".boot_repository" is created in the directory containing architecture subdirectories and remove alpine_repo from the kernel arguments. The repository will be autodetected by searching for ".boot_repository". Eventually Alpine will be able to load kernel modules from this export.

==Configure mkinitfs to generate a PXE-bootable initrd==

NOTE: There is currently a mkinitfs profile just for networking called: network.
Using it will automatically add pxe support and all ethernet drivers to the initramfs.

You need to add drivers for any Ethernet cards with which you might PXE boot to your initrd. To do this, create <code>/etc/mkinitfs/features.d/network.modules</code>. List any kernel drivers you require for your Ethernet card. If you are using an Intel E1000 card (this is used by VMware and VirtualBox, and so is good for testing), add
kernel/drivers/net/ethernet/intel/e1000/*.ko

You also must create the following files so that the modules and scripts necessary for DHCP and NFS are inserted into the initrd.
/etc/mkinitfs/features.d/dhcp.files, containing:
/usr/share/udhcpc/default.script
/etc/mkinitfs/features.d/dhcp.modules, containing:
kernel/net/packet/af_packet.ko
/etc/mkinitfs/features.d/nfs.modules, containing:
kernel/fs/nfs/*
Finally edit <code>/etc/mkinitfs/mkinitfs.conf</code> and add features '''squashfs, network, dhcp and nfs'''.

Generate a PXE-capable initrd by running
mkinitfs -o /srv/http/prov/pxerd

You should now be able to PXE-boot Alpine Linux. This feature is still in development and non-fatal post-initrd boot errors (regarding modloop, etc.) are to be expected.

==Specifying an apkovl==

The location of the .apkovl to load can be specified using the kernel parameters `apkovl`. (Full definitions above.)

For example, to have the apkovl loaded from the device sda5 add to the kernel arguments:
apkovl=sda5

Or, to load a specific apkovl from a HTTP server:
apkovl=http://..../file.apkovl.tar.gz

All string occurences of {MAC} and {UUID} in this parameter will be substituted with the MAC address of the boot interface and the machine UUID respectively. If you use these strings, ensure you place the URL in quotes.

==A note about UEFI==
If you are booting a uefi system you will need to append initrd=initrdname to the kernel options to boot correctly.

[[Category:Booting]]