Alpine Linux - User contributions [en]

Infinitime

2026-05-02T04:12:05Z

John3-16: Added Categories: Embedded Systems, Hardware

[https://infinitime.io/ InfiniTime] is an open source firmware for the Pinetime smartwatch written in C++ and based on [https://www.freertos.org/ FreeRTOS].

All dependencies for compiling the firmware are packaged in the Alpine repositories, and can be installed via:

<pre>
apk add -t .infinitime-dev \
cmake \
gcc-arm-none-eabi \
lv_font_conv \
nrf5-sdk \
py3-cbor2 \
py3-cryptography \
py3-intelhex
</pre>

[[Category:Embedded Systems]]
[[Category:Hardware]]

Talk:Infinitime

2026-05-02T04:10:14Z

John3-16: Amending page title from Infinitime to InfiniTime

== Amending page title to InfiniTime ==

Adding <nowiki>{{DISPLAYTITLE:InfiniTime}}</nowiki> was attempted, but that does not currently amend the page title from Infinitime to InfiniTime. Moving page is an option.
[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:10, 2 May 2026 (UTC)

ZFS

2026-04-23T01:36:49Z

John3-16: Style/grammar amendments.

[https://openzfs.org/wiki/Main_Page ZFS] or OpenZFS is an open-source storage platform. It includes the functionality of both traditional file systems and volume manager.

This page has instructions for creating and automounting an encrypted ZFS drive or partition on an existing encrypted Alpine Linux system using ZFS's own encryption capabilities. To do a fresh install of Alpine Linux with root partition on ZFS, see [[Root on ZFS with native encryption]].

== Installation ==

Install the necessary packages and utilities by using the command:{{Cmd|# apk add zfs}}
Ensure that the kernel modules are loaded and verify that the device nodes are present:{{Cmd|<nowiki># modprobe zfs
# mdev -s </nowiki> }}
If your use of ZFS depends on volumes appearing in {{Path|/dev/zvol/$ZPOOL/$ZVOL}}, you will also need to [[Eudev|setup eudev]] and:{{Cmd|# apk add zfs-udev}}

== Configuration ==

The system will be encrypted when powered off but will not require you to type an extra password at boot, since it uses a key stored on the encrypted root partition. Alternative options are also given, such as prompting for a password at boot rather than storing the key on the root drive. The example in this guide is modeled around creating a ZFS filesystem to be used as a user's home directory, but it can be trivially modified to create a filesystem for other purposes.

=== Create an encryption key ===

This section can be skipped if you intend to unlock the drive by typing a password rather than unlocking automatically. You should use a password instead if your root partition is not encrypted. The location of the file {{Path|/etc/home.key}} can be anywhere. {{Cmd|<nowiki># dd if=/dev/random of=/etc/home.key bs=32 count=1
# chmod 600 /etc/home.key</nowiki>}}

IMPORTANT: Make sure you don't lose this key by overwriting your root filesystem or similar. You might want to store a copy of it on an encrypted USB drive, for instance.

=== Create the zpool ===

Replace <code>/dev/sd...</code> with the name of the disk or partition where you would like to make the zfs filesystem, such as <code>/dev/nvme0n1</code> or <code>/dev/sda1</code>. If you would like to be prompted for a password at boot rather than using the key as generated above, then replace <code>-O keylocation=file:///etc/home.key -O keyformat=raw</code> with <code>-O keylocation=prompt -O keyformat=passphrase</code>. The name <var>"homepool"</var> can be anything.{{Cmd|<nowiki># zpool create -o ashift=12 -O acltype=posixacl -O compression=lz4 \
-O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \
-O encryption=aes-256-gcm -O keylocation=file:///etc/home.key -O keyformat=raw \
-O mountpoint=none homepool /dev/sd...</nowiki>}}

After completing this, verifying that the pool has been created should return something similar to the following: {{Cmd|<nowiki># zpool status
pool: homepool
state: ONLINE
config:

NAME STATE READ WRITE CKSUM
homepool ONLINE 0 0 0
sd... ONLINE 0 0 0

errors: No known data errors</nowiki>}}

To create and mount the filesystem, issue the command {{Cmd|<nowiki># zfs create -o mountpoint=/home/username homepool/username
# chown username:username /home/username </nowiki>}}

The last command i.e ''chown'' is likely unnecessary if not creating a homedir.

=== Service configuration ===

Setup the following services to automount the new filesystem using [[OpenRC]].
To import existing zpools:{{Cmd|# rc-update add zfs-import}}
To load the encryption keys:{{Cmd|# rc-update add zfs-load-key}}
Finally, to mount the filesystems:{{Cmd|# rc-update add zfs-mount}}

Reboot the system so that the encrypted ZFS drive is automounted and becomes available for use.

== Maintenance ==

On Alpine Linux, there is no cron/script provided to scrub (and eventually trim) your pool(s) on a regular basis, like in other Linux distributions.

=== Scrub ===

Scrubbing (and eventually trim) your pool(s) on a regular basis is essential, as discussed in [https://blogs.oracle.com/oracle-systems/post/disk-scrub-why-and-when an official Oracle blog post] on Exadata disk scrubbing. The scrub examines all data in the specified pools to verify that it checksums correctly. For replicated (mirror, raidz, or draid) devices, ZFS automatically repairs any damage discovered during the scrub.

When scrubbing a pool with encrypted filesystems, the keys do not need to be loaded. However, if the keys are not loaded and an unrepairable checksum error is detected the file name cannot be included in the zpool status -v verbose error report.

A scrub is split into two parts: metadata scanning and block scrubbing. The metadata scanning sorts blocks into large sequential ranges which can then be read much more efficiently from disk when issuing the scrub I/O.

This script is taken from Debian ZFS scripts. It is used to list the pools, making sure that they are online and that no scrub is being done at the time. The contents of the script placed at {{path|/usr/libexec/zfs/scrub}} are as follows:{{cat|/usr/libexec/zfs/scrub|<nowiki>#!/bin/sh -eu

# directly exit successfully when zfs module is not loaded
if ! [ -d /sys/module/zfs ]; then
exit 0
fi

# [auto] / enable / disable
PROPERTY_NAME="org.alpine:periodic-scrub"

get_property () {
# Detect the ${PROPERTY_NAME} property on a given pool.
# We are abusing user-defined properties on the root dataset,
# since they're not available on pools https://github.com/openzfs/zfs/pull/11680
# TODO: use zpool user-defined property when such feature is available.
pool="$1"
zfs get -H -o value "${PROPERTY_NAME}" "${pool}" 2>/dev/null || return 1
}

scrub_if_not_scrub_in_progress () {
pool="$1"
if ! zpool status "${pool}" | grep -q "scrub in progress"; then
# Ignore errors and continue with scrubbing other pools.
zpool scrub "${pool}" || true
fi
}

# Scrub all healthy pools that are not already scrubbing as per their configs.
zpool list -H -o health,name 2>&1 | \
awk -F'\t' '$1 == "ONLINE" {print $2}' | \
while read pool
do
# read user-defined config
ret=$(get_property "${pool}")
if [ $? -ne 0 ] || [ "disable" = "${ret}" ]; then
:
elif [ "-" = "${ret}" ] || [ "auto" = "${ret}" ] || [ "enable" = "${ret}" ]; then
scrub_if_not_scrub_in_progress "${pool}"
else
cat > /dev/stderr <<EOF
$0: [WARNING] illegal value "${ret}" for property "${PROPERTY_NAME}" of ZFS dataset "${pool}".
$0: Acceptable choices for this property are: auto, enable, disable. The default is auto.
EOF
fi
done
</nowiki>}}

Make the script executable: {{cmd|# chmod +x /usr/libexec/zfs/scrub}}

It is recommended to scrub regularly to ensure that your pool(s) and data are in good shape. In our example, the scrub script will be launched once a month, on the 2nd Sunday of the month using [[cron]].

Edit your crontabs using the command: {{cmd|# crontab -e}}

and add these 2 lines:
<pre>
# ZFS scrub the 2nd Sunday of every month
24 0 8-14 * * if [ $(date +\%w) -eq 0 ] && [ -x /usr/libexec/zfs/scrub ]; then /usr/libexec/zfs/scrub; fi
</pre>

=== Trim ===

The command {{ic|zpool trim}} initiates an immediate on-demand TRIM operation for all of the free space in a pool. This operation informs the underlying storage devices of all blocks in the pool which are no longer allocated and allows thinly provisioned devices to reclaim the space.

A manual on-demand TRIM operation can be initiated irrespective of the [https://openzfs.github.io/openzfs-docs/man/v2.2/7/zpoolprops.7.html#autotrim autotrim] pool property setting. The link shows the types of VDEV devices that can be trimmed.

This script is taken from Debian ZFS scripts. It is used to list the pools, making sure that they are online, built only with NVMe SSD drive(s) and that no trim is being done at the time. The contents of the script placed at {{path|/usr/libexec/zfs/trim}} are as follows:{{cat|/usr/libexec/zfs/trim|<nowiki>#!/bin/sh -eu

# directly exit successfully when zfs module is not loaded
if ! [ -d /sys/module/zfs ]; then
exit 0
fi

# [auto] / enable / disable
PROPERTY_NAME="org.alpine:periodic-trim"

get_property () {
# Detect the ${PROPERTY_NAME} property on a given pool.
# We are abusing user-defined properties on the root dataset,
# since they're not available on pools https://github.com/openzfs/zfs/pull/11680
# TODO: use zpool user-defined property when such feature is available.
pool="$1"
zfs get -H -o value "${PROPERTY_NAME}" "${pool}" 2>/dev/null || return 1
}

trim_if_not_already_trimming () {
pool="$1"
if ! zpool status "${pool}" | grep -q "trimming"; then
# Ignore errors (i.e. HDD pools),
# and continue with trimming other pools.
zpool trim "${pool}" || true
fi
}

zpool_is_nvme_only () {
zpool=$1
# get a list of devices attached to the specified zpool
zpool list -vHPL "${zpool}" |
awk -F'\t' '$2 ~ /^\/dev\// {
if($2 !~ /^\/dev\/nvme/)
exit 1
}'
}

# TRIM all healthy pools that are not already trimming as per their configs.
zpool list -H -o health,name 2>&1 | \
awk -F'\t' '$1 == "ONLINE" {print $2}' | \
while read pool
do
# read user-defined config
ret=$(get_property "${pool}")
if [ $? -ne 0 ] || [ "disable" = "${ret}" ]; then
:
elif [ "enable" = "${ret}" ]; then
trim_if_not_already_trimming "${pool}"
elif [ "-" = "${ret}" ] || [ "auto" = "${ret}" ]; then
if zpool_is_nvme_only "${pool}"; then
trim_if_not_already_trimming "${pool}"
fi
else
cat > /dev/stderr <<EOF
$0: [WARNING] illegal value "${ret}" for property "${PROPERTY_NAME}" of ZFS dataset "${pool}".
$0: Acceptable choices for this property are: auto, enable, disable. The default is auto.
EOF
fi
done
</nowiki>
}}

Make the script executable: {{cmd|# chmod +x /usr/libexec/zfs/trim}}

It is recommended to trim regularly to ensure that your pool(s) and data are in good shape. In our example, the trim script will be launched once a month, on the 1st Sunday of the month using [[cron]].

Edit your crontabs using the command: {{cmd|# crontab -e}}
and add these 2 lines:
<pre>
# ZFS trim the 1st Sunday of every month
24 0 1-7 * * if [ $(date +\%w) -eq 0 ] && [ -x /usr/libexec/zfs/trim ]; then /usr/libexec/zfs/trim; fi
</pre>

== See also ==

* [https://openzfs.org/wiki/System_Administration ZFS System Administration]
* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]
* [[Root on ZFS with native encryption]]
* [[Setting up ZFS on LUKS]]
[[Category:Filesystems]]
[[Category:Storage]]
[[Category:Installation]]
[[Category:Security]]

ZFS

2026-04-21T04:23:30Z

John3-16: Style/grammar amendments.

[https://openzfs.org/wiki/Main_Page ZFS] or OpenZFS is an open-source storage platform. It includes the functionality of both traditional file systems and volume manager.

This page has instructions for creating and automounting an encrypted ZFS drive or partition on an existing encrypted Alpine Linux system using ZFS's own encryption capabilities. To do a fresh install of Alpine Linux with root partition on ZFS, see [[Root on ZFS with native encryption]].

== Installation ==

Install the necessary packages and utilities by using the command:{{Cmd|# apk add zfs}}
Ensure that the kernel modules are loaded and verify that the device nodes are present:{{Cmd|<nowiki># modprobe zfs
# mdev -s </nowiki> }}
If your use of ZFS depends on volumes appearing in {{Path|/dev/zvol/$ZPOOL/$ZVOL}}, you will also need to [[Eudev|setup eudev]] and:{{Cmd|# apk add zfs-udev}}

== Configuration ==

The system will be encrypted when powered off but will not require you to type an extra password at boot, since it uses a key stored on the encrypted root partition. Alternative options are also given, such as prompting for a password at boot rather than storing the key on the root drive. The example in this guide is modeled around creating a ZFS filesystem to be used as a user's home directory, but it can be trivially modified to create a filesystem for other purposes.

=== Create an encryption key ===

This section can be skipped if you intend to unlock the drive by typing a password rather than unlocking automatically. You should use a password instead if your root partition is not encrypted. The location of the file {{Path|/etc/home.key}} can be anywhere. {{Cmd|<nowiki># dd if=/dev/random of=/etc/home.key bs=32 count=1
# chmod 600 /etc/home.key</nowiki>}}

IMPORTANT: Make sure you don't lose this key by overwriting your root filesystem or similar. You might want to store a copy of it on an encrypted USB drive, for instance.

=== Create the zpool ===

Replace <code>/dev/sd...</code> with the name of the disk or partition where you would like to make the zfs filesystem, such as <code>/dev/nvme0n1</code> or <code>/dev/sda1</code>. If you would like to be prompted for a password at boot rather than using the key as generated above, then replace <code>-O keylocation=file:///etc/home.key -O keyformat=raw</code> with <code>-O keylocation=prompt -O keyformat=passphrase</code>. The name <var>"homepool"</var> can be anything.{{Cmd|<nowiki># zpool create -o ashift=12 -O acltype=posixacl -O compression=lz4 \
-O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \
-O encryption=aes-256-gcm -O keylocation=file:///etc/home.key -O keyformat=raw \
-O mountpoint=none homepool /dev/sd...</nowiki>}}

After completing this, verifying that the pool has been created should return something similar to the following: {{Cmd|<nowiki># zpool status
pool: homepool
state: ONLINE
config:

NAME STATE READ WRITE CKSUM
homepool ONLINE 0 0 0
sd... ONLINE 0 0 0

errors: No known data errors</nowiki>}}

To create and mount the filesystem, issue the command {{Cmd|<nowiki># zfs create -o mountpoint=/home/username homepool/username
# chown username:username /home/username </nowiki>}}

The last command i.e ''chown'' is likely unnecessary if not creating a homedir.

=== Service configuration ===

Setup the following services to automount the new filesystem using [[OpenRC]].
To import existing zpools:{{Cmd|# rc-update add zfs-import}}
To load the encryption keys:{{Cmd|# rc-update add zfs-load-key}}
Finally, to mount the filesystems:{{Cmd|# rc-update add zfs-mount}}

Reboot the system so that the encrypted ZFS drive is automounted and becomes available for use.

== Maintenance ==

On Alpine Linux, there in no cron/script provided to scrub (and eventually trim) your pool(s) on a regular basis, like in other Linux distributions.

=== Scrub ===

Scrubbing (and eventually trim) your pool(s) on a regular basis is essential, as discussed in [https://blogs.oracle.com/oracle-systems/post/disk-scrub-why-and-when an official Oracle blog post] on Exadata disk scrubbing. The scrub examines all data in the specified pools to verify that it checksums correctly. For replicated (mirror, raidz, or draid) devices, ZFS automatically repairs any damage discovered during the scrub.

When scrubbing a pool with encrypted filesystems, the keys do not need to be loaded. However, if the keys are not loaded and an unrepairable checksum error is detected the file name cannot be included in the zpool status -v verbose error report.

A scrub is split into two parts: metadata scanning and block scrubbing. The metadata scanning sorts blocks into large sequential ranges which can then be read much more efficiently from disk when issuing the scrub I/O.

This script is taken from Debian ZFS scripts. It is used to list the pools, making sure that they are online and that no scrub is being done at the time. The contents of the script placed at {{path|/usr/libexec/zfs/scrub}} are as follows:{{cat|/usr/libexec/zfs/scrub|<nowiki>#!/bin/sh -eu

# directly exit successfully when zfs module is not loaded
if ! [ -d /sys/module/zfs ]; then
exit 0
fi

# [auto] / enable / disable
PROPERTY_NAME="org.alpine:periodic-scrub"

get_property () {
# Detect the ${PROPERTY_NAME} property on a given pool.
# We are abusing user-defined properties on the root dataset,
# since they're not available on pools https://github.com/openzfs/zfs/pull/11680
# TODO: use zpool user-defined property when such feature is available.
pool="$1"
zfs get -H -o value "${PROPERTY_NAME}" "${pool}" 2>/dev/null || return 1
}

scrub_if_not_scrub_in_progress () {
pool="$1"
if ! zpool status "${pool}" | grep -q "scrub in progress"; then
# Ignore errors and continue with scrubbing other pools.
zpool scrub "${pool}" || true
fi
}

# Scrub all healthy pools that are not already scrubbing as per their configs.
zpool list -H -o health,name 2>&1 | \
awk -F'\t' '$1 == "ONLINE" {print $2}' | \
while read pool
do
# read user-defined config
ret=$(get_property "${pool}")
if [ $? -ne 0 ] || [ "disable" = "${ret}" ]; then
:
elif [ "-" = "${ret}" ] || [ "auto" = "${ret}" ] || [ "enable" = "${ret}" ]; then
scrub_if_not_scrub_in_progress "${pool}"
else
cat > /dev/stderr <<EOF
$0: [WARNING] illegal value "${ret}" for property "${PROPERTY_NAME}" of ZFS dataset "${pool}".
$0: Acceptable choices for this property are: auto, enable, disable. The default is auto.
EOF
fi
done
</nowiki>}}

Make the script executable: {{cmd|# chmod +x /usr/libexec/zfs/scrub}}

It is recommended to scrub regularly to assure your pool(s) and data are in good shape. In our example, the scrub script will be launched once a month, on the 2nd Sunday of the month using [[cron]].

Edit your crontabs using the command: {{cmd|# crontab -e}}

and add these 2 lines:
<pre>
# zfs scrub the 2nd Sunday of every month
24 0 8-14 * * if [ $(date +\%w) -eq 0 ] && [ -x /usr/libexec/zfs/scrub ]; then /usr/libexec/zfs/scrub; fi
</pre>

=== Trim ===

The command {{ic|zpool trim}} initiates an immediate on-demand TRIM operation for all of the free space in a pool. This operation informs the underlying storage devices of all blocks in the pool which are no longer allocated and allows thinly provisioned devices to reclaim the space.

A manual on-demand TRIM operation can be initiated irrespective of the [https://openzfs.github.io/openzfs-docs/man/v2.2/7/zpoolprops.7.html#autotrim autotrim] pool property setting. The link shows the types of VDEV devices that can be trimmed.

This script is taken from Debian ZFS scripts. It is used to list the pools, making sure that they are online, built only with NVMe SSD drive(s) and that no trim is being done at the time. The contents of the script placed at {{path|/usr/libexec/zfs/trim}} are as follows:{{cat|/usr/libexec/zfs/trim|<nowiki>#!/bin/sh -eu

# directly exit successfully when zfs module is not loaded
if ! [ -d /sys/module/zfs ]; then
exit 0
fi

# [auto] / enable / disable
PROPERTY_NAME="org.alpine:periodic-trim"

get_property () {
# Detect the ${PROPERTY_NAME} property on a given pool.
# We are abusing user-defined properties on the root dataset,
# since they're not available on pools https://github.com/openzfs/zfs/pull/11680
# TODO: use zpool user-defined property when such feature is available.
pool="$1"
zfs get -H -o value "${PROPERTY_NAME}" "${pool}" 2>/dev/null || return 1
}

trim_if_not_already_trimming () {
pool="$1"
if ! zpool status "${pool}" | grep -q "trimming"; then
# Ignore errors (i.e. HDD pools),
# and continue with trimming other pools.
zpool trim "${pool}" || true
fi
}

zpool_is_nvme_only () {
zpool=$1
# get a list of devices attached to the specified zpool
zpool list -vHPL "${zpool}" |
awk -F'\t' '$2 ~ /^\/dev\// {
if($2 !~ /^\/dev\/nvme/)
exit 1
}'
}

# TRIM all healthy pools that are not already trimming as per their configs.
zpool list -H -o health,name 2>&1 | \
awk -F'\t' '$1 == "ONLINE" {print $2}' | \
while read pool
do
# read user-defined config
ret=$(get_property "${pool}")
if [ $? -ne 0 ] || [ "disable" = "${ret}" ]; then
:
elif [ "enable" = "${ret}" ]; then
trim_if_not_already_trimming "${pool}"
elif [ "-" = "${ret}" ] || [ "auto" = "${ret}" ]; then
if zpool_is_nvme_only "${pool}"; then
trim_if_not_already_trimming "${pool}"
fi
else
cat > /dev/stderr <<EOF
$0: [WARNING] illegal value "${ret}" for property "${PROPERTY_NAME}" of ZFS dataset "${pool}".
$0: Acceptable choices for this property are: auto, enable, disable. The default is auto.
EOF
fi
done
</nowiki>
}}

Make the script executable: {{cmd|# chmod +x /usr/libexec/zfs/trim}}

It is recommended to trim regularly to ensure that your pool(s) and data are in good shape. In our example, the trim script will be launched once a month, on the 1st Sunday of the month using [[cron]]

Edit your crontabs using the command: {{cmd|# crontab -e}}
and add these 2 lines:
<pre>
# zfs trim the 1st Sunday of every month
24 0 1-7 * * if [ $(date +\%w) -eq 0 ] && [ -x /usr/libexec/zfs/trim ]; then /usr/libexec/zfs/trim; fi
</pre>

== See also ==

* [https://openzfs.org/wiki/System_Administration ZFS System Administration]
* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]
* [[Root on ZFS with native encryption]]
* [[Setting up ZFS on LUKS]]
[[Category:Filesystems]]
[[Category:Storage]]
[[Category:Installation]]
[[Category:Security]]

ZFS

2026-04-19T03:59:10Z

John3-16: Style/grammar amendments.

[https://openzfs.org/wiki/Main_Page ZFS] or OpenZFS is an open-source storage platform. It includes the functionality of both traditional file systems and volume manager.

This page has instructions for creating and automounting an encrypted ZFS drive or partition on an existing encrypted Alpine Linux system using ZFS's own encryption capabilities. To do a fresh install of Alpine Linux with root partition on ZFS, see [[Root on ZFS with native encryption]].

== Installation ==

Install the necessary packages and utilities by using the command:{{Cmd|# apk add zfs}}
Ensure that the kernel modules are loaded and verify that the device nodes are present:{{Cmd|<nowiki># modprobe zfs
# mdev -s </nowiki> }}
If your use of ZFS depends on volumes appearing in {{Path|/dev/zvol/$ZPOOL/$ZVOL}}, you will also need to [[Eudev|setup eudev]] and:{{Cmd|# apk add zfs-udev}}

== Configuration ==

The system will be encrypted when powered off but will not require you to type an extra password at boot, since it uses a key stored on the encrypted root partition. Alternative options are also given, such as prompting for a password at boot rather than storing the key on the root drive. The example in this guide is modeled around creating a ZFS filesystem to be used as a user's home directory, but it can be trivially modified to create a filesystem for other purposes.

=== Create an encryption key ===

This section can be skipped if you intend to unlock the drive by typing a password rather than unlocking automatically. You should use a password instead if your root partition is not encrypted. The location of the file {{Path|/etc/home.key}} can be anywhere. {{Cmd|<nowiki># dd if=/dev/random of=/etc/home.key bs=32 count=1
# chmod 600 /etc/home.key</nowiki>}}

IMPORTANT: Make sure you don't lose this key by overwriting your root filesystem or similar. You might want to store a copy of it on an encrypted USB drive, for instance.

=== Create the zpool ===

Replace <code>/dev/sd...</code> with the name of the disk or partition where you would like to make the zfs filesystem, such as <code>/dev/nvme0n1</code> or <code>/dev/sda1</code>. If you would like to be prompted for a password at boot rather than using the key as generated above, then replace <code>-O keylocation=file:///etc/home.key -O keyformat=raw</code> with <code>-O keylocation=prompt -O keyformat=passphrase</code>. The name <var>"homepool"</var> can be anything.{{Cmd|<nowiki># zpool create -o ashift=12 -O acltype=posixacl -O compression=lz4 \
-O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \
-O encryption=aes-256-gcm -O keylocation=file:///etc/home.key -O keyformat=raw \
-O mountpoint=none homepool /dev/sd...</nowiki>}}

After completing this, verifying that the pool has been created should return something similar to the following: {{Cmd|<nowiki># zpool status
pool: homepool
state: ONLINE
config:

NAME STATE READ WRITE CKSUM
homepool ONLINE 0 0 0
sd... ONLINE 0 0 0

errors: No known data errors</nowiki>}}

To create and mount the filesystem, issue the command {{Cmd|<nowiki># zfs create -o mountpoint=/home/username homepool/username
# chown username:username /home/username </nowiki>}}

The last command i.e ''chown'' is likely unnecessary if not creating a homedir.

=== Service configuration ===

Setup the following services to automount the new filesystem using [[OpenRC]].
To import existing zpools:{{Cmd|# rc-update add zfs-import}}
To load the encryption keys:{{Cmd|# rc-update add zfs-load-key}}
Finally, to mount the filesystems:{{Cmd|# rc-update add zfs-mount}}

Reboot the system so that the encrypted ZFS drive is automounted and becomes available for use.

== Maintenance ==

On Alpine Linux, there in no cron/script provided to scrub (and eventually trim) your pool(s) on a regular basis, like in other Linux distributions.

=== Scrub ===

Scrubbing (and eventually trim) your pool(s) on a regular basis is essential, as discussed in [https://blogs.oracle.com/oracle-systems/post/disk-scrub-why-and-when an official Oracle blog post] on Exadata disk scrubbing. The scrub examines all data in the specified pools to verify that it checksums correctly. For replicated (mirror, raidz, or draid) devices, ZFS automatically repairs any damage discovered during the scrub.

When scrubbing a pool with encrypted filesystems, the keys do not need to be loaded. However, if the keys are not loaded and an unrepairable checksum error is detected the file name cannot be included in the zpool status -v verbose error report.

A scrub is split into two parts: metadata scanning and block scrubbing. The metadata scanning sorts blocks into large sequential ranges which can then be read much more efficiently from disk when issuing the scrub I/O.

This script is taken from debian zfs scripts. It is used to list the pools, make sure they are online, and no scrub is being done at the time. The contents of the script placed at {{path|/usr/libexec/zfs/scrub}} are as follows:{{cat|/usr/libexec/zfs/scrub|<nowiki>#!/bin/sh -eu

# directly exit successfully when zfs module is not loaded
if ! [ -d /sys/module/zfs ]; then
exit 0
fi

# [auto] / enable / disable
PROPERTY_NAME="org.alpine:periodic-scrub"

get_property () {
# Detect the ${PROPERTY_NAME} property on a given pool.
# We are abusing user-defined properties on the root dataset,
# since they're not available on pools https://github.com/openzfs/zfs/pull/11680
# TODO: use zpool user-defined property when such feature is available.
pool="$1"
zfs get -H -o value "${PROPERTY_NAME}" "${pool}" 2>/dev/null || return 1
}

scrub_if_not_scrub_in_progress () {
pool="$1"
if ! zpool status "${pool}" | grep -q "scrub in progress"; then
# Ignore errors and continue with scrubbing other pools.
zpool scrub "${pool}" || true
fi
}

# Scrub all healthy pools that are not already scrubbing as per their configs.
zpool list -H -o health,name 2>&1 | \
awk -F'\t' '$1 == "ONLINE" {print $2}' | \
while read pool
do
# read user-defined config
ret=$(get_property "${pool}")
if [ $? -ne 0 ] || [ "disable" = "${ret}" ]; then
:
elif [ "-" = "${ret}" ] || [ "auto" = "${ret}" ] || [ "enable" = "${ret}" ]; then
scrub_if_not_scrub_in_progress "${pool}"
else
cat > /dev/stderr <<EOF
$0: [WARNING] illegal value "${ret}" for property "${PROPERTY_NAME}" of ZFS dataset "${pool}".
$0: Acceptable choices for this property are: auto, enable, disable. The default is auto.
EOF
fi
done
</nowiki>}}

Make the script executable: {{cmd|# chmod +x /usr/libexec/zfs/scrub}}

It is recommended to scrub regularly to assure your pool(s) and datas are in good shape. In our example, the scrub script will be launched once a month, on the 2nd Sunday of the month using [[cron]].

Edit your crontabs using the command: {{cmd|# crontab -e}}

and add these 2 lines:
<pre>
# zfs scrub the 2nd Sunday of every month
24 0 8-14 * * if [ $(date +\%w) -eq 0 ] && [ -x /usr/libexec/zfs/scrub ]; then /usr/libexec/zfs/scrub; fi
</pre>

=== Trim ===

The command {{ic|zpool trim}} initiates an immediate on-demand TRIM operation for all of the free space in a pool. This operation informs the underlying storage devices of all blocks in the pool which are no longer allocated and allows thinly provisioned devices to reclaim the space.

A manual on-demand TRIM operation can be initiated irrespective of the [https://openzfs.github.io/openzfs-docs/man/v2.2/7/zpoolprops.7.html#autotrim autotrim] pool property setting. The link shows the types of vdev devices which can be trimmed.

This script is taken from debian zfs scripts. It is used to list the pools, make sure they are online, build only with NVME ssd drive(s) and no trim is being done at the time. The contents of the script placed at {{path|/usr/libexec/zfs/trim}} is as follows:{{cat|/usr/libexec/zfs/trim|<nowiki>#!/bin/sh -eu

# directly exit successfully when zfs module is not loaded
if ! [ -d /sys/module/zfs ]; then
exit 0
fi

# [auto] / enable / disable
PROPERTY_NAME="org.alpine:periodic-trim"

get_property () {
# Detect the ${PROPERTY_NAME} property on a given pool.
# We are abusing user-defined properties on the root dataset,
# since they're not available on pools https://github.com/openzfs/zfs/pull/11680
# TODO: use zpool user-defined property when such feature is available.
pool="$1"
zfs get -H -o value "${PROPERTY_NAME}" "${pool}" 2>/dev/null || return 1
}

trim_if_not_already_trimming () {
pool="$1"
if ! zpool status "${pool}" | grep -q "trimming"; then
# Ignore errors (i.e. HDD pools),
# and continue with trimming other pools.
zpool trim "${pool}" || true
fi
}

zpool_is_nvme_only () {
zpool=$1
# get a list of devices attached to the specified zpool
zpool list -vHPL "${zpool}" |
awk -F'\t' '$2 ~ /^\/dev\// {
if($2 !~ /^\/dev\/nvme/)
exit 1
}'
}

# TRIM all healthy pools that are not already trimming as per their configs.
zpool list -H -o health,name 2>&1 | \
awk -F'\t' '$1 == "ONLINE" {print $2}' | \
while read pool
do
# read user-defined config
ret=$(get_property "${pool}")
if [ $? -ne 0 ] || [ "disable" = "${ret}" ]; then
:
elif [ "enable" = "${ret}" ]; then
trim_if_not_already_trimming "${pool}"
elif [ "-" = "${ret}" ] || [ "auto" = "${ret}" ]; then
if zpool_is_nvme_only "${pool}"; then
trim_if_not_already_trimming "${pool}"
fi
else
cat > /dev/stderr <<EOF
$0: [WARNING] illegal value "${ret}" for property "${PROPERTY_NAME}" of ZFS dataset "${pool}".
$0: Acceptable choices for this property are: auto, enable, disable. The default is auto.
EOF
fi
done
</nowiki>
}}

Make the script executable: {{cmd|# chmod +x /usr/libexec/zfs/trim}}

It is recommended to trim regularly to assure your pool(s) and datas are in good shape. So the trim script will be launched once a month, on the 1st sunday of the month using [[cron]]

Edit your crontabs using the command: {{cmd|# crontab -e}}
and add these 2 lines
<pre>
# zfs trim the first sunday of every month
24 0 1-7 * * if [ $(date +\%w) -eq 0 ] && [ -x /usr/libexec/zfs/trim ]; then /usr/libexec/zfs/trim; fi
</pre>

== See also ==

* [https://openzfs.org/wiki/System_Administration ZFS System Administration]
* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]
* [[Root on ZFS with native encryption]]
* [[Setting up ZFS on LUKS]]
[[Category:Filesystems]]
[[Category:Storage]]
[[Category:Installation]]
[[Category:Security]]

Prism Launcher

2026-03-30T10:46:20Z

John3-16: 1. Added Category: Gaming; 2. Style/grammar amendments.

[https://prismlauncher.org/ Prism Launcher] is a [https://www.minecraft.net/en-us Minecraft] launcher that allows for easy management of multiple versions of Minecraft with or without mods.

== Prerequisites ==
* A running graphical environment.

== Installation ==
Prism Launcher can be installed either through [[Flatpak]] (recommended) or via the {{Pkg|prismlauncher}} package.

=== Flatpak Installation ===

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that the [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Prism Launcher flatpak package from Flathub.{{Cmd|$ flatpak --user install org.prismlauncher.PrismLauncher}}
# After installation, Prism Launcher can be started through its {{Path|.desktop}} file or from the command line: {{Cmd|$ flatpak run org.prismlauncher.PrismLauncher}}

=== apk Installation ===
# Install the {{Pkg|prismlauncher}} package.
# Install the {{Pkg|openjdk*}} version required by your Minecraft version.
# Install the {{Pkg|jemalloc}} and {{Pkg|openal-soft-libs}} packages.

== Troubleshooting ==

=== Problematic frame: liblwjgl.so ===
Versions of Minecraft that use [https://www.lwjgl.org/ LWJGL] version 3.3.1 will not start, with the error:
{{Cmd|Problematic frame: C [liblwjgl.so+0x4e81d]}}
Affected versions include everything between snapshot 22w15a(>1.19) and snapshot 23w35a(<1.20.2).
There is no known fix at this time.

[[Category:Gaming]]

Openconnect-SSO in Docker

2026-02-26T00:54:08Z

John3-16: 1. Added 'See also' section: 'Docker image example on hub.docker.com', 'An openconnect-sso Docker implementation for X11', 'openconnect-sso GitHub repository'; 2. Added categories: Networking, VPN, Virtualization‏‎, Authentication.

= VPN via openconnect-sso (Docker) =

This guide describes how to connect to a Cisco AnyConnect-compatible VPN using openconnect-sso running inside a Docker container, with automatic DNS configuration on connect. It is assumed the WM / compositor of the client is Wayland.

== Prerequisites ==

* [[Docker]] installed and running
* doas configured
* The <code>openconnect-sso</code> Docker image built (see below)
* A VPN-specific <code>resolv.conf</code> saved at <code>~/.local/resolv.conf</code>

If you don't know the DNS for <code>resolv.conf</code>, you can remove that part and connect via IP(s) directly, not DNS.

== Building the Docker image ==

Save the following as <code>Dockerfile.openconnect-sso</code>:

<pre>
FROM python:3.11-slim

RUN apt-get update && \
apt-get install -y \
openconnect \
sudo \
libqt6gui6 \
libqt6widgets6 \
libqt6webenginecore6 \
libqt6webenginewidgets6 \
qt6-wayland \
libgl1 \
libxkbcommon0 \
libdbus-1-3 \
libegl1 \
libnss3 \
libnspr4 \
libxcomposite1 \
libxdamage1 \
libxrandr2 \
libxtst6 \
libxslt1.1 \
libglib2.0-0 \
libasound2 \
libxcursor1 \
fonts-liberation && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir openconnect-sso

RUN useradd -m -s /bin/bash vpnuser && \
echo "vpnuser ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers

USER vpnuser
WORKDIR /home/vpnuser

ENV QT_QPA_PLATFORM=wayland
ENV XDG_RUNTIME_DIR=/tmp

ENTRYPOINT ["openconnect-sso"]
</pre>

Build and create the container:

<pre>
docker build -f Dockerfile.openconnect-sso -t openconnect-sso .
doas docker create -it \
--name openconnect-sso \
--privileged \
--net=host \
-v /etc/ssl/certs:/etc/ssl/certs:ro \
-e WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
-e XDG_RUNTIME_DIR=/tmp \
-e QT_QPA_PLATFORM=wayland \
-v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY:rw \
--device /dev/net/tun \
openconnect-sso:latest \
--server your-vpn-gateway \
--user your-username
</pre>

== DNS configuration ==

When the VPN connects, a <code>tun0</code> interface is created but the system DNS is not automatically updated. To resolve internal hostnames, save your VPN network's DNS settings to <code>~/.local/resolv.conf</code>. This file will be copied to <code>/etc/resolv.conf</code> once the tunnel is up.

== Connecting ==

Save the following script (e.g. <code>~/.local/bin/vpn-connect.sh</code>) and make it executable:

<pre>
#!/bin/sh
# Wait for tun interface, then set DNS
(
while ! ip addr show tun0 2>/dev/null | grep -q inet; do
sleep 1
done
doas cp ~/.local/resolv.conf /etc/
) &
# Start VPN in foreground
doas docker start -ai openconnect-sso
</pre>

<pre>
chmod +x ~/.local/bin/vpn-connect.sh
</pre>

Run it:

<pre>
~/.local/bin/vpn-connect.sh
</pre>

A browser window will open for SSO authentication. After completing login, the VPN tunnel will establish and DNS will be updated automatically.

== How it works ==

The script starts a background subshell that polls for the <code>tun0</code> interface. Once the interface has an IP address assigned (meaning the tunnel is up), it copies the VPN-specific <code>resolv.conf</code> into place. Meanwhile, the Docker container runs in the foreground so its output and the SSO browser window remain accessible.

== Disconnecting ==

Close the foreground process with {{Key|Ctrl|C}} or stop the container:

<pre>
doas docker stop openconnect-sso
</pre>

You may also want to restore your original <code>/etc/resolv.conf</code> afterwards if it is not managed by another service.

== Why use Docker? ==
System updates broke the bare metal openconnect-sso install. Docker keeps things static. Another way would be pyenv - please add steps below if you succeed with it.

== See also ==
* [https://hub.docker.com/r/morgan404/openconnect-client Docker image example on hub.docker.com] - Uses an Alpine Linux-based container using OpenConnect and OpenSSH Docker. Also enables automatic server certificate handling, which simplifies configuration.
* [https://github.com/tuapuikia/openconnect-sso-docker An openconnect-sso Docker implementation for X11] - Includes host networking.
* [https://github.com/vlaci/openconnect-sso openconnect-sso GitHub repository] - Installation, authentication logic, usage (without Docker), authentication logic and for updates upstream.

[[Category:Networking]]
[[Category:VPN]]
[[Category:Virtualization‏‎]]
[[Category:Authentication]]

Alpine Linux:FAQ

2026-02-19T20:45:52Z

John3-16: /* Why don't I have man pages or where is the 'man' command? */ Two syntax amendments.

[[Image:filetypes.svg|64px|left|link=]]

Alpine Linux is an independent, non-commercial, general purpose Linux distribution designed for power users who appreciate security, simplicity and resource efficiency.

This is a list of '''frequently asked questions''' about Alpine Linux. If your question is not answered on this page, check the available [[Alpine Linux:Support|support]] options.

== General ==
=== Where to start? ===

The [[Installation]] page and the [[Installation#Post-Installation|Post Installation]] section on that page, provide a basic orientation.

A broader overview may be found on the official [https://alpinelinux.org/about About] page and at the [[Alpine Linux:Overview|wiki overview]].

Please note that testing is safer on your own virtual machine.

=== I have found a bug, where can I report it? ===
You can report it on the [https://gitlab.alpinelinux.org/groups/alpine/-/issues bugtracker], but search it first to see if the issue has already been reported.

=== Are there any details about the releases available? ===
Please check the [https://alpinelinux.org/releases/ Release Branches] page for more information.

=== What is the difference between edge and stable release branch? ===

[[Repositories#Edge|'''Edge''']] is the name given to the current [[Aports tree|development tree]] of Alpine Linux. ''edge'' can be considered as '''rolling release version''' of Alpine Linux. This version contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis.

[[Repositories#Release Branches|Stable release branches]] are just what they sound like: initially a point-in-time snapshot of the package archives, but then maintained with bugfixes only in order to keep a stable environment. Occasionally, snapshot ISO images of the then-current state of edge are made and are available for download. Typically these are made when there are major kernel upgrades or package upgrades that require initramfs rebuilds.

=== What architectures does Alpine Linux support? ===
The table below lists the architectures that are officially supported.
{{:Include:Architecture support matrix}}
Please check [https://alpinelinux.org/downloads Downloads] page for media availability on each one.


=== How can I contribute? ===
You can contribute by:
* Using the software and giving [https://gitlab.alpinelinux.org/groups/alpine/-/issues feedback].
* Documenting your [https://www.alpinelinux.org Alpine Linux] experiences on this [[Main_Page|wiki]].
* Flag packages as outdated in the [https://pkgs.alpinelinux.org/packages package database], or even better enable release monitoring in [https://release-monitoring.org/ Anitya] for them.
* In many other ways.
Please visit the [[Contribute|Contribute page]] to read more about this topic.

=== Why don't I have man pages or where is the 'man' command? ===

The <code>man</code> command, the {{pkg|man-pages}} and the system's ''core'' manual pages are not installed by default. Since binary packages are thinned out and split, documentation sub-packages in the format '''packagename-doc''' are not installed by default.
The core utilities provided by [[BusyBox]] – e.g. {{ic|ls}}, {{ic|traceroute}} and {{ic|poweroff}} – do not have individual man pages in keeping with BusyBox's minimalist design. Instead, the man page package for BusyBox, {{pkg|busybox-doc}}, supplies a single '''busybox''' man page that lists all the available switches for those utility applets; once '''busybox-doc''' is installed, the switches for each utility can be listed using the {{ic|--help}} option – e.g. {{ic|ls --help}} – or by scrolling through {{ic|$ man busybox}}.

Install the ''man pages reader'' called {{pkg|mandoc}}. It is the default reader since Alpine Linux v3.12, preferred over {{pkg|man-db}} or {{pkg|man-pages}}, as it supplies a smaller, faster and more secure <code>man</code> command:
{{cmd|# apk add {{pkg|mandoc}}}}

Once {{pkg|mandoc}} is installed, add documentation for the package where you need it. For example, say you installed '''nftables''', and you now require its man page:
{{cmd|# apk add {{pkg|nftables-doc}}}}

The {{pkg|docs}} meta package will immediately install the documentation sub-package for all of the currently installed packages, plus the {{pkg|mandoc}} reader, if not installed. {{pkg|docs}} additionally ensures that documentation sub-packages are installed/removed automatically for any packages that one may add/remove in the future.

{{cmd|# apk add docs}}

Optionally, to be able to search all ''installed'' man pages for a given command, say, {{ic|<var>password</var>}}, install {{pkg|mandoc-apropos}}, which supplies the <code>apropos</code> instruction.

{{cmd|# apk add {{pkg|mandoc-apropos}}}}

Then, search installed man pages for the command:

$ apropos <var>password</var>
chage(1) - change user password expiry information
expiry(1) - check and enforce password expiration policy
git-credential-cache(1) - Helper to temporarily store passwords in memory
keepassxc(1) - a modern open-source password manager
[...]

Keep in mind that not all packages have a corresponding documentation package, and even when it has one, it may not be in the form of '''man pages'''.

==Setup==

=== What is the difference between ''sys'', ''data'', and ''diskless'' when running <code>setup-alpine</code> or <code>setup-disk</code>? ===

[[System Disk Mode|'''sys''' or '''system''' disk]] mode is the traditional hard disk installation. The following partitions will be created on the disk: ''/boot/'', ''/'' (filesystem root) and ''swap'', if <code>setup-alpine</code> is used, or use <code>setup-disk</code> script for custom partitioning. This mode may be used for development boxes, desktops, virtual servers, etc.

In [[Data Disk Mode|'''data''' disk]] mode, disk(s) are used for data storage, not for the operating system. Runs from the media and only a ''/var/'' is created on disk. The system itself will run from a ''tmpfs'' (RAM). Use this mode if you only want to use the disk(s) for data, like ''mailspool'', ''databases'', ''logs'', etc.

In [[Diskless Mode|'''diskless''']] mode, no disks are to be used. Here the entire system run from a ''tmpfs'' (RAM). [[Alpine local backup]] may still be used in this mode.

=== How do I upgrade Alpine? ===

To upgrade to a new stable release or edge refer to [[Upgrading Alpine Linux to a new release branch]].

=== Why don't my cron jobs run? ===
{{Main|Cron}}
Start service ''crond'' and add it to the default runlevel:{{cmd|rc-service crond start && rc-update add crond}}

After that the cron daemon is started automatically on system boot and executes the scripts placed in the folders under ''/etc/periodic/'' - there are folders for ''15min'', ''hourly'', ''daily'', ''weekly'' and ''monthly'' scripts.

To check whether your scripts are likely to run, use the ''run-parts'' command, for example:{{cmd|run-parts --test /etc/periodic/15min}}

This command will tell you what should run but will not actually execute the scripts.

If the results of the test are not as expected, check the following:

* Make sure the script is executable - if unsure, issue the command {{cmd|chmod +x /etc/periodic/[path/scriptname]}}
* Make sure the first line of your script is <code>#!/bin/sh</code>
* Do not use periods on your script file names - this stops them from working; for example: {{Path|/etc/periodic/daily/myscript}} will run, but {{Path|/etc/periodic/daily/myscript.sh}} won't.

== Time and timezones ==

=== How do I set the local timezone? ===

If you wish to edit the ''timezone'' (TZ) after installation, run the [[Alpine_setup_scripts#setup-timezone|setup-timezone]] script.

== Packages ==

=== Can you build an APK package for ...? ===
Please create an [https://gitlab.alpinelinux.org/alpine/aports/issues/new issue] in the [https://gitlab.alpinelinux.org bugtracker]. Prefix it with "package request:" in the title and include a short description (one-line), a URL for the home page, why you need it, and a URL for the source package.

=== How can I build my own package? ===
Please see the [[Creating an Alpine package]] page.

=== What does "required by: world[$pkgname]" mean? ===

It means that the package you tried to install does not exist in the [[Alpine Package Keeper#Packages and Repositories|repositories]] you have configured.

Ensure that the [[Repositories#Managing_repositories|community repository is enabled]] in the {{path|/etc/apk/repositories}} file.

Or is the package in a [[Repositories#Tagged_repository|tagged repository]] and you forgot to suffix the package with the repo tag? Example:{{cmd|# apk add experimental-package@testing}}

=== How can I find out if a certain package exists in Alpine? ===

If you want to only search repositories you have configured in /etc/apk/repositories, then <code>apk search $pkgname</code> should get you sorted. If you want to search all repositories have a look at the [https://pkgs.alpinelinux.org/ online pkg oracle]

=== WARNING: Ignoring APKINDEX.xxxx.tar.gz ===
If you get <code>WARNING: Ignoring APKINDEX.xxxx.tar.gz: No such file or directory</code> while running [[Alpine_Linux_package_management|package related tools]], check your {{Path|/etc/apk/repositories}} file.

To check the content of the repositories file
{{Cmd|cat /etc/apk/repositories}}

or
{{Cmd|setup-apkrepos}}

== Dynamic DNS ==
=== How do I schedule a regular dynamic DNS update? ===
You'll want to install the {{pkg|ez-ipupdate}} package:
{{cmd|apk add ez-ipupdate}}

After that, create a new file at {{path|/etc/ez-ipupdate.conf}} with contents similar to:
service-type=dyndns
user=myusername:mypassword
interface=eth1
host=myhostname.dyndns.org

Make the new ip cache directory:
{{cmd|mkdir /var/cache/ez-ipupdate
lbu add /var/cache/ez-ipupdate}}

Then schedule a new cron job with this command:
{{cmd|echo >> /var/log/ez-ipupdate && \ /bin/date >> /var/log/ez-ipupdate && \ ez-ipupdate --config-file /etc/ez-ipupdate.conf -f -F /var/run/ez-ipupdate.pid \ --cache-file /var/cache/ez-ipupdate/ipcache --quiet >> /var/log/ez-ipupdate 2>&1}}

Don't forget to backup your settings!
{{cmd|lbu ci}}

== Terminal ==

=== How to enable/fix colors for git? ===

The problem is not in git itself or terminal, but in the <tt>less</tt> command.
Busybox’s <tt>less</tt> doesn’t support <tt>-r</tt> (<tt>--raw-control-chars</tt>) and <tt>-R</tt> (<tt>--RAW-CONTROL-CHARS</tt>) options.

The simplest (yet not ideal) solution is to install GNU less:

{{cmd|apk add less}}

Additionally, for colorized diff while using verbose commit (<tt>git commit -v</tt>), add this to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>export GIT_EDITOR=vim</nowiki>}}

=== Fix lacking lsusb / lspci output ===
{{Main|How to get regular stuff working}}
If you launch {{ic|lsusb}} or {{ic|lspci}} on a default installation, there's no device descriptions, and the latter doesn't exist.

This can be fixed by installing the '''{{pkg|usbutils}}''' and '''{{pkg|hwdata}}''' tables.

== Old questions, no longer frequently asked ==

=== Alpine freezes during boot from Compact Flash, how can I fix? ===
Most Compact Flash card readers do not support proper DMA. 
You should append '''nodma''' to the ''append'' line in {{path|syslinux.cfg}}.

=== How do I remove the CD-ROM? ===
Since the modloop loopback device is on CD-ROM you cannot just run <code>eject</code>. You need to unmount the modloop first. 
Unmounting both the modloop and the CDROM in one step can be done by executing:
{{Cmd|/etc/init.d/modloop stop}}

Then it's possible to eject the CD-ROM:
{{Cmd|eject}}

=== How can I install custom firmware in a diskless system? ===

The modules and firmware are both special images which are mounted as read-only. 
To fix this issue you can copy the firmware directory to your writeable media (cf/usb) and copy your custom firmware to it. 
After reboot Alpine should automatically use the directory on your local storage instead of the loopback device.

=== OpenNTPD reports an error with "adjtime" ===
Your log contains something like:
reply from 85.214.86.126: offset 865033148.784255 delay 0.055466, next query 32s
reply from 202.150.212.24: offset 865033148.779314 delay 0.400771, next query 3s
adjusting local clock by 865033148.779835s
adjtime failed: Invalid argument

{{pkg|openntpd}} is supposed to make small adjustments in the time without causing time jumps. 
If the adjustment is too big then something is clearly wrong and ntpd gives up. (its actually adjtime(3) that has a limit on how big adjustments are allowed)

You can make ntpd set the time at startup by adding ''-s'' option to ntpd. This is done by setting '''NTPD_OPTS="-s"''' in {{path|/etc/conf.d/ntpd}}.

=== Using a cron job to keep the time in sync ===
The [[Cron#Basic_example|cron]] page explains how to run the command {{ic|ntpd -d -q -n -p uk.pool.ntp.orgA}} as a cron job.

=== Windows clients reports an error when trying to sync ===
{{pkg|openntpd}} needs to run for a while before it is satisfied it is in sync.
Until then it will set a flag "clock not synchronized" and Windows will report an error while trying to sync with your openntpd server.

Only thing to do is wait, do something else for 15-20mins and then check.

Alpine Linux:FAQ

2026-02-19T20:31:46Z

John3-16: /* Why don't I have man pages or where is the 'man' command? */ 1. Enhanced guidance re any man page availability for core utils, mandoc, mandoc-apropos; 2. Reordered information according to usage i.e. docs package promoted; 3. Style/grammar amendments.

[[Image:filetypes.svg|64px|left|link=]]

Alpine Linux is an independent, non-commercial, general purpose Linux distribution designed for power users who appreciate security, simplicity and resource efficiency.

This is a list of '''frequently asked questions''' about Alpine Linux. If your question is not answered on this page, check the available [[Alpine Linux:Support|support]] options.

== General ==
=== Where to start? ===

The [[Installation]] page and the [[Installation#Post-Installation|Post Installation]] section on that page, provide a basic orientation.

A broader overview may be found on the official [https://alpinelinux.org/about About] page and at the [[Alpine Linux:Overview|wiki overview]].

Please note that testing is safer on your own virtual machine.

=== I have found a bug, where can I report it? ===
You can report it on the [https://gitlab.alpinelinux.org/groups/alpine/-/issues bugtracker], but search it first to see if the issue has already been reported.

=== Are there any details about the releases available? ===
Please check the [https://alpinelinux.org/releases/ Release Branches] page for more information.

=== What is the difference between edge and stable release branch? ===

[[Repositories#Edge|'''Edge''']] is the name given to the current [[Aports tree|development tree]] of Alpine Linux. ''edge'' can be considered as '''rolling release version''' of Alpine Linux. This version contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis.

[[Repositories#Release Branches|Stable release branches]] are just what they sound like: initially a point-in-time snapshot of the package archives, but then maintained with bugfixes only in order to keep a stable environment. Occasionally, snapshot ISO images of the then-current state of edge are made and are available for download. Typically these are made when there are major kernel upgrades or package upgrades that require initramfs rebuilds.

=== What architectures does Alpine Linux support? ===
The table below lists the architectures that are officially supported.
{{:Include:Architecture support matrix}}
Please check [https://alpinelinux.org/downloads Downloads] page for media availability on each one.


=== How can I contribute? ===
You can contribute by:
* Using the software and giving [https://gitlab.alpinelinux.org/groups/alpine/-/issues feedback].
* Documenting your [https://www.alpinelinux.org Alpine Linux] experiences on this [[Main_Page|wiki]].
* Flag packages as outdated in the [https://pkgs.alpinelinux.org/packages package database], or even better enable release monitoring in [https://release-monitoring.org/ Anitya] for them.
* In many other ways.
Please visit the [[Contribute|Contribute page]] to read more about this topic.

=== Why don't I have man pages or where is the 'man' command? ===

The <code>man</code> command, the {{pkg|man-pages}} and the system's ''core'' manual pages are not installed by default. Since binary packages are thinned out and split, documentation sub-packages in the format '''packagename-doc''' are not installed by default.
The core utilities provided by [[BusyBox]] e.g. {{ic|ls}}, {{ic|traceroute}} and {{ic|poweroff}}) do not have individual man pages in keeping with BusyBox's minimalist design. Instead, the man page package for BusyBox, {{pkg|busybox-doc}}, supplies a single '''busybox''' man page that lists all the available switches for those utility applets; once '''busybox-doc''' is installed, the switches for each utility can be listed using the {{ic|--help}} option – e.g. {{ic|ls --help}} – or by scrolling through {{ic|$ man busybox}}.

Install the ''man pages reader'' called {{pkg|mandoc}}. It is the default reader since Alpine Linux v3.12, preferred over {{pkg|man-db}} or {{pkg|man-pages}}, as it supplies a smaller, faster and more secure <code>man</code> command:
{{cmd|# apk add {{pkg|mandoc}}}}

Once {{pkg|mandoc}} is installed, add documentation for the package where you need it. For example, say you installed '''nftables''', and you now require its man page:
{{cmd|# apk add {{pkg|nftables-doc}}}}

The {{pkg|docs}} meta package will immediately install the documentation sub-package for all of the currently installed packages, plus the {{pkg|mandoc}} reader, if not installed. {{pkg|docs}} additionally ensures that documentation sub-packages are installed/removed automatically for any packages that one may add/remove in the future.

{{cmd|# apk add docs}}

Optionally, to be able to search all ''installed'' man pages for a given command, say, {{ic|<var>password</var>}}, install {{pkg|mandoc-apropos}}, which supplies the <code>apropos</code> instruction.

{{cmd|# apk add {{pkg|mandoc-apropos}}}}

Then, search installed man pages for the command:
<pre>
$ apropos <var>password</var>
chage(1) - change user password expiry information
expiry(1) - check and enforce password expiration policy
git-credential-cache(1) - Helper to temporarily store passwords in memory
keepassxc(1) - a modern open-source password manager
[...]
</pre>

Keep in mind that not all packages have a corresponding documentation package, and even when it has one, it may not be in the form of '''man pages'''.

==Setup==

=== What is the difference between ''sys'', ''data'', and ''diskless'' when running <code>setup-alpine</code> or <code>setup-disk</code>? ===

[[System Disk Mode|'''sys''' or '''system''' disk]] mode is the traditional hard disk installation. The following partitions will be created on the disk: ''/boot/'', ''/'' (filesystem root) and ''swap'', if <code>setup-alpine</code> is used, or use <code>setup-disk</code> script for custom partitioning. This mode may be used for development boxes, desktops, virtual servers, etc.

In [[Data Disk Mode|'''data''' disk]] mode, disk(s) are used for data storage, not for the operating system. Runs from the media and only a ''/var/'' is created on disk. The system itself will run from a ''tmpfs'' (RAM). Use this mode if you only want to use the disk(s) for data, like ''mailspool'', ''databases'', ''logs'', etc.

In [[Diskless Mode|'''diskless''']] mode, no disks are to be used. Here the entire system run from a ''tmpfs'' (RAM). [[Alpine local backup]] may still be used in this mode.

=== How do I upgrade Alpine? ===

To upgrade to a new stable release or edge refer to [[Upgrading Alpine Linux to a new release branch]].

=== Why don't my cron jobs run? ===
{{Main|Cron}}
Start service ''crond'' and add it to the default runlevel:{{cmd|rc-service crond start && rc-update add crond}}

After that the cron daemon is started automatically on system boot and executes the scripts placed in the folders under ''/etc/periodic/'' - there are folders for ''15min'', ''hourly'', ''daily'', ''weekly'' and ''monthly'' scripts.

To check whether your scripts are likely to run, use the ''run-parts'' command, for example:{{cmd|run-parts --test /etc/periodic/15min}}

This command will tell you what should run but will not actually execute the scripts.

If the results of the test are not as expected, check the following:

* Make sure the script is executable - if unsure, issue the command {{cmd|chmod +x /etc/periodic/[path/scriptname]}}
* Make sure the first line of your script is <code>#!/bin/sh</code>
* Do not use periods on your script file names - this stops them from working; for example: {{Path|/etc/periodic/daily/myscript}} will run, but {{Path|/etc/periodic/daily/myscript.sh}} won't.

== Time and timezones ==

=== How do I set the local timezone? ===

If you wish to edit the ''timezone'' (TZ) after installation, run the [[Alpine_setup_scripts#setup-timezone|setup-timezone]] script.

== Packages ==

=== Can you build an APK package for ...? ===
Please create an [https://gitlab.alpinelinux.org/alpine/aports/issues/new issue] in the [https://gitlab.alpinelinux.org bugtracker]. Prefix it with "package request:" in the title and include a short description (one-line), a URL for the home page, why you need it, and a URL for the source package.

=== How can I build my own package? ===
Please see the [[Creating an Alpine package]] page.

=== What does "required by: world[$pkgname]" mean? ===

It means that the package you tried to install does not exist in the [[Alpine Package Keeper#Packages and Repositories|repositories]] you have configured.

Ensure that the [[Repositories#Managing_repositories|community repository is enabled]] in the {{path|/etc/apk/repositories}} file.

Or is the package in a [[Repositories#Tagged_repository|tagged repository]] and you forgot to suffix the package with the repo tag? Example:{{cmd|# apk add experimental-package@testing}}

=== How can I find out if a certain package exists in Alpine? ===

If you want to only search repositories you have configured in /etc/apk/repositories, then <code>apk search $pkgname</code> should get you sorted. If you want to search all repositories have a look at the [https://pkgs.alpinelinux.org/ online pkg oracle]

=== WARNING: Ignoring APKINDEX.xxxx.tar.gz ===
If you get <code>WARNING: Ignoring APKINDEX.xxxx.tar.gz: No such file or directory</code> while running [[Alpine_Linux_package_management|package related tools]], check your {{Path|/etc/apk/repositories}} file.

To check the content of the repositories file
{{Cmd|cat /etc/apk/repositories}}

or
{{Cmd|setup-apkrepos}}

== Dynamic DNS ==
=== How do I schedule a regular dynamic DNS update? ===
You'll want to install the {{pkg|ez-ipupdate}} package:
{{cmd|apk add ez-ipupdate}}

After that, create a new file at {{path|/etc/ez-ipupdate.conf}} with contents similar to:
service-type=dyndns
user=myusername:mypassword
interface=eth1
host=myhostname.dyndns.org

Make the new ip cache directory:
{{cmd|mkdir /var/cache/ez-ipupdate
lbu add /var/cache/ez-ipupdate}}

Then schedule a new cron job with this command:
{{cmd|echo >> /var/log/ez-ipupdate && \ /bin/date >> /var/log/ez-ipupdate && \ ez-ipupdate --config-file /etc/ez-ipupdate.conf -f -F /var/run/ez-ipupdate.pid \ --cache-file /var/cache/ez-ipupdate/ipcache --quiet >> /var/log/ez-ipupdate 2>&1}}

Don't forget to backup your settings!
{{cmd|lbu ci}}

== Terminal ==

=== How to enable/fix colors for git? ===

The problem is not in git itself or terminal, but in the <tt>less</tt> command.
Busybox’s <tt>less</tt> doesn’t support <tt>-r</tt> (<tt>--raw-control-chars</tt>) and <tt>-R</tt> (<tt>--RAW-CONTROL-CHARS</tt>) options.

The simplest (yet not ideal) solution is to install GNU less:

{{cmd|apk add less}}

Additionally, for colorized diff while using verbose commit (<tt>git commit -v</tt>), add this to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>export GIT_EDITOR=vim</nowiki>}}

=== Fix lacking lsusb / lspci output ===
{{Main|How to get regular stuff working}}
If you launch {{ic|lsusb}} or {{ic|lspci}} on a default installation, there's no device descriptions, and the latter doesn't exist.

This can be fixed by installing the '''{{pkg|usbutils}}''' and '''{{pkg|hwdata}}''' tables.

== Old questions, no longer frequently asked ==

=== Alpine freezes during boot from Compact Flash, how can I fix? ===
Most Compact Flash card readers do not support proper DMA. 
You should append '''nodma''' to the ''append'' line in {{path|syslinux.cfg}}.

=== How do I remove the CD-ROM? ===
Since the modloop loopback device is on CD-ROM you cannot just run <code>eject</code>. You need to unmount the modloop first. 
Unmounting both the modloop and the CDROM in one step can be done by executing:
{{Cmd|/etc/init.d/modloop stop}}

Then it's possible to eject the CD-ROM:
{{Cmd|eject}}

=== How can I install custom firmware in a diskless system? ===

The modules and firmware are both special images which are mounted as read-only. 
To fix this issue you can copy the firmware directory to your writeable media (cf/usb) and copy your custom firmware to it. 
After reboot Alpine should automatically use the directory on your local storage instead of the loopback device.

=== OpenNTPD reports an error with "adjtime" ===
Your log contains something like:
reply from 85.214.86.126: offset 865033148.784255 delay 0.055466, next query 32s
reply from 202.150.212.24: offset 865033148.779314 delay 0.400771, next query 3s
adjusting local clock by 865033148.779835s
adjtime failed: Invalid argument

{{pkg|openntpd}} is supposed to make small adjustments in the time without causing time jumps. 
If the adjustment is too big then something is clearly wrong and ntpd gives up. (its actually adjtime(3) that has a limit on how big adjustments are allowed)

You can make ntpd set the time at startup by adding ''-s'' option to ntpd. This is done by setting '''NTPD_OPTS="-s"''' in {{path|/etc/conf.d/ntpd}}.

=== Using a cron job to keep the time in sync ===
The [[Cron#Basic_example|cron]] page explains how to run the command {{ic|ntpd -d -q -n -p uk.pool.ntp.orgA}} as a cron job.

=== Windows clients reports an error when trying to sync ===
{{pkg|openntpd}} needs to run for a while before it is satisfied it is in sync.
Until then it will set a flag "clock not synchronized" and Windows will report an error while trying to sync with your openntpd server.

Only thing to do is wait, do something else for 15-20mins and then check.

Configure a Wireguard interface (wg)

2026-02-19T16:26:44Z

John3-16: 1. Added stubs: 'Alternative Integrations into the Network Stack', 'Tools' and 'WireGuard Monitoring and Management'; 2. /* See also */ Added Prometheus/Grafana/Alerts setup link at medium.com.

{{TOC right}}

[https://en.wikipedia.org/wiki/WireGuard WireGuard] multiple platform vpn solution. WireGuard itself is now integrated into the linux kernel since v5.6. Only the userland configuration tools are required.

== Installation ==

The most straightforward method to configure WireGuard is to use the tool <code>wg-quick</code> available in the package {{pkg|wireguard-tools-wg-quick}}.

Install the meta package {{pkg|wireguard-tools}} to install the necessary WireGuard packages and {{pkg|iptables}} as follows: {{Cmd|# apk add wireguard-tools iptables}}

== Configuration ==

=== Create Server Keys and Interface Config ===

Create a server private and public key: {{Cmd|<nowiki># wg genkey | tee server.privatekey | wg pubkey > server.publickey</nowiki>}}

Remove any permissions on the file for users and groups other than the root user to ensure that only it can access the private key: {{Cmd|<nowiki># chmod go= server.privatekey</nowiki>}}

Then, we create a new config file {{Path|/etc/wireguard/wg0.conf}} using these new keys as follows:{{Cat|/etc/wireguard/wg0.conf|<nowiki>
[Interface]
Address = 192.168.2.1/24, fddd::ffff/64
ListenPort = 45340
PrivateKey = <server private key value> # the key from the previously generated privatekey file
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;iptables -A FORWARD -o %i -j ACCEPT; ip6tables -A FORWARD -i %i -j ACCEPT; ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;ip6tables -A FORWARD -o %i -j ACCEPT
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;iptables -D FORWARD -o %i -j ACCEPT; ip6tables -D FORWARD -i %i -j ACCEPT; ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;ip6tables -D FORWARD -o %i -j ACCEPT

[Peer]
PublicKey = <client public key value> # obtained from client device via wireguard connection setup process
AllowedIPs = 192.168.2.2/32, fddd::1/128</nowiki>}}

The PostUp and PostDown iptable rules forward traffic from the wg0 subnet (192.168.2.1/24) to the lan subnet on interface eth0. Refer to [https://github.com/pirate/wireguard-docs#user-content-config-reference this WireGuard documentation] for information on adding peers to the config file.

Bring up the new {{ic|wg0}} interface:{{Cmd|# wg-quick up wg0}}

To take it down, we can use <code>wg-quick down wg0</code> which will clean up the interface and remove the iptables rules.

{{Note|If running in a Docker container, you will need to run with <code>--cap-add{{=}}NET_ADMIN</code> to modify your interfaces.}}

=== Use with network interfaces ===

To enable connecting with Wireguard on boot, open your {{Path|/etc/network/interfaces}} and add this information after your auto other network interfaces as follows:{{Cat|/etc/network/interfaces|<nowiki>...
auto wg0
iface wg0 inet static
pre-up wg-quick up /etc/wireguard/wg0.conf</nowiki>}}

=== Service configuration ===

Since Alpine 3.20, {{pkg|wireguard-tools-openrc}} package provides an OpenRC initd service file.

To use this, install the package:{{Cmd|# apk add wireguard-tools-openrc }}

To use the WireGuard OpenRC script with {{ic|wg-quick.wg0}}, create a symbolic link to it with the configuration name as follows:{{Cmd|# ln -s /etc/init.d/wg-quick /etc/init.d/wg-quick.wg0}}

Add the {{ic|wg-quick.wg0}} service to the default runlevel:{{Cmd|# rc-update add wg-quick.wg0}}
To start|stop|restart the [[OpenRC]] service:{{Cmd|# rc-service wg-quick.wg0 start}}

=== Enable IP Forwarding ===

With a NAT destination rule in place on your router, you should be able connect to the wireguard instance and access the host. However, if you intend for peers to be able to access external resources (including the internet), you will need to enable ip forwarding.

Edit the file {{Path|/etc/sysctl.conf}} or a <code>.conf</code> file under {{Path|/etc/sysctl.d/}} folder add the following line as follows:{{Cat|/etc/sysctl.conf|
net.ipv4.ip_forward {{=}} 1
net.ipv6.conf.all.forwarding {{=}} 1
net.ipv6.conf.default.forwarding {{=}} 1}}

Add the sysctl service to run at boot:{{Cmd|# rc-update add sysctl}}

Then either reboot or run {{ic|# sysctl -p /etc/sysctl.conf}} to reload the settings. To ensure forwarding is turned on, run {{ic|# sysctl -a | grep ip_forward}} and ensure <Code>net.ipv4.ip_forward</code> is set to <code>1</code>.

In the file {{Path|/etc/conf.d/iptables}}, Change the setting as follows:{{Cat|/etc/conf.d/iptables|...
IPFORWARD{{=}}"yes"}}

== Running with modloop ==

If you are running [[Diskless Mode]] i.e from a RAM disk, you can't modify the modloop.

You can get around it by unpacking the modloop, mounting the unpacked modules folder, then installing WireGuard.

#!/bin/sh
apk add squashfs-tools # install squashfs tools to unpack modloop
unsquashfs -d /root/squash /lib/modloop-lts # unpack modloop to root dir
umount /.modloop # unmount existing modloop
mount /root/squash/ /.modloop/ # mount unpacked modloop
apk del wireguard-lts # uninstall previous WireGuard install
apk add wireguard-lts
apk add wireguard-tools

You can repack the squash filesystem or put this script in the /etc/local.d/ path so it runs at boot-up.

== Preventing leaks ==

When using a private network over Wireguard, it may be desirable to prevent traffic from leaking onto other networks with the same range (e.g.: a Wi-Fi network using the same range).

Suppose we are using the network <code>fd00:feed:c0de::</code> over Wireguard. To prevent leaks using [[nftables]], use the following <code>/etc/nftables.d/private-network.nft</code>:

#!/usr/sbin/nft -f

table inet filter {
chain output {
type filter hook output priority 0;

# Allow traffic to fd00:feed:c0de::1 only via wg0.
ip6 daddr fd00:feed:c0de::1 oifname "wg0" accept

# Drop all other attempts to reach fd00:feed:c0de::1.
ip6 daddr fd00:feed:c0de::1 drop
}
}

== Alternative Integrations into the Network Stack ==
{{Expand|Contributions welcome. Thank you!}}

=== ConnMan Wireguard ===

'''{{Pkg|connman-wireguard}}''': An integration plugin enabling ConnMan management of WireGuard interfaces.

=== ifupdown-ng-wireguard ===

'''{{Pkg|ifupdown-ng-wireguard}}''': Supplies a declarative WireGuard interface for '''ifupdown-ng'''.

=== wireguard-go ===

'''{{Pkg|wireguard-go}}''': A userspace implementation of WireGuard in '''go''', not used by default in Alpine Linux except in containerized or restricted environments where kernel module loading is not possible. It can be used as a fallback on older kernels that do not offer WireGuard support.

== Tools ==
{{Expand|Contributions are encouraged.}}

=== Tailscale and NetBird ===

'''{{Pkg|tailscale}}''', '''{{Pkg|netbird}}''': Mesh VPNs built over WireGuard that streamline peer discovery and access control.

=== Rosenpass ===

'''{{Pkg|rosenpass}}''': Verified, post-quantum key exchange tool.

=== Innernet ===

'''{{Pkg|innernet}}''': A private network based on WireGuard using centralized key management. Currently in testing repository as of February 2026: test by [[Repositories#Using_testing_repository|enabling and tagging the testing repository]] and installing as {{ic|innernet@testing}}.

=== py3-wgconfig ===

'''{{Pkg|py3-wgconfig}}''': Python library to parse and modify WireGuard config files that preserves comments. Currently in testing repository as of February 2026: ensure that the [[Repositories#Using_testing_repository|the testing repo is enabled and tagged]], and install as {{ic|py3-wgconfig@testing}}.

=== WireGuard Bash Completion ===

'''{{Pkg|wireguard-tools-bash-completion}}''': Enables tab completion in bash for {{Pkg|wg}} and {{Pkg|wg-quick}}.

== WireGuard Monitoring and Management ==
{{Expand|Contributions are encouraged.}}

=== Prometheus Wireguard Exporter ===

'''{{Pkg|prometheus-wireguard-exporter}}''': To monitor active peers, traffic. Rust-based, and must run with root privileges or with {{ic|CAP_NET_ADMIN}}.

== See also ==

* [https://github.com/pirate/wireguard-docs WireGuard documentation]
* [https://medium.com/nerd-for-tech/wireguard-vpn-monitoring-alerting-e1e1d1eaaa4e Setting up Prometheus WireGuard exporter, Grafana Dashboard, Alerts Manager.]

[[Category:Networking]]

Desktop environments and Window managers

2026-02-19T06:36:09Z

John3-16: /* Window managers */ Added mangowc; removed spurious reference in a Pkg template

{{TOC right}}


'''Alpine Linux''' has no official desktop although setting up a graphical environment is proposed in the [[Installation#Post-Installation|post-installation]] guide. Alpine Linux desktops may meet the needs for ''general'' daily desktop use:-
* Fewer packages still require [https://www.gnu.org/software/libc/ glibc], as numerous popular applications are now available here on [https://musl.libc.org/ musl]: {{Pkg|libreoffice*}}, {{Pkg|chromium*}}, [[Firefox]], etc
* Several Alpine Linux desktop environments have been benchmarked to be competitive for both [https://everybytecounts.org/#desktop-environment-comparison speed and memory]
* Arguably, there is a reduced attack surface through the use of a comparatively lightweight '''musl''' and [[BusyBox]] system core

All window managers and desktop environments that are available in Alpine Linux are listed on this page. A quick installation using the [[Alpine_setup_scripts#setup-desktop|setup-desktop]] script is available for several [[Setup-desktop|desktops]].

{{Tip|For servers, consider using [[Alpine_Configuration_Framework_Design|Alpine Configuration Framework (ACF)]] for security considerations in that use case.}}

== Desktop environments ==

A ''desktop environment'' (DE) is made of a bundle of programs that share a common ''graphical user interface'' (GUI), sometimes described as a ''graphical shell''. A desktop environment typically consists of icons, windows, toolbars, folders, wallpapers and desktop widgets, and might also provide drag-and-drop functionality.

* {{Pkg|budgie*}}
* [[COSMIC]]
* [[GNOME]]
* [[KDE|KDE Plasma]]
* {{Pkg|lomiri*|arch=}}
* [[Lumina]]
* [[LXQt]]
* [[MATE]]
* [[Xfce]]

=== Mobile/tablet UI ===
Certain desktop environments have been ported for use as ''mobile user interfaces'' (UI) while other mobile/tablet UIs may have been developed using other existing unix toolkits. ''Convergent desktop environments'' are designed with a view to be consistent regardless of the platform used (pc, mobile, tablet, etc) such as the aforementioned '''lomiri''' environment.
* {{Pkg|phosh*}} - Wayland shell for GNOME on [https://phosh.mobi/ mobile devices].
* {{Pkg|plasma-mobile*}} - [https://plasma-mobile.org/ Mobile UI using a KDE Plasma foundation].
* {{Pkg|sxmo*}} - [https://sxmo.org/ Minimalist mobile Linux environment.]

== Window managers ==

A ''window manager'' is software that controls the placement and appearance of windows within a windowing system in a graphical user interface. In the case of [[Wayland]], these are called ''compositors'' because they additionally perform the task of a ''compositing window manager''.

Almost all components of a desktop need to be added manually by the user. Both [[Alpine_Linux:Glossary#S|stacking]] (a.k.a. ''floating'') and [[Alpine_Linux:Glossary#T|tiling]]/''dynamic'' layouts are commonly used for window management.

{|class="wikitable sortable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
! WM Name !! Protocol!! Style !! Toolkit!!class="unsortable"|Inspiration
|-
| {{Pkg|2bwm|arch=}} || X11 || Stacking || C/Roff
|| [https://www.hack.org/~mc/hacks/mcwm mcwm]
|-
| [[AwesomeWM|Awesome]] ||X11 || Tiling || Lua ||
|-
| {{Pkg|berry|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|bspwm|arch=}} || X11 || Tiling || C ||
|-
| {{Pkg|cage |arch=}} || Wayland || Kiosk || C/wlroots || {{Pkg|ratpoison|arch=}}
|-
| {{Pkg|cagebreak|arch=}} || Wayland || Tiling ||C/wlroots || {{Pkg|ratpoison|arch=}}, {{Pkg|cage|arch=}}
|-
| {{Pkg|compiz|arch=}} || X11 || Compositing || C++/C/Python ||
|-
| {{Pkg|cwm|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|dk|arch=}} || X11 || Tiling || C || {{Pkg|dwm|arch=}}, {{Pkg|bspwm|arch=}}, [https://xmonad.org/ xmonad]
|-
| {{Pkg|dwl|arch=}} || Wayland || Tiling || C/wlroots||[[dwm]]
|-
| [[dwm]] || X11 || Tiling || C ||
|-
| [[Fluxbox]] || X11 || Stacking || C++ || [https://sourceforge.net/projects/blackboxwm/ blackbox]
|-
| {{Pkg|flwm|arch=}} || X11 || Stacking || C++/FLTK || [https://all-day-breakfast.com/wm2/ wm2]
|-
| {{Pkg|gamescope|arch=}} || X11/Wayland || Compositing || C++/C/Lua ||
|-
| {{Pkg|goomwwm||-
| {{Pkg|icewm|arch=}} || X11 || Stacking || C++/C/M4 ||
arch=}} || X11 || Stacking || C/Roff ||
|-
| {{Pkg|herbstluftwm|arch=}} || X11 || Tiling || C++ ||
|-
| [[Hyprland]] || Wayland || Tiling || C++ ||
|-
| [[I3wm|i3]] || X11 || Tiling || C ||
|-
| {{Pkg|icewm|arch=}} || X11 || Stacking || C++/C/M4 ||
|-
| {{Pkg|jwm|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|kwin|arch=}} || X11/Wayland || Compositing || C++ ||
|-
| [[LabWC]] || Wayland || Stacking || C/wlroots||[[Openbox]]
|-
| {{Pkg|mangowc|arch=}} || Wayland || Tiling || C/Nix/other || {{Pkg|dwl|arch=}}
|-
| {{Pkg|marco|arch=}} || X11 || Stacking || C || {{Pkg|metacity|arch=}}
|-
| {{Pkg|metacity|arch=}} || X11 || Compositing || C ||
|-
| {{Pkg|mutter|arch=}} || X11/Wayland || Compositing || C ||
|-
| {{Pkg|mwm|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|niri|arch=}} || Wayland || Tiling || Rust/GLSL/other || [https://github.com/paperwm/PaperWM PaperWM]
|-
| [[Openbox]] || X11 || Stacking || C ||
|-
| {{Pkg|pekwm|arch=}} || X11 || Stacking || C++/CMake/Perl/C || [http://sapphire.sourceforge.net/ aewm++]
|-
| [[Qtile]] || X11/Wayland || Tiling || Python ||
|-
| {{Pkg|ratpoison|arch=}} || X11 || Kiosk || C ||
|-
| [[River|river-classic/River]] || Wayland || Tiling || Zig || [[dwm]], [https://xmonad.org/ xmonad]
|-
| {{Pkg|spectrwm |arch=}} || X11 || Tiling || C|| [https://xmonad.org/ xmonad], [[dwm]]
|-
| [[Sway]] || Wayland || Tiling || C/wlroots || [[I3wm|i3]]
|-
| {{Pkg|sxmo-dwm|arch=}} || X11 || Tiling || C || {{Pkg|dwm|arch=}}
|-
| [[twm]] || X11 || Tiling || C ||
|-
| {{Pkg|wayfire|arch=}} || Wayland || Stacking || C++/wlroots || {{Pkg|compiz|arch=}}
|-
| [[Weston]] || Wayland || Stacking || C ||
|-
| {{Pkg|windowmaker|arch=}} || X11 || Stacking || C/Shell/M4/Perl/Makefile/Emacs Lisp/other || NeXTSTEP
|-
| {{Pkg|xfwm4|arch=}} || X11 || Compositing || C/Makefile/Meson/other ||
|}

== See also ==
* [[Installation#Post-Installation|Post Installation]]
* [[Wayland]]
* [[Xorg]]
* [[Display manager]]
* [https://wiki.archlinux.org/title/Desktop_environment Desktop environment - Archwiki]
* [https://wiki.gentoo.org/wiki/Desktop_environment Desktop environment - Gentoo Wiki]

[[Category:Desktop]]
[[Category:Desktop Environments]]
[[Category:Window Managers]]
[[Category:Compositor]]

Alpine Package Keeper

2026-02-18T03:01:21Z

John3-16: 1. /* Check file ownership */ Enhanced 'apk info --who-owns' guidance; indicated that '/usr' needs to be prepended on ''/usr merge'' systems; 2. /* apk fix */ Added that 'apk fix' will not fix packages if the repo version does not match the installed version; consider 'apk upgrade --available', if applicable.

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility and new features are flagged on the relevant sections of this page as seen on the right side. The diff output of the documentation between V2 and V3 is [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |Repository and package maintenance
|-
|mkndx || Create repository index (v3) file from packages
|-
|mkpkg || Create package (v3)
|-
|index || Create repository index (v2) file from packages
|-
|fetch || Download packages from repositories to a local directory
|-
|manifest|| Show checksums of package contents
|-
|extract || Extract package file contents
|-
|verify || Verify package integrity and signature
|-
|adbsign || Sign, resign or recompress v3 packages and indexes
|-
|style="background:black; color:white" colspan=2 align=center |Miscellaneous
|-
|audit|| Audit system for changes
|-
|stats || Show statistics about repositories and installations
|-
|version|| Compare package versions or perform tests on version strings
|-
|adbdump|| Dump v3 files in textual representation
|-
|adbgen || Generate v3 files from text representation
|-
|convdb || Convert v2 installed database to v3 format
|-
|convndx || Convert v2 indexes to v3 format
|-
|}

== Packages and Repositories ==
{{Main|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

=== Subpackages ===

In Alpine Linux, software packages are thinned out and split into subpackages to give more control over what features are installed and keeps the installation as small and efficient as possible.

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any package.

== World ==

At {{Path|/etc/apk/world}}, apk maintains the world, that is, a list of constraints the package selection needs to fulfill. World describes the desired system state. {{Path|/etc/apk/world}} is a plaintext file with one constraint using dependency notation per line. Each line has the format: 
<code>[!]NAME{@tag}{[<>~=]version}</code>.

There can be only one line with a given package NAME in the file and except the package NAME, all the other options are optional.

* '''!''' is used for [[#Masking a specific package|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/etc/apk/world}} must be solvable in order for the system to be considered correct, and no transaction may be committed that is incorrect. If apk cannot verify the correctness of the requested change, it will back out adding the constraint before attempting to change what packages are actually installed on the system. Thus apk will never [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== Update Package list ==

Alpine Linux [[Repositories|'''repositories''']] change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. This command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}. {{Cmd|# apk update}}

Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

It is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages from the repositories.

== Add a Package ==

Use '''add''' to install packages from a [[Repositories|'''repository''']]. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package. {{Cmd|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|held back or pinned]] at a specific level or version.

=== Add a local Package ===

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag: {{cmd|# apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|# apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<Pre>
# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages
</Pre>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/etc}} directory. Whenever apk installs a file there, but realizes a potentially edited one is already present, it will write its file to that filename with {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# apk upgrade
(1/2) Upgrading openrc-user-pam (0.62.2-r2 -> 0.62.2-r3)
(2/2) Upgrading openrc (0.62.2-r2 -> 0.62.2-r3)
openrc-0.62.2-r3: installing file to etc/rc.conf.apk-new
openrc-0.62.2-r3.post-upgrade: Executing script}}

You may handle these by hand, or use the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|search]] commands to interrogate the installed database and indexes for information related to packages. The command outputs human readable format in addition to json and yaml output.

== Search for Packages ==

{{Tip|Alpine Linux provides a specialized [https://pkgs.alpinelinux.org web interface] dedicated to looking through various available packages.}}

The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|$ apk search -v}}
* To list all packages are part of the ACF system: {{cmd|$ apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|$ apk search -v --description 'NTP' }}
* To list all packages that provide the <code>git</code> command: {{cmd|$ apk search -v 'cmd:git'}}

== Information on Packages ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|$ apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

=== Check file ownership ===

The '''info''' command is also useful to determine which package a file belongs to when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

{{Note|The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[https://wiki.alpinelinux.org/wiki/Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge /usr merge]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, in order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}
}}

=== Check Dependencies ===

The '''info''' command specific to check package dependency and reverse dependency is explained below:

The option '''-R''' or '''--depends''' lists the dependencies of the package: {{Cmd|$ apk info --depends pipewire}}
<pre>
pipewire-1.0.6-r1 depends on:
/bin/sh
so:libc.musl-x86_64.so.1
so:libpipewire-0.3.so.0
</pre>

The option '''-r''' or '''--rdepends''' lists the reverse dependencies of the package (all other packages which depend on the package). {{Cmd|$ apk info --rdepends pipewire}}
<pre>
pipewire-1.0.6-r1 is required by:
xdg-desktop-portal-wlr-0.7.1-r0
pipewire-pulse-1.0.6-r1
</pre>

=== Listing installed packages ===

To list all installed packages, use: {{Cmd|$ apk info}}

To list all installed packages in alphabetical order, with a description of each, do:{{Cmd|$ apk -vv info|sort}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ apk list --quiet --origin util-linux}}

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>
#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done
</pre>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|sys mode]] installs don't need an apk cache, it still allows to serve packages over the network, though, e.g. to get installed by other local machines.

{{Note|For [[Diskless Mode|diskless]] installations, [[Local APK cache|local package cache]] is needed to automatically (re-)install packages when booting.}}

When newer packages are added to the cache over time, the older versions of the packages default to remain in the cache directory. The older versions of packages can be removed with the '''clean''' command. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# apk cache download}}

The above two steps can be combined into one with the '''sync''' command - this cleans out old packages and downloads missing packages. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ dot -Tpng seatd_dependencies.dot -o seatd_dependencies.png}}

== apk fix ==

If a package is specified, the '''fix''' subcommand applies repair strategies to correct errors in the installation of the specified packages. If no packages are specified, this command synchronizes all the installed packages with the [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''': {{Cmd|$ apk policy ''package''}}

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
https://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community
</pre>

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/etc/config/apk|logfile no}}

== Advanced APK Usage ==

=== Commandline repository options ===

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:
{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

{{cmd|# apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|Repositories#Tagged repository}}

In certain cases, you may want to upgrade a system, but keep a specific package at a specific level or version by pinning a Package. It is possible to add "sticky" or versioned dependencies.

{{Warning| If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. Always pin to a package version that is intended for your [[Repositories#Release_Branches|release branch]]. Pinning to a version on the [[Repositories#Edge|edge]] branch may stop working after the package version is revoked from the repo.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# apk add 'asterisk>1.6.1'}}

You can also use "fuzzy" version matching to pin the version to a major/minor release. To match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) use the command: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

In case a package is pulled in yet is superfluous or unwanted, or if it were to be installed and conflict with another, one could ''mask'' it i.e. ''exclude it'' from being installed unless '''apk''' is later instructed ''explicitly'' to add it. To mask/exclude an unwanted package hypothetically called ''foo'':
{{Cmd|# apk add '!foo'}}
Beforehand, ensure that the '''''package is not installed'''''. If so, ''uninstall it first'', as otherwise, it would become an ''"orphaned package"'': installed, yet not being managed by the '''apk''' package keeper, which could cause an obfuscated problem(s) if it or its dependencies linger and later conflict with another package; it could be harder to trace the issue(s) then.

The exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/etc/apk/world}} where the package is negated. Be sure not to leave any spurious character.

=== Commit hooks ===

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1.
This is an example of a hook to do different things before and after commit:

{{cmd|1=#!/bin/sh

if [ "$1" = "pre-commit" ]; then
do_something

elif [ "$1" = "post-commit" ]; then
do_something_else
fi}}

Commit hooks are $PATH-aware, so for the sake of security it's recommended to specify absolute paths to executables.

== Rosetta Stone ==

[[Comparison with other distros#Comparison chart/Rosetta Stone|Rosetta Stone]] or a Comparison chart shows how standard things related to package management are done in Alpine Linux compared to other popular distributions.

== Troubleshooting ==

=== ERROR: unable to select packages ===

This error typically indicates that the package manager cannot find a suitable package to install. On issuing a command to add a package for eg: {{ic|# apk add labwc}}, you may receive below error message:
<Pre>
ERROR: unable to select packages:
labwc (no such package):
required by: world[labwc]
</Pre>

The above error indicates {{pkg|labwc}} does not exist in the [[Repositories|repositories]] currently configured in {{Path|/etc/apk/repositories}}. Ensure that <code>community</code> repository is [[Repositories#Managing_repositories|enabled]], as by default only <code>main</code> repository is enabled. You may also want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and the [[Repositories|repository]] in which the package is available.

<Pre>
ERROR: unable to select packages:
so:libxml2.so.2 (no such package):
required by: llvm19-libs-19.1.7-r1[so:libxml2.so.2]
</Pre>

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ rebuilt]. You may want to wait for some time to try again.

=== ERROR: unsatisfiable constraints ===

This error signifies a dependency conflict. It means that the package you're trying to install has dependencies that cannot be simultaneously satisfied within the current package repository.

You may want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and version and the [[Repositories|repository]] in which the package is available.

=== WARNING: This apk-tools is OLD! ===

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# apk add --upgrade apk-tools@edgemain}}

=== ERROR: UNTRUSTED signature ===

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:
{{Cmd|# apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|# apk fix --upgrade --allow-untrusted alpine-keys}}

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># apk add vim
ERROR: unable to select packages:
vim-common-9.1.1566-r0:
breaks: world[!vim-common]
satisfies: vim-9.1.1566-r0[vim-common=9.1.1566-r0]</nowiki>}}

When issuing package management commands, the above error will arise, if the command cannot be solved without breaking the [[#World|World]]. 

=== World updated but the following packages are not removed ===

On issuing a command to remove a package for eg: {{ic|# apk del btrfs-progs}}, you may receive below error message:
<Pre>
World updated, but the following packages are not removed due to:
btrfs-progs: btrbk
</Pre>

Here, the removal of package {{Pkg|btrfs-progs}} affects another package {{Pkg|btrbk}} in the constraints file [[#World|/etc/apk/world]]. So the package {{Pkg|btrfs-progs}} will be removed from the constraints file, but not removed from the system. The {{Pkg|btrfs-progs}} will remain in the system, until the constraint i.e {{Pkg|btrbk}} which depends on {{Pkg|btrfs-progs}} is removed.

If {{ic|apk del btrbk}} is issued, the package {{Pkg|btrfs-progs}} will be automatically removed from system as the constraint {{Pkg|btrfs-progs}} does not exist in {{Path|/etc/apk/world}}.

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html spelunking through the apk-tools dependency solver]
* [https://whynothugo.nl/journal/2023/02/18/in-praise-of-alpine-and-apk/ In praise of alpine and apk]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Steam

2026-02-15T06:02:33Z

John3-16: /* See also */ Added 'Gamescope'.

This page explains how to run [https://store.steampowered.com/about/ Steam], a popular game distribution platform by Valve on Alpine Linux. Steam requires glibc to run, and thus won't run natively on Alpine Linux. The simplest approach is to run it as [[Flatpak]]. Other workarounds involve using a virtual machine, a chroot or a container. It is theoretically possible to run the windows version of Steam using {{Pkg|wine}}.

== Installation via Flatpak ==

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Steam flatpak package from Flathub.{{Cmd|$ flatpak --user install com.valvesoftware.Steam}}
# After installation Steam can be started either using its .desktop file or from the command line: {{Cmd|$ flatpak run com.valvesoftware.Steam}}

== Troubleshooting ==

=== My controllers aren't detected ===

By default Steam doesn't have permission to read your controllers.
This can be fixed by installing an [[udev]] rule from the official Steam package, but the udev rules are also available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

These udev rules rely on the <code>TAG+="uaccess"</code>, and are therefore only expected to work reliably when using [[Elogind]].

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and {{path|~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log}} says that you are missing X server or <var>DISPLAY</var>, it means your <var>DISPLAY</var> is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

'''[[Sway]]''': Go into your sway config file and ensure that <var>DISPLAY</var> appears in the {{ic|dbus-update-activation environment}} line, as well as the [https://github.com/swaywm/sway/wiki#systemd-and-dbus-activation-environments others stated here], then restart:
<pre>exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME</pre>
For more information about this line, please see the [[Sway|Alpine Linux wiki entry]] on Sway

'''Hyprland''': Add an exec-once to the configuration file at {{path|~/.config/hypr/hyprland}} to set <var>DISPLAY</var>. Similarly to Sway you may already have a line that sets other variables. If so, add <var>DISPLAY</var> to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

== See Also ==
* [[Gaming on Alpine|Gaming on Alpine Linux]]
* [[Flatpak]]
* [https://github.com/ValveSoftware/gamescope Gamescope] - SteamOS session compositing window manager, available on Alpine Linux as {{Pkg|gamescope}}
* [https://wiki.postmarketos.org/wiki/Steam Steam on postmarketOS]

[[category:Gaming]]

Game development on Alpine Linux

2026-02-15T06:00:27Z

John3-16: Added 'Gaming' category.

This page documents the various software development libraries available in Alpine Linux from the perspective of developing games on Alpine Linux. Visit [[Gaming on Alpine]] page, if you are interested in knowing about various ways to play games in Alpine Linux.

== Learning curve ==

For programmers, it's strongly recommended that you use a [[#Game engines|game engine]] if you are starting video game programming which will handle most of the low level setup. If you have advanced knowledge in programming, you should see the [[#Multimedia libraries|multimedia section]] and [[#3D libraries|3D libraries]] section.

For artists, see [[#Tools used to work with or create art assets|Tools used to work with or create art assets]] section.

== Software libraries used in game development ==

=== Game engines ===

{| class="wikitable"
|-
! Name !! Package !! Description
|-
| [https://plib.sourceforge.net/ PLIB] || {{pkg|plib}} || game engine
|-
| [https://www.blender.org/ Blender] || {{pkg|blender}} || a 3D modeler and animator with a [https://upbge.org/ game engine]
|-
| [https://www.minetest.net/ Minetest] || {{pkg|minetest}} || both a game engine and a game
|-
| [https://love2d.org/ LÖVE] || {{pkg|love}} || 2D game engine using Lua and wrapping SDL
|}

=== Multimedia libraries ===

{| class="wikitable"
|-
! Name !! Package(s) !! Description
|-
| [https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer Simple DirectMedia Layer 2.0] || {{pkg|sdl2-dev}} || has input, audio, video, opengl, touch screen, game controller support
|-
| [https://en.wikipedia.org/wiki/Simple_and_Fast_Multimedia_Library SFML (Simple and Fast Multimedia Library)] || {{pkg|sfml-dev}} {{pkg|csfml-dev}} || has input, audio, video, networking, opengl support
|-
| [http://kcat.strangesoft.net/openal.html OpenAL Soft]{{dead link}} || {{pkg|openal-soft-dev}} || can be used for 3D sound for 3D games
|-
| [http://www.glfw.org/ GLFW] || {{pkg|glfw-dev}} || To create OpenGL context quickly with input support
|-
| [https://en.wikipedia.org/wiki/FreeGLUT FreeGLUT] || {{pkg|freeglut-dev}} || To create OpenGL context quickly with input support
|-
| [http://pyopengl.sourceforge.net/ PyOpenGL] || {{pkg|py3-opengl}} || OpenGL on Python
|-
| [https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer Simple DirectMedia Layer] || <code>sdl-dev</code> (dropped support for sdl 1.x . Use 2.0 instead) || has input, audio, video, joystick support
|}

=== 3D libraries ===

{| class="wikitable"
|-
! Name !! Package(s) !! Description
|-
| [https://glm.g-truc.net/0.9.8/index.html OpenGL Mathematics] || {{pkg|glm-dev}} || for 3D calculations to transform, rotate, scale stuff
|}

==== Rendering and loading assets ====

{| class="wikitable"
|-
! Name !! Package(s) !! Description
|-
| [https://en.wikipedia.org/wiki/OpenSceneGraph OpenSceneGraph] || {{pkg|openscenegraph-dev}} || can be used to load 3D models and handle complexities of rendering a 3d scene
|}

==== Fonts ====

{| class="wikitable"
|-
! Name !! Package(s) !! Description
|-
| [https://sourceforge.net/projects/ftgl/ FTGL] || {{pkg|ftgl-dev}} || to display text in OpenGL
|}

== Tools used to work with or create art assets ==

{| class="wikitable"
|-
! Name !! Package(s) !! Description
|-
| [https://en.wikipedia.org/wiki/GIMP GIMP] || {{pkg|gimp}} || edit 2D assets
|-
| [https://en.wikipedia.org/wiki/Audacity_(audio_editor) Audacity] || {{pkg|audacity}} || edit sound assets
|-
| [https://en.wikipedia.org/wiki/Inkscape Inkscape] || {{pkg|inkscape}} || edit vector 2D assets
|-
| [https://en.wikipedia.org/wiki/Blender_(software) Blender] || {{pkg|blender}} || edit 3D assets or models
|}
== See also ==

[[Category:Programming]]
[[Category:Gaming]]

Gamepad

2026-02-15T05:56:15Z

John3-16: Added /* See also */ section: Gaming on Alpine - Support Software section, 'qt5-qtgamepad' and 'razercfg'.

This article covers gamepads, joysticks and other game controllers.

== With [[Eudev|eudev]] ==

By default, only members of the <code>input</code> group can access gamepad and joystick devices. However, making users members of the <code>input</code> group has a negative security impact on which processes can obtain raw keyboard and mouse input.

To grant members of the <code>plugdev</code> group access to gamepads, create an udev rule. For example, {{Cat|/etc/udev/rules.d/90-joysticks.rules|<nowiki>
ACTION=="add", KERNEL=="js[0-9]*", SUBSYSTEM=="input", RUN+="/bin/chown root:plugdev /dev/input/js%n"</nowiki>}}

Reload all rules with

{{cmd|# udevadm control --reload}}

Then (re)connect the game controller.

== See also ==
* [[Gaming_on_Alpine#Support_Software|Gaming on Alpine - Support Software section]].
* {{Pkg|qt5-qtgamepad}} - Adds support to get events from gamepad devices.
* {{Pkg|razercfg}} - Razer mouse configuration tool.

[[Category:Hardware]]
[[Category:Gaming]]

Gaming on Alpine

2026-02-15T05:50:27Z

John3-16: /* See also */ 'obs-studio' syntax restored.

This page documents the various game-related packages that are available in Alpine Linux and lists alternative ways to game. If you are interested in developing games on Alpine Linux, visit [[Game development on Alpine Linux]].

== Installing Games ==

As when installing any other package, run the following:

{{Cmd|$ doas apk add <var>game</var>}}

Where <var>game</var> is the name of the package containing the game, such as {{Pkg|micro-tetris}} from among the [[#List of games|available games]].

== Steam ==
{{Main|Steam}}
Steam, a popular game distribution platform by Valve, can be run on Alpine Linux as a [[Flatpak]] or as this [https://github.com/ivan-hc/Steam-appimage AppImage].

== Wine ==

{{Pkg|wine}} enables a variety of Windows software to be run, including games, under Linux. If one is using x86_64 architecture, then 32-bit applications will run in Wine's ''WoW64'' mode, which may not be compatible with all software.

=== Wine inside docker ===

To run windows app/games inside a [https://www.reddit.com/r/linux4noobs/comments/1fegh0i/winealpine/ docker container] on Alpine Linux, {{pkg|libcap}} is required in order to fix issues related to [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ#failed-to-use-icmp-network-ping-this-requires-special-permissions raw sockets].

<Pre>
RUN apk add --no-cache libcap
RUN setcap cap_net_raw+epi /usr/bin/wine-preloader
</Pre>

== Permissions ==

To make sure that your user's account (<var>youruser</var>) is in the ''"games"'' group, first check whether the group is listed in <var>youruser</var>'s groups listing:

{{Cmd|$ id <var>youruser</var>}}

If ''"games"'' does not appear in the listing, then add the group to the user by executing the following:

{{Cmd|$ doas adduser <var>youruser</var> games}}

Log-off and then log back on in order for the changes to take effect. Most games do not require this in order to work.

== List of games ==

Below is a list of game packages that are available on Alpine Linux:-
{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| width="20%" |Game
|width="20%" | Package name
|| Description
|-
| [https://www.advancemame.it/ AdvanceMAME] || {{Pkg|advancemame}} || Arcade simulator.
|-
| [https://gitlab.gnome.org/GNOME/aisleriot Aisleriot] || {{Pkg|aisleriot}} || Solitaire card games.
|-
| [https://bsd-games.sourceforge.io/ bsd-games] || {{Pkg|bsd-games}} || Traditional text mode games from BSD.
|-
|[https://www.chocolate-doom.org/wiki/index.php/Chocolate_Doom Chocolate Doom] || {{Pkg|chocolate-doom}} || Portable release of Doom, Heretic, Hexen, and Strife.
|-
| [https://www.dosbox-staging.org/ DOSBox Staging] || {{Pkg|dosbox-staging}} || DOS-emulator that uses SDL.
|-
| [http://juzzlin.github.io/DustRacing2D/ Dust Racing 2D (dustrac)] || {{Pkg|dustracing2d}} || Traditional top-down car racing game including a level editor.
|-
| [http://www.flarerpg.org/ Flare (game)] || {{Pkg|flare-game}} || Fantasy action RPG using the FLARE engine (not to be confused with {{Pkg|flare}}, the unofficial Signal GTK client).
|-
| [https://www.flightgear.org/ FlightGear]|| {{Pkg|flightgear}} || Flight simulator.
|-
| [https://www.freeciv.org Freeciv]|| {{Pkg|freeciv}} || Free and Open Source empire-building strategy game.
|-
|[https://freedoom.github.io/ Freedoom]|| {{Pkg|freedoom}} || an entirely free software game running on a Doom engine.
|-
| [https://davidgriffith.gitlab.io/frotz/ Frotz] || {{Pkg|frotz}} || Z machine (Infocom interactive fiction) Interpreter.
|-
| [https://gcompris.net/index-en.html GCompris] || {{Pkg|gcompris-qt}} || Educational software suite comprising of numerous activities for children aged 2 to 10.
|-
| [https://www.gnu.org/software/chess/ GNU Chess]|| {{Pkg|gnuchess}} || Play chess against the computer.
|-
|[https://zdoom.org/index GZDoom] || {{Pkg|gzdoom}} || Modern game engine resembling modern FPSes compatible with Doom WADs
|-
| [https://gitlab.gnome.org/World/highscore Highscore] || {{Pkg|highscore}} || A 'rewrite' of Highscore, formerly known as gnome-games.
|-
| [https://apps.kde.org/kpat/ KPat (KPatience)] || {{Pkg|kpat}} || A selection of solitaire card games packaged by KDE.
|-
| [https://lgames.sourceforge.io/LBreakout2/ LBreakout2]|| {{Pkg|lbreakout2}} || Ball-and-paddle game.
|-
| [https://lgames.sourceforge.io/LBreakoutHD LBreakoutHD] || {{Pkg|lbreakouthd}} || {{Note|No level editor available.}}
The successor to LBreakout2.
{{Pkg|lbreakout2}} is needed for level creation.
|-
| [https://lgames.sourceforge.io/LPairs LPairs]|| {{Pkg|lpairs2}} || Classical memory game.
|-
| [https://www.luanti.org/ Luanti] || {{Pkg|luanti}} || An open source voxel game engine.
|-
| [https://github.com/troglobit/tetris Micro Tetris] || {{Pkg|micro-tetris}} || A version of Tetris that uses ANSI escape sequences and can fit in embedded devices.
|-
| [https://www.nethack.org NetHack] || {{Pkg|nethack}} || A single player Rogue-like dungeon crawler or dungeon exploration game.
|-
| [https://github.com/abakh/nbsdgames New BSD Games] || {{Pkg|nbsdgames}} || A package of 18 text-based modern games.
|-
| [https://openrct2.io/ OpenRCT2] || {{Pkg|openrct2}} || A free and open-source reimplementation of “RollerCoaster Tycoon 2”.
{{Note| Requires original files of “RollerCoaster Tycoon 2” to play.}}
|-
| [https://www.openttd.org/ OpenTTD]|| {{Pkg|openttd}} || A business simulation game.
|-
| [https://www.retroarch.com/ RetroArch] || {{Pkg|retroarch}} || Frontend for emulators, game engines, and media players using libretro.
|-
| [https://www.scummvm.org/ ScummVM]|| {{Pkg|scummvm}} || Engine for several graphical adventure games.
|-
| [https://www.chiark.greenend.org.uk/~sgtatham/puzzles/ Simon Tatham's Portable Puzzle Collection] || {{Pkg|sgt-puzzles}} || Small programs offering puzzle games for one player.
|-
| [https://www.supertux.org/ SuperTux] || {{Pkg|supertux}} || Classic 2D jump'n'run side-scroller game in a style similar to the original Super Mario games.
|-
|[https://supertuxkart.net/Main_Page SuperTuxKart] || {{pkg|supertuxkart}} || Kart racing game with OSS mascots.
|-
|[https://www.xonotic.org/ Xonotic] || {{Pkg|xonotic}} || The Free and Fast Arena Shooter.
Clients are: {{Pkg|xonotic-sdl}} or {{Pkg|xonotic-glx}}. Install {{Pkg|xonotic-server}} to run a dedicated server.
|}

== Support Software ==
{{Expand|Contributions/guidance encouraged – here or as new wiki pages. Thank you!}}{{Seealso|Gamepad}}
Available on Alpine Linux:-
* {{Pkg|game-devices-udev}} - Udev rules for various game controllers.
* {{Pkg|gamemode}} - Optimise Linux system performance on demand.
* {{Pkg|kodi-game-libretro*}} - Emulator add-ons for [[Kodi]] to enable older/retro games using the Libretro system.
* {{Pkg|libgnome-games-support}} - Code shared between GNOME games.
* {{Pkg|libkdegames}} - Common code and data for many KDE games.
* {{Pkg|py3-pygame}} - Python library for making applications and games based on SDL.
* {{Pkg|texlive-games}} - TeX Live games typesetting tools.
* {{Pkg|texmf-dist-games}} - Games typesetting using texmf-dist.

== See also ==

* [[Steam|Steam on Alpine Linux]]
* [https://wine.htmlvalidator.com/install-wine-on-alpine-linux-3.html How to Install Wine on Alpine Linux 3]
* [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ Wine FAQ]
* [https://obsproject.com/ OBS Studio] ({{Pkg|obs-studio}}) - Used by live streamers on streaming platforms such as YouTube and Twitch.
* [[Using Distrobox For VR Gaming]]

[[category:Gaming]]

Gaming on Alpine

2026-02-15T05:47:22Z

John3-16: 1. /*Permissions*/Added 'id' cli to check whether the user is in the games group; 2. /* List of games */ Added bsd-games, dustracing2d, flare-game, highscore, kpat, nbsdgames and sgt-puzzles; 3. Added /*Support Software*/ section with encouragement to expand it; 4. /* See also */ Promoted 'How to Install Wine on Alpine Linux 3' link; added Using Distrobox For VR Gaming; 5. Style/grammar amendments.

This page documents the various game-related packages that are available in Alpine Linux and lists alternative ways to game. If you are interested in developing games on Alpine Linux, visit [[Game development on Alpine Linux]].

== Installing Games ==

As when installing any other package, run the following:

{{Cmd|$ doas apk add <var>game</var>}}

Where <var>game</var> is the name of the package containing the game, such as {{Pkg|micro-tetris}} from among the [[#List of games|available games]].

== Steam ==
{{Main|Steam}}
Steam, a popular game distribution platform by Valve, can be run on Alpine Linux as a [[Flatpak]] or as this [https://github.com/ivan-hc/Steam-appimage AppImage].

== Wine ==

{{Pkg|wine}} enables a variety of Windows software to be run, including games, under Linux. If one is using x86_64 architecture, then 32-bit applications will run in Wine's ''WoW64'' mode, which may not be compatible with all software.

=== Wine inside docker ===

To run windows app/games inside a [https://www.reddit.com/r/linux4noobs/comments/1fegh0i/winealpine/ docker container] on Alpine Linux, {{pkg|libcap}} is required in order to fix issues related to [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ#failed-to-use-icmp-network-ping-this-requires-special-permissions raw sockets].

<Pre>
RUN apk add --no-cache libcap
RUN setcap cap_net_raw+epi /usr/bin/wine-preloader
</Pre>

== Permissions ==

To make sure that your user's account (<var>youruser</var>) is in the ''"games"'' group, first check whether the group is listed in <var>youruser</var>'s groups listing:

{{Cmd|$ id <var>youruser</var>}}

If ''"games"'' does not appear in the listing, then add the group to the user by executing the following:

{{Cmd|$ doas adduser <var>youruser</var> games}}

Log-off and then log back on in order for the changes to take effect. Most games do not require this in order to work.

== List of games ==

Below is a list of game packages that are available on Alpine Linux:-
{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| width="20%" |Game
|width="20%" | Package name
|| Description
|-
| [https://www.advancemame.it/ AdvanceMAME] || {{Pkg|advancemame}} || Arcade simulator.
|-
| [https://gitlab.gnome.org/GNOME/aisleriot Aisleriot] || {{Pkg|aisleriot}} || Solitaire card games.
|-
| [https://bsd-games.sourceforge.io/ bsd-games] || {{Pkg|bsd-games}} || Traditional text mode games from BSD.
|-
|[https://www.chocolate-doom.org/wiki/index.php/Chocolate_Doom Chocolate Doom] || {{Pkg|chocolate-doom}} || Portable release of Doom, Heretic, Hexen, and Strife.
|-
| [https://www.dosbox-staging.org/ DOSBox Staging] || {{Pkg|dosbox-staging}} || DOS-emulator that uses SDL.
|-
| [http://juzzlin.github.io/DustRacing2D/ Dust Racing 2D (dustrac)] || {{Pkg|dustracing2d}} || Traditional top-down car racing game including a level editor.
|-
| [http://www.flarerpg.org/ Flare (game)] || {{Pkg|flare-game}} || Fantasy action RPG using the FLARE engine (not to be confused with {{Pkg|flare}}, the unofficial Signal GTK client).
|-
| [https://www.flightgear.org/ FlightGear]|| {{Pkg|flightgear}} || Flight simulator.
|-
| [https://www.freeciv.org Freeciv]|| {{Pkg|freeciv}} || Free and Open Source empire-building strategy game.
|-
|[https://freedoom.github.io/ Freedoom]|| {{Pkg|freedoom}} || an entirely free software game running on a Doom engine.
|-
| [https://davidgriffith.gitlab.io/frotz/ Frotz] || {{Pkg|frotz}} || Z machine (Infocom interactive fiction) Interpreter.
|-
| [https://gcompris.net/index-en.html GCompris] || {{Pkg|gcompris-qt}} || Educational software suite comprising of numerous activities for children aged 2 to 10.
|-
| [https://www.gnu.org/software/chess/ GNU Chess]|| {{Pkg|gnuchess}} || Play chess against the computer.
|-
|[https://zdoom.org/index GZDoom] || {{Pkg|gzdoom}} || Modern game engine resembling modern FPSes compatible with Doom WADs
|-
| [https://gitlab.gnome.org/World/highscore Highscore] || {{Pkg|highscore}} || A 'rewrite' of Highscore, formerly known as gnome-games.
|-
| [https://apps.kde.org/kpat/ KPat (KPatience)] || {{Pkg|kpat}} || A selection of solitaire card games packaged by KDE.
|-
| [https://lgames.sourceforge.io/LBreakout2/ LBreakout2]|| {{Pkg|lbreakout2}} || Ball-and-paddle game.
|-
| [https://lgames.sourceforge.io/LBreakoutHD LBreakoutHD] || {{Pkg|lbreakouthd}} || {{Note|No level editor available.}}
The successor to LBreakout2.
{{Pkg|lbreakout2}} is needed for level creation.
|-
| [https://lgames.sourceforge.io/LPairs LPairs]|| {{Pkg|lpairs2}} || Classical memory game.
|-
| [https://www.luanti.org/ Luanti] || {{Pkg|luanti}} || An open source voxel game engine.
|-
| [https://github.com/troglobit/tetris Micro Tetris] || {{Pkg|micro-tetris}} || A version of Tetris that uses ANSI escape sequences and can fit in embedded devices.
|-
| [https://www.nethack.org NetHack] || {{Pkg|nethack}} || A single player Rogue-like dungeon crawler or dungeon exploration game.
|-
| [https://github.com/abakh/nbsdgames New BSD Games] || {{Pkg|nbsdgames}} || A package of 18 text-based modern games.
|-
| [https://openrct2.io/ OpenRCT2] || {{Pkg|openrct2}} || A free and open-source reimplementation of “RollerCoaster Tycoon 2”.
{{Note| Requires original files of “RollerCoaster Tycoon 2” to play.}}
|-
| [https://www.openttd.org/ OpenTTD]|| {{Pkg|openttd}} || A business simulation game.
|-
| [https://www.retroarch.com/ RetroArch] || {{Pkg|retroarch}} || Frontend for emulators, game engines, and media players using libretro.
|-
| [https://www.scummvm.org/ ScummVM]|| {{Pkg|scummvm}} || Engine for several graphical adventure games.
|-
| [https://www.chiark.greenend.org.uk/~sgtatham/puzzles/ Simon Tatham's Portable Puzzle Collection] || {{Pkg|sgt-puzzles}} || Small programs offering puzzle games for one player.
|-
| [https://www.supertux.org/ SuperTux] || {{Pkg|supertux}} || Classic 2D jump'n'run side-scroller game in a style similar to the original Super Mario games.
|-
|[https://supertuxkart.net/Main_Page SuperTuxKart] || {{pkg|supertuxkart}} || Kart racing game with OSS mascots.
|-
|[https://www.xonotic.org/ Xonotic] || {{Pkg|xonotic}} || The Free and Fast Arena Shooter.
Clients are: {{Pkg|xonotic-sdl}} or {{Pkg|xonotic-glx}}. Install {{Pkg|xonotic-server}} to run a dedicated server.
|}

== Support Software ==
{{Expand|Contributions/guidance encouraged – here or as new wiki pages. Thank you!}}{{Seealso|Gamepad}}
Available on Alpine Linux:-
* {{Pkg|game-devices-udev}} - Udev rules for various game controllers.
* {{Pkg|gamemode}} - Optimise Linux system performance on demand.
* {{Pkg|kodi-game-libretro*}} - Emulator add-ons for [[Kodi]] to enable older/retro games using the Libretro system.
* {{Pkg|libgnome-games-support}} - Code shared between GNOME games.
* {{Pkg|libkdegames}} - Common code and data for many KDE games.
* {{Pkg|py3-pygame}} - Python library for making applications and games based on SDL.
* {{Pkg|texlive-games}} - TeX Live games typesetting tools.
* {{Pkg|texmf-dist-games}} - Games typesetting using texmf-dist.

== See also ==

* [[Steam|Steam on Alpine Linux]]
* [https://wine.htmlvalidator.com/install-wine-on-alpine-linux-3.html How to Install Wine on Alpine Linux 3]
* [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ Wine FAQ]
* [https://obsproject.com/ OBS Studio] ({Pkg|obs-studio}}) - Used by live streamers on streaming platforms such as YouTube and Twitch.
* [[Using Distrobox For VR Gaming]]

[[category:Gaming]]

Display manager

2026-02-15T04:47:48Z

John3-16: 1. Added passage describing display managers as a subset of login managers, and elaborated on the latter; indicated not to mistake Greetd greeters as login managers; 2. Amended listings for both of these types of login managers, as agetty and greetd should not be listed as display managers; 3. Added getty as console login manager; 4. Added 'Configuration' section: 'PAM'; 5. Added 'See also' section: Elogind, Seatd, PAM, Setup-desktop, Getty howto; 6. Style/grammar amendments.

A [https://en.wikipedia.org/wiki/X_display_manager ''display manager (DM)''] presents the user with a login screen. A session starts when a user successfully enters a valid combination of username and password. It is typically a graphical user interface that is displayed at the end of the boot process in place of the default shell.

A ''basic login manager'' only handles basic console authentication: a prompt for username and password. This is what Alpine Linux displays when it is first run — the ''getty'' basic login manager, launched by inittab.

A ''full login manager'' would additionally provide:-
* Session type detection ({{ic|XDG_SESSION_TYPE}}) and automatic [[XDG_RUNTIME_DIR]] setup, possibly through '''elogind'''/'''seatd''' session managers (requires [[#PAM|PAM]] when using '''elogind''').
* A desktop environment selection for the session.
* Optional PAM integration - [[Display_manager#PAM|see PAM section below]].
* A graphical greeter may optionally be included.

''Display managers'' are a subset of full login managers that offer further features:-
* A graphical user interface (GUI) greeter, possibly with a choice of themes.
* Autologin, guest sessions and/or fast user switching.
* Wayland/X11 display server control.
* Remote login facility e.g. a [[Remote Desktop Server]] or the X-display manager's XDMCP protocol.

There also exist [[Greetd]] ''greeters'': user interface (UI) frontends (not to be mistaken for actual login managers) that run under the [[Greetd]] daemon login manager:-
* {{Pkg|greetd-agreety}} - Simple, text-based greeter (console UI).
* {{Pkg|greetd-tuigreet}} - A graphical, text-based user interface (TUI) console greeter for Greetd.

== List of Display Managers (Graphical Login Managers) ==

* [https://gitlab.gnome.org/GNOME/gdm GDM] ({{Pkg|gdm}}): [[GNOME]] display manager
* [https://github.com/canonical/lightdm LightDM] ({{Pkg|lightdm}}): Cross-desktop display manager
* [[SDDM]] ({{Pkg|sddm}}): Simple Desktop Display Manager. Recommended for [[KDE]] (Plasma) and [[LXQt]].
* [https://gitlab.freedesktop.org/xorg/app/xdm XDM] ({{Pkg|xdm}}): X Display Manager
* [[LXDM]] ({{Pkg|lxdm}}): A lightweight desktop login manager
* [[SLiM]] ({{Pkg|slim}}): Desktop-independent graphical login manager for X11 (abandoned since 2013)

== List of Non-Graphical or Daemon-Based Login Managers ==

=== Console ===

* [https://linuxvox.com/blog/linux-getty/ Getty login] - Part of the {{Pkg|util-linux}} package
* [[TTY_Autologin|Agetty]] ({{Pkg|agetty}}): Console-based login manager

=== Daemon ===

* [[greetd|Greetd]] ({{Pkg|greetd}}): Desktop-independent, lightweight login manager daemon

== Configuration ==

=== PAM ===
{{Main|PAM}}

PAM provides improved security, but it is not mandatory. It is recommended for advanced features, such as [[Configure OpenLDAP|LDAP]], 2-factor-authentification (2FA)/multi-factor-authentification (MFA) and session setup via [[elogind]].

Most login managers – including display managers – on Alpine Linux do not use PAM by default, in keeping with the operating system's minimalistic goal; those login managers would require manual setup of PAM:

* Basic login managers, such as '''getty''' or '''login''', authenticate directly with {{Path|/etc/passwd}} and {{Path|/etc/shadow}}.
* Display managers such as '''lightdm''', '''sddm''', plus the '''greetd''' login manager, support PAM, but they would need PAM to be installed and configured.

See Alpine Linux's [[PAM]] wiki page for further information.

== See also ==

* [[Elogind]] - Session and seat management integration.
* [[Seatd]] - An alternative to '''elogind''' for session and seat management.
* [[PAM]] - For advanced authentication and session configuration.
* [[Setup-desktop]] - Set up desktops and display managers automatically.
* [https://tldp.org/HOWTO/Text-Terminal-HOWTO-15.html Getty howto] - From the Linux Documentation Project ([https://tldp.org tldp.org]).

[[Category:Display Managers]]

Repositories

2026-02-03T23:57:01Z

John3-16: Style/grammar amendments; repos standardized to italics, as per majority use on this page, but preserving boldface in introductory instances.

{{TOC right}}

A [https://en.wikipedia.org/wiki/Software_repository repository] is a storage location with a collection of Alpine Linux [[Alpine Package Keeper#Packages and Repositories|packages]]. In addition to the three [[#Official repositories|official repositories]], technically, any directory with a collection of {{ic|*.apk}} files with a special index file named {{Path|APKINDEX.tar.gz}} can be considered a repository, albeit a personal repository. [[Alpine Package Keeper|Alpine Package Keeper ('''apk''')]] loads repository definitions from {{Path|/etc/apk/repositories}}, has sub-commands to query repositories, and maintains the desired system state as per [[Alpine_Package_Keeper#World|world]].

== Official repositories ==

There are three official package repositories available in Alpine Linux: [[#Main|main]], [[#Community|community]] and [[#Testing|testing]]. These repositories directly correspond to three directories of [[Aports tree|aports]].

=== Main ===

Packages in the '''main''' repository are the software that has direct support and updates from the Alpine core team. Alpine Linux tries to limit the amount of packages in ''main'' to only include essential base system packages i.e. those that are required to set up a minimal functional system, along with those packages' dependencies.

=== Community ===

Packages in the '''community''' repository are those made by users in team with the official developers and are close to the Alpine Linux packaging process. They are supported by those user(s) contributions, and support ends [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html#_repositories_releases_and_mirrors six months after their release]. They may also be removed in a future release due to lack of support by upstream authors or, rarely, if the user contribution(s) stop(s).

If packages from the ''community'' repository are used, one would need to upgrade that repo [[Upgrading_Alpine#Upgrading_to_latest_release|to the latest stable release branch]] to continue to have support.

=== Testing ===

The '''testing''' repository is only available on the [[#Edge|edge]] branch, i.e. the development branch, and this is where new packages go. These are made by any contributor to Alpine Linux. Packages from ''testing'' that are accepted go to the ''community'' repository or (more rarely) to the ''main'' repository. Packages in ''testing'' have no support (staging only) and are built only for the [[#Edge|edge]] branch.

== Release Branches ==

Each stable release branch of Alpine Linux has its own ''main'' and ''community'' repositories. The [https://alpinelinux.org/releases/ releases] page has information on all the release branches along with support status. Support entails security patches for the given feature versions.

'''The current stable release branch of Alpine Linux is {{#expr:{{AlpineLatest}}}}'''.

== Edge ==

'''Edge''' is the name given to the current [[Aports tree|development tree]] of Alpine Linux. The ''edge'' branch includes all three [[#Official repositories|official repositories]] and contains the latest build of all available Alpine Linux packages. Those packages are updated on a regular basis. Since ''edge'' is a development branch, many changes are not heavily tested (or tested at all), and packages can and sometimes do break without warning. ''edge'' can be considered as the '''rolling release version''' of Alpine Linux.

[[#Upgrading to edge|Upgrading to the ''edge'']] branch and installing packages from [[Repositories#Testing|''testing'']] repository, and then submitting '''[https://gitlab.alpinelinux.org/alpine/aports/issues bug reports]''' is one of the best ways to [[Contribute|contribute]] to Alpine Linux. This is a very valuable activity that helps Alpine Linux development, as it ensures that the quality of stable releases is high.

The currently installed ''edge'' version – i.e the build date that is attached to the ''edge'' release – may be checked with the command:{{Cmd|$ cat /etc/alpine-release}}
{{Warning|Do not use the [[#Edge|''edge'' branch]] in production nor if you desire deterministic, repeatable package installation (such as with containerized environments) via [[Alpine Package Keeper#Package pinning|package pinning]], as it is under constant development. Instead, use a [[#Release Branches|stable release branch]].}}

=== Message on /usr merge ===

''Edge'' currently issues a message encouraging users to install the {{pkg|merge-usr}} package that would update the base filesystem hierarchy. Consult the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html news release on /usr merge] for background information, including its rationale.

This is currently not a requirement but will be implemented in the future as part of standard system upgrade to a [[Upgrading_Alpine#Upgrading_to_latest_release|new release]], as mentioned in gitlab issue {{Issue|17624}}. You can disable this nag message by [[Alpine_Package_Keeper#Package_masking|masking]] the {{Pkg|usr-merge-nag}} package: {{Cmd|$ doas apk add '!usr-merge-nag'}}

{{Warning|If any error is reported upon trying a dry run by using {{ic|$ doas merge-usr --dryrun}}, do not proceed with the ''/usr merge'', as this would break your system. Instead, it would be appreciated if you could kindly submit a '''[https://gitlab.alpinelinux.org/alpine/aports/issues bug report]''' and provide all requested information when doing so.}}

== Managing repositories ==

The package repositories that '''apk''' uses to retrieve package files for installation are specified in the {{path|/etc/apk/repositories}} file. Each line in {{path|/etc/apk/repositories}} specifies the location of a package repository, one repository per line, and optionally with a [[#Tagged_repository|tag]]. Lines that start with a hash character (#) are there for comments or to disable a "repo" line (temporarily or not) and are ignored by '''apk'''.

The location may be an <code>http://</code> or <code>https://</code> URL, or the path to a directory on the local filesystem. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), then your repository file probably looks something like this: {{Cat|/etc/apk/repositories|/media/sda1/apks/}}

{{Tip|During [[installation]], only the [[#Main|''main'']] repository is enabled, so [[#Enabling the community repository|enable the ''community'' repository]] if required, as follows.}}

=== Enabling the community repository ===

The [[Alpine setup scripts#setup-apkrepos|setup-apkrepos]] script can be used to enable the [[#Community|''community'']] repository, as follows: {{cmd|# setup-apkrepos -c}}

With the above change, the {{path|/etc/apk/repositories}} file will look something like: {{cat|/etc/apk/repositories|#/media/cdrom/apks
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
http://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community}}

{{Note|For better security, you should probably change the urls from '''http''' to '''https'''. Some Alpine Linux package mirrors may not support '''https'''. If that is the case, you will need to change mirrors or revert back. You can check whether your mirror supports '''https''' on the [https://mirrors.alpinelinux.org official mirrors listing].}}

=== Tagged repository ===

A tagged repository is prefixed with the <code>@tag</code> specifier, followed by a space and the repository location in the {{Path|/etc/apk/repositories}} file, as follows.{{Cat|/etc/apk/repositories|https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
@personal https:/personal-repo.example.com/alpine-apks/}}

The optional <code>@tag</code> specifier, when used as shown above (<code>@personal</code>), indicates that the tagged repository should not be used by default: [[apk]] will by default only use the untagged repositories, but adding a package from an <code>@</code>-tagged repository will make '''apk''' prefer the tagged repository for the named package, even if a later version of the ''same package'' is available in another repository. It allows pulling in dependencies for the tagged package from the tagged repository, though it ''prefers to use untagged repositories to satisfy dependencies'' when possible.

For example, {{ic|apk add busybox@personal}} enables the selection of {{ic|busybox}} from a tagged repository named <code>@personal</code>. That command enables the installation of {{ic|busybox}} and its dependencies from the <code>@personal</code> tagged repository. Since tagged repositories are ''not'' prioritized, if a version of {{ic|busybox}}'s ''dependency'' from an untagged repository is a better fit, it will be used.

=== Upgrading to edge ===

Follow the instructions for [[Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge|Upgrading to Edge]].

When using edge branch, the [[Repositories#Testing|''testing'']] repository can be added as a [[Repositories#Tagged repository|tagged repository]]. Remember that packages in [[Repositories#Testing|''testing'']] repository have no support.

{{Warning|Do not enable ''main''/''community'' repositories from both the [[Repositories#Release Branches|'''stable''' release branch]] and from [[Repositories#Edge|'''edge''']] at the same time. This can break your system. Either use edge '''or''' stable. If you mix stable and edge repositories, you're on your own.}}

=== Using testing repository ===

Unlike [[#Edge|edge]] branch, installing packages from ''testing'' repository in a '''stable''' [[#Release Branches|release branch]] is not recommended and is not guaranteed to work. However, if you need a package that is only available in the [[#Testing|''testing'']] repository, add the ''testing'' repository as a [[#Tagged repository|tagged repository]] by editing the {{path|/etc/apk/repositories}} file as follows:{{Cat|/etc/apk/repositories|https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/main
https://dl-cdn.alpinelinux.org/alpine/v{{#expr:{{AlpineLatest}}}}/community
@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing}}

Before installing a package from the ''testing'' repository, [[Alpine_Package_Keeper#Check_Dependencies|check for dependencies]]. Installing a package from ''testing'' repository that depends on libraries in ''main'' or ''community'' often won't work due to a potential version mismatch. Alpine Linux does not officially support mixing branches this way, as mixing packages from stable and edge releases can break your system.

For example, with the command {{ic|# apk add wireguard-go@testing}}, the <code>@testing</code> tag allows [[apk]] to pull the necessary package(s) from the ''testing'' repository without potentially messing up your installation (too badly).

== See also ==

* [[Alpine_Package_Keeper|Alpine Package Keeper]]
* [[Alpine_Package_Keeper#World| The Alpine Linux world file]]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-repositories.5.scd Manual for apk-repositories(5)]
* [[Alpine Linux in a chroot]]
* [https://bugs.alpinelinux.org/ Report Bugs]

[[Category:Development]]
[[Category:Package Manager]]

Talk:Mumble

2026-02-02T04:26:20Z

John3-16: /* Mumble page created with contents of of Murmur page */ Thanks for the useful tip about moving page; how to find previous history, if required.

== Mumble page created with contents of of Murmur page ==
#Murmur was the old name for the {{Pkg|mumble-server}} package, and '''Mumble''' is the preferred naming of the joint client/server program upstream.
#Expanded Beginning section to describe distinction between the client and server.
#Updated "murmur" package and service to their renamed version: "mumble-server".
#Indicated that installing "murmur" will install "mumble-server" due to the "Provides" directive, etc.
#Added that Alpine Linux v3.21 and earlier still retain the original "murmur" package & service naming.
#Added that the {{Pkg|mumble-server-openrc}} package would be installed automatically on Alpine Linux's default openrc init installations
#Added command prompts and doas.
#Added ''See also'': [[Generating SSL certs with ACF]].
#Style/grammar amendments.
[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:55, 1 February 2026 (UTC)
: Dear [[User:John3-16|John3-16]], Thanks for updating the wiki. For examples like this Murmur->Mumble, you may want to consider '''moving a page''' instead of creating a new page as that will provide an option to preserve all the previous editing history. Moving a page will add also the redirect tag automatically. Thanks again for your contributions. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 04:02, 2 February 2026 (UTC)
::Thank you for your useful points, [[User:Prabuanand|Prabuanand]], which I hope to remember to apply next time. In case it could help users, in order to find the history of the original contents, users could search the wiki for "murmur", which will redirect to the "Mumble" page, and it will display a subheading: ''"(Redirected from [https://wiki.alpinelinux.org/w/index.php?title=Murmur&redirect=no Murmur])"''. By clicking on that Murmur link, users will find the Murmur page without a redirect, and then click on its [https://wiki.alpinelinux.org/w/index.php?title=Murmur&action=history history] link. Your approach would have quicker and preferable, thank you. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:26, 2 February 2026 (UTC)

Talk:Mumble

2026-02-01T04:55:11Z

John3-16: /* Mumble page created with contents of of Murmur page */ Moved and updated contents of Murmur page further to preferred naming upstream.

Murmur

2026-02-01T04:50:00Z

John3-16: Moved contents to new "Mumble" page, further to the preferred main program name (Mumble) upstream, including recent renaming of the murmur server to mumble-server See Talk:Mumble. Added redirect. Also: 1. "Mumble" wiki page had been referred to in the Beginning paragraph, but the page did not exist; 2. [https://wiki.mumble.info/wiki/Running_Murmur Murmur] was a broken link, but is now updated in the Mumble page; 3. mention of mumble.ini also needed updating, now named murmur.ini.

#REDIRECT [[Mumble]]

Mumble

2026-02-01T04:48:14Z

John3-16: 1. Created Mumble page by moving and updating contents of Murmur page, further to preferred and updated naming upstream; 2. Expanded Beginning to include client side; 3. Added 'See also'. See Talk:Mumble.

[https://www.mumble.info/ Mumble] is an open source, cross platform, low-latency, high quality voice over IP (VoIP) voice-chat program. It uses a client/server architecture and is primarily used by gamers, but can be used for any VoIP purpose:-
* {{Pkg|mumble}} (lowercase) is the client.
* {{Pkg|mumble-server}} is the server component. It was previously called [https://github.com/mumble-voip/mumble#mumble---open-source-voice-chat-software murmur] and still retains that package name and service name in Alpine Linux v3.21 and earlier.

== Installation ==
First of all, we need '''mumble-server'''. Its dependencies will be pulled in automatically, including {{Pkg|mumble-server-openrc}} on Alpine Linux installations where OpenRC has been conserved as the init system.

{{Cmd|$ doas apk add mumble-server}}

{{Note|
* On Alpine Linux 3.22 and above, installing '''murmur''' will install '''mumble-server''' thanks to the {{ic|Provides: murmur}} directive of {{Pkg|mumble-server}}, thus providing backward compatibility for the ''packages''.
* Thanks to the {{Pkg|murmur-compat}} subpackage of {{Pkg|mumble-server}} on Alpine Linux v3.22 and above, references to '''murmur''' there are recognized as '''mumble-server''' (via a symlink from {{Path|/etc/init.d/murmur}} pointing to {{Path|/etc/init.d/mumble-server}}), thus providing backward compatibility for the ''services''.}}

=== Setting up SSL certificates ===
If you already have used Certbot to set up certificates in your web server, then you can easily make a new certificate for a subdomain 'mumble' and add the cert paths to the {{Path|murmur.ini}} configuration file. You can use nano or vim, etc., to edit the file manually.
{{Cmd|$ doas nano /etc/murmur.ini}}
It should look something like this.
{{Cat|/etc/murmur.ini|<nowiki>
sslCert=/etc/letsencrypt/live/your_domain.com/fullchain.pem
sslKey=/etc/letsencrypt/live/your_domain.com/privkey.pem
</nowiki>
}}

== Running as a service ==

=== Configuration ===
Make sure that the following line is present in your {{Path|murmur.ini}}:
{{Cat|/etc/murmur.ini|<nowiki>
pidfile=/var/run/murmur/murmur.pid
</nowiki>
}}
This will allow OpenRC to track the status of the process.

=== Starting up the service ===
Start the '''mumble-server''' service.
{{Cmd|$ doas rc-service mumble-server start}}
You can add the '''mumble-server''' service to the default runlevel:
{{Cmd|$ doas rc-update add mumble-server default}}
In case at one point you don't want '''mumble-server''' to be on the default runlevel, rollback with this command:
{{Cmd|$ doas rc-update delete mumble-server default}}

== See also ==
* [[Generating SSL certs with ACF]] - Configuration of ''sslCert'' and ''sslKey''.

[[Category: telephony]]

Custom Kernel

2026-02-01T02:05:47Z

John3-16: "Work-in-progress" flag removed further to no objections; see Talk:Custom Kernel/Page ready for regular release?

This process of building a '''custom configured kernel''' assumes you are running on Alpine Linux utilizing abuild & aports.

== But why? ==

You want to build a custom kernel to enable experimental hardware or features or outdated hardware, to reduce bloat further, to tune the kernel to the hardware.

The lts kernel for most Alpine ARCHs uses defaults to balance throughput at the expense of some responsiveness, and support for many devices. You can tweak the kernel for desktop use and low latency and responsiveness.

You should disable modules to increase security. By default, Alpine will install modules but not disable most of them. Disabling modules will reduce an DMA attack but not eliminate it completely. If you have a newer processor with VT-d, you can mitigate as long as you:

Leave <code>CONFIG_INTEL_IOMMU_DEFAULT_ON=y</code> or pass <code>intel_iommu=on</code> as a kernel parameter and disable kernel logging so the attacker doesn't gain DMAR address information through dmesg.[https://blog.frizk.net/2016/11/disable-virtualization-based-security.html] Also remove references to the kernel version to calculate the IOMMU addresses.[https://link.springer.com/content/pdf/10.1186/s13173-017-0066-7.pdf]

You may also want to harden your kernel by adding at least some of the config changes recommended by <code>kernel-hardening-checker</code> [https://github.com/a13xp0p0v/kernel-hardening-checker/]

To increase the security of the boot process, if you have a TPM, you could set <code>CONFIG_INTEL_TXT=y</code> (Enable Intel(R) Trusted Execution Technology (Intel(R) TXT)) (which is not enabled in the hardened kernel by default), then you would need the SINIT module (provided only by Intel)[https://software.intel.com/en-us/articles/intel-trusted-execution-technology], a possibly compiled TrustedGrub2[https://github.com/Rohde-Schwarz-Cybersecurity/TrustedGRUB2], trousers[https://sourceforge.net/projects/trousers/?source=navbar], tboot[https://sourceforge.net/projects/tboot/]. These packages are not in aports and it is unknown if these tools work on musl. It's not recommended for Edge. Also, there would be trigger packages to generate hashes for the kernel and the mkinitfs updates.

== Setting up the Alpine Build System ==

First, you need to follow the steps in [[Creating_an_Alpine_package#Setup_your_system_and_account|Setup your system and account for building packages]]. You also need to configure your {{path|/etc/apk/repositories}} so that they search locally for your apks. See [[Creating_an_Alpine_package#Testing_the_package_locally|Testing the package locally]] for details.

After setting up accounts and repos, change your shell's current working directory to '''aports''' that you just cloned.

{{cmd|$ cd aports}}

== Working with aports ==

We will try using an existing lts kernel just tweaking the {{path|lts.ARCH.config}} file.

=== Switching to the proper release version ===

You need to switch to the proper branch that matches the release so that the kernel compiles against the dependencies properly.

{| cellpadding="5" border="1" class="wikitable"
|-
! Alpine version
! Remote branch
|-
| Edge
| master
|-
|{{#expr:{{AlpineLatest}}}}
|{{#expr:{{AlpineLatest}}}}-stable
|-
|}

The following is required to get access to the {{path|APKBUILD}} released for that version of Alpine and which you will create a commit for.

If you are on {{#expr:{{AlpineLatest}}}} do:

{{cmd|$ git checkout -b {{#expr:{{AlpineLatest}}}}-stable origin/{{#expr:{{AlpineLatest}}}}-stable}}

If you are on Edge do:

{{cmd|$ git checkout master}}

=== Creating your config ===

You can use {{pkg|linux-lts}} but what you should do is create a local branch by doing:

For <var>linux-lts</var> kernel on Alpine {{#expr:{{AlpineLatest}}}}:

{{cmd|$ git checkout -b my-custom-kernel origin/{{#expr:{{AlpineLatest}}}}-stable}}

For Alpine Edge:

{{cmd|$ git checkout -b my-custom-kernel}}

Doing it this way, you do less work in maintaining. All you need to do is keep ''master'' or ''{{#expr:{{AlpineLatest}}}}-stable'' in sync[https://help.github.com/articles/syncing-a-fork/][https://help.github.com/articles/configuring-a-remote-for-a-fork/] and merge any conflicts.

First switch to the branch by doing:{{cmd|$ git checkout my-custom-kernel}}
Then, you need to navigate to the {{path|main/linux-lts}} folder where you should see a APKBUILD and some config- files.

It is a good idea to use custom `FLAVOR` in order to change the name of your kernel and package (custom flavor or revision) so you newly build kernel will not override the existing linux-lts and it's modules. Flavor build will only use your config and omit files that are not for your cpu architectures or virt* configs.(Virt configs provide optimized kernel configurations for running Alpine as a guest in virtual machines.)
This will also speed up the process of applying kernel patches by applying it for your architecture only. (Obviously ARCH in the following example is whatever architecture x86, x86_64...you use.)

First make a copy of your ARCH config file:
<pre>
cp lts.x86_64.config lts-my_custom.x86_64.config
</pre>

Edit your custom config file and add your changes. When you are done with your edits you need to run checksum to update APKBUILD:

<code>FLAVOR=lts-my_custom abuild checksum</code>

Then commit your changes:

<code>git commit -a -m "Enabled these options ...."</code>

You do this so that git can keep your code separate from Alpine's and so your changes float forward between kernel updates.

== Adding custom patches ==

Custom patches should be added to ''sources=''.

After you added the URL, you need to produce a checksum by doing <code>abuild checksum</code>.

The custom patches may not be autopatched, due to being distributed as an archive or different patch level, so you need to define what to do with it in the prepare().

== Configuring kernel ==

There are multiple ways to prepare and change kernel config. The basic one is to just edit your custom config file. You can also attempt to create a config tailored for your currently running system and modules.

To create a kernel config based on your currently running PC, use:
<pre>
make localmodconfig
</pre>
This command reads your current kernel's configuration from /proc/config.gz (if available) or /boot/config-* and creates a .config file that includes only the modules currently loaded on your system. This results in a minimal configuration tailored to your hardware.
Alternatively, you can use:
<pre>make localyesconfig</pre>
This is similar to ''localmodconfig'', but instead of building features as modules (m), it builds them directly into the kernel (y), which can result in a larger kernel image but eliminates the need for separate module files.
Note: Before running either command, make sure you have all the hardware you want to support actively in use (USB devices plugged in, network cards active, etc.) so their modules are loaded and included in the configuration.

The alternative is to use the kernel configuration menu in the build-NAME folder, but before you do that you need to <code>sudo apk add {{pkg|ncurses-dev}}</code>

After you are done using the menu in the build-NAME folder by doing:

<pre>make menuconfig</pre>

You want to remove <code>ncurses-dev</code>. When you are done, it will be stored in ''.config'' which you need to again override the {{path|lts.ARCH.config}} file.

When you are done updating the {{path|config-NAME.ARCH}}, you need to update sums:
<pre>
abuild checksum
</pre>

The options in the kernel config are typically defaults. If your device is old, it may be set to n by default.

=== Vanilla targets and tuning ===

{|cellpadding="5" border="1" class="wikitable"
!ARCH
!Processor Type / CPU Selection / System Type
!Code Generation / Instruction Extensions
!Timer Frequency
!Preemption Model
!Bitness
|-
|s390x
|IBM zEnterprise 114 and 196
|IBM zBC12 and zEC12 (<code>-march=zEC12 -mtune=zEC12</code>)
|1000 Hz
|No Forced Preemption (Server)
|64
|-
|ppc64le
|Server processors
|POWER8 (<code>-mcpu=power8</code>), AltiVec (<code>-Wa,-maltivec</code> to assembler or <code>-maltivec -mabi=altivec</code>), VSX
|1000 HZ
|No Forced Preemption (Server)
|64
|-
|ppc
|
512x/52xx/6xx/7xx/74xx/82xx/83xx/86xx
* Apple PowerMac based machines
|AltiVec (<code>-Wa,-maltivec</code> to assembler or <code>-maltivec -mabi=altivec</code>) on >=74xx
|1000 HZ
|No Forced Preemption (Server)
|32
|-
|x86_64
|Generic-x86-64
|(-mtune=generic ; SIMD assembly modules enabled based on simple compile test and/or presence of CPU flag)
|1000 HZ
|Voluntary Kernel Preemption (Desktop)
|64
|-
|x86
|586/K5/5x86/6x86/6x86MX
|(-mtune=generic ; SIMD assembly modules enabled based on simple compile test and/or presence of CPU flag)
|1000 HZ
|Voluntary Kernel Preemption (Desktop)
|32
|-
|armv7
|
* ARMv7 based platforms (Cortex-A, PJ4, Scorpion, Krait)
* Freescale i.MX family -- Cortex A (i.MX51, i.MX53, i.MX6 Quad/DualLite, i.MX6 SoloLite, i.MX6 SoloX, i.MX6 UltraLite, i.MX7 Dual)
* Qualcomm -- (MSM8X60, MSM8960, MSM8974)
* Allwinner SoCs -- (A10 (sun4i), A10s / A13 (sun5i), A31 (sun6i), A20 (sun7i), sun8i Family, (sun9i))
* ARM Ldt Versatile Express family --
|Either <code>-march=armv7-a</code> or <code>-march=armv5t -Wa,-march=armv7-a</code> based on a compile test. <code>-mfpu=vfp</code>
|1000 Hz
|Voluntary Kernel Preemption (Desktop)
|32
|-
|aarch64
|
* Allwinner sunxi 64-bit SoC Family
* Broadcom BCM2835 family
* Marvell Berlin SoC Family
* ARMv8 based Samsung Exynos SoC family
* ARMv8 based Freescale Layerscape SoC family
* Hisilicon SoC Family
* Mediatek MT65xx & MT81xx ARMv8 SoC
* Marvell EBU SoC Family
* Qualcomm Platforms
* Rockchip Platforms
* AMD Seattle SoC Family
* Altera's Stratix 10 SoCFPGA Family
* NVIDIA Tegra SoC Family
* Spreadtrum SoC platform
* Cavium Inc. Thunder SoC Family
* ARMv8 software model (Versatile Express)
* AppliedMicro X-Gene SOC Family
* Xilinx ZynqMP Family
|
|1000 HZ
|Voluntary Kernel Preemption (Desktop)
|64
|-
|}
If you do desktop multitasking, you may want to switch to Voluntary Kernel Preemption (Desktop) or Preemptible Kernel (Low-Latency Desktop) and up the Timer Frequency. If you run a dedicated render farm node or a dedicated bitcoin miner use No Forced Preemption (Server) and decrease the Timer Frequency.

Optimized modules (most are already compiled as modules):
* raid6 -- altivec, avx512, ssse3, avx2, mmx, sse, sse2, neon
* some operations of raid5 -- mmx (32 bit), sse (64 bit), avx
For Kernel API:
* 32-bit memcpy -- 3dnow
* 32-bit memory page clearing and copying -- sse (Athlon/K7 only), mmx
From x86/crypto, arm/crypto, powerpc/crypto:
* CAMELLIA -- avx2, avx, aes-ni
* CHACHA20 -- avx2, neon
* CAST5 -- avx
* CAST6 -- avx
* TWOFISH -- avx
* SERPENT -- avx2, avx, sse2
* SHA1 -- avx2, ssse3, neon, spe
* SHA2 -- avx2
* SHA256 -- ssse3, neon, spe
* SHA512 -- avx2, ssse3, neon
* POLY1305 -- avx2
* GHASH -- pclmulqdq (part of aes-ni), vmx (power8)
* AES -- aes-ni, neon, vmx (power8), spe
* CRC32 -- pclmulqdq, sse, neon, vmx (power8)
* CRCT10DIF -- pclmulqdq, sse, neon, vmx (power8)

=== Fast reboots with kexec ===
{{main|kexec}}

If you want to reboot the kernel fast avoiding the POST test, you need {{ic|doas apk add {{pkg|kexec-tools}}}} and enable kexec in the kernel:

Processor type and features
[*] kexec system call

=== Hibernation to prevent data loss ===

Power management and ACPI options
[*] Hibernation (aka 'suspend to disk')

Hibernation should be used if you have a laptop. You don't want the laptop to suddenly shut off resulting in data loss, you want it to save your work based on a percentage of battery life (this requires special script). When hibernation resumes, should lock and ask for credentials. Depending on your needs, the hibernated image can be encrypted/decrypted which again requires additional customization to scripts.

Hibernation with an unsanitized swap file is generally insecure because data and unlocked memory pages are swapped out in plaintext. To increase the security either disable swap or use an encrypted swap. The swap file/partition is typically used as the hibernation resume image.

== Building ==

Before building, make sure you have ccache installed. This should reduce compile time on multiple builds.
You may also want to read up on compile flags - perhaps you want your build to be optimized for speed (or size which is the default).
Review <code>/etc/abuild.conf</code> and set:
<pre>
PACKAGER_PRIVKEY="/home/MY_USER_HERE/.abuild/my-email@mydomain.com-ID.rsa"
USE_CCACHE=1
</pre>
Please note that kernel build process may not use some of the settings you set in `abuild.conf` so in order to customize compiler or linker and/or it's flags you may need to edit APKBUILD.
If you have your config ready, first try building with:

<pre>
FLAVOR=lts-my_custom abuild -rK 2>&1 | tee build1.log
</pre>

This will install most of the dependencies and keep buildtime temp dirs and files (srcdir/pkgdir/deps).

If it complains about a dependency like {{pkg|elfutils-dev}} use <code>-rKd</code>.
Then, when it prompts for values for new found config options just hold enter till it starts compiling the kernel.
Unless you use <code>FLAVOR</code> or removed or commented out <code>virt.*.config</code> configs in APKBUILD there should be two sets one for -lts and the other for the -virt.
Just {{Key|Ctrl}}+{{Key|C}} out of the compilation process after
the second set so you can further customize the config.
Then you go into the {{path|src/linux-VER}} and edit the config file.
Copy the {{path|.config}} file overriding the {{path|lts.ARCH.config}} in the srcdir.

== Installing ==

If the build was successful the kernel packages are located in <code>~/packages/main/ARCH</code>
You probably already know how to install a package in your Alpine Linux...

== Testing ==

In case your new kernel may be missing a module and can't boot it is generally a good idea to keep the default <code>linux-lts</code>, so make sure you have it installed using the command: {{Cmd|# apk add {{pkg|linux-lts}}}}

Normally during the installation using with [[apk]], there are tools that will update initramfs and a boot loader automatically for you. For easier debugging you may want to change boot loader config and remove <code>quiet</code> from linux command line in {{Path|/etc/default/grub}} or {{Path|/etc/update-extlinux.conf}}.
Or perhaps you want to change other kernel options in {{Path|/etc/mkinitfs/mkinitfs.conf}}. Please remember to generate initramfs and update your bootloader manually, eg:
{{Cmd|<nowiki># mkinitfs
# grub-mkconfig -o /boot/grub/grub.cfg</nowiki>}}

In case something goes wrong with a boot process it is also a good idea to have a bootable rescue Alpine USB ready.

Once you have the default lts kernel and rescue USB <code>reboot</code> the computer.

If you are curious about correctness testing, some kernel modules or components do preform self tests at the beginning of the boot process. The tools may have test suites that you run with the make command.

== See Also ==
* [[Kernels]]
* [https://wiki.archlinux.org/title/Kernel Archwiki Kernels]
* [https://wiki.gentoo.org/wiki/Kernel Gentoo Wiki Kernel]
* [https://wiki.gentoo.org/wiki/Kernel/Configuration Gentoo Wiki Kernel Configuration]
* [[How to build the Alpine Linux kernel]]
* [[Kernel_live_patching|Kernel Live Patching (KLP)]]

[[Category:Kernel]]

Talk:Custom Kernel

2026-02-01T02:02:28Z

John3-16: /* Page ready for regular release? */ "Work-in-progress" flag removed further to no objections.

Needs to be adjusted for other archs

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Orson Teodoro|Orson Teodoro]] ([[User talk:Orson Teodoro|{{int:talkpagelinktext}}]] • [[Special:Contributions/Orson Teodoro|{{int:contribslink}}]]) 03:36, 4 March 2018‎

== Locations/paths of build config files ==

My goal is to build the Virt (not Standard/LTS) kernel using the defaults for Virt, and I don't understand which files are needed in exactly which paths.

I had difficulty understanding the excerpt below. Is anyone willing to assist me in understanding it? For example, where/what is the "linux-4.15" folder?

:''When you are done with your edits either by editing directly the APKBUILD and copying the lts.ARCH.config as .config in the linux-4.15 folder. You will then move the .config back overriding the lts.ARCH.config generated by make menuconfig.''

— Preceding [[Help:Signature|unsigned]] comment added by [[User:-anthumchris-|-anthumchris-]] ([[User talk:-anthumchris-|{{int:talkpagelinktext}}]] • [[Special:Contributions/-anthumchris-|{{int:contribslink}}]]) 17:34, 23 November 2024‎

== build_NAME ==

''After you are done using the menu in the build-NAME folder by doing make menuconfig''

It is really not clear what is meant by "the build-NAME folder" here.

== Locations/paths of build config files Answer ==

Usually these are the directories you would look for in linux-lts apk package development (replace "x86_64" with different $ARCH if needed) (replace $YOUR_WORK_DIR to which directory you downloaded aports to),

Below should contain <code>APKBUILD</code>, <code>lts.x86_64.config</code>, <code>virt.x86_64.config</code> and <code>.patch</code> files (and more $ARCH's by default, but to keep it simple, I will just state the x86_64 files)
{{cmd|$YOUR_WORK_DIR/aports/main/linux-lts}}

ALL <code>.patch</code> files that are in $YOUR_WORK_DIR/aports/main/linux-lts are also in below
{{cmd|$YOUR_WORK_DIR/aports/main/linux-lts/src}}

Below is a tar compressed linux file that decompresses into linux-$VERSION
{{cmd|$YOUR_WORK_DIR/aports/main/linux-lts/src/linux-$VERSION.tar.gz}}

{{cmd|$YOUR_WORK_DIR/aports/main/linux-lts/src/linux-$VERSION}}
{{cmd|$YOUR_WORK_DIR/aports/main/linux-lts/src/build-lts.x86_64}}
{{cmd|$YOUR_WORK_DIR/aports/main/linux-lts/src/build-virt.x86_64}}

In the "<code>APKBUILD</code>" file, change this "<code>source</code>" line to this:
{{cat|$YOUR_WORK_DIR/aports/main/linux-lts/APKBUILD|...
source{{=}}"https://cdn.kernel.org/pub/linux/kernel/v${pkgver%%.*}.x/linux-$_kernver.tar.xz
0001-powerpc-boot-wrapper-Add-z-notext-flag-for-ppc64le.patch
0002-x86-Compress-vmlinux-with-zstd-19-instead-of-22.patch
0003-kexec-add-kexec_load_disabled-boot-option.patch
0004-objtool-respect-AWK-setting.patch
0005-powerpc-config-defang-gcc-check-for-stack-protector-.patch

lts.x86_64.config

virt.x86_64.config
"
...}}

do <code>make menuconfig</code> within <code>$YOUR_WORK_DIR/aports/main/linux-lts/src/linux-$VERSION</code> and copy the .config file to <code>$YOUR_WORK_DIR/aports/main/linux-lts/lts.x86_64.config</code> and/or <code>$YOUR_WORK_DIR/aports/main/linux-lts/virt.x86_64.config</code>

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Pursuable1652|Pursuable1652]] ([[User talk:Pursuable1652|{{int:talkpagelinktext}}]] • [[Special:Contributions/Pursuable1652|{{int:contribslink}}]]) 16:55, 25 December 2024‎

== build_NAME Answer ==

''After you are done using the menu in the build-NAME folder by doing make menuconfig''

the "build-NAME" folder should actually be <code>$YOUR_WORK_DIR/aports/main/linux-lts/src/linux-$VERSION</code>

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Pursuable1652|Pursuable1652]] ([[User talk:Pursuable1652|{{int:talkpagelinktext}}]] • [[Special:Contributions/Pursuable1652|{{int:contribslink}}]]) 16:55, 25 December 2024‎

== Page ready for regular release? ==
Perhaps this [[Custom Kernel]] page is now ready for regular use, and the "This material is work-in-progress" banner can be removed, unless there is a shortcoming found. This draft state has held since it was helpfully created in 2014.
Thanks for kind updates by [[User:Prabuanand|Prabuanand]], [[User:Pawciobiel|Pawciobiel]], [[User:Teopp7|Teopp7]], [[User:Fossdd|Fossdd]], [[User:Anthumchris|Anthumchris]], [[User:Gsora|Gsora]], [[User:Zcrayfish|Zcrayfish]], [[User:Omni|Omni]], [[User:Nabbi|Nabbi]], [[User:Psykose|Psykose]], [[User:Egberts|Egberts]] and thanks also for kind contributions by others that have not been active on the wiki for over five years. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 19:22, 30 December 2025 (UTC)
:Further to one month without objections, having tagged recent contributors, the ''"Work-in-progress"'' flag is being removed. The contributor who kindly initiated this useful page duly placed the flag in the original [https://wiki.alpinelinux.org/w/index.php?title=Custom_Kernel&oldid=10201 draft version] in 2014 and last contributed to the wiki that year. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 02:02, 1 February 2026 (UTC)

Xen PCI Passthrough

2026-02-01T01:33:35Z

John3-16: Style/grammar amendments.

This guide is to show how to configure PCI Passthrough on Alpine Linux.

First, use ''lspci'' to find the PCI address of the device that you want to passthrough:
<pre>
node03:~# lspci
00:00.0 Host bridge: Intel Corporation Xeon E3-1200 Processor Family DRAM Controller (rev 09)
00:19.0 Ethernet controller: Intel Corporation 82579LM Gigabit Network Connection (rev 05)
00:1a.0 USB controller: Intel Corporation 6 Series/C200 Series Chipset Family USB Enhanced Host Controller #2 (rev 05)
00:1c.0 PCI bridge: Intel Corporation 6 Series/C200 Series Chipset Family PCI Express Root Port 1 (rev b5)
00:1c.4 PCI bridge: Intel Corporation 6 Series/C200 Series Chipset Family PCI Express Root Port 5 (rev b5)
00:1d.0 USB controller: Intel Corporation 6 Series/C200 Series Chipset Family USB Enhanced Host Controller #1 (rev 05)
00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev a5)
00:1f.0 ISA bridge: Intel Corporation C204 Chipset Family LPC Controller (rev 05)
00:1f.2 SATA controller: Intel Corporation 6 Series/C200 Series Chipset Family SATA AHCI Controller (rev 05)
00:1f.3 SMBus: Intel Corporation 6 Series/C200 Series Chipset Family SMBus Controller (rev 05)
01:00.0 Serial Attached SCSI controller: LSI Logic / Symbios Logic SAS2008 PCI-Express Fusion-MPT SAS-2 [Falcon] (rev 03)
02:00.0 Ethernet controller: Intel Corporation 82574L Gigabit Network Connection
03:03.0 VGA compatible controller: Matrox Electronics Systems Ltd. MGA G200eW WPCM450 (rev 0a)
</pre>

In this example, let's passthrough the SAS controller. So the address is ''01:00.0''.

Make sure that ''xen_pciback'' is in your {{Path|/etc/modules}}:
<pre>
node03:~# grep pciback /etc/modules
xen_pciback
</pre>

Edit {{Path|/etc/conf.d/xen-pci}} to add the device:
<pre>
node03:~# cat /etc/conf.d/xen-pci
# /etc/conf.d/xen-pci

# PCI devices that will be used by domUs
DEVICES="01:00.0"
</pre>

Add the ''xen-pci'' daemon to the default runlevel, and reboot:
<pre>
rc-update add xen-pci default
</pre>

After rebooting, you should be able to verify that the PCI device is using the pciback kernel module, and that it is visible to passthrough via ''xl'':
<pre>
node03:~# lspci -k | grep -A2 '01:00.0'
01:00.0 Serial Attached SCSI controller: LSI Logic / Symbios Logic SAS2008 PCI-Express Fusion-MPT SAS-2 [Falcon] (rev 03)
Subsystem: LSI Logic / Symbios Logic Device 3020
Kernel driver in use: pciback
node03:~# xl pci-assignable-list
0000:01:00.0
</pre>

Add the following line to your DomU's configuration file:
<pre>
pci = [ '01:00.0' ]
</pre>

====Known Issue with LSI Controllers====
As the kernel module for LSI controllers is built into the Alpine Linux initramfs, the real module is loaded before the pciback module can be assigned.
 You will need to blacklist the ''mpt2sas'' module in {{Path|/etc/modprobe.d/blacklist.conf}} and rebuild your initramfs:
<pre>
node03:~# grep sas /etc/modprobe.d/blacklist.conf
blacklist mpt2sas
node03:~# mkinitfs
==> initramfs: creating /boot/initramfs-grsec
11538 blocks
33641 blocks
</pre>

[[Category:Virtualization]]

Talk:Software management

2026-01-26T07:38:46Z

John3-16: /* AppImage */ Flatpaks prioritized over AppImages: subsection order restored further to testing.

Please add the following if pertinent:
https://github.com/sgerrand/alpine-pkg-glibc/

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Mekineer|Mekineer]] ([[User talk:Mekineer|{{int:talkpagelinktext}}]] • [[Special:Contributions/Mekineer|{{int:contribslink}}]]) 11:04, 26 February 2024‎
----

I thought about the MegaCli wrapper.
It should be possible to make it read the name it was called by and then launch the respective program
(i.e. symlink any to-be-wrapped command to /var/lib/glibcstuff ...)

that way you get along with one wrapper script and symlinks to it in /usr/bin.

Another thing I couldnt figure is if it's important to use all 32bit versions?

And the download links for archlinux are not working because they forward wget to an https url.
maybe this is some limitation in the default wget version. If i figure it out i'll do updates on this.

this is my /usr/bin/MegaCli now, using a minimal Debian install in /debian.

<nowiki>
#!/bin/bash

KEYS="kernel.grsecurity.chroot_caps kernel.grsecurity.chroot_deny_chmod \
kernel.grsecurity.chroot_deny_chroot kernel.grsecurity.chroot_deny_fchdir \
kernel.grsecurity.chroot_deny_mknod kernel.grsecurity.chroot_deny_mount \
kernel.grsecurity.chroot_deny_pivot kernel.grsecurity.chroot_deny_shmat \
kernel.grsecurity.chroot_deny_sysctl kernel.grsecurity.chroot_deny_unix \
kernel.grsecurity.chroot_enforce_chdir kernel.grsecurity.chroot_findtask \
kernel.grsecurity.chroot_restrict_nice"

for key in $KEYS ; do
sysctl -w ${key}=0 1>/dev/null
done

export CHROOT=/debian
user=$(whoami)
if [ "$user" != "root" ];then
echo "This script needs root access"
exit
fi
mount -t proc proc $CHROOT/proc/
mount --bind /dev/ $CHROOT/dev/
mount --bind /sys/ $CHROOT/sys/
#we may need dev and maybe proc too to use this program
chroot $CHROOT /opt/MegaRAID/MegaCli/MegaCli $@
umount $CHROOT/proc
umount $CHROOT/dev
umount $CHROOT/sys</nowiki>

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Darkfader|Darkfader]] ([[User talk:Darkfader|{{int:talkpagelinktext}}]] • [[Special:Contributions/Darkfader|{{int:contribslink}}]]) 15:32, 11 July 2014‎

----

If you know how to relax grsecurity without using vanilla on Gentoo to allow PAM to not trigger a postinst error, you should edit the Gentoo section.

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Orson Teodoro|Orson Teodoro]] ([[User talk:Orson Teodoro|{{int:talkpagelinktext}}]] • [[Special:Contributions/Orson Teodoro|{{int:contribslink}}]]) 13:12, 3 February 2018‎

I'm unsure, if it's OK to add the following to page: will leave it here for reference:
Here are the steps to run vscode, If running [[Sway]] on Alpine Linux.
# From your Alpine Linux host, download Visual Studio Code from the official website https://code.visualstudio.com/docs/?dv=linux64_deb to your home folder.
# Install the vscode as follows: {{Cmd|$ distrobox enter my-debian --sudo apt-get install -f /home/<Username>/code_<version_number>_amd64.deb}}
# Run vscode as follows: {{Cmd|<nowiki>$ distrobox enter my-debian -- code --ozone-platform=wayland</nowiki>}}
--[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 11:10, 2 June 2025 (UTC)

== AppImage ==

Dear [[User:John3-16|John3-16]], your [https://wiki.alpinelinux.org/w/index.php?title=Software_management&diff=prev&oldid=31876 edit] changed the preferred method of running glibc applications from [[Flatpak]] to [[AppImage]]. Flathub is a known repository with a lot of applications that is guaranteed to work in Alpine Linux. I'm not aware of an equivalent reliable i.e trusted source for AppImages that is guaranteed to work in Alpine Linux.
I tested a few from http://www.appimagehub.com and many did not work.

Please reconsider the above edit and consider restoring the Flatpak suggestion, until AppImages consistently work in Alpine Linux. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 13:43, 25 January 2026 (UTC)

:Thank you very much for comparing use, which is helpful. It's good to feed your useful point into the wiki about so many AppImages currently failing in Alpine Linux, assuming that you had applied the gcompat layer instruction. In view of your examination and feedback, the order of the subsections and the preference for flatpaks have been restored, as flatpaks would therefore work out easier to install in the long run despite AppImages taking fewer steps to install when they do work. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 07:38, 26 January 2026 (UTC)

Software management

2026-01-26T07:35:24Z

John3-16: Flatpaks prioritized over AppImages: subsection order restored further to testing – see Talk:Software_management#AppImage.

This page documents various ways to [[#Running glibc programs|run software compiled with glibc]] and to manage software using [[#Graphical software manager|graphical software managers]] in Alpine Linux. There are pages elsewhere regarding compiling [[Compile software from source|software from source]] and for creating a [[Custom Kernel|custom kernel]].

== Alpine package keeper ==
{{Main|Alpine Package Keeper}}
The official package manager in Alpine Linux, [[Alpine Package Keeper|Alpine Package Keeper(apk)]], is a ''cli'' tool. [[Comparison_with_other_distros#Comparison_chart/Rosetta_Stone|Rosetta stone]] shows how standard package management tasks are done in Alpine Linux compared to other popular distributions.

== Graphical software manager ==

The following graphical tools are available to manage official software packages from Alpine Linux [[Repositories|repositories]] and [[#Flatpak|flatpaks]] instead of using the [[#Alpine Package Keeper|cli-based apk tool]].

=== GNOME software ===

[[GNOME#Configuration|GNOME software]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

=== KDE Discover ===

[[KDE#Discover|KDE Discover]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

== Flatpak ==
{{Main|Flatpak}}

[[Flatpak#Installing_Flatpak|Flatpaks]] are by far the easiest method for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. To use flatpaks, ensure that the [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.

== AppImage ==
{{Main|AppImage}}

[[AppImage|AppImages]] are another alternative to [[Flatpak|flatpaks]] for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. However, not as many AppImages work on Alpine Linux as compared to Flatpaks, since AppImages are more commonly built for glibc operating systems, as opposed to Alpine Linux's use of musl.
Refer to the [[AppImage]] page for prerequisites and for detailed instructions to run AppImages in Alpine Linux.

== Coldbrew ==

'''Coldbrew''' is a package manager that can install Alpine Linux aports Edge packages without needing root access, somewhat similar to '''brew'''. This is particularly useful on immutable operating systems such as with [https://postmarketos.org/blog/2025/10/12/pmOS-update-2025-09/#immutable-postmarketos PostmarketOS's duranium image]. '''Coldbrew''' is available in Alpine Linux Edge testing repository as of January 2026; the testing repository is [[Repositories#Using_testing_repository|recommended to be tagged]] if installing '''coldbrew''' on any supported Alpine Linux release.

'''Coldbrew''' replaces the [https://github.com/kcxt/iced '''iced'''] package on Alpine Linux, which used the {{Pkg|mkosi-sandbox}}; packages run inside a chroot using '''bubblewrap''' instead. They have access to the home directory, but have only controlled access to all other files through explicit bind mounts. Packages installed using '''coldbrew''' are referred to as tools. See [https://gitlab.postmarketos.org/postmarketOS/coldbrew further details upstream].

To install '''coldbrew''':
{{Cmd|$ doas apk add coldbrew@testing}}

To install a tool to be run by '''coldbrew''', say, {{Pkg|corepad}}:
{{Cmd|$ coldbrew install corepad}}

Note that even though the output ends...

Installed binary /usr/bin/corepad

...the path being referred to exists within a new mount namespace using bind mounts in the '''bubblewrap''' sandbox.

A wrapper program is installed to {{Path|~/.local/bin}} on Alpine Linux.

To run the tool under '''coldbrew''':
{{Cmd|$ coldbrew run corepad}}

To remove the tool:
{{Cmd|$ coldbrew remove corepad}}

All installed tools can be listed through the {{ic|$ coldbrew ls}} command.

== Running glibc programs ==

If you want to run [https://www.gnu.org/software/libc/ glibc] programs in Alpine Linux, there are a few ways of doing so.

For simpler binaries, you can install [[#gcompat|gcompat]], which is a compatibility layer; or you could do it the easy way and use [[#Flatpak|Flatpaks]] or [[#AppImage|AppImages]]. See [[#Containers|containers]] or the [[#Chroot|chroot]] section for ways to run glibc programs, including graphical ones such as {{ic|VSCode}}, {{ic|google-chrome}}, {{ic|obsidian}}, etc.

=== gcompat ===

[https://git.adelielinux.org/adelie/gcompat gcompat] is a library that provides glibc-compatible APIs for use on musl libc systems such as Alpine Linux. To install, issue the command: {{cmd|$ doas apk add {{pkg|gcompat}}}}
After that, you run your binaries as normally.

For an usage example, refer to the [[Firefox#DRM_content_using_Widevine_workaround|Firefox]] page where gcompat is used to run the glibc-compiled Widevine binary.

== Chroot ==
{{Main|Chroot}}

An option that is easier to generalize to other glibc applications is to install a glibc-based distribution into a chroot. You can then either chroot into it, or use a symlink and some configuration to make its glibc (and associated libraries) usable from Alpine.

{{Tip|The most reliable way to enter a chroot is to use the [[Chroot#Enter_chroot|start-chroot]] script.}}

After setting up a chroot using any of the methods described below, the loader can be set up in Alpine as follows (these instructions are for a Debian chroot in {{Path|/var/chroots/debian}}, on x86_64, but can be adapted to other systems by using the appropriate paths):

{{cmd|$ doas mkdir -p /lib64
$ doas ln -s /var/chroots/debian/lib/x86_64-linux-gnu/ld-2.33.so /lib64
$ doas printf '/var/chroots/debian/lib/x86_64-linux-gnu\n/var/chroots/debian/usr/lib/x86_64-linux-gnu\n' > /etc/ld.so.conf
$ doas /var/chroots/debian/sbin/ldconfig}}

=== Gentoo Linux ===

Select a ''stage3'' from [https://www.gentoo.org/downloads/ here] and the ''portage'' latest from [https://www.gentoo.org/downloads/mirrors/ here] at gentoo/snapshots/portage-latest.tar.xz.

First,{{cmd|$ doas apk add {{pkg|xz}}}}

Enter the chroot:
{{cmd|$ doas mkdir ~/chroot
$ doas cd ~/chroot
$ doas tar -xvf stage3-*.tar.xz
$ doas tar -xvf portage-latest.tar.xz
$ doas mv portage usr
$ doas mount --bind /dev dev
$ doas mount --bind /sys sys
$ doas mount -t proc proc proc
$ doas cp /etc/resolv.conf etc
$ doas chroot . /bin/bash}}

And voilà, you have your working Gentoo chroot! 

You can now take a look at [https://wiki.gentoo.org/wiki/Handbook:Main_Page Gentoo's Handbook] to find out how you can configure and install your system, or simply extract/copy the program that you need to run in your chroot enviroment, and then execute it.

Here is a wrapper script that is similar to {{ic|arch-chroot}} when you frequently reuse this chroot. Also, create an account with the same username as host current user to the chroot, or make changes to the {{ic|userspec}} option to chroot line:

{{Cat|gentoo-chroot.sh|<nowiki>#!/bin/bash
CHROOT_PATH="/home/$USER/chroot"
cd $CHROOT_PATH
mount | grep $CHROOT_PATH/dev || doas mount --bind /dev dev
mount | grep $CHROOT_PATH/sys || doas mount --bind /sys sys
mount | grep $CHROOT_PATH/proc || doas mount -t proc proc proc
cp /etc/resolv.conf etc
doas chroot --userspec=$USER:users . /bin/bash
echo "You must manually unmount $CHROOT_PATH/dev, $CHROOT_PATH/sys, $CHROOT_PATH/proc."
</nowiki>
}}

Do {{ic|$ chmod +x gentoo-chroot.sh}} to make it executable.

=== Arch Linux ===

{{Seealso|Installing ArchLinux inside an Alpine chroot}}
Either use '''pacstrap''' (included with the arch-install-scripts package) or an Arch bootstrap image:

{{cmd|$ doas apk add {{pkg|arch-install-scripts}}
$ mkdir ~/chroot && cd ~/chroot
$ curl -O https://mirrors.edge.kernel.org/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.zst
$ doas tar -x --zstd -f archlinux-bootstrap-x86_64.tar.zst && rm archlinux-bootstrap-x86_64.tar.zst
$ doas sed -i '/evowise/s/^#//' root.x86_64/etc/pacman.d/mirrorlist
$ doas sed -i '/CheckSpace/s/^/#/' root.x86_64/etc/pacman.conf
$ doas arch-chroot root.x86_64
[chroot]# pacman-key --init
[chroot]# pacman-key --populate archlinux}}

Once that is done, update the system and install the desired package(s) (denoted by ''"foo"'' in this example):

{{cmd|[chroot]# pacman -Syu <var>foo</var>}}

=== Debian ===

Alpine Linux provides the {{pkg|debootstrap}} package to create the Debian chroot. Here are the steps: {{cmd|$ doas apk add debootstrap
$ doas mkdir -p /var/chroots/debian
$ doas debootstrap --arch amd64 stable /var/chroots/debian/ https://deb.debian.org/debian}}

The {{ic|--arch}} is optional, depending on your needs.

For updating the chroot, or for installing packages and their dependencies using {{ic|apt-get}}, mount it, and then login as root:
{{cmd|$ doas mount --bind /dev /var/chroots/debian/dev
$ doas mount --bind /proc /var/chroots/debian/proc
$ doas mount --bind /dev/pts /var/chroots/debian/dev/pts
$ doas chroot /var/chroots/debian /bin/bash
[chroot]# apt update && apt upgrade}}

After installing the necessary applications and whatever else you might do, exit the chroot:
{{cmd|[chroot]# exit}}

Then, unmount the binds for /dev/pts, dev and proc to avoid issues:
{{cmd|$ doas umount /var/chroots/debian/dev/pts
$ doas umount /var/chroots/debian/dev
$ doas umount /var/chroots/debian/proc}}

== Containers ==

=== Distrobox + Podman ===

[[Distrobox]], combined with [[Podman|podman]] container running in rootless mode, allows to easily run [[Distrobox#Running_graphical_programs|glibc-compiled graphical programs]]. This will not require root privileges once set up.

=== Bubblewrap + Chroot ===

{{ic|glibc}} and {{ic|glibcX11}} shell aliases are defined interactively using bwrap to create a container with [[Bubblewrap]], using a [[#Debian|Debian chroot]] as its content. It's not just a chroot anymore: it's a bubblewrap-powered isolated environment. This allows for easily running graphical programs and does not require root privileges once installed.

[[Install]] the {{pkg|bubblewrap}} package.

Set up [[#Debian|Debian chroot]] at {{path|/var/chroots/debian}} and install necessary glibc applications using {{ic|apt-get}}.

Create a {{ic|glibc}} alias using bwrap in the Alpine Linux host in order to start applications from the [[#Debian|Debian chroot]]:
{{cmd|$ alias glibc{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group"}}

To run programs that use X11/Xorg, you can use:
{{cmd|$ alias glibcX11{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group --bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X0 --setenv DISPLAY :0"}}

In this case, you might need to use {{ic|xhost}} on the Alpine Linux host in order to allow local connections. For example:{{cmd|# xhost + local:}}

Now we can invoke glibc-built binaries using the alias from the Alpine Linux host, as follows:
{{cmd|$ glibc ./binary}} or {{cmd|$ glibcX11 ./binary}}

When a [[Wayland]] desktop such as [[Sway]] runs without XWayland on the Alpine Linux host, Electron apps need to be started with Ozone Wayland support:

* For VS Code (note the use of the {{ic|code}} command):
{{cmd|<nowiki>glibc code --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

* For Google Chrome, etc:
{{cmd|<nowiki>glibc google-chrome --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

The flags enforce Wayland rendering, thus avoiding XWayland and improving display, particularly if fractional scaling is also used.

== See also ==

* [[Alpine Package Keeper]]
* [[Installing ArchLinux inside an Alpine chroot]]
* [[Compile software from source]]
* [[Kernels]]

[[Category:Package Manager]] [[Category:Development]]

Sshguard

2026-01-17T18:20:33Z

John3-16: Removed {{DISPLAYTITLE:SSHGuard}} as DISPLAYTITLE is not currently changing page title from Sshguard to SSHGuard (upstream name) - see discussion at Display title - amend to SSHGuard; otherwise, page appears under "Categories: Pages with ignored display titles".

[https://www.sshguard.net/ SSHGuard] protects hosts from brute-force attacks against SSH and other services. It aggregates system logs and blocks repeat offenders using one of several firewall backends, including '''iptables''' and '''nftables'''; SSHGuard also supports firewalls used elsewhere, including ipfw and pf.

SSHGuard can read log messages from standard input (suitable for piping from ''syslog'') or monitor one or more log files. Log messages are parsed, line-by-line, for recognized patterns. If an attack, such as several login failures within a few seconds, is detected, the offending IP is blocked. Offenders are unblocked after a set interval, but can be semi-permanently banned using the blacklist option.

SSHGuard does not support custom log parsing. Check the website upstream to see which services they support.

== Installation ==

SSHGuard can use several backends; you can see them listed with {{ic|$ ls /usr/libexec/sshg-fw*}}. The easiest backend on Alpine Linux is [[Nftables|nftables]], but a section is given below for [[Iptables]] also. After either firewall has been installed, install {{Pkg|sshguard}}:

{{Cmd|$ doas apk add sshguard}}

You will need to create the following configuration file or else SSHGuard won't start.

{{Cat|/etc/sshguard.conf|#!/bin/sh
BACKEND{{=}}'/usr/libexec/sshg-fw-nft-sets'
FILES{{=}}'/var/log/messages'
}}

== nftables backend ==

The nftables ruleset (tables and sets) required by SSHGuard are created dynamically with this SSHGuard daemon. You can view the rules that are active with:

{{ic|$ doas nft list ruleset}}

== iptables backend ==

To use the '''iptables''' backend, you must first create a chain called "sshguard". Enable the iptables-service to save the rules at shutdown and reload them when booting

{{Cmd|$ doas iptables -N sshguard
$ doas iptables -A INPUT -j sshguard
$ doas rc-update add iptables boot}}

You can view the rules with {{ic|$ doas iptables -L}}

[[category:Security]]

Bootloaders

2026-01-17T17:37:01Z

John3-16: 1. Added paragraph (following listing of bootloaders): gummiboot is deprecated; 2. /* See also */ Added Silent boot, otherwise an orphaned page; amended link descriptions; and updated denx.de/wiki/U-Boot/ReleaseCycle to redirect: https://docs.u-boot.org/en/latest/develop/release_cycle.html; 4. Amended styles/grammar.

A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux. 
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader. 
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader. 
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.

Note that {{pkg|gummiboot}} is a ''deprecated'' UEFI boot manager that was originally able to leverage UEFI firmware and detect bootable images such as Linux kernels that have an EFI stub on the EFI System Partition (ESP). The [https://cgit.freedesktop.org/gummiboot/ gummiboot project] was discontinued in 2015 and renamed as {{Pkg|systemd-boot}} for systemd systems and is only available in Alpine Linux in the [[Repositories#Testing|testing repository]]. As it had no runtime dependencies, '''gummiboot''' was appreciated for its simplicity as a lightweight, minimal UEFI boot solution. Its UEFI stub, {{pkg|gummiboot-efistub}}, was used [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|to generate a Unified Kernel Images (UKIs)]] e.g. for [[DM-verity]] and Secure Boot, but [[Release_Notes_for_Alpine_3.22.0#Secure_Boot_and_Gummiboot|it has been deprecated since Alpine Linux 3.22]] and is no longer maintained; it has been replaced by '''systemd-efistub''' (note that the latter package [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|only supplies EFI stub binaries]] and doesn’t depend on any systemd components).

== Syslinux ==

If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the {{pkg|syslinux}} package:

{{cmd|# apk add syslinux}}

If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}

Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.

{{cmd|# extlinux --install /boot}}

The configuration file is located in {{path|/boot/extlinux.conf}}.

Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.

You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory e.g. for dual booting.

=== Using EFI with syslinux ===

The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux.

Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:

{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}

You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).

In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
MENU DEFAULT
MENU LABEL Linux lts
LINUX /vmlinuz-lts
INITRD /initrd-lts
APPEND root=/dev/sda3 modules=sd-load,usb-storage,ext4 quiet
</nowiki>}}

Finally, add <code>syslinux</code> to the EFI boot menu. Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':

{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}

You can now verify that the boot entry has been added:

'''efibootmgr'''
<pre>
BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.

== GRUB ==

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.

{{cmd|# apk add grub-efi efibootmgr}}

Next, install the MBR and GRUB binaries to disk for BIOS mode:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

Then, add this line to {{path|/etc/default/grub}}:

{{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.

== EFI Boot Stub ==

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.

=== efibootmgr ===

Install {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

{{cat|add-bootentry|<nowiki>#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-stable}}, then replace <code>lts</code> with <code>stable</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can populate {{ic|$params}} from {{ic|/proc/cmdline}}. Make sure to append {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly-created entry as the default:

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> is the boot number of the new entry.

{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}. }}

== Using a UKI ==

'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI. While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the stable kernel, install the UKI into the default UEFI path.
if [ "$1" == "stable" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}

== See also ==
* [[Enable Serial Console on Boot]]
* [[Silent boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki - Bootloaders]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki - Boot loader]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki - Bootloaders]
* [https://docs.u-boot.org/en/latest/develop/release_cycle.html u-boot.org docs - U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Desktop environments and Window managers

2026-01-14T02:34:08Z

John3-16: 1. Added budgie* to list of desktop environments; 2. Added subsection /* Mobile/tablet UI */; moved sxmo* there from Desktop Environments listing

{{TOC right}}


'''Alpine Linux''' has no official desktop although setting up a graphical environment is proposed in the [[Installation#Post-Installation|post-installation]] guide. Alpine Linux desktops may meet the needs for ''general'' daily desktop use:-
* Fewer packages still require [https://www.gnu.org/software/libc/ glibc], as numerous popular applications are now available here on [https://musl.libc.org/ musl]: {{Pkg|libreoffice*}}, {{Pkg|chromium*}}, [[Firefox]], etc
* Several Alpine Linux desktop environments have been benchmarked to be competitive for both [https://everybytecounts.org/#desktop-environment-comparison speed and memory]
* Arguably, there is a reduced attack surface through the use of a comparatively lightweight '''musl''' and [[BusyBox]] system core

All window managers and desktop environments that are available in Alpine Linux are listed on this page. A quick installation using the [[Alpine_setup_scripts#setup-desktop|setup-desktop]] script is available for several [[Setup-desktop|desktops]].

{{Tip|For servers, consider using [[Alpine_Configuration_Framework_Design|Alpine Configuration Framework (ACF)]] for security considerations in that use case.}}

== Desktop environments ==

A ''desktop environment'' (DE) is made of a bundle of programs that share a common ''graphical user interface'' (GUI), sometimes described as a ''graphical shell''. A desktop environment typically consists of icons, windows, toolbars, folders, wallpapers and desktop widgets, and might also provide drag-and-drop functionality.

* {{Pkg|budgie*}}
* [[COSMIC]]
* [[GNOME]]
* [[KDE|KDE Plasma]]
* {{Pkg|lomiri*|arch=}}
* [[Lumina]]
* [[LXQt]]
* [[MATE]]
* [[Xfce]]

=== Mobile/tablet UI ===
Certain desktop environments have been ported for use as ''mobile user interfaces'' (UI) while other mobile/tablet UIs may have been developed using other existing unix toolkits. ''Convergent desktop environments'' are designed with a view to be consistent regardless of the platform used (pc, mobile, tablet, etc) such as the aforementioned '''lomiri''' environment.
* {{Pkg|phosh*}} - Wayland shell for GNOME on [https://phosh.mobi/ mobile devices].
* {{Pkg|plasma-mobile*}} - [https://plasma-mobile.org/ Mobile UI using a KDE Plasma foundation].
* {{Pkg|sxmo*}} - [https://sxmo.org/ Minimalist mobile Linux environment.]

== Window managers ==

A ''window manager'' is software that controls the placement and appearance of windows within a windowing system in a graphical user interface. In the case of [[Wayland]], these are called ''compositors'' because they additionally perform the task of a ''compositing window manager''.

Almost all components of a desktop need to be added manually by the user. Both [[Alpine_Linux:Glossary#S|stacking]] (a.k.a. ''floating'') and [[Alpine_Linux:Glossary#T|tiling]]/''dynamic'' layouts are commonly used for window management.

{|class="wikitable sortable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
! WM Name !! Protocol!! Style !! Toolkit!!class="unsortable"|Inspiration
|-
| {{Pkg|2bwm|arch=}} || X11 || Stacking || C/Roff
|| [https://www.hack.org/~mc/hacks/mcwm mcwm]
|-
| [[AwesomeWM|Awesome]] ||X11 || Tiling || Lua ||
|-
| {{Pkg|berry|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|bspwm|arch=}} || X11 || Tiling || C ||
|-
| {{Pkg|cage |arch=}} || Wayland || Kiosk || C/wlroots || {{Pkg|ratpoison|arch=}}
|-
| {{Pkg|cagebreak|arch=}} || Wayland || Tiling ||C/wlroots || {{Pkg|ratpoison|arch=}}, {{Pkg|cage|arch=}}
|-
| {{Pkg|compiz|arch=}} || X11 || Compositing || C++/C/Python ||
|-
| {{Pkg|cwm|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|dk|arch=}} || X11 || Tiling || C || {{Pkg|dwm|arch=}}, {{Pkg|bspwm|arch=}}, [https://xmonad.org/ xmonad]
|-
| {{Pkg|dwl|arch=}} || Wayland || Tiling || C/wlroots||[[dwm]]
|-
| [[dwm]] || X11 || Tiling || C ||
|-
| [[Fluxbox]] || X11 || Stacking || C++ || [https://sourceforge.net/projects/blackboxwm/ blackbox]
|-
| {{Pkg|flwm|arch=}} || X11 || Stacking || C++/FLTK || [https://all-day-breakfast.com/wm2/ wm2]
|-
| {{Pkg|gamescope|arch=}} || X11/Wayland || Compositing || C++/C/Lua ||
|-
| {{Pkg|goomwwm||-
| {{Pkg|icewm|arch=}} || X11 || Stacking || C++/C/M4 ||
arch=}} || X11 || Stacking || C/Roff ||
|-
| {{Pkg|herbstluftwm|arch=}} || X11 || Tiling || C++ ||
|-
| [[Hyprland]] || Wayland || Tiling || C++ ||
|-
| [[I3wm|i3]] || X11 || Tiling || C ||
|-
| {{Pkg|icewm|arch=}} || X11 || Stacking || C++/C/M4 ||
|-
| {{Pkg|jwm|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|kwin|arch=}} || X11/Wayland || Compositing || C++ ||
|-
| [[LabWC]] || Wayland || Stacking || C/wlroots||[[Openbox]]
|-
| {{Pkg|marco|arch=}} || X11 || Stacking || C || {{Pkg|metacity|arch=}}
|-
| {{Pkg|metacity|arch=kwin}} || X11 || Compositing || C ||
|-
| {{Pkg|mutter|arch=}} || X11/Wayland || Compositing || C ||
|-
| {{Pkg|mwm|arch=}} || X11 || Stacking || C ||
|-
| {{Pkg|niri|arch=}} || Wayland || Tiling || Rust/GLSL/other || [https://github.com/paperwm/PaperWM PaperWM]
|-
| [[Openbox]] || X11 || Stacking || C ||
|-
| {{Pkg|pekwm|arch=}} || X11 || Stacking || C++/CMake/Perl/C || [http://sapphire.sourceforge.net/ aewm++]
|-
| [[Qtile]] || X11/Wayland || Tiling || Python ||
|-
| {{Pkg|ratpoison|arch=}} || X11 || Kiosk || C ||
|-
| [[River|river-classic/River]] || Wayland || Tiling || Zig || [[dwm]], [https://xmonad.org/ xmonad]
|-
| {{Pkg|spectrwm |arch=}} || X11 || Tiling || C|| [https://xmonad.org/ xmonad], [[dwm]]
|-
| [[Sway]] || Wayland || Tiling || C/wlroots || [[I3wm|i3]]
|-
| {{Pkg|sxmo-dwm|arch=}} || X11 || Tiling || C || {{Pkg|dwm|arch=}}
|-
| [[twm]] || X11 || Tiling || C ||
|-
| {{Pkg|wayfire|arch=}} || Wayland || Stacking || C++/wlroots || {{Pkg|compiz|arch=}}
|-
| [[Weston]] || Wayland || Stacking || C ||
|-
| {{Pkg|windowmaker|arch=}} || X11 || Stacking || C/Shell/M4/Perl/Makefile/Emacs Lisp/other || NeXTSTEP
|-
| {{Pkg|xfwm4|arch=}} || X11 || Compositing || C/Makefile/Meson/other ||
|}

== See also ==
* [[Installation#Post-Installation|Post Installation]]
* [[Wayland]]
* [[Xorg]]
* [[Display manager]]
* [https://wiki.archlinux.org/title/Desktop_environment Desktop environment - Archwiki]
* [https://wiki.gentoo.org/wiki/Desktop_environment Desktop environment - Gentoo Wiki]

[[Category:Desktop]]
[[Category:Desktop Environments]]
[[Category:Window Managers]]
[[Category:Compositor]]

Setting up a SSH server

2026-01-10T20:39:25Z

John3-16: 1. /* Further Reading*/ Added: Remote Desktop Server; 2. Style/grammar amendments, including correcting header level styling.

== Overview ==

This article provides a short overview of SSH on Alpine Linux.

Also see [https://en.wikipedia.org/wiki/Secure_Shell Secure Shell (Wikipedia)].

{{Note|This article describes two popular SSH implementations: OpenSSH and Dropbear. Either can be installed using the [[Alpine setup scripts#setup-sshd|setup-sshd]] script, or by following the instructions below.}}

== OpenSSH ==

[https://www.openssh.com/ OpenSSH] is a popular SSH implementation for remote encrypted login to a machine. OpenSSH defines ''sshd'' as the daemon, and ''ssh'' as the client program.

The {{Pkg|openssh}} package provides OpenSSH on Alpine Linux.

=== Installation ===
Install the {{Pkg|openssh}} package:
{{Cmd|apk add openssh}}

{{Note|To use the ACF-frontend for openssh, install {{Pkg|acf-openssh}} instead (assuming that you have the setup-acf script).}}

Also see [[Alpine_Package_Keeper|Alpine Linux package management]].

=== Service commands ===
Enable the sshd service so that it starts at boot:
{{Cmd|rc-update add sshd}}

List services to verify sshd is enabled:
{{Cmd|rc-status}}

Start the sshd service immediately and create configuration files:
{{Cmd|rc-service sshd start}}

{{Note|If you are running from RAM, ensure you save your settings using the 'lbu ci' command as necessary. See [https://wiki.alpinelinux.org/wiki/Alpine_local_backup Alpine local backup].}}

Also see [[OpenRC|Alpine Linux Init System]].

=== Fine tuning ===

You may wish to change the default configuration. This section describes some of the configuration options as examples. However, this is by no means an exhaustive list. See [https://www.openssh.com/manual.html the manual] for full details.

The fine tuning is done by editing {{Path|/etc/ssh/sshd_config}}. Any line starting with "#" is ignored by ''sshd''.

UseDNS no # By setting this to no, connection speed can increase.
PasswordAuthentication no # Do not allow password authentication.

Other configuration options are shown in {{Path|etc/ssh/sshd_config}}. The file includes comments that explain many of the options.

=== Firewalling and Port Changes ===
By default, sshd will communicate on TCP port '''22'''. 

Sometimes '''22/tcp''' is blocked by a firewall over which you have no control. Changing the '''Port''' option to an unused port number in {{Path|/etc/ssh/sshd_config}} may be useful in this situation. 
Port 443 # Use whichever port number fits your needs

{{Note|Ensure the port you wish to use is not already in use by running '''netstat -lnp''' on the machine running ''sshd''.}}

Restart ''sshd'' after making modifications to the configuration file:
{{Cmd|rc-service sshd restart}}

{{Note|If you are running from RAM, ensure you save your settings using the 'lbu ci' command as necessary. See [https://wiki.alpinelinux.org/wiki/Alpine_local_backup Alpine local backup].}}

== Dropbear ==

[https://matt.ucc.asn.au/dropbear/dropbear.html Dropbear] is a lightweight SSH client/server alternative to OpenSSH.

=== Server ===
{{Tip|You can use {{Path|~/.ssh/authorized_keys}} in the same way as with OpenSSH.}}

{{Pkg|dropbear}} can be install through the [[Alpine setup scripts]], or manually with:
{{Cmd|apk add dropbear}}

Start it:
{{Cmd|rc-service dropbear start}}
Add it to the default runlevel:
{{Cmd|rc-update add dropbear}}

Use the following command to check all available server options:
{{Cmd|dropbear -h}}

The config file is located at {{Path|/etc/conf.d/dropbear}}

{{Tip|<code>DROPBEAR_OPTS{{=}}"-w -s"</code> will forbid root login and password login}}

=== Client ===
{{Pkg|dropbear-dbclient}} contains the SSH client and can be installed manually with:
{{Cmd|apk add dropbear-dbclient}}

In its simplest form, it can be used like this:
{{Cmd|dbclient <user>@host.example.com}}
{{Cmd|dbclient host.example.com}}
{{Cmd|dbclient x.x.x.x}} (where x.x.x.x is the IP address of the remote machine).

Use <code>dbclient -h</code> to see all available options.

== See also ==
* [[HOWTO OpenSSH 2FA with password and Google Authenticator|Two Factor Authentication With OpenSSH]]

== Further Reading ==

* [https://www.openssh.com/portable.html OpenSSH (openssh.com)] 
* [https://en.wikipedia.org/wiki/OpenSSH OpenSSH (wikipedia.org)]
* [[Remote Desktop Server]]

[[Category:Server]]
[[Category:Networking]]
[[Category:Security]]

Remote Desktop Server

2026-01-10T20:00:01Z

John3-16: 1. Consolidated note and instructions re xrdp and KDE under new subheading; 2. /* Remote Desktop Server based on Vino and xrdp */ Added: "Consider securing '''vino''' over SSH tunnels." 3. /* See also */ Added Setting up a SSH server, xrdp.org; 4. Style/grammar amendments, including standardizing xrdp to lower case, as per upstream.

These guides assume that the community repo [[Enable_Community_Repository|has been enabled]].

== Remote Desktop Server Based on xrdp and xorgxrdp ==

This was tested and works for v 3.17.2 with [[Xfce]] as the desktop.

First ensure that the desktop is working without remote access (if feasible).

Install {{Pkg|xrdp}} and {{Pkg|xorgxrdp}}:

{{Cmd|# apk add xrdp xorgxrdp}}

Start the necessary services:

{{Cmd|# rc-service xrdp start
# rc-service xrdp-sesman start}}

After testing that this works, you may set the services to start automatically:

{{Cmd|# rc-update add xrdp
# rc-update add xrdp-sesman}}

That should be all that is needed to connect from a Windows client with its default "Remote Desktop" client. The xrdp configuration file though will contain several services that will not work, so to remove them, edit {{Pkg|/etc/xrdp/xrdp.ini}} and remove all lines from, and including, {{ic|[Xvnc]}} to the end.

=== xrdp and KDE ===

On Alpine Linux Edge and from v3.22 onwards, xrdp is broken in combination with KDE because the latter only supports Wayland on versions released [[Release_Notes_for_Alpine_3.22.0| since then]].

On an earlier Alpine Linux release, if you are using KDE, please create a link as follows so that there is no screen after logging in:
{{Cmd|$ ln -s /usr/bin/startplasma-x11 ~/.xinitrc}}

{{ic|doas}} should only be used for that command if {{Path|~/.xinitrc}} is owned by root or by another user, but that would be atypical for a user-specific configuration.

== Remote Desktop Server based on Vino and xrdp ==

'''THIS DOES NOT WORK on 3.17.2 with Xfce - Not Yet Deleted in Case it helps others'''

First of all, make sure that you have a desktop environment properly installed (See: [[Desktop environments and Window managers]]).

Next, install {{Pkg|vino}} and {{Pkg|xrdp}} with the following command:

{{Cmd|# apk add vino xrdp}}

Replace the {{Path|/etc/xrdp/xrdp.ini}} file's content with:

{{Cat|/etc/xrdp/xrdp.ini|<nowiki>[globals]
bitmap_cache=yes
bitmap_compression=yes
port=3389
crypt_level=low
channel_code=1
max_bpp=24

[xrdp1]
name=Vino
lib=libvnc.so
ip=127.0.0.1
port=5900
username=ask
password=ask</nowiki>}}

Consider securing '''vino''' over [[Setting_up_a_SSH_server|SSH tunnels]].

If you want the xrdp service to start automatically, add the services to the default runlevel:

{{Cmd|# rc-update add xrdp
# rc-update add xrdp-sesman
# rc-update add vino}}

To start:

{{Cmd|# rc-service xrdp start
# rc-service xrdp-sesman start
# rc-service vino start}}

=== Misc ===

==== Disabling xrdp Notification and Confirmation ====

If you do not want the client confirmation before the session being accepted:

<code>export DISPLAY=:0.0</code>

{{Cmd|gsettings set org.gnome.Vino notify-on-connect false
gsettings set org.gnome.Vino prompt-enabled false
}}

== X11vnc ==

{{Main|X11vnc}}
[[X11vnc]] enables connection to the active X11 session, so one sees what is on the physical display, to include login screens and onscreen applications. Unlike certain VNC servers that launch a virtual desktop, it does not create an additional X session and is therefore leaner.

== Remmina as client ==

{{Draft}}
Remmina is a remote desktop client that can connect to servers such as x11vnc, xrdp, and Windows RDP.

== See also ==

* [[Setting_up_a_SSH_server|Setting up a SSH server]]
* [https://www.xrdp.org xrdp]

[[Category:System Administration]]
[[Category:Security]]

Software management

2026-01-09T20:07:05Z

John3-16: /* Coldbrew */ Amended "$ coldbrew list" as "$ coldbrew ls"

This page documents various ways to [[#Running glibc programs|run software compiled with glibc]] and to manage software using [[#Graphical software manager|graphical software managers]] in Alpine Linux. There are pages elsewhere regarding compiling [[Compile software from source|software from source]] and for creating a [[Custom Kernel|custom kernel]].

== Alpine package keeper ==
{{Main|Alpine Package Keeper}}
The official package manager in Alpine Linux, [[Alpine Package Keeper|Alpine Package Keeper(apk)]], is a ''cli'' tool. [[Comparison_with_other_distros#Comparison_chart/Rosetta_Stone|Rosetta stone]] shows how standard package management tasks are done in Alpine Linux compared to other popular distributions.

== Graphical software manager ==

The following graphical tools are available to manage official software packages from Alpine Linux [[Repositories|repositories]] and [[#Flatpak|flatpaks]] instead of using the [[#Alpine Package Keeper|cli-based apk tool]].

=== GNOME software ===

[[GNOME#Configuration|GNOME software]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

=== KDE Discover ===

[[KDE#Discover|KDE Discover]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

== AppImage ==
{{Main|AppImage}}

AppImages are by far the easiest method for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. Refer to the [[AppImage]] page for prerequisites and for detailed instructions to run them in Alpine Linux.

== Flatpak ==
{{Main|Flatpak}}

[[Flatpak#Installing_Flatpak|Flatpak]] is an alternative to [[AppImage|AppImages]] for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. To use flatpaks, ensure that the [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.

== Coldbrew ==

'''Coldbrew''' is a package manager that can install Alpine Linux aports Edge packages without needing root access, somewhat similar to '''brew'''. This is particularly useful on immutable operating systems such as with [https://postmarketos.org/blog/2025/10/12/pmOS-update-2025-09/#immutable-postmarketos PostmarketOS's duranium image]. '''Coldbrew''' is available in Alpine Linux Edge testing repository as of January 2026; the testing repository is [[Repositories#Using_testing_repository|recommended to be tagged]] if installing '''coldbrew''' on any supported Alpine Linux release.

'''Coldbrew''' replaces the [https://github.com/kcxt/iced '''iced'''] package on Alpine Linux, which used the {{Pkg|mkosi-sandbox}}; packages run inside a chroot using '''bubblewrap''' instead. They have access to the home directory, but have only controlled access to all other files through explicit bind mounts. Packages installed using '''coldbrew''' are referred to as tools. See [https://gitlab.postmarketos.org/postmarketOS/coldbrew further details upstream].

To install '''coldbrew''':
{{Cmd|$ doas apk add coldbrew@testing}}

To install a tool to be run by '''coldbrew''', say, {{Pkg|corepad}}:
{{Cmd|$ coldbrew install corepad}}

Note that even though the output ends...

Installed binary /usr/bin/corepad

...the path being referred to exists within a new mount namespace using bind mounts in the '''bubblewrap''' sandbox.

A wrapper program is installed to {{Path|~/.local/bin}} on Alpine Linux.

To run the tool under '''coldbrew''':
{{Cmd|$ coldbrew run corepad}}

To remove the tool:
{{Cmd|$ coldbrew remove corepad}}

All installed tools can be listed through the {{ic|$ coldbrew ls}} command.

== Running glibc programs ==

If you want to run [https://www.gnu.org/software/libc/ glibc] programs in Alpine Linux, there are a few ways of doing so.

For simpler binaries, you can install [[#gcompat|gcompat]], which is a compatibility layer; or you could do it the easy way and use [[#Flatpak|Flatpaks]] or [[#AppImage|AppImages]]. See [[#Containers|containers]] or the [[#Chroot|chroot]] section for ways to run glibc programs, including graphical ones such as {{ic|VSCode}}, {{ic|google-chrome}}, {{ic|obsidian}}, etc.

=== gcompat ===

[https://git.adelielinux.org/adelie/gcompat gcompat] is a library that provides glibc-compatible APIs for use on musl libc systems such as Alpine Linux. To install, issue the command: {{cmd|$ doas apk add {{pkg|gcompat}}}}
After that, you run your binaries as normally.

For an usage example, refer to the [[Firefox#DRM_content_using_Widevine_workaround|Firefox]] page where gcompat is used to run the glibc-compiled Widevine binary.

== Chroot ==
{{Main|Chroot}}

An option that is easier to generalize to other glibc applications is to install a glibc-based distribution into a chroot. You can then either chroot into it, or use a symlink and some configuration to make its glibc (and associated libraries) usable from Alpine.

{{Tip|The most reliable way to enter a chroot is to use the [[Chroot#Enter_chroot|start-chroot]] script.}}

After setting up a chroot using any of the methods described below, the loader can be set up in Alpine as follows (these instructions are for a Debian chroot in {{Path|/var/chroots/debian}}, on x86_64, but can be adapted to other systems by using the appropriate paths):

{{cmd|$ doas mkdir -p /lib64
$ doas ln -s /var/chroots/debian/lib/x86_64-linux-gnu/ld-2.33.so /lib64
$ doas printf '/var/chroots/debian/lib/x86_64-linux-gnu\n/var/chroots/debian/usr/lib/x86_64-linux-gnu\n' > /etc/ld.so.conf
$ doas /var/chroots/debian/sbin/ldconfig}}

=== Gentoo Linux ===

Select a ''stage3'' from [https://www.gentoo.org/downloads/ here] and the ''portage'' latest from [https://www.gentoo.org/downloads/mirrors/ here] at gentoo/snapshots/portage-latest.tar.xz.

First,{{cmd|$ doas apk add {{pkg|xz}}}}

Enter the chroot:
{{cmd|$ doas mkdir ~/chroot
$ doas cd ~/chroot
$ doas tar -xvf stage3-*.tar.xz
$ doas tar -xvf portage-latest.tar.xz
$ doas mv portage usr
$ doas mount --bind /dev dev
$ doas mount --bind /sys sys
$ doas mount -t proc proc proc
$ doas cp /etc/resolv.conf etc
$ doas chroot . /bin/bash}}

And voilà, you have your working Gentoo chroot! 

You can now take a look at [https://wiki.gentoo.org/wiki/Handbook:Main_Page Gentoo's Handbook] to find out how you can configure and install your system, or simply extract/copy the program that you need to run in your chroot enviroment, and then execute it.

Here is a wrapper script that is similar to {{ic|arch-chroot}} when you frequently reuse this chroot. Also, create an account with the same username as host current user to the chroot, or make changes to the {{ic|userspec}} option to chroot line:

{{Cat|gentoo-chroot.sh|<nowiki>#!/bin/bash
CHROOT_PATH="/home/$USER/chroot"
cd $CHROOT_PATH
mount | grep $CHROOT_PATH/dev || doas mount --bind /dev dev
mount | grep $CHROOT_PATH/sys || doas mount --bind /sys sys
mount | grep $CHROOT_PATH/proc || doas mount -t proc proc proc
cp /etc/resolv.conf etc
doas chroot --userspec=$USER:users . /bin/bash
echo "You must manually unmount $CHROOT_PATH/dev, $CHROOT_PATH/sys, $CHROOT_PATH/proc."
</nowiki>
}}

Do {{ic|$ chmod +x gentoo-chroot.sh}} to make it executable.

=== Arch Linux ===

{{Seealso|Installing ArchLinux inside an Alpine chroot}}
Either use '''pacstrap''' (included with the arch-install-scripts package) or an Arch bootstrap image:

{{cmd|$ doas apk add {{pkg|arch-install-scripts}}
$ mkdir ~/chroot && cd ~/chroot
$ curl -O https://mirrors.edge.kernel.org/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.zst
$ doas tar -x --zstd -f archlinux-bootstrap-x86_64.tar.zst && rm archlinux-bootstrap-x86_64.tar.zst
$ doas sed -i '/evowise/s/^#//' root.x86_64/etc/pacman.d/mirrorlist
$ doas sed -i '/CheckSpace/s/^/#/' root.x86_64/etc/pacman.conf
$ doas arch-chroot root.x86_64
[chroot]# pacman-key --init
[chroot]# pacman-key --populate archlinux}}

Once that is done, update the system and install the desired package(s) (denoted by ''"foo"'' in this example):

{{cmd|[chroot]# pacman -Syu <var>foo</var>}}

=== Debian ===

Alpine Linux provides the {{pkg|debootstrap}} package to create the Debian chroot. Here are the steps: {{cmd|$ doas apk add debootstrap
$ doas mkdir -p /var/chroots/debian
$ doas debootstrap --arch amd64 stable /var/chroots/debian/ https://deb.debian.org/debian}}

The {{ic|--arch}} is optional, depending on your needs.

For updating the chroot, or for installing packages and their dependencies using {{ic|apt-get}}, mount it, and then login as root:
{{cmd|$ doas mount --bind /dev /var/chroots/debian/dev
$ doas mount --bind /proc /var/chroots/debian/proc
$ doas mount --bind /dev/pts /var/chroots/debian/dev/pts
$ doas chroot /var/chroots/debian /bin/bash
[chroot]# apt update && apt upgrade}}

After installing the necessary applications and whatever else you might do, exit the chroot:
{{cmd|[chroot]# exit}}

Then, unmount the binds for /dev/pts, dev and proc to avoid issues:
{{cmd|$ doas umount /var/chroots/debian/dev/pts
$ doas umount /var/chroots/debian/dev
$ doas umount /var/chroots/debian/proc}}

== Containers ==

=== Distrobox + Podman ===

[[Distrobox]], combined with [[Podman|podman]] container running in rootless mode, allows to easily run [[Distrobox#Running_graphical_programs|glibc-compiled graphical programs]]. This will not require root privileges once set up.

=== Bubblewrap + Chroot ===

{{ic|glibc}} and {{ic|glibcX11}} shell aliases are defined interactively using bwrap to create a container with [[Bubblewrap]], using a [[#Debian|Debian chroot]] as its content. It's not just a chroot anymore: it's a bubblewrap-powered isolated environment. This allows for easily running graphical programs and does not require root privileges once installed.

[[Install]] the {{pkg|bubblewrap}} package.

Set up [[#Debian|Debian chroot]] at {{path|/var/chroots/debian}} and install necessary glibc applications using {{ic|apt-get}}.

Create a {{ic|glibc}} alias using bwrap in the Alpine Linux host in order to start applications from the [[#Debian|Debian chroot]]:
{{cmd|$ alias glibc{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group"}}

To run programs that use X11/Xorg, you can use:
{{cmd|$ alias glibcX11{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group --bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X0 --setenv DISPLAY :0"}}

In this case, you might need to use {{ic|xhost}} on the Alpine Linux host in order to allow local connections. For example:{{cmd|# xhost + local:}}

Now we can invoke glibc-built binaries using the alias from the Alpine Linux host, as follows:
{{cmd|$ glibc ./binary}} or {{cmd|$ glibcX11 ./binary}}

When a [[Wayland]] desktop such as [[Sway]] runs without XWayland on the Alpine Linux host, Electron apps need to be started with Ozone Wayland support:

* For VS Code (note the use of the {{ic|code}} command):
{{cmd|<nowiki>glibc code --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

* For Google Chrome, etc:
{{cmd|<nowiki>glibc google-chrome --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

The flags enforce Wayland rendering, thus avoiding XWayland and improving display, particularly if fractional scaling is also used.

== See also ==

* [[Alpine Package Keeper]]
* [[Installing ArchLinux inside an Alpine chroot]]
* [[Compile software from source]]
* [[Kernels]]

[[Category:Package Manager]] [[Category:Development]]

Software management

2026-01-09T20:04:02Z

John3-16: Added Coldbrew section

This page documents various ways to [[#Running glibc programs|run software compiled with glibc]] and to manage software using [[#Graphical software manager|graphical software managers]] in Alpine Linux. There are pages elsewhere regarding compiling [[Compile software from source|software from source]] and for creating a [[Custom Kernel|custom kernel]].

== Alpine package keeper ==
{{Main|Alpine Package Keeper}}
The official package manager in Alpine Linux, [[Alpine Package Keeper|Alpine Package Keeper(apk)]], is a ''cli'' tool. [[Comparison_with_other_distros#Comparison_chart/Rosetta_Stone|Rosetta stone]] shows how standard package management tasks are done in Alpine Linux compared to other popular distributions.

== Graphical software manager ==

The following graphical tools are available to manage official software packages from Alpine Linux [[Repositories|repositories]] and [[#Flatpak|flatpaks]] instead of using the [[#Alpine Package Keeper|cli-based apk tool]].

=== GNOME software ===

[[GNOME#Configuration|GNOME software]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

=== KDE Discover ===

[[KDE#Discover|KDE Discover]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

== AppImage ==
{{Main|AppImage}}

AppImages are by far the easiest method for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. Refer to the [[AppImage]] page for prerequisites and for detailed instructions to run them in Alpine Linux.

== Flatpak ==
{{Main|Flatpak}}

[[Flatpak#Installing_Flatpak|Flatpak]] is an alternative to [[AppImage|AppImages]] for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. To use flatpaks, ensure that the [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.

== Coldbrew ==

'''Coldbrew''' is a package manager that can install Alpine Linux aports Edge packages without needing root access, somewhat similar to '''brew'''. This is particularly useful on immutable operating systems such as with [https://postmarketos.org/blog/2025/10/12/pmOS-update-2025-09/#immutable-postmarketos PostmarketOS's duranium image]. '''Coldbrew''' is available in Alpine Linux Edge testing repository as of January 2026; the testing repository is [[Repositories#Using_testing_repository|recommended to be tagged]] if installing '''coldbrew''' on any supported Alpine Linux release.

'''Coldbrew''' replaces the [https://github.com/kcxt/iced '''iced'''] package on Alpine Linux, which used the {{Pkg|mkosi-sandbox}}; packages run inside a chroot using '''bubblewrap''' instead. They have access to the home directory, but have only controlled access to all other files through explicit bind mounts. Packages installed using '''coldbrew''' are referred to as tools. See [https://gitlab.postmarketos.org/postmarketOS/coldbrew further details upstream].

To install '''coldbrew''':
{{Cmd|$ doas apk add coldbrew@testing}}

To install a tool to be run by '''coldbrew''', say, {{Pkg|corepad}}:
{{Cmd|$ coldbrew install corepad}}

Note that even though the output ends...

Installed binary /usr/bin/corepad

...the path being referred to exists within a new mount namespace using bind mounts in the '''bubblewrap''' sandbox.

A wrapper program is installed to {{Path|~/.local/bin}} on Alpine Linux.

To run the tool under '''coldbrew''':
{{Cmd|$ coldbrew run corepad}}

To remove the tool:
{{Cmd|$ coldbrew remove corepad}}

All installed tools can be listed through the {{ic|$ coldbrew list}} command.

== Running glibc programs ==

If you want to run [https://www.gnu.org/software/libc/ glibc] programs in Alpine Linux, there are a few ways of doing so.

For simpler binaries, you can install [[#gcompat|gcompat]], which is a compatibility layer; or you could do it the easy way and use [[#Flatpak|Flatpaks]] or [[#AppImage|AppImages]]. See [[#Containers|containers]] or the [[#Chroot|chroot]] section for ways to run glibc programs, including graphical ones such as {{ic|VSCode}}, {{ic|google-chrome}}, {{ic|obsidian}}, etc.

=== gcompat ===

[https://git.adelielinux.org/adelie/gcompat gcompat] is a library that provides glibc-compatible APIs for use on musl libc systems such as Alpine Linux. To install, issue the command: {{cmd|$ doas apk add {{pkg|gcompat}}}}
After that, you run your binaries as normally.

For an usage example, refer to the [[Firefox#DRM_content_using_Widevine_workaround|Firefox]] page where gcompat is used to run the glibc-compiled Widevine binary.

== Chroot ==
{{Main|Chroot}}

An option that is easier to generalize to other glibc applications is to install a glibc-based distribution into a chroot. You can then either chroot into it, or use a symlink and some configuration to make its glibc (and associated libraries) usable from Alpine.

{{Tip|The most reliable way to enter a chroot is to use the [[Chroot#Enter_chroot|start-chroot]] script.}}

After setting up a chroot using any of the methods described below, the loader can be set up in Alpine as follows (these instructions are for a Debian chroot in {{Path|/var/chroots/debian}}, on x86_64, but can be adapted to other systems by using the appropriate paths):

{{cmd|$ doas mkdir -p /lib64
$ doas ln -s /var/chroots/debian/lib/x86_64-linux-gnu/ld-2.33.so /lib64
$ doas printf '/var/chroots/debian/lib/x86_64-linux-gnu\n/var/chroots/debian/usr/lib/x86_64-linux-gnu\n' > /etc/ld.so.conf
$ doas /var/chroots/debian/sbin/ldconfig}}

=== Gentoo Linux ===

Select a ''stage3'' from [https://www.gentoo.org/downloads/ here] and the ''portage'' latest from [https://www.gentoo.org/downloads/mirrors/ here] at gentoo/snapshots/portage-latest.tar.xz.

First,{{cmd|$ doas apk add {{pkg|xz}}}}

Enter the chroot:
{{cmd|$ doas mkdir ~/chroot
$ doas cd ~/chroot
$ doas tar -xvf stage3-*.tar.xz
$ doas tar -xvf portage-latest.tar.xz
$ doas mv portage usr
$ doas mount --bind /dev dev
$ doas mount --bind /sys sys
$ doas mount -t proc proc proc
$ doas cp /etc/resolv.conf etc
$ doas chroot . /bin/bash}}

And voilà, you have your working Gentoo chroot! 

You can now take a look at [https://wiki.gentoo.org/wiki/Handbook:Main_Page Gentoo's Handbook] to find out how you can configure and install your system, or simply extract/copy the program that you need to run in your chroot enviroment, and then execute it.

Here is a wrapper script that is similar to {{ic|arch-chroot}} when you frequently reuse this chroot. Also, create an account with the same username as host current user to the chroot, or make changes to the {{ic|userspec}} option to chroot line:

{{Cat|gentoo-chroot.sh|<nowiki>#!/bin/bash
CHROOT_PATH="/home/$USER/chroot"
cd $CHROOT_PATH
mount | grep $CHROOT_PATH/dev || doas mount --bind /dev dev
mount | grep $CHROOT_PATH/sys || doas mount --bind /sys sys
mount | grep $CHROOT_PATH/proc || doas mount -t proc proc proc
cp /etc/resolv.conf etc
doas chroot --userspec=$USER:users . /bin/bash
echo "You must manually unmount $CHROOT_PATH/dev, $CHROOT_PATH/sys, $CHROOT_PATH/proc."
</nowiki>
}}

Do {{ic|$ chmod +x gentoo-chroot.sh}} to make it executable.

=== Arch Linux ===

{{Seealso|Installing ArchLinux inside an Alpine chroot}}
Either use '''pacstrap''' (included with the arch-install-scripts package) or an Arch bootstrap image:

{{cmd|$ doas apk add {{pkg|arch-install-scripts}}
$ mkdir ~/chroot && cd ~/chroot
$ curl -O https://mirrors.edge.kernel.org/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.zst
$ doas tar -x --zstd -f archlinux-bootstrap-x86_64.tar.zst && rm archlinux-bootstrap-x86_64.tar.zst
$ doas sed -i '/evowise/s/^#//' root.x86_64/etc/pacman.d/mirrorlist
$ doas sed -i '/CheckSpace/s/^/#/' root.x86_64/etc/pacman.conf
$ doas arch-chroot root.x86_64
[chroot]# pacman-key --init
[chroot]# pacman-key --populate archlinux}}

Once that is done, update the system and install the desired package(s) (denoted by ''"foo"'' in this example):

{{cmd|[chroot]# pacman -Syu <var>foo</var>}}

=== Debian ===

Alpine Linux provides the {{pkg|debootstrap}} package to create the Debian chroot. Here are the steps: {{cmd|$ doas apk add debootstrap
$ doas mkdir -p /var/chroots/debian
$ doas debootstrap --arch amd64 stable /var/chroots/debian/ https://deb.debian.org/debian}}

The {{ic|--arch}} is optional, depending on your needs.

For updating the chroot, or for installing packages and their dependencies using {{ic|apt-get}}, mount it, and then login as root:
{{cmd|$ doas mount --bind /dev /var/chroots/debian/dev
$ doas mount --bind /proc /var/chroots/debian/proc
$ doas mount --bind /dev/pts /var/chroots/debian/dev/pts
$ doas chroot /var/chroots/debian /bin/bash
[chroot]# apt update && apt upgrade}}

After installing the necessary applications and whatever else you might do, exit the chroot:
{{cmd|[chroot]# exit}}

Then, unmount the binds for /dev/pts, dev and proc to avoid issues:
{{cmd|$ doas umount /var/chroots/debian/dev/pts
$ doas umount /var/chroots/debian/dev
$ doas umount /var/chroots/debian/proc}}

== Containers ==

=== Distrobox + Podman ===

[[Distrobox]], combined with [[Podman|podman]] container running in rootless mode, allows to easily run [[Distrobox#Running_graphical_programs|glibc-compiled graphical programs]]. This will not require root privileges once set up.

=== Bubblewrap + Chroot ===

{{ic|glibc}} and {{ic|glibcX11}} shell aliases are defined interactively using bwrap to create a container with [[Bubblewrap]], using a [[#Debian|Debian chroot]] as its content. It's not just a chroot anymore: it's a bubblewrap-powered isolated environment. This allows for easily running graphical programs and does not require root privileges once installed.

[[Install]] the {{pkg|bubblewrap}} package.

Set up [[#Debian|Debian chroot]] at {{path|/var/chroots/debian}} and install necessary glibc applications using {{ic|apt-get}}.

Create a {{ic|glibc}} alias using bwrap in the Alpine Linux host in order to start applications from the [[#Debian|Debian chroot]]:
{{cmd|$ alias glibc{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group"}}

To run programs that use X11/Xorg, you can use:
{{cmd|$ alias glibcX11{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group --bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X0 --setenv DISPLAY :0"}}

In this case, you might need to use {{ic|xhost}} on the Alpine Linux host in order to allow local connections. For example:{{cmd|# xhost + local:}}

Now we can invoke glibc-built binaries using the alias from the Alpine Linux host, as follows:
{{cmd|$ glibc ./binary}} or {{cmd|$ glibcX11 ./binary}}

When a [[Wayland]] desktop such as [[Sway]] runs without XWayland on the Alpine Linux host, Electron apps need to be started with Ozone Wayland support:

* For VS Code (note the use of the {{ic|code}} command):
{{cmd|<nowiki>glibc code --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

* For Google Chrome, etc:
{{cmd|<nowiki>glibc google-chrome --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

The flags enforce Wayland rendering, thus avoiding XWayland and improving display, particularly if fractional scaling is also used.

== See also ==

* [[Alpine Package Keeper]]
* [[Installing ArchLinux inside an Alpine chroot]]
* [[Compile software from source]]
* [[Kernels]]

[[Category:Package Manager]] [[Category:Development]]

Tutorials and Howtos

2026-01-07T21:39:49Z

John3-16: /* Raspberry Pi */ Added Raspberry Pi Zero W - Installation (previously orphaned page).

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* Use [https://github.com/ifupdown-ng/ifupdown-ng/blob/main/doc/interfaces-vxlan.scd vxlan], if using [[Ifupdown-ng]] instead of [[VLAN]]
* [[Setting up a Home Router]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Fingerprint Authentication with swaylock]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi|Raspberry Pi main page]]
* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[Raspberry_Pi_Zero_W_-_Installation|Raspberry Pi Zero W - Installation]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''
* [[RPI Video Receiver]]

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

== Security ==

* [[#Desktop security|Desktop security]] lists steps for securing Alpine Linux desktops
* [[Setting up a laptop]] page has detailed guidelines to configure a secured laptop
* [[Securing Alpine Linux|Secure Alpine Linux]] using Security Technical Implementation Guides (STIGs)
* [[Sshguard|SSHGuard]] - Protects hosts against brute-force attacks: monitoring logs, attack detection, blocking using firewall.

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]] ''(Simple and easy to use wiki, no database required)''
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[Moodle]] ''(Online Learning Management system)''

=== Database ===

* [[MariaDB]] or [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* Unbound
** [[Setting up unbound DNS server]]
** [[Using Unbound as an Ad-blocker]] ''(Setup ad blocking for your network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall ===

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[Zero-To-Awall]] -''AWall for dummies''
** [[How-To Alpine Wall]] - ''AWall for Shorewall users''
** [[Alpine Wall]] - ''AWall - Firewall management framework - Design Document''
* [[Iptables]]
* [[nftables]]
* [[Uncomplicated Firewall|Uncomplicated Firewall or UFW]]

=== HTTP and web services ===

* [[Althttpd]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎|Production LAMP system: Lighttpd + PHP + MariaDB/MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== VPN ===
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[IGMPproxy]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Tor]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[Vpnc]]

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system) [Deprecated]''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* [[ZFS]]
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux
* [[Runc]]

== [[Simple_Walkthrough]] ==
* [[About-virtualization-simple]]
* [[LXC_Alpinelinux_Simple]]
* [[Qemu-simple]]

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]
* [https://ww2.coastal.edu/mmurphy2/oer/alpine/ Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor]
* [[Michael's base installation procedure|Michael's base installation procedure]]
* [[Michael's cwm desktop (minimal)|Michael's cwm desktop (minimal)]]
* [[Michael's sway desktop (minimal)|Michael's Sway desktop (minimal)]]
* [[Sway_customization_guide|Sway customization guide]] ''(Tutorial re Sway config file basics)''
* [[Using Distrobox For VR Gaming|Using Distrobox For VR Gaming]]

Talk:Sshguard

2026-01-07T21:25:46Z

John3-16: Added /* Display title - amend to SSHGuard */ section

== Display title - amend to SSHGuard ==
The display title was attempted to be amended from '''Sshguard''' to the '''SSHGuard''' upstream style, using the code:

<nowiki>{{DISPLAYTITLE:SSHGuard}}</nowiki>

However, it does not work. Further to summary research, the wiki media would require that {{ic|<nowiki>$wgAllowDisplayTitle = true;</nowiki>}} be set, as is reportedly the usual default, in {{ic|LocalSettings.php}} . This is beyond the scope of a wiki contributor.

Sshguard

2026-01-07T21:13:50Z

John3-16: 1. /* nftables backend */ Added subheading and amended context accordingly; 2. Amended page title from Sshguard to SSHGuard; 3. Style/grammar amendments, including clarification that ipfw and pf are not available on Alpine Linux.

{{DISPLAYTITLE:SSHGuard}}

[https://www.sshguard.net/ SSHGuard] protects hosts from brute-force attacks against SSH and other services. It aggregates system logs and blocks repeat offenders using one of several firewall backends, including '''iptables''' and '''nftables'''; SSHGuard also supports firewalls used elsewhere, including ipfw and pf.

SSHGuard can read log messages from standard input (suitable for piping from ''syslog'') or monitor one or more log files. Log messages are parsed, line-by-line, for recognized patterns. If an attack, such as several login failures within a few seconds, is detected, the offending IP is blocked. Offenders are unblocked after a set interval, but can be semi-permanently banned using the blacklist option.

SSHGuard does not support custom log parsing. Check the website upstream to see which services they support.

== Installation ==

SSHGuard can use several backends; you can see them listed with {{ic|$ ls /usr/libexec/sshg-fw*}}. The easiest backend on Alpine Linux is [[Nftables|nftables]], but a section is given below for [[Iptables]] also. After either firewall has been installed, install {{Pkg|sshguard}}:

{{Cmd|$ doas apk add sshguard}}

You will need to create the following configuration file or else SSHGuard won't start.

{{Cat|/etc/sshguard.conf|#!/bin/sh
BACKEND{{=}}'/usr/libexec/sshg-fw-nft-sets'
FILES{{=}}'/var/log/messages'
}}

== nftables backend ==

The nftables ruleset (tables and sets) required by SSHGuard are created dynamically with this SSHGuard daemon. You can view the rules that are active with:

{{ic|$ doas nft list ruleset}}

== iptables backend ==

To use the '''iptables''' backend, you must first create a chain called "sshguard". Enable the iptables-service to save the rules at shutdown and reload them when booting

{{Cmd|$ doas iptables -N sshguard
$ doas iptables -A INPUT -j sshguard
$ doas rc-update add iptables boot}}

You can view the rules with {{ic|$ doas iptables -L}}

[[category:Security]]

Hosting Web/Email services on Alpine

2026-01-07T20:26:30Z

John3-16: /* See also */ Added SSHGuard (previously orphaned page).

{{Accuracy|Various passages are based on the obsolete [[Protecting your email server with Alpine]] page}}
{{Merge|Hosting services on Alpine}}

== Introduction ==

This information was pulled from a few other pages on this Alpine Wiki website: see links, along with the websites for the particular packages. It is a suggestion list and step-by-step instruction guide.

You might be wondering, why would anyone want to run Web and Email services off a Linux install that runs in ram? Good question. With '''Vservers''', we can run the host in memory and do all sorts of things with the guests. Put the guests on DAS in the host machine or do raided iSCSI for the guest. This way, if your disks start going bad or drop off entirely, you most likely will be able to get at the data from a running system.

Guest OS here or
[Host Alpine Box] --------------------- [DAS]
| |
| |Guest OS here
| |
iSCSI iSCSI

== Web Services ==
There are many http servers out there. Alpine comes with a few different ones. For this guide, we installed [[Lighttpd|lighttpd]].

apk update
apk add lighttpd openssl php

Most everything is already taken care of with lighttpd. Make sure to uncomment the SSL (Secure Sockets Layer) options:-
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"

rc-service lighttpd start
See below for generating the {{ic|server.pem}}.

Now, you can start using '''lighttpd''' and start making your own website. Alpine Linux comes with '''phpBB''' and [[MediaWiki]], if you want to use those. You may have to use an SQL database. The place to put your pages is:
/var/www/localhost/htdocs/
By default, '''lighttpd''' uses symlinks and does so correctly. So, you can just symlink to directories when your pages may be also:
ln -s /home/user/htdocs /var/www/localhost/htdocs/user

===Generating the Server.pem===
For other services, we are also going to be using SSL. An easy way to just start using it is by generating your own self-sign cert. Script and configuration files are taken from the {{ic|setup-webconf}} script (now-deprecated).

ssl.cnf
[ req ]
default_bits = 1024
encrypt_key = yes
distinguished_name = req_dn
x509_extensions = cert_type
prompt = no
[ req_dn ]
OU=HTTPS server
CN=example.net
emailAddress=postmaster@example.net
[ cert_type ]
nsCertType = server

ssl.sh
#/bin/sh
openssl genrsa 512/1024 >server.pem
openssl req -new -key server.pem -days 365 -out request.pem
openssl genrsa 2048 > keyfile.pem
openssl req -new -x509 -nodes -sha1 -days 3650 -key keyfile.pem \
-config ssl.cnf > server.pem
cat keyfile.pem >> server.pem

If you use this to generate the SSL certs for other services, then you may just change the {{ic|req_dn}} information.

==Mail Services==

Some of the information presented here can be found in the [[Protecting your email server with Alpine]] page, now obsolete. This, however, is for an email gateway.
apk add postfix dovecot clamav clamsmtp gross

===Postfix===
Postfix has a few things that need to be added to its configuration so that it can send email through {{Pkg|clamav}}, and also so that it will accept mail for domains and users.

====Main.cf====
vi /etc/postfix/main.cf
#/etc/postfix/main.cf
myhostname = mx.example.net
mydomain = example.net
relayhost = #blank will do dns lookups for destinations
home_maildir = Maildir/
smtpd_banner = $myhostname ESMTP #The way postfix answers.
transport_maps = hash:/etc/postfix/transport #Place to add how you want to route domains. See example below. Show how to host more than one domain.
local_transport = virtual
virtual_mailbox_domains = example.net, bobo.net #list of hosted domains
virtual_mailbox_base = /var/spool/vhosts
virtual_uid_maps = static:1004 # uid of user to be used to read/write mail
virtual_gid_maps = static:1004 # gid of user to be used to read/write mail
virtual_alias_maps = hash:/etc/postfix/valias #alias for each different hosted domain. See below.
virtual_mailbox_maps = hash:/etc/postfix/vmap #where and what mailbox to drop the mail to. See below.
smtpd_helo_required = yes
disable_vrfy_command = yes
content_filter = scan:[127.0.0.1]:10025 # clamscan to be configured later
smtpd_recipient_restrictions = reject_unauth_pipelining, permit_sasl_authenticated,permit_mynetworks,reject_invalid_hostname, reject_non_fqdn_hostname,reject_non_fqdn_sender, reject_non_fqdn_recipient,reject_unknown_sender_domain, reject_unknown_recipient_domain,reject_unauth_destination, check_policy_service inet:127.0.0.1:5525,permit
smtpd_data_restrictions = reject_unauth_pipelining, permit
smtpd_sasl_auth_enable = yes
broken_sasl_auth_clients = yes
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_tls_cert_file = /etc/ssl/postfix/server.pem
smtpd_tls_key_file = $smtpd_tls_cert_file

====Master.cf====
Settings in the {{Path|master.cf}} file for virus/spam scanning. Add these to the end of the file, similar to those found in [[Protecting your email server with Alpine]].

scan unix - - n - 16 smtp
-o smtp_send_xforward_command=yes
-o smtp_enforce_tsl=no
127.0.0.1:10026 inet n - n - 16 smtpd
-o content_filter=
-o receive_override_options=no_unknown_recipient_checks,no_header_body_checks
-o smtpd_helo_restrictions=
-o smtpd_client_restrictions=
-o smtpd_sender_restrictions=
-o smtpd_recipient_restrictions=permit_mynetworks,reject
-o mynetworks_style=host
-o smtpd_authorized_xforward_host=127.0.0.1/8

====Valias====
#etc/postfix/valias
postmaster@example.net user1@example.net
hostmaster@example.net user2@example.net
hostmaster@bobo.net user1@example.net
postmaster@bobo.net user2@bobo.net

====Vmap====
#/etc/postfix/vmap
user1@example.net example.net/user1
user2@example.net example.net/user2
@example.net example.net/catchall #everyone else doesn't match rule above

====Transport====
#/etc/postfix/transport
example.net virtual:
bobo.net virtual:
foo.net smtp:1.2.3.4 #send foo.net through this smtp server
* : #everything else go through relayhost rule

Once these files are created, you will need to make them into {{Path|.db}} files:
postmap valias
postmap transport
postmap vmap

===Dovecot===
'''Dovecot''' on Alpine Linux will only do '''imap''' and '''imaps''' services for now.

Most of '''dovecot''' is configured already for '''imap'''. You may have to gen the key, as shown above. Just change the {{Path|cnf}} file a little to say something about {{ic|mail.domainname}}:

ssl_cert_file = /etc/ssl/dovecot/server.pem
ssl_key_file = /etc/ssl/dovecot/keyfile.pem
mail_location = maildir:/var/spool/vhosts/&d/%n
valid_chroot_dirs = /var/spool/vhosts
passdb passwd-file {
args = /etc/dovecot/passwd
}
userdb passwd-file {
args = /etc/dovecot/users
}
#section for postfix sasl auth
socket listen {
client {
path = /var/spool/postfix/private/auth
user = postfix
group = postfix
mode = 0660
}
}

To generate the passwords, you can use the {{ic|dovecotpw}} command:
dovecotpw -s MD5-CRYPT

The hash below can be used for the password <var>test123</var>. The {{Path|/etc/dovecot/passwd}} file should look like this:
user1@example.net:$1$tz5sbjAD$Wq9.NkSyNo/oElzFgI68.0
user2@example.net:$1$tz5sbjAD$Wq9.NkSyNo/oElzFgI68.0

The {{Path|/etc/dovecot/userdb}} file should look like this:
user1@example.net::1004:1004::/var/spool/vhosts/example.net/:/bin/false::
user2@example.net::1004:1004::/var/spool/vhosts/example.net/:/bin/false::
user@domain::uid : gid of found in virtual_uid_maps::location of maildir:shell::

===Clamsmtpd===
Configure according to instructions [[Protecting your email server with Alpine]]

===Gross===
Configure according to instructions [[Protecting your email server with Alpine]]

===Final Steps ===
Start the services and make sure to rc-update them
rc-service postfix start
rc-update add postfix default

== See also ==

* [[Grommunio_Mail_Server|Grommunio Mail Server]] - Open-source groupware solution
* [[Aerc]] - Terminal email client (MUA)
* [[Sshguard|SSHGuard]] - Protects hosts against brute-force attacks: monitoring logs, attack detection, blocking using firewall.

[[Category:Server]]
[[Category:Mail]]

Tutorials and Howtos

2026-01-07T20:16:53Z

John3-16: /* Security */ Added SSHGuard

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* Use [https://github.com/ifupdown-ng/ifupdown-ng/blob/main/doc/interfaces-vxlan.scd vxlan], if using [[Ifupdown-ng]] instead of [[VLAN]]
* [[Setting up a Home Router]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Fingerprint Authentication with swaylock]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi|Raspberry Pi main page]]
* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''
* [[RPI Video Receiver]]

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

== Security ==

* [[#Desktop security|Desktop security]] lists steps for securing Alpine Linux desktops
* [[Setting up a laptop]] page has detailed guidelines to configure a secured laptop
* [[Securing Alpine Linux|Secure Alpine Linux]] using Security Technical Implementation Guides (STIGs)
* [[Sshguard|SSHGuard]] - Protects hosts against brute-force attacks: monitoring logs, attack detection, blocking using firewall.

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]] ''(Simple and easy to use wiki, no database required)''
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[Moodle]] ''(Online Learning Management system)''

=== Database ===

* [[MariaDB]] or [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* Unbound
** [[Setting up unbound DNS server]]
** [[Using Unbound as an Ad-blocker]] ''(Setup ad blocking for your network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall ===

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[Zero-To-Awall]] -''AWall for dummies''
** [[How-To Alpine Wall]] - ''AWall for Shorewall users''
** [[Alpine Wall]] - ''AWall - Firewall management framework - Design Document''
* [[Iptables]]
* [[nftables]]
* [[Uncomplicated Firewall|Uncomplicated Firewall or UFW]]

=== HTTP and web services ===

* [[Althttpd]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎|Production LAMP system: Lighttpd + PHP + MariaDB/MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== VPN ===
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[IGMPproxy]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Tor]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[Vpnc]]

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system) [Deprecated]''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* [[ZFS]]
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux
* [[Runc]]

== [[Simple_Walkthrough]] ==
* [[About-virtualization-simple]]
* [[LXC_Alpinelinux_Simple]]
* [[Qemu-simple]]

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]
* [https://ww2.coastal.edu/mmurphy2/oer/alpine/ Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor]
* [[Michael's base installation procedure|Michael's base installation procedure]]
* [[Michael's cwm desktop (minimal)|Michael's cwm desktop (minimal)]]
* [[Michael's sway desktop (minimal)|Michael's Sway desktop (minimal)]]
* [[Sway_customization_guide|Sway customization guide]] ''(Tutorial re Sway config file basics)''
* [[Using Distrobox For VR Gaming|Using Distrobox For VR Gaming]]

Stream a DV-camera using vlc

2026-01-07T20:01:07Z

John3-16: 1. Added /*See also */ Streaming Security Camera Video with VLC (previously orphaned page); 2. Style amendments: header use

{{draft}}
In this howto we are going to stream the video coming from a DV-camera connected through ie1394 (firewire). 
vlc is used to stream the content. 
We will be using h264 and AAC to transcode the stream ''(should be fairly easy to change to whatever suits your needs)''.

== Setup Alpine ==
=== Initial Setup ===
Follow [[Installing_Alpine]] to setup Alpine Linux.

=== Install programs ===
{{Cmd| apk add vlc-daemon vlc-dev }}
{{note|If you intend to use a desktop environment with vlc you will need to install {{pkg|vlc-qt}} in order to get that working. {{pkg|vlc-dev}} or {{pkg|vlc}} package does not contain the graphical part of vlc ''(menus etc.)''.}}
{{todo| I haven't figured out why vlc-dev is needed. Manually adding all vlc-dev dependencies does not work. 
The 'require vlc-dev' thing is reported at {{Issue|1051}} and might be solved soon ''(or 'vlc-dev' really is needed as a dependency)''.}}

=== Using ACF to control vlc ===
{{tip|A easy way to control vlc-daemon would be through [[Alpine Configuration Framework Design|ACF]]. Consider following these simple steps. 
But as it is ''optional'' you could just skip this [[Alpine Configuration Framework Design|ACF]] section.}}
Setup/install acf ''(unless it's not already done)''.
{{cmd| setup-acf}}
Install acf-package for vlc
{{cmd| apk add acf-vlc-daemon}}
We won't describe in this tutorial how you would use [[Alpine Configuration Framework Design|ACF]] to control vlc-daemon ''(basically because it's so simple it does not need any describing)''. 
If you installed [[Alpine Configuration Framework Design|ACF]], just browse <nowiki>https://ip.of.your.box</nowiki> and you would from this tutorial understand what to do. 

== Configure vlc ==
Configuration is done by modifying '/etc/conf.d/vlc'. 
Here comes the actual configuration that makes vlc stream the DV-camera.
<pre>
###############
BITRATE=500
XRES=720
YRES=576

###############
# Chose one of the following 'preset' values depending on how fast your CPU is:
# ultrafast,superfast,veryfast,faster,fast,medium,slow,slower,veryslow,placebo
TVIDEO="venc=x264{preset=ultrafast,vbv-maxrate=${BITRATE},vbv-bufsize=256,keyint=250,min-keyint=25},vcodec=h264,vb=${BITRATE},scale=1,width=${XRES},height=${YRES}"
TAUDIO="acodec=mp4a,ab=96,channels=2,samplerate=44100"
TMISC="deinterlace,audio-sync"

###############
TRANSPORT="std{access=http,mux=ts,dst=:8080}"

VLC_OPTS="--daemon -I dummy dv:///dev/fw0 --rawdv-hurry-up --sout-keep --sout-transcode-audio-sync \
--file-logging --logfile /var/log/vlc/vlc.log \
--sout #transcode{$TVIDEO,$TAUDIO,$TMISC}:$TRANSPORT"
</pre>

== Start it up ==
== Prepare the hardware ==
Here comes the hardest part in this tutorial... Attach the DV-camera to your ie1394/firewire port. 
Well... that wasn't too hard! :-)

=== Manual start ===
Start vlc-daemon either from terminal:
{{cmd|rc-service vlc start}}
or using ACF and just klick [Start].

=== Make it start at next reboot ===
You might want to make it automatically start at next reboot
{{cmd|rc-update add vlc-daemon default}}

== Debug ==
In case something goes wrong, consider looking at the logfiles.
{{cmd|less -I /var/log/vlc/vlc.log}}
If you don't find any useful information you could add verbosity by adding '-v' or '-vv' to /etc/conf.d/vlc and restart vlc ''(you would need to restart vlc-daemon to see more information in the logs)''.

== See also ==

* [[Streaming_Security_Camera_Video_with_VLC|Streaming Security Camera Video with VLC]]

[[Category:Multimedia]]

Streaming Security Camera Video with VLC

2026-01-07T19:51:05Z

John3-16: 1. Added See also; 2. Style amendments: header use

== Goal ==

Setup a streaming video solution that small locations can use easily for broadcasting small events, security video or other uses. Because those locations may not have a static IP, route video traffic from your main static IP (on your openvpn server) over a tunnel to the remote location.

== Overview ==

The remote location will require internet access. They will be provided with the following equipment:
* Minibox style x86 computer
* Monitor/Keyboard/Mouse
* Axis P1344 camera w/ POE injector OR Axis Q-7401 capture box
* network (2 blue cables are straight through, red is crossover) + power cables

== Setup instructions ==

=== Axis camera ===

* Power up camera.
* Connect to web interface of the camera.
* Set admin password (example root:test123).
* Setup -> Video Stream -> Audio -> Check Enable Audio checkbox.
* Setup -> Video Stream -> Image -> Resolution = 640x480.

=== Axis capture box ===

* Power up box.
* Connect to web interface of the camera.
* Set admin password (example root:test123).
* Setup -> Video Stream -> Audio -> Check Enable Audio checkbox.
* Setup -> Video Stream -> Image -> Resolution = 720x480.
* Enable anonymous video viewer.

=== Minibox ===

* Setup USB key w/ Alpine Linux 2.4.5.
* Enable apk cache.
* Install the following packages:
<pre>
alpine-base xscreensaver xf86-input-evdev openssh vlc rsync vim openvpn gawk bash vlc-xorg alsa-utils alsaconf alsa-lib vlc-daemon gstreamer gstreamer-tools gst-plugins-ugly gst-plugins-good gst-plugins-base chrony xf86-video-vesa linux-firmware pciutils usbutils iptables dnsmasq beep shorewall dnscache slim udev nmap tcpdump xf86-video-openchrome abiword busybox evince firefox gnumeric lxdm ristretto sudo xf86-input-keyboard xf86-input-mouse xfce4 xorg-server iftop
</pre>
* /etc/network/interfaces
<pre>
auto eth0
iface eth0 inet dhcp

auto eth1
iface eth1 inet static
address 10.14.197.1
netmask 255.255.255.224

auto lo
iface lo inet loopback
</pre>
* /etc/ssh/sshd_config - disable password auth
* /root/.ssh/authorized_keys - install all needed keys
* adduser jbilyk
* /etc/chrony/chrony.conf
<pre>
chrony/chrony.conf
# default config

server time.nrc.ca
initstepslew 10 time.nrc.ca
commandkey 10
keyfile /etc/chrony/chrony.keys
driftfile /etc/chrony/chrony.drift

cmdallow 127.0.0.1

allow all
</pre>
* rc-update add chronyd
* /etc/conf.d/dnscache
<pre>
# DNSCACHE configuration variables:

# IPSEND - ip address to use for requests use 0.0.0.0 for default route
IPSEND=0.0.0.0

# CACHESIZE - Num bytes to use for the cache
CACHESIZE=1000000

# IP - IP addr to listen on
IP=127.0.0.1

#------------------------------------------------------------------------
# The following are flags. Setting them to ANY value
# (even "false" or "off") will turn the feature on.
#------------------------------------------------------------------------

# HIDETTL - always return TTL as 0
#HIDETTL=

# FORWARDONLY - servers/@ are parent caches, not root servers
#FORWARDONLY=

# UPDATEHINTS - refresh zone hints
UPDATEHINTS=1

</pre>
* rc-update add dnscache
* /etc/dnsmasq.conf (replacing MAC and IP on dhcp-host line as required)
<pre>
domain-needed
bogus-priv
no-resolv
no-poll
server=10.14.197.1
interface=eth1
except-interface=lo
bind-interfaces
expand-hosts
domain=example.com
dhcp-authoritative
cache-size=0 # dnscache does caching
no-negcache
log-dhcp
dhcp-range=10.14.197.10,10.14.197.20,255.255.255.224,12h
dhcp-option=option:ntp-server,10.14.197.1
dhcp-option=6,10.14.197.1,10.14.0.1
dhcp-option=option:domain-search,example.com
dhcp-host=00:40:8c:c4:7e:99,10.14.197.5,24h # Axis Camera
dhcp-option=option:ntp-server,10.14.197.1
dhcp-option=2,-18000
</pre>
* rc-update add dnsmasq
* /etc/openvpn/openvpn.conf
<pre>
client
dev tun
proto udp
remote public.ip.addr.ess 1194
resolv-retry infinite
nobind

persist-key
persist-tun

ca ca.pem
cert cert.pem
key key.pem

comp-lzo
verb 3

script-security 2
up /etc/openvpn/up.sh
down /etc/openvpn/down.sh
</pre>
* Extract your openvpn cert parts into /etc/openvpn/
<pre>
openssl pkcs12 -in %CERTPFX% -cacerts -nokeys -out ca.pem
openssl pkcs12 -in %CERTPFX% -nocerts -nodes -out key.pem
openssl pkcs12 -in %CERTPFX% -nokeys -clcerts -out cert.pem
</pre>
* rc-update add openvpn
* /etc/resolv.conf.tail
<pre>
nameserver 127.0.0.1
</pre>
* /etc/conf.d/vlc
<pre>
# Sample vlc params suitable for running as a daemon

## --daemon detach from prompt
## --file-logging enable file logging
## --logfile logfile name/path
## -vvv verbose logging
## -I dummy disable X11 interface
## --sout PARAMS encoding parameters
## Do NOT quote 'PARAMS' otherwise shell expansions will broke vlc

VLC_OPTS="-I dummy --daemon --file-logging --logfile /var/log/vlc/vlc.log --loop --rtsp-caching=200 rtsp://10.14.197.5:554/axis-media/media.amp?videocodec=h264 --sout #standard{access=http,mux=ts,dst=0.0.0.0:8080}"
</pre>
* rc-update add vlc
* /etc/shorewall/params
<pre>
A_IF=tun0
B_IF=eth1
E_IF=eth0
</pre>
* /etc/shorewall/interfaces
<pre>
A $A_IF detect dhcp
B $B_IF detect dhcp
E $E_IF detect dhcp
</pre>
* /etc/shorewall/policy
<pre>
A all REJECT info
B A ACCEPT
B E ACCEPT
all all REJECT info
</pre>
* /etc/shorewall/rules
<pre>
# FW management
ACCEPT A fw tcp 22,80,443

# Manage the camera from the HQ if need be
ACCEPT A B tcp 80

ACCEPT fw all icmp 8
ACCEPT fw E tcp 53,80
ACCEPT fw E udp 53,1194
ACCEPT fw B
ACCEPT B fw udp 53
ACCEPT B fw tcp 53
ACCEPT A fw tcp 8080
</pre>
* /etc/shorewall/zones
<pre>
fw firewall
A ipv4
B ipv4
E ipv4
</pre>
* /etc/shorewall/shorewall.conf
<pre>
STARTUP_ENABLED=Yes
...
IP_FORWARDING=On
</pre>
* rc-update add shorewall
* rc-update add lxdm
* home/jbilyk/.config/autostart/firefox.desktop
<pre>
[Desktop Entry]
Encoding=UTF-8
Version=0.9.4
Type=Application
Name=firefox
Comment=
Exec=nice -n 5 firefox
OnlyShowIn=XFCE;
StartupNotify=false
Terminal=false
Hidden=false
</pre>
* Set FF homepage to 10.14.197.5 (replacing with ip address of Axis)
* lbu commit
* Plug in internet connection to eth0.
* Plug in crossover cable to axis PoE injector and straight through to Axis.
* Plug in line-out from mixer to axis.
* Power up blackbox with monitor, keyboard, mouse connected.
* Once desktop appears, power on axis.

== OpenVPN router ==

* /etc/shorewall/rules
<pre>
DNAT E G_196:10.14.196.10 tcp 8080 - public.ip.addr.ess
</pre>
* /etc/shorewall/masq
<pre>
tun0 0.0.0.0/0 10.14.196.1 tcp 8080
</pre>

== End User Instructions ==

Please verify that all of the following components shipped properly:

* Router
* Monitor
* Camera
* Camera power injector
* 2 x 50' blue network cables
* 1 x 14' red network cable
* 2 x 6' black power cables
* 1 x AC power brick
* 1 x monitor video cable
* 1 x keyboard
* 1 x mouse

* Place router in desired location. It should be placed on a flat, stable surface.
* Place monitor nearby to the router.
* Use one 6' power cord, connect to the monitor and power the monitor on.
* Connect the monitor video cable from the monitor "RGB" port to the corresponding port on the router.
* Place camera power injector in desired location.
* Connect red network cable from the "Data In" jack on the power injector to the router port labelled "Camera".
* Connect Internet connection to the router port labelled "Internet" using a blue network cable.
* Connect keyboard and mouse to USB ports on the rear of the router.
* Plug the AC power brick into the router and then an available power outlet. The router will turn itself on automatically.
* Wait for a 3 toned beep from the router and the desktop environment to appear. (Note: Mozilla Firefox will open with the error message "Well, this is embarassing". This is normal.).
* Connect blue network cable from the camera to the "Data & Power Out" jack on the power injector.
* Once the light on the top of the camera turns green, click "Start New Session" in Firefox. A video window should appear after a brief delay.
* Adjust the focus and zoom of the camera manually using the dials on the front of the camera.
* To test the stream on the remote location end, open VLC on a computer with Internet connectivity, then run File -> Open Network Stream and connect to <nowiki>http://public.ip.addr.ess:8080</nowiki>.

== See also ==

* [[Stream_a_DV-camera_using_vlc|Stream a DV-camera using vlc]]

[[Category:Server]]
[[Category:Multimedia]]

Alpine on ARM

2026-01-07T18:49:40Z

John3-16: /* See also */ Added DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs

{{TOC right}}
Alpine Linux supports [https://en.wikipedia.org/wiki/ARM_architecture_family ARM architecture], a family of reduced instruction set computing (RISC) architectures for computer processors. ARM is the most widely used processor architecture in the world, powering most smartphones and millions of the simplest IoT devices to sophisticated machine learning applications.

== Supported SoCs ==

Alpine Linux is compiled with support files for so many formidable SoCs — besides the [[Raspberry Pi]] — that to find out about a particular chipset's support it can be useful to refine the search for all <code>*.dtb</code> files in the package database (i.e. filter for "<code>*<some-board-or-SoC-identifying-string>*.dtb</code>" file).

For example, by refining the following search in the current "edge" release:

DTB-files in the current edge branch:
https://pkgs.alpinelinux.org/contents?repo=main&file=*.dtb&branch=edge

Fully supported boards are those for which there is a working bootloader shipped in the download.

== Preparing installation media ==

There are no ISO installation images for ARM, since different boards require slightly different builds of u-boot. Hence, preparation steps are a bit more involved than x86_64.

The latest images are available [https://alpinelinux.org/downloads/ on the Alpine Linux downloads page].

For [[Raspberry Pi]] boards, use images specific for your board. In case the download page provides no specific image for your particular board, download the "Generic ARM" image. armv7 is the most compatible and aarch64 is the best choice for modern ARM SoCs.

=== Formating the sd card ===

To install Alpine, an SD card is required, and it will be completely wiped while preparing it for use as installation media.

Insert the SD card onto the host where you've downloaded the Alpine tarball and find out its devices name with <code>dmesg</code> or <code>fdisk -l</code>.

Create a partition in the SD card. The usual choice is to use <code>doas fdisk /dev/sdX</code>. Care must be taken when creating the partition; it should never overlap with the u-boot (which will be set up in the following step). It is recommended to use <code>start: 32768</code> as a safe choice when creating the partition. Make sure that the partition is also marked as bootable.

It is also recommended to use FAT32, since ext4 is sometimes problematic with GRUB2, so set the partition type to <code>W95 FAT32 (LBA)</code>.

Once the partition has been created, it needs to be formatted. Use, for example: <code>mkfs.vfat /dev/sdX1</code>

=== Copying installation files onto the sd card ===

Now extract the downloaded tarball into the SD card:

doas mount /dev/sdX1 /mnt
cd /mnt
doas tar -xf $HOME/downloads/alpine-uboot-3.18.2-aarch64.tar.gz

=== Installing u-boot onto the SD card ===

Finally, u-boot needs to be installed into the SD card. The exact steps vary per board. The following example installs u-boot for a pinebook-pro:

# Copy the U-Boot TPL/SPL
doas dd if=u-boot/pinebook-pro-rk3399/idbloader.img of=/dev/sdb bs=512 seek=64 conv=notrunc
# Copy u-boot.itb itself
doas dd if=u-boot/pinebook-pro-rk3399/u-boot.itb of=/dev/sdb bs=512 seek=16384 conv=notrunc

For rk3399-based boards, these steps should be quite similar. Other boards are an exercise left to the reader.

=== Installing Alpine ===

Insert the SD card into the ARM board, and turn it on. At this point, you should continue the general installation process as described in the [[Installation#Installation Step Details]].

{{Note|Installing packages with `apk` fails with a certificate warning if the system time is too far off, i.e. by default on boards without an internal real time clock (RTC). So make sure to first adjust the clock properly.}}

== Board-specific notes for supported boards==

=== Raspberry Pi ===
{{Main|Raspberry Pi}}

List of all Raspberry related [[:Category:Raspberry|Articles]].

=== Wandboard ===

Follow the steps above on [[Alpine_on_ARM#Preparing installation media|Preparing installation media]]. To install u-boot into the SD card, use:

dd if=u-boot/wandboard/SPL of=/dev/sdX seek=1 bs=1k
dd if=u-boot/wandboard/u-boot.img of=/dev/sdX seek=69 bs=1k

Finally, put the SD card in the Wandboard and boot it with a serial console connected. The board should now boot from the SD card.

=== Pine64 A64 LTS ===

Use the "Generic ARM aarch64" image. Install u-boot using:

dd if=u-boot-sunxi-with-spl.bin of=/dev/SDX bs=1024 seek=8</code>

Decompress (<code>gunzip</code>) the kernel image (<code>boot/vmlinuz-lts</code>) as the device's u-boot can't boot from a compressed kernel

=== Libre Computer "Le Potato" ===

For this system to boot at all, it must have an SD card with the bootloader in sector 1. This can't coexist with a GPT partition table. You will have to prepare the SD card manually from another machine:

* Use e.g. <code>fdisk</code> to create an MBR (DOS) disklabel. Leave at least 1 MB before the start of the first partition. Create one partition of type EFI and at least one of type Linux. For example:

Device Boot Start End Sectors Size Id Type
/dev/sdc1 * 2048 1050623 1048576 512M ef EFI (FAT-12/16/32)
/dev/sdc2 1050624 9005055 7954432 3.8G 82 Linux swap / Solaris
/dev/sdc3 9005056 122136575 113131520 53.9G 83 Linux

* Find bootloader binaries here: [https://boot.libre.computer/ci/ Libre Computer]
* Copy to SD card: <code>sudo dd if=aml-s905x-cc of=/dev/sdTARGET bs=512 seek=1</code>
* With this SD card in the Potato, it should now be possible to boot a (separate) USB stick containing any of the aarch64 ISO images. The rest of the steps should be done from the Potato:
* Format the partitions (device names will have changed):

mkfs.ext4 /dev/mmcblk1p3
mkfs.vfat /dev/mmcblk1p1

* Mount the partitions:

mount /dev/mmcblk1p3 /mnt
mount /dev/mmcblk1p1 /mnt/boot

* Use <code>setup-disk /mnt</code> rather than <code>setup-alpine</code>, to avoid rewriting the disklabel and damaging the bootloader.

=== More specific guides ===

* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Odroid-C2]]
* [https://github.com/rickyrockrat/nanopi-alpine NanoPi Neo build script]
* [[A20 OLinuXino Lime2]]

== Installing Alpine on boards without full support ==

{{Style}}

If you have, for example, an armv6/armv7 board that is not fully supported, but whose SoC is already supported by the mainline kernel and uboot, then it's still possible to install Alpine. It may involve a couple more manual steps.

===Requirements===

* Alpine's forked uboot to support tarballs (fabled?)
* serial console
* crosscompiler/toolchain if you can not compile natively

===The embedded world===

A lot of the SoCs have their own way of doing things, although they use uboot and Linux kernel but often they are heavily modified to suit easy flashing of "ROMs" or other unknown reasons, e.g. Rockchip's notion "partition" are neither DOS nor GPT partitions.
Here, we will try to install Alpine in a more standard way, like on the x86 platform, with either DOS or GPT partitions. To boot this, you will most likely have to install/flash the mainline uboot, which can be non-destructive if you can load it from external storage.

===Storage===

One can load uboot from the following block devices if it's supported.

* NAND
* eMMC
* SD card
* USB

===Power on===

Some SoCs need both SPL and uboot, you need to check uboot for your board. Most (if not all) boards boots from the internal storage first (either NAND or eMMC) you will have to check documentation of your board if you wish to boot the SPL/uboot from SD/USB.

One can view SPL+uboot as BIOS and boot-loader on PC. Think that you could put the BIOS on an external storage :D

Once you have loaded the "standard" uboot, things are more or less like on x86.

===Booting Linux kernel===

* uboot uses extlinux.conf file to locate the kernel/initramfs/... just like syslinx, you need to put that file on the partitions which is marked bootable in the /boot directory
* there should be an extra line "FDTDIR" which points to the DTBs
e.g.
<pre>
label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img
</pre>

== Using QEMU ==

<pre>
qemu-system-arm -M vexpress-a9 -kernel zImage -initrd initramfs-grsec -dtb vexpress-v2p-ca9.dtb -hda hda.img -serial stdio
</pre>

== See also ==

* [[DIY_Fully_working_Alpine_Linux_for_Allwinner_and_Other_ARM_SOCs|DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [http://www.armadeus.org/wiki/index.php?title=Kernel-with-device-tree dtb (Device Tree Binary)]
* [https://forum.odroid.com/viewtopic.php?t=30459 Odroid-C2] 2018 ''([https://archlinuxarm.org/platforms/armv8/amlogic/odroid-c2 ARMv8, AArch64]; [https://forum.odroid.com/viewtopic.php?f=138&t=32608 Alpine Linux custom build])''
* [https://github.com/tolstoyevsky/pieman Pieman]
* [https://kernelci.org/soc/ <s>Available</s> SoCs]
* [https://wiki.postmarketos.org/wiki/About_postmarketOS About postmarketOS]

[[Category:Hardware]]
[[category:ARM]]

DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs

2026-01-07T18:44:43Z

John3-16: 1. Reordered 'Style', 'Move' and 'Obsolete' boxes in order of priority; 2. Added comment to 'Move' box that recommends renaming page: 'Edit: Another contributor proposes merging page with Alpine on ARM instead.'; 3. /* See also */ Added heading to this preexisting section; 4. Added two /*See also */ entries; 5. Style amendment.

{{TOC right}}
{{Obsolete|The article needs to be updated to cover supported versions of Alpine. Looks like it was written for something older than 3.10.9}}
{{Move|ARM SoCs|Edit: Another contributor proposes merging page with [[Alpine_on_ARM|Alpine on ARM]] instead.}}
{{Style}}

THIS WORKS - TESTED

''Please dont hesitate to contact me at atlury@gmail.com or on oneinsect@gmail.com.''

'''''MAINLINE KERNEL with MAINLINE U-Boot'''''

== Prologue ==

* Please note that most of the below is specific to NanoPi M1 but can be extended to any ARM Soc with understanding
* NanoPi M1 and Orange Pi PC are very similar except the Orqange Pi PC has 512MB more RAM. They have similar specifications (USB, Ethernet, I/O etc.)

Sometimes these SOCs are always being fed with a constant 1.3V, e.g. the NanoPi M1 or an Orange PI One. However, an Orange Pi PC has a programable voltage generator than can reduce the voltage.

A primitive voltage regulator feeds the H3 all the time with 1.3V on some boards. In this mode, throttling is rather inefficient since temperatures does not decrease much when only the clock speed is reduced. Therefore, expect severe performance problems unless you use a large heatsink and fan.

Sometimes you have to modify your dts file if your board has a fixed voltage regulator to limit the temperature and prevent the board from completly burning out when you are not using a heat-sink. However, I would suggest you use some kind of passive/active cooling for H3 boards.

At the time of this writing, the NanoPi M1 still doesnt have its own .dtb file, hence we use a similar board's .dtb file (Orange Pi PC).

You are free to try legacy kernels. The process may vary a bit, please see linux-sunxi.org for more information and links.

'''Your SOC may not be supported by a mainline kernel. However, you can still use alpine linux.
'''

Lots of people are writing .dtb files. For example, below is a mainline kernel dts configuration for passive cooling of H3 based boards with a fixed voltage regulator

https://github.com/megous/linux/wiki/Fixed-voltage-regulator-test

Written for the Orange Pi One. Treats it as if it had a fixed voltage regulator and limits the temperature to ~75°C during stress test. You are free to play around. The internet is huge. Hang out in the IRC channels.

There is a workaround for issues where at times the display doesn't show up if you use say, a DVI to HDMI converter, etc. Suggest you use VGA to HDMI or play around with the settings of boot.scr and other files.

'''''We expect as the Alpine linux kernel versions progress further, you will be able to use Alpine linux directly without recompiling your own kernel, initramfs files etc'''''

== Comprehensive Introduction ==
Why do we need alpine linux when there are so many xyz distros available? Well it is one the most lightweight platforms with hot swap support for SD-cards and USB devices. There are options for allocation of SD-card free space for application storage.

There are possibilities to completely upgrade a device running remotely with minimum downtime. Console logins are possible with USB null modems for field servicing. Most importantly you can be rest assured that it can survive against power cuts, restarts. For devices without onboard mmc, especially working on sd-card its way more important.

The philosophy of commit only when required, keeps the entire OS read-only and in-memory without touching the storage at all. Thus devices can survive for longer times without crash.

Arm devices unlike x86 dont come with bios in general. BIOS in x86 PCs is generally, a firmware configuring and connecting the hardware to the operating system and it offers support for a variety of OS and supports new OS versions.

ARM use a different approach involving a boot loader for hardware configuration and operating system start-up. The boot loader is developed specifically for the application, adapted to one well-defined hardware SOC configuration, one operating system and only one version of it, which means you cannot probably use it for other SOCs without significant changes.

We here generally talk about Allwinner especially H3 SOCs but you could probably apply this philosophy to other SOCs. The nanopi m1, Orange pi pc and Orange pi lite are only around $10 making them great home servers, firewalls for lowest possible cost.

A linux os cannot be started just like that on an ARM Device, without a small amount of machine specific code to initialize that system.

There are typically 4 stages involved in the ARM Device boot-up process

* (stage 1) ROM - Reads from initialized persistent storage (selected by boot mode), loads SPL into internal Ram
* (stage 2) SPL Loader - SPL once loaded does additional setup and loads from persistent storage bootloader (u-boot) into DDR RAM
* (stage 3) U-boot - U-boot once loaded continues the processor setup and reads the Linux Kernel into DDR RAM
* (stage 4) Kernel - Once Kernel is loaded, it boots Linux and initializes the user run time environment

The first stage of the boot process is the Secondary Program Loader (SPL). This preliminary piece of code is responsible for board initialization, loading the u-boot binary (“secondary program”) and handling the control flow over to the u-boot main program. It is device specific, and is often provided as a closed source binary blob by the SoC vendor.

The secondary program loader (SPL) and the u-boot binary reside in a special on-board flash memory region or on the first sectors of the uSD/eMMC card. Arm devices use microSD or eMMC modules for storing the SPL and u-boot binary

At the second stage of the boot process, the u-boot main program is executed. U-boot first looks for a custom environment stored at a reserved space on the microSD or eMMC module, or falls back to the compile time default environment if needed. At this time, you can interrupt the automatic boot process by pressing a key on your serial console, which starts an interactive u-boot shell. The u-boot variable called '''bootdelay''' specifies the number of seconds to wait for a keypress before continuing automatic boot.

The automatic boot process executes a special u-boot macro, called bootcmd, which loads and executes the following procedures:

1. (opt.) a custom u-boot environment: uEnv.txt
2. (opt.) a precompiled u-boot macro: boot.scr
3. the kernel image, e.g. vmlinuz
4. (opt.) the device tree binary, e. g. .dtb
5. (opt.) the initial ramdisk, e. g. initramfs

The third stage is the loading of the Linux kernel. However, before the Linux kernel takes control, u-boot passes a command line to the kernel containing essential parameters.

For example in u-boot you could set bootargs for it pass to the kernel some parameters

* setenv bootargs /boot/vmlinuz-4.6.0-rc1-sunxi earlyprintk modules=loop,squashfs,sd-mod,usb-storage modloop=/boot/modloop-sunxi console=${console} rootwait panic=10

Parameters can be viewed after the operating system has booted by typing the following into a Terminal window (just an example):

* cat /proc/cmdline root=/dev/mmcblk0p2 rootwait rw console=ttyS0,115200n8 console=tty0 no_console_suspend vdaccfg=0xa00 logo=osd1,loaded,0x7900000,720p,full dmfc=3 cvbsmode=576cvbs hdmimode=1080p m_bpp=32 vout=hdmi disablehpd=true

The kernel initializes the hardware, mount the root file-system (according to the root=.. kernel parameter) and passes the control flow to /sbin/init.

The Linux kernel consists of the following components:

* Kernel image 32 bit platform: <boot-partition>/zImage or <boot-partition>/uImage, depending on your u-boot's capabilities and configuration
* Kernel image 64 bit platform: <boot-partition>/Image
* Device tree binary, a low level device description, specific to your device (<boot-partition>/<board>.dtb)
* Kernel modules (/lib/modules/<kernel-version>/*)
* Device firmware (/lib/firmware/*)
* Kernel C header files (/usr/include/linux)

These components are build out of the kernel sources with the help of the make utility. Usually the kernel image and the device tree binary are loaded from a small vfat boot partition (mounted as /boot or /media/boot), whereas the rest resides in the root file system.

However for our case here, we will have one raw u-boot sector followed by a large fat partition

Each stage adds functionality. It is important to note that SPL, U-Boot and the Linux Kernel are all statically linked to start running at specific locations from a memory map defined by the CPU. That memory map is nothing but a layout that defines where both internal memory and DDR are mapped to.

In here we are concerned with SD-Cards, and depending on how the SD card is connected, the location to where to write the data to can be different.

OKAY WAIT!!! WRITING DATA???

Dont be confused, yes you will need to compile from source the SPL Loader and write it to SD-Card in a particular way and then compile u-boot from source and write it in a particular and same goes for the rest. Otherwise how will you boot our favorite alpine linux?

But where do you get the sources? Generally if the SOC is supported in Linux (its called mainline) you can directly use the latest kernel, otherwise you will need to get the sources from the SOC manufacturer.

Below is a SD-CARD layout for typical Allwinner which generally combine U-boot with the SPL loader from block 8. This then loads initramfs etc.

"start" is a 1k-block number here. (Multiply it by two to get the corresponding sector number - assuming 512 byte sectors). This layout works generally for Linux Mainline Kernels 4.x and above

{| class="wikitable"
! start
! size
! usage
|-
| 0 || 8KB || Unused, available for partition table
|-
| 8 || 1024KB || Initial SPL loader + u-boot (just burn using dd)
|-
| 1024 || till end || vmlinuz + initramfs + modloop + dtb + Alpine apks folder (format vfat + enable boot flag, preferred from 2048)
|}

'''Please noted in general the third fat partition is from 2048 till end'''

Notice that while discussing above, I told there are generally four stages, I have infact combined SPL with U-boot and shown as one stage; indeed it is now possible to generate a single file say '''"u-boot-sunxi-with-spl.bin"''' while compiling.

And yes, you saw it right, the partition that holds vmlinuz eta al is actually fat and no we will NOT have any issues with symbolic links etc. Yes its not your typical rootfs.

'''The idea is that Alpinelinux beautifully loads and compresses into memory the entire OS and maintains it there, so aspects of symbolic links issues etc never come into picture, as the fat partition is never touched and whenever any changes occur and if and only they are committed, they are saved in a pre-compressed tar.gz archive, saved and then loaded back on fly during the next boot'''

== Boot-loaders aka U-Boot ==
Let us begin. The first is to understand U-boot.

Distros like alpine linux for that matter any linux do not need to manipulate any kind of bootloader-specific
configuration data to indicate which storage device the system should boot from.

Distros simply need to copy the boot configuration files in an ext2/3/4 or FAT partition, mark the partition bootable (via
the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or any other bootloader) will find those boot files and execute them. This is conceptually identical to creating a grub2 configuration file on a desktop PC.

Note that in the absence of any partition that is explicitly marked bootable, '''U-Boot falls back to searching the first valid partition of a disk for boot configuration files'''. Other bootloaders are recommended to do the same, since I believe that partition table bootable flags aren't so commonly used outside the realm of x86 PCs.

U-Boot can also search for boot configuration files from a TFTP server. The standard format for boot configuration files is that of extlinux.conf, as
handled by U-Boot's "syslinux" (disk) or "pxe boot" (network).

U-Boot searches for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or pxelinux.cfg/default over the network.

One example extlinux.conf generated by the Alpine Linux installer is:
LABEL grsec
MENU DEFAULT
MENU LABEL Linux grsec
LINUX /boot/vmlinuz-grsec
INITRD /boot/initramfs-grsec
DEVICETREEDIR /boot/dtbs
APPEND BOOT_IMAGE=/boot/vmlinuz-grsec modules=loop,squashfs,sd-mod,usb-storage modloop=/boot/modloop-grsec console=${console}

Another example extlinux.conf is:
LABEL Linux Mailine 4.6RC2
LINUX /boot/vmlinuz-4.6.0-rc1-sunxi
INITRD /boot/initramfs-new.uImage
FDT /boot/sun8i-h3-orangepi-pc.dtb
APPEND BOOT_IMAGE=/boot/vmlinuz-4.6.0-rc1-sunxi modules=loop,squashfs,sd-mod,usb-storage modloop=/boot/modloop-sunxi console=${console}

== What to compile ==
What are you basically looking for? What files do you need to compile, how and where do you need to compile from? And where do you need to put them? How do you need to put them? Well dont worry we will cover them here.

You will need the following files (incase of mainline or 4.x latest kernels incase your SOC is supported - In our case yes Allwinner H3)
* U-boot bootloader (aka u-boot-sunxi-with-spl.bin file say for Orange pi pc Allwinner H3) - compiled separately
* Device specific .dtb file (in here called sun8i-h3-orangepi-pc.dtb) generated as part of your mainline kernel compilation
* Linux Kernel Image either uImage/zImage (In our case zImage called vmlinuz-4.6-rc1-sunxi)
* Initramfs file (what is it? you will learn as we progress)
* modloop file (what is it again? you will learn as we progress)
* boot.scr or extlinux.conf file for telling U-boot where from and how to find and load all above files into memory

'''Note that we will be using boot.scr going forward instead of extlinux.conf, u-boot generally searches /boot.scr or /boot/boot.scr'''

Incase of legacy kernels (3.x etc) you will need the following which we will not cover here
* uImage (linux kernel)
* script.bin (converted from fex format, notice if we have fex, we dont need dtb files here)
* ext4/ext3 rootfs file system
* U-boot bootloader etc

== Compiling U-boot ==
You can follow this process or compile it along with Armbian kernel in the next section. Assuming below that you are building on an x64 bit ubuntu 14.04 LTS

* git clone git://git.denx.de/u-boot.git

Determine your build target aka your board. Go to your u-boot tree and search in the directory configs/ for your board, the file name looks like <board_name>_defconfig. So, if your device is orange pi pc your build target is orangepi_pc_defconfig

* make CROSS_COMPILE=arm-linux-gnueabihf- <board_name>_defconfig

* make CROSS_COMPILE=arm-linux-gnueabihf- menuconfig (optional in-case you want to play with menuconfig)

* make CROSS_COMPILE=arm-linux-gnueabihf-

When compiling natively on ARM board, omit the CROSS_COMPILE=…

When the build is completed, there will be '''u-boot-sunxi-with-spl.bin''' available in your u-boot tree.

create a file boot.cmd and configure it as above.

== Compiling Kernel with .dtb file ==

The first and foremost thing to compiling a kernel is to verify your SOC is supported by mainline linux kernel. The kernel must also have these options enabled and compiled in, instead of a module (better)

CONFIG_SQUASHFS=y The squashfs 4.0 is in "misc" under "filesystems"

CONFIG_BLK_DEV_LOOP=y This is under "Device drivers" -> "Block devices" -> "Loopback device support"

* [*]Enable loadable module support --->
* Device Drivers --->Graphics support --->Frame buffer Devices --->[*]support for frame buffer devices --->[*]Simple framebuffer support
* Device Drivers --->Graphics support --->Console display driver support --->[*]Framebuffer Console support

simplefb is a quick and easy way to get a display up on a HDMI monitor is to build U-Boot with sunxi cfb console support and Don't forget to change your console in your boot.cmd/boot.scr to console=tty1 to enable the simple framebuffer driver.

Pickup stable release

* git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

or pick up the sunxi-next branch maintained with all the inclusions that have been accepted, merged and will be included in the next stable release

* git clone git://github.com/linux-sunxi/linux-sunxi.git -b sunxi-next

* make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- sunxi_defconfig

* make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig (you want to include above squashfs and blk_dev_loop with menuconfig)

to build run the following and after the compilation ends, you should have generated both the zImage in arch/arm/boot, and a device tree blob (.dtb) in arch/arm/boot/dts.

* ARCH=arm CROSS_COMPILE=<toolchain-prefix> make zImage dtbs

This device tree blob (or simply dtb) gives to the kernel the description of the hardware it's currently running on.

In device tree blob (dtb) goal, it's pretty similar to the FEX scripts that Allwinner uses, yet far more generic. Dont worry remember we shown fex files incase of legacy kernels (3.x etc) converted to script.bin.

Dtb allows to compile a single kernel image that will run on several platforms.

To identify the dtb file that you will use on your board, first look into arch/arm/boot/dts. You should see a whole bunch of them, most being irrelevant to us because targeting boards based on other ARM SoCs. All the sunxi dtb follow the pattern <family>-<soc>-<board>.dtb

If you have configured certain drivers as modules, you need to build and install these as well:

* ARCH=arm CROSS_COMPILE=<toolchain-prefix> INSTALL_MOD_PATH=<any-path-you-like> make modules modules_install

After the build succeeds, you can find the modules in the supplied INSTALL_MOD_PATH directory.

'''Armbian has an easy way of compiling kernel as well (just incase), so look below:''' - Till we fill this section with Alpine way of compiling things

* Create a VM Ubuntu 14.04 LTS x64 server image with 40GB of disk (dont need install any compilation tools, the scripts will download suitable)
* apt-get -y -qq install git
* git clone --depth 1 https://github.com/igorpecovnik/lib
* cp lib/compile.sh .
* vim compile.sh

Please make sure you have the following options as follows

KERNEL_ONLY="yes" //compile only kernel, u-boot and other packages and not buid complete OS image
KERNEL_CONFIGURE="yes" //to include your modules
CLEAN_LEVEL="make,images,debs"
KERNEL_KEEP_CONFIG="yes"

Note that you can add your patches in the patches folder. All patches must have file name extension .patch.

or use

* ./compile.sh BRANCH=dev BOARD=orangepih3 KERNEL_ONLY=yes PROGRESS_DISPLAY=plain COMPRESS_OUTPUTIMAGE=yes RELEASE=jessie

Let us go with first option. You will prompted to select board.

Select '''orangepih3''' and then select '''dev''' branch

Select your kernel config options as told above (squashfs modules etc).

Once the compilation is finished in the output folder you will notice the following files

'''DTB FILE'''
linux-dtb-dev-sunxi_5.07_armhf.deb -- untar it and it will contain boot/dtb-4.6.0-rc1-sunxi/sun8i-h3-orangepi-pc.dtb

'''UBOOT+SPL FILE'''
linux-u-boot-dev-orangepih3_5.07_armhf.deb -- untar it and it will contain usr/lib/linux-u-boot-dev-orangepih3_5.07_armf/u-boot-sunxi-with-spl.bin

'''VMLINUZ KERNEL'''
linux-image-dev-sunxi_5.07_armhf.deb -- untar it and it will contain boot/vmlinuz-4.6.0-rc1-sunxi

'''MODLOOP FILES'''
linux-image-dev-sunxi_5.07_armhf.deb -- untar it (it should ultimately be in lib/modules/4.6.0-rc1-sunxi)
linux-firmware-image-dev-sunxi_5.07_armhf.deb -- untar it (it should ultimately be in /lib/modules/firmware)

'''INITRAMFS FILES'''
linux-image-dev-sunxi_5.07_armhf.deb -- untar it (it should ultimately be in lib/modules/4.6.0-rc1-sunxi)
linux-firmware-image-dev-sunxi_5.07_armhf.deb -- untar it (it should ultimately be in /lib/firmware)

MAKE SURE YOU ALSO GET Generic ARM Image from http://www.alpinelinux.org/downloads/

EXTRACT THE tar.gz file and you will need the '''initramfs-grsec''' and the '''apk folder'''

Next proceed to below sections.

'''Alpinelinux is expected to have a bleeding edge release option soon along with LTS releases.'''

== Creating Initramfs File ==
The purpose of initrd and initramfs (also known, generically, as "initial RAM disk") is similar: they contain a minimal root file-system, along with some scripts. When the kernel boots, if it is instructed to use an initrd or initramfs (done with boot loader configuration) it unpacks the file in RAM, chroot()s into it, and run some predefined scripts. Finally, the "real" root file system is mounted, the kernel switches to it and the normal init process can begin.

Why do we need an initial RAM disk in the first place? You're probably wondering this if you use to build your own kernel with the necessary modules for your hardware built-in. In that case, you almost never need an initial RAM disk.

But many distributions have to ship a binary kernel that should work on most, or even all, different combinations of hardware, storage, file-systems, etc. They can't obviously build all the possible modules into the kernel. So they ship a minimal, generic kernel, and use an initial RAM disk that contains most hardware modules and some logic to detect which modules need to be loaded to be able to continue to boot the system normally (ie from the hard drive).

An initramfs contains at least one file called /init. This file is executed by the kernel as the main init process (PID 1). It has to do all the work. In addition, there can be any number of additional files and directories that are required by /init. They are usually files you'll also find on any other root filesystem, such as /dev for device nodes, /proc for kernel information, /bin for binaries, and so on. The structure of an initramfs can be simple, or it can be complicated, depending on what you are planning to do.

When the kernel mounts the initramfs, your target root partition is not yet mounted, so you can't access any of your files. That means there is nothing but the initramfs. So everything you need, everything you want, you have to include it in your initramfs. If you want a shell, you have to include it in your initramfs. If you want to mount something, you need a mount utility. If you need to load a module, your initramfs has to provide both the module, as well as a utility to load it. If the utility depends on libraries in order to work, you have to include the libraries as well. This seems complicated, and it is, because the initramfs has to function independently.

This means that it's possible to boot the kernel, load some modules and run some tasks (from the RAM disk), and finally start the normal boot process (/sbin/init etc.).

The initial RAM disk must contain a fully functional file system, including some essential programs and libraries.

For space reasons, small footprint binaries are usually used (eg ash, busybox, or klibc).

Once the initial RAM disk's job is over and the kernel has switched to the real root file system, the memory used by the RAM disk is freed.

As briefly mentioned, there are two types of initial RAM disk: initrd and initramfs. The main difference is that an initrd contain a raw filesystem image (eg ext2), while an initramfs contains a cpio archive (which, when expanded, produces a directory hierarchy). Note that there are quite a few other differences, not mentioned here.

In both cases, the image file is compressed (typically with gzip) and the kernel expands and mount it. All the recent Linux distribution that use an initial RAM disk use an initramfs image. initrd is being used less and less. To check if the file you're interested in is an initrd or an initramfs, you can decompress it and feed it to file:

* gunzip -c /boot/initrd-2.6 | file -

Output is as below and that file is a real initrd
/dev/stdin: Linux rev 1.0 ext2 filesystem data

Here's what you'd see with an initramfs:
* gunzip -c /root/initrams-grsec | file -

Note the output which says "SVR4 with no CRC" format which will be useful later.
/dev/stdin: ASCII cpio archive (SVR4 with no CRC)

Modify initramfs-grsec taken from the Generic ARM Image of Alpinelinux
---------
As said, an initramfs image is a compressed cpio archive, although the file name may sometimes be deceiving; sometimes it still has "initrd" in its name, and also many times it does not end in .gz or other suffixes that indicate compression:

* file /root/initrams-grsec

/boot/root: gzip compressed data, from Unix, last modified:..., max compression

Now cpio is an ancient (and a bit weird) archive format. When de-archiving, it needs to read the archive from standard input (GNU cpio also has a --file option to specify the file on the command line). The directory hierarchy is created in the current working directory. So:

* mkdir temp
* cd temp
* gunzip -c /boot/root/initrams-grsec | cpio -i
28293 blocks

* ls -l
total 64....
drwxr-xr-x 2 root root 4096 2016-04-28 14:16 bin
drwxr-xr-x 3 root root 4096 2016-04-28 14:16 dev
drwxr-xr-x 6 root root 4096 2016-04-28 14:16 etc
-rwxr-xr-x 1 root root 3355 2016-04-28 14:16 init
drwxr-xr-x 5 root root 4096 2016-04-28 14:16 lib/modules/4.6.0-rc1-sunxi
drwxr-xr-x 5 root root 4096 2016-04-28 14:16 lib/modules/firmware
drwxr-xr-x 2 root root 4096 2016-04-28 14:16 media
drwxr-xr-x 2 root root 4096 2016-04-28 14:16 newroot
drwxr-xr-x 12 root root 4096 2016-04-28 14:16 proc
drwxr-xr-x 3 root root 4096 2016-04-28 14:16 run

Now you can finally edit and change the contents at will (no space limitations, unlike initrd). When you're done, you have to recreate the compressed cpio archive. Again, cpio is a bit weird when archiving, because it wants to read the names of the files to archive on standard input (and writes the archive on standard output).

* Extract from linux-image-dev-sunxi_5.07_armhf.deb the /lib/modules/4.6.0-rc1-sunxi folder and copy it into the above extracted lib/modules dir.

* Note it may already contain a folder called "4.1.20-0-grsec", it is not required and you can delete it

* Extract from linux-firmware-image-dev-sunxi_5.07_armhf.deb /lib/firmware folder and copy it into the above extracted lib/modules dir

next you can do as follows:

* pwd

/root/temp

* find . | cpio -H newc -o | gzip -9 > /root/initramfs-sunxi
34207 blocks

The only catch is that the -H newc option must be specified because the cpio archive contained in the initramfs has to be in the (new) "SVR4 with no CRC" portable format, as we saw at the beginning. In case you're wondering, cpio can create archives in other formats: bin, odc, crc, tar, ustar, hpbin, hpodc are those listed in the info page for GNU cpio.

Note that the construct

* find . | something

is generally considered unsafe and to be avoided in shell scripting, because files could have newlines and control characters in them that could deceive the consumer of those filenames. This is generally not the case for filenames contained in an initramfs image, so it is "safe enough" to use here.

* change back to /root

* mkimage -n initramfs-sunxi -A arm -O linux -T ramdisk -C none -d initramfs-sunxi initramfs-sunxi-new

This will create a u-boot compatible ramdisk with its headers.

So your initramfs file is '''initramfs-sunxi-new'''

== Creating modloop File ==
The modloop file contains the folders like below...
* /modules/4.6.0-rc1-sunxi
* /modules/4.6.0-rc1-sunxi/kernel
* /modules/4.6.0-rc1-sunxi/arch
* /modules/firmware

If you run the following command on modloop-grsec or any other similar modloop file got from the Generic ARM Image of Alpinelinux
* file modloop-grsec

You will realize, it outpus as
Squashfs filesystem, little endian, version 4.0, xzy bytes, xyz nodes, blocksize: xzy bytes, created...

You can create a "squashfs-temp" directory and create a sub-dir "modules" and then copy above required files concerning your particular kernel from the above deb extracted sources of Armbian and you are good to go. Then just run the command below.

* mksquashfs [source folder] [SquashFS target file] -b 1048576 -comp xz -Xdict-size 100%
* mksquashfs squashfs-temp/ modloop-sunxi -b 1048576 -comp xz -Xdict-size 100%

Resulting file '''modloop-sunxi''' is ready for usage

Please understand that mksquashfs compresses using gzip (deflate) as default, but if the compression time doesn’t matter as much, you should use the xz (LZMA2) option of more recent SquashFS version. Yes please use xz.

The command above activates xz using the highest possible compression options and the highest possible blocksize (1 MiB instead of the default 128 kiB). Therefore the process of creating the SquashFS file is slower than if using default options, but the resulting file is much smaller and might be (depending on disk IO time etc) a bit faster. LZMA2 is a highly asymmetric compression algorithm, so decompression is much faster than compression

The command compresses the entire source folder into the SquashFS target file.

Make sure that the SquashFS target file doesn’t exist before using this command. If it already exists, mksquashfs tries to update it, but this might yield undesirable results (I didn’t check that, it probably only produces a lot of error messages but a valid output file)

You can mount the resulting file using this command (assuming the target folder exists and is empty):
* mount [SquashFS file] [folder you want to mount it in]

If this command fails, you might need to specify some options explicitly:
* mount -o loop -t squashfs [SquashFS file] [folder you want to mount it in]

If you want to auto-mount the SquashFS, you can also add an _/etc/fstab _entry like this:
* [SquashFS file] [folder you want to mount it in] squashfs auto,defaults 0 0

== How to burn to SD Card ==
Let us write to the SD-Card, I will assume here that you already have compiled your kernel, u-boot and want to move forward.

When we need to actually put things on the SD card, be careful with dd it can and will wipe your hard disk if you make a mistake. In my case I had an SD card reader so I set things to point at that slot only by using the by-id links from udev. These by-id links which include the serial number which helped to avoid mistakes. The following commands assume you have done the same and are using by-id links.

In linux blank the first 1MB of the card using the following (my sd-card is /dev/sda1

* '''dd if=/dev/zero of=/dev/sda bs=1M count=1'''

But you need to be careful when using dd on special files (i.e., devices).

For example, the below command will write one tape block of 1024 bytes;

* dd if=(whatever input) of=(a magnetic tape device) bs=1024 count=1

However, the below command will write 1024 small blocks of one byte each

* dd if=(whatever input) of=(a magnetic tape device) bs=1 count=1024

These are not the same; the 1024 small blocks will take up more room on the tape than the one large block, because of inter-record gaps, and may cause problems for reading the tape.

Now Assuming you have got the file u-boot-sunxi-with-spl.bin, it just has to be burned to sd card using the following command:

* '''dd if=u-boot-sunxi-with-spl.bin of=/dev/sda bs=1024 seek=8'''

Sometimes depending on how you compile; you can generate spl and u-boot separately (it is not recommended by me) you can install the components separately using

* dd if=spl/sunxi-spl.bin of=/dev/sda bs=1024 seek=8
* dd if=u-boot.img of=/dev/sda bs=1024 seek=40

Please note, if you are using old source (v2013.07 or earlier, then the procedure is slightly different)

* dd if=spl/sunxi-spl.bin of=/dev/sdX bs=1024 seek=8
* dd if=u-boot.bin of=/dev/sdX bs=1024 seek=32

Typically for understanding, this is how the layout for SD-Card in above cases is;

{| class="wikitable"
! start
! size
! usage
|-
| 0 || 8KB || Unused, available for partition table etc.
|-
| 8 || 32KB || Initial SPL loader (8 to 24KB prior to 2013.07 and earlier)
|-
| 40 || 504KB || U-Boot (32KB to 512KB for 2013.07 and earlier)
|-
| 544 || 128KB || environment
|-
| 672 || 352KB || reserved
|-
| 1024 || - || Free for partitions
|}

Remember to leave sufficient space for all u-boot files when partitioning the card. The u-boot will not have any partition type defined. Recommended to have first fat partition start at sector 2048 (1MB)

* '''Next Using fdisk, create a new primary partition on the card (so far there are no partitions, only uboot has been burned on the card)'''
* '''Set the starting sector of the card as 2048'''
* '''Now install fat file system on the newly created partition by running mkfs.fat /dev/sda1'''
* '''Using fdisk, set the bootable flag of the partition'''

When setting the bootable flag of the partition, to create a FAT32 partition, if you are using fdisk, the FAT32 partition type is called W95 FAT32 (LBA) and its ID is 0xc

You can rename the sd-card as rootfs...

Please note that with recent U-Boot it's fine to use ext2/ext3/ext4 as boot partition, or as in our case fat file-systems in the any partition.

--------------------------------------------------------------------
There is debug serial port which you can use to connect to PC using putty set @ 115200 kbps. You should able to watch the following.

U-Boot SPL 2016.03-armbian (Apr 08 2016 - 01:09:18)
DRAM: 512 MiB
Failed to set core voltage! Can't set CPU frequency
Trying to boot from MMC1
U-Boot 2016.03-armbian (Apr 08 2016 - 01:09:18 +0530) Allwinner Technology
CPU: Allwinner H3 (SUN8I 1680)
Model: Xunlong Orange Pi PC
I2C: ready
DRAM: 512 MiB
MMC: SUNXI SD/MMC: 0
*** Warning - bad CRC, using default environment
In: serial
Out: serial
Err: serial
Net: No ethernet found.
starting USB...
USB0: USB EHCI 1.00
USB1: USB OHCI 1.0
USB2: USB EHCI 1.00
USB3: USB OHCI 1.0
USB4: USB EHCI 1.00
USB5: USB OHCI 1.0
scanning bus 0 for devices... 1 USB Device(s) found
scanning bus 2 for devices... 1 USB Device(s) found
scanning bus 4 for devices... 1 USB Device(s) found
Hit any key to stop autoboot: 0
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0:1...
Found /boot/extlinux/extlinux.conf
Retrieving file: /boot/extlinux/extlinux.conf
reading /boot/extlinux/extlinux.conf
232 bytes read in 29 ms (7.8 KiB/s)
1: Linux Mailine 4.6RC2
Retrieving file: /boot/uinitrd
reading /boot/uinitrd
**Unable to read file /boot/uinitrd
for failure retrieving initrd
SCRIPT FAILED: continuing...
USB device 0: unknown device
No ethernet found.
missing environment variable: pxeuuid
No ethernet found.
Retrieving file: /boot/extlinux/pxelinux.cfg/0
No ethernet found.
Retrieving file: /boot/extlinux/pxelinux.cfg/default-arm-sunxi
No ethernet found.
Retrieving file: /boot/extlinux/pxelinux.cfg/default-arm
No ethernet found.
Retrieving file: /boot/extlinux/pxelinux.cfg/default
No ethernet found.
Config file not found
No ethernet found.
=>

You can use the following to browser through the sd-card
* fatls mmc 0:1 boot

Next step would require simply copying the required files like boot configuration files, kernels etc in the above FAT partition (note there is only one FAT partition and it is marked as bootable) and U-Boot (or any other bootloader) will find those boot files and execute them.

* '''Assuming you have compiled vmlinuz-4.6.0-rc1-sunxi, you can create a directory called /boot in the root of micro-sd fat partition and copy it there.
'''

* '''Similarly create another folder called /boot/dtbs in the micro-sd card and copy the corresponding sun8i-h3-orangepi-pc.dtb file'''

* '''Similarly create boot.scr and copy it to the /boot folder'''

Basically while booting, U-boot will look for uEnv.txt or boot.scr in the first partition FAT or it will look for extlinux.conf. In here we will define boot.scr.

boot.scr contains needed uboot commands for loading kernel, initrd, setting kernel parameters and booting.

To create boot.scr first make a u-boot script boot.cmd with the u-boot commands you need for booting the system:

* setenv fdt_high ffffffff
* setenv machid 1029
* setenv bootargs earlyprintk /boot/vmlinuz-4.6.0-rc1-sunxi modules=loop,squashfs,sd-mod,usb-storage modloop=/boot/modloop-sunxi console=${console}
* load mmc 0:1 0x43000000 boot/dtbs/sun8i-h3-orangepi-pc.dtb
* load mmc 0:1 0x41000000 boot/vmlinuz-4.6.0-rc1-sunxi
* load mmc 0:1 0x45000000 boot/initramfs-sunxi-new
* bootz 0x41000000 0x45000000 0x43000000

Then translate this to a boot.scr by using the mkimage command

mkimage -C none -A arm -T script -d boot.cmd boot.scr

If you are using an older U-Boot (you shouldn't - Which?), you might require the following line, '''fdt_high ffffffff''' to keep the extracted kernel from overwriting the device tree configuration, however in general you dont require it.

setenv is for setting flags in the u-boot environment

The bootm/bootz command is used to start operating system images. From the image header it gets information about the type of the operating system, the file compression method used (if any), the load and entry point addresses, etc. The command will then load the image to the required memory address, uncompressing it on the fly if necessary. Depending on the OS it will pass the required boot arguments and start the OS at it's entry point.

The first argument to bootm is the memory address (in RAM, ROM or flash memory) where the image is stored, followed by optional arguments that depend on the OS. Load is nothing but loading the file into the RAM location.

Linux requires the flattened device tree blob to be passed at boot time, and bootm expects its third argument to be the address of the blob in memory.

Second argument to bootm depends on whether an initrd initial ramdisk image is to be used. If the kernel should be booted without the initial ramdisk, the second argument should be given as "-", otherwise it is interpreted as the start address of initrd (in RAM, ROM or flash memory).

To boot a Linux kernel image without a initrd ramdisk image, the following command can be used:

=> bootm ${kernel_addr} - ${fdt_addr}
If a ramdisk image shall be used, you can type:

=> bootm ${kernel_addr} ${ramdisk_addr} ${fdt_addr}
Both examples of course imply that the variables used are set to correct addresses for a kernel, fdt blob and a initrd ramdisk image

bootm <Linux uImage address> <mkimage wrapped ramdisk address> <device tree (dtb) address>

With the bootm/bootz command, U-Boot is relocating the images before it boots Linux such that the addresses above may not be what the kernel sees. U-Boot also alters the device tree to tell the kernel where the ramdisk image is located in memory (initrd-start and initrd-end). The command sets the r2 register to the address of the device tree in memory which is not done by the go command.

* ''Remember the console=${console} is important for you to interact with Alpinelinux once it boots''
* ''Instead of bootm, you use bootz''
* ''bootz basically starts a kernel image loaded at the given address in RAM along with other images ''
* ''You could possibly use 0x42000000 for your vmlinuz''
* ''the setenv machid commands asks nanopi m1 to report itself as orange pi pc as we loading orange pi pc dtb and kernel''
* ''all the above commands can also be run via the u-boot prompt and examined via the serial debug port without compiling boot.cmd''

People generally caution as below:

* ''The new kernels have CMA enabled by default. CMA is trying to reserve 192MB of physically contiguous memory between physical addresses 0x43000000 and 0x50000000. Using specifically this address range is important because CedarX hardware can work only with the first 256MB of physical DRAM (the base physical address of DRAM is 0x40000000). Now if initrd is placed by u-boot somewhere in the middle of this memory area (cutting it into two halves), then CMA can't reserve physically contiguous 192MB memory block there anymore. So the reservation of the CMA memory area fails at boot time:''

* ''The solution for this problem is not to place initrd anywhere between 0x43000000 and 0x50000000''

* '''Make sure you also create and copy the files modloop-sunxi, initramfs-sunxi-new to the /boot folder'''

* '''Lastly copy the apks folder to the root of the sdcard'''

The apks folder can be extracted by downloading the Generic ARM Image from http://www.alpinelinux.org/downloads/

Your SD-Card will look as below.
* /boot
* /apks

and under /boot directory, the following
* /boot/dtbs/sun8i-h3-orangepi-pc.dtb
* /boot/boot.scr
* /boot/initramfs-new
* /boot/modloop-sunxi
* /boot/vmlinuz-4.6.0-rc1-sunxi

== Conclusion ==

Practice, read, ask, hang out in the forums, channels and that is how you can learn. Dont worry about people not responding, they are not being rude, some could be busy, the ones that aren't will respond, finally dont be shy, drop an email to the mailing list.

== For debugging purposes only ==
need to paste tested scenarios

== See also ==
* [[Alpine_on_ARM|Alpine on ARM]]
* [https://blog.christophersmart.com/2016/10/23/building-and-booting-upstream-linux-and-u-boot-for-orange-pi-one-arm-board/ Building and Booting Upstream Linux and U-Boot for Orange Pi One ARM Board (with Ethernet) (2016)]
* {{Issue|17280}} - Orange Pi Zero 3 installation attempts of Alpine Linux v3.22 onwards - Gitlab reports.
* [https://linux-sunxi.org/ linux-sunxi.org]

[[category: ARM]]

Locale

2026-01-04T17:08:19Z

John3-16: /* See also */ Added [https://devurandom.xyz/tech/alpine_linux_stuff/#:~:text=russian%20console%20keymap devurandom.xyz - Russian console keymap]

[[Musl]] does not implement most of the locale features that glibc implements.

To Fix unicode defaults:
<code>sed -i 's/#unicode="NO"/#unicode="NO"\nunicode="YES"/' /etc/rc.conf</code>

Musl does not implement most of the locale features that glibc implements. The {{Pkg|musl-locales}} package provides [https://git.adelielinux.org/adelie/musl-locales translations] with varying degrees of completion. The below command installs a limited set of locales (languages) for musl (C library) generated console messages.
{{Cmd|# apk add musl-locales}}

The {{Pkg|musl-locales}} package also provides <code>locale</code> command. To list defined locales:
{{cmd|locale -a}}

This package includes a file {{Path|/etc/profile.d/00locale.sh}}. You'll need to re-login or source it manually for locales to work.

Copy the default locale settings file {{Path|/etc/profile.d/20locale.sh}} to a custom override file:{{Cmd|# cp /etc/profile.d/20locale.sh /etc/profile.d/20locale.sh.sh}}

Now custom override file can be edited with <Code>nano /etc/profile.d/locale.sh.sh</Code>.

== Language support ==



To pull in the translation packages for all installed packages: {{Cmd|# apk add lang}}

To list available hunspell dictionary packages, so that you relevant language dictionary can be added: {{Cmd|apk list hunspell*}}

To list translation packages for your specific(xy) language: {{Cmd|apk list *-xy *-xy-*}}

For example, to list translation packages for Portuguese(pt) language: {{Cmd|apk list *-pt *-pt-*}}

== See also ==

* [[Compose key]]
* [https://git.adelielinux.org/adelie/musl-locales Adelielinux musl-locales page]
* [https://devurandom.xyz/tech/alpine_linux_stuff/#:~:text=russian%20console%20keymap devurandom.xyz - Russian console keymap]

[[Category:Localization]]

ACF how to write

2026-01-03T04:19:13Z

John3-16: /* See also */ "Legacy ACF view patterns - web elements.lua – For historical reference only." Page was orphaned and is obsolete.

=How to Write an ACF=

For some examples please see the Web Configuration Framework projects in the Alpine Linux git repository

https://git.alpinelinux.org/

*acf-unbound - a simple ACF to control a service
*acf-awall - a slightly more complicated ACF for a firewall
*acf-provisioning - a complicated database application based on ACF
*...

==From <nil> to a running ACF example application==

===Step 1 - The Programming Language===
* ACF uses lua as its programming language. Have a look at [https://www.lua.org/ lua.org] before starting.

===Step 2 - The Application Environment===
* Setup the ACF web application by running ''setup-acf''

===Step 3 - Create A Development Directory===
* In your user home create a directory for your application (e.g. mkdir ~/myapp)
* And cd into it (e.g. cd ~/myapp)

===Step 4 - MVC, How Does It Affect My Coding?===
ACF is an MVC based framework. What does this mean to you? Your application is separated into three layers: Model, View, Controller - each of which may have one or more files.
* Controller: The event dispatcher. Most of the controller functionality is handled by the ACF mvc.lua code and some standard controllers (such as acf_www-controller.lua or acf_cli-controller.lua). For the controller layer of your new ACF package, you must export one lua function per action in a lua module named 'myapp-controller.lua'. The ACF controller code will interpret the user interaction to load your new controller and fire the appropriate action - the same-named function in your controller will be called.
* View: The view layer defines what your application will look like. For most actions, such as forms, your application can use the built-in automatic view generation. For others, you can link to standard views which are included in the acf-core package. For other actions, such as lists of data, you may create view files, each presenting a dynamic HTML page with only as much code as necessary to display the data you receive from the controller.
* Model: The 'real work' is done in the Model (e.g. modifying config files, starting/stopping services etc.). Each action exported by your controller will call into model functions to retrieve data and carry out actions.

===Step 5 - The Example Files To Start With===
Now let us have a look at the files we need to place into our application directory:

* config.mk
* Makefile
* myapp-controller.lua
* myapp-model.lua
* myapp.roles
* myapp.menu

'''config.mk:'''
For use with the Makefile. Just copy/paste it. We will look at it later.
prefix=/usr
datadir=${prefix}/share
sysconfdir=${prefix}/etc
localstatedir=${prefix}/var
acfdir=${datadir}/acf
wwwdir=${acfdir}/www
cgibindir=${acfdir}/cgi-bin
appdir=${acfdir}/app
acflibdir=${acfdir}/lib
sessionsdir=${localstatedir}/lib/acf/sessions

'''Makefile:'''

The Makefile is called to install our ACF application so that we can see it working.
APP_NAME=myapp
PACKAGE=acf-$(APP_NAME)
VERSION=0.1

APP_DIST= \
myapp* \

EXTRA_DIST=README Makefile config.mk

DISTFILES=$(APP_DIST) $(EXTRA_DIST)

TAR=tar

P=$(PACKAGE)-$(VERSION)
tarball=$(P).tar.bz2
install_dir=$(DESTDIR)/$(appdir)/$(APP_NAME)

all:
clean:
rm -rf $(tarball) $(P)

dist: $(tarball)

install:
mkdir -p "$(install_dir)"
cp -a $(APP_DIST) "$(install_dir)"

$(tarball): $(DISTFILES)
rm -rf $(P)
mkdir -p $(P)
cp $(DISTFILES) $(P)
$(TAR) -jcf $@ $(P)
rm -rf $(P)

# target that creates a tar package, unpacks is and install from package
dist-install: $(tarball)
$(TAR) -jxf $(tarball)
$(MAKE) -C $(P) install DESTDIR=$(DESTDIR)
rm -rf $(P)

include config.mk

.PHONY: all clean dist install dist-install

'''myapp-controller.lua:'''
-- the myapp controller
local mymodule = {}

mymodule.default_action = "myaction"

mymodule.myaction = function(self)
-- self.clientdata contains the user data
-- self.model points to our model
-- use the helper function to implement our form
return self.handle_form(self, self.model.getdata, self.model.setdata, self.clientdata, "Submit", "Edit data", "Data Submitted")
end

return mymodule

'''myapp-model.lua:'''
-- acf model for myapp
local mymodule = {}

local cfgfile = "/tmp/myfile"

-- This function returns a cfe (table of values) containing the file's
-- value as a string. If the file does not exist, we'll
-- simply return "" (an empty string, but NOT nil)
mymodule.getdata = function(self, clientdata)
local retval = cfe({ type="group", value={}, label="Data" })
retval.value.data = cfe({ type="longtext", label="Data" })

local fileptr = io.open(cfgfile, "r")
if fileptr ~= nil then
retval.value.data.value = fileptr:read("*a") or ""
fileptr:close()
end

return retval
end

-- This function will write new contents into our file
-- The newdata parameter receives the same cfe as returned by getdata, now with the user data filled in
mymodule.setdata = function(self, newdata, action)
fileptr = io.open( cfgfile, "w+" )
if fileptr ~= nil then
fileptr:write(newdata.value.data.value)
fileptr:close()
else
newdata.errtxt = "Failed to save data"
end
return newdata
end

return mymodule

'''myapp.roles:'''
GUEST=myapp:myaction

'''myapp.menu:'''
# Cat Group Tab Action
Test MyApp MyAction myaction

===Step 6 - What Does It Do?===
This program just displays a <textarea> box and a "Submit" button. The user can enter text that is saved into a file once he presses "Submit".

====In Depth====
Now let us have a closer look at the different files' contents:

=====myapp-controller.lua=====
The controller is an event dispatcher. So, here you define all the actions that the user can call or that are defined in the menu. Each action is a separate function that will receive ''self'' as the only parameter.

In our case the action is ''myaction'' - a simple form.

This function can call the ''model's'' functions to update and/or retrieve data (e.g. self.model.getdata()).

Anything that this function returns will be passed on to the ''view''

=====myapp-model.lua=====
The functions defined in here can be accessed by the controller to update/set/retrieve data, start/stop services, basically do any 'real work'.

In our case, we have implemented the getdata/setdata functions required for a form.

The getdata function receives a copy of 'self', a clientdata table, and a string containing the submit action. It will generate a 'CFE' table defining the form and including the current data.

The setdata function is only called when the form is submitted, and it receives a copy of 'self' and the updated form 'CFE' now containing the submitted data. The setdata function will attempt to perform the action, returning the same form 'CFE'. If there is an error, it will fill in the errtxt field of the 'CFE'.

=====myapp.roles=====
This file determines which users have access to which controllers and views. A separate ''roles'' file is generally defined for each ACF. The format of the file is as follows:
group=controller:action[,controller:action]
Each line defines controller:action combinations that are permitted for a particular group. '''GUEST''' is a special group to which all users, including anonymous users, are members.

=====myapp.menu=====
In this file you define:
* '''The Category''' in which a menu entry for your program will appear
* '''The Group''' menu name under Category for this controller
* '''The Tab''' name on the controller page
* '''The Action''' with-in your controller that will be called once the user clicks on the menu entry or tab defined by Category, Group, and Tab.

===Step 7 - How To Get It Going?===
Once you have completed all the above mentioned steps, go on with:
* sudo make install (this will install your app)
* point your browser to <nowiki>https://ip-of-your-dev-host/</nowiki>

===More Info===
====Where is the View?====
The above example does not contain any code for a view. So, how is the action getting displayed?

For every action that you define in myapp-controller.lua, you can define a separate view file named: myapp-''action''-html.lsp

If there is no view file for a specific action, the application will look for a generic view file for the controller named: myapp-html.lsp

If that file does not exist, the ACF controller will attempt to display the 'CFE' using the built-in library functions. This works well for forms, and is what allows us to display our view here.

Here is a ''view'' file that displays our action using the built-in library functions. It looks exactly the same as when no view exists.

'''myapp-myaction-html.lsp:'''
<%
local form, viewlibrary, page_info, session = ...
htmlviewfunctions = require("htmlviewfunctions")

htmlviewfunctions.displayitem(form, page_info)
%>

The view receives the data to be displayed from the ''controller''. The view has access to the table returned by the controller action along with a helper library, a table of page information, and the session data ''(see the second line)''. The view can also load other libraries, but it should not directly access the ''controller'', ''model'', or any global variables.

====How to exchange data between model-view-controller?====
To exchange data between model, view, and controller ACF uses ''Configuration Framework Entities (CFEs)''.

Please see [[ACF_core_principles]] for further details on CFEs.

=See Also=
* [[Acf-core-0.15_Release_Notes]] - Separation between ACF functionality and web interface.
* [[Web_elements.lua|Legacy ACF view patterns - web elements.lua]] – For historical reference only.

[[Category:ACF]]

Web elements.lua

2026-01-03T04:10:24Z

John3-16: Added Obsolete box: refers to legacy 2012 version.

{{Obsolete|This version relates to the legacy Alpine Configuration Framework (ACF) (2012}}

=== render_table ===
'''INPUT:''' 
This library function required the following inputs/parameters.
* Element
** The element should be type 'table'
** Element could be: group, label, html, log, link, form
* Level
** Level should be a 'number'
'''OUTPUT:''' 
This library function deliverers the following output/parameters.
* HTML
** HTML formated output/elements
** The output is partially generated by html.lua
=== render_mainmenu ===
'''INPUT:''' 
This library function required the following inputs/parameters.
* menu
* prefix
* controller
* action
'''OUTPUT:''' 
This library function deliverers the following output/parameters.
* MainMenu (HTML)
** HTML formated output/elements
** The output is partially generated by html.lua
=== render_submenu ===
'''INPUT:''' 
This library function required the following inputs/parameters.
* menu
* group
* cat
* subcat
'''OUTPUT:''' 
This library function deliverers the following output/parameters.
* SubMenu (HTML)
** HTML formated output/elements
** The output is partially generated by html.lua

[[Category:Lua]]

Tutorials and Howtos

2026-01-03T03:57:45Z

John3-16: /* VPN */ Added Vpnc

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* Use [https://github.com/ifupdown-ng/ifupdown-ng/blob/main/doc/interfaces-vxlan.scd vxlan], if using [[Ifupdown-ng]] instead of [[VLAN]]
* [[Setting up a Home Router]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Fingerprint Authentication with swaylock]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi|Raspberry Pi main page]]
* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''
* [[RPI Video Receiver]]

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

== Security ==

* [[#Desktop security|Desktop security]] lists steps for securing Alpine Linux desktops
* [[Setting up a laptop]] page has detailed guidelines to configure a secured laptop
* [[Securing Alpine Linux|Secure Alpine Linux]] using Security Technical Implementation Guides (STIGs)

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]] ''(Simple and easy to use wiki, no database required)''
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[Moodle]] ''(Online Learning Management system)''

=== Database ===

* [[MariaDB]] or [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* Unbound
** [[Setting up unbound DNS server]]
** [[Using Unbound as an Ad-blocker]] ''(Setup ad blocking for your network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall ===

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[Zero-To-Awall]] -''AWall for dummies''
** [[How-To Alpine Wall]] - ''AWall for Shorewall users''
** [[Alpine Wall]] - ''AWall - Firewall management framework - Design Document''
* [[Iptables]]
* [[nftables]]
* [[Uncomplicated Firewall|Uncomplicated Firewall or UFW]]

=== HTTP and web services ===

* [[Althttpd]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎|Production LAMP system: Lighttpd + PHP + MariaDB/MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== VPN ===
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[IGMPproxy]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Tor]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[Vpnc]]

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system) [Deprecated]''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* [[ZFS]]
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux
* [[Runc]]

== [[Simple_Walkthrough]] ==
* [[About-virtualization-simple]]
* [[LXC_Alpinelinux_Simple]]
* [[Qemu-simple]]

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]
* [https://ww2.coastal.edu/mmurphy2/oer/alpine/ Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor]
* [[Michael's base installation procedure|Michael's base installation procedure]]
* [[Michael's cwm desktop (minimal)|Michael's cwm desktop (minimal)]]
* [[Michael's sway desktop (minimal)|Michael's Sway desktop (minimal)]]
* [[Sway_customization_guide|Sway customization guide]] ''(Tutorial re Sway config file basics)''
* [[Using Distrobox For VR Gaming|Using Distrobox For VR Gaming]]

Setting up a Home Router

2026-01-03T03:44:12Z

John3-16: Added /*See also */ : Setting up a wireless AP with udhcpd and NAT (page had been orphaned).

{{Expand|To include information on ipv6}}

This HowTo is written to indicate the basics necessary to get a simple router set up for a network. Unlike most HowTos, this will not form an exhaustive list of instructions, as a home router is not one piece of software, and not every piece of software listed here will be relevant to your specific requirements. Moreover, the individual pieces of software themselves, in particular firewalls, require configuration which requires documentation in their own right.

As such this HowTo will indicate the relevant pieces of software, and link to the corresponding documentation. It will also contain some more general guidance.

== Before You Start ==

=== You should know ===

This article presumes that you are familiar with the fundamentals of IP networks. In particular you should have a good understanding of the terms:

* IP Address
* Address Mask
* Subnet
* CIDR (Notation of the form 192.168.1.0/24)

==Enable Routing and Set Up Routes==

The clue is in the name that routing is at the heart of what a router does.

To enable routing, you will need to add a line
<code>net.ipv4.ip_forward=1</code> to the file /etc/sysctl.conf and then run
<code>sysctl -p</code> with administrative privileges.

If you have subnets managed by their own routers in your network, you may need to add [[How to configure static routes|static routing]].

Dynamic routing is an advanced topic which goes beyond the range of this HowTo.

==Configuring Network Interfaces==

Generally speaking, routers are in charge of their own IP addresses, as such you will need to understand how to [[Configure Networking#Static address configuration|configure static IP addresses on the interfaces]].

==Connecting to the Internet - pppd==

{{Warning|If you are planning on connecting your router directly to the internet, you should have a firewall in place. See next section.}}

If you are looking to connect your router directly to the internet without using the router from your ISP, then you will need to configure pppd. The documentation for pppd can be found [https://linux.die.net/man/8/pppd here].

On a practical note, it is helpful to download pppd and your firewall of choice using your ISPs provided router and configure them prior to connecting your home-made router to the internet directly.

==Firewalls==

Firewalls At the time of writing, there are three main firewall options available of which the author is aware:

* [[Uncomplicated Firewall|ufw - the uncomplicated firewall]]
* [https://wiki.nftables.org/wiki-nftables/index.php/Main_Page nftables]
* IPTables is also an option - but be advised that it is an older piece of software with a somewhat arcane syntax. It has been superseded by nftables.

==DHCP Server==

A DHCP server is responsible for assigning dynamic IP addresses to computers attached to your network.

If your network is small enough, and the constituent computers do not change regularly, you might consider sticking with static (manually) assigned IP addresses. However, beyond a certain size and/or if you have changing members of your network (for example, house guests using your wi-fi), then DHCP becomes quite important.

The only DHCP server that the author was able to install and operate from the default repositories at the time of writing was [https://dnsmasq.org/docs/dnsmasq-man.html dnsmasq.]

==Hosting Wi-Fi==

See [[How to setup a wireless access point]].

==See also==

* [[Wireless_AP_with_udhcpd_and_NAT|Setting up a wireless AP with udhcpd and NAT]]

[[Category: Networking]]

Remote Desktop Server

2026-01-03T03:13:16Z

John3-16: 1. Added 'X11vnc' stub. 2. Promoted 'Remmina as client' section to top-level, instead of being a server under 'Remote Desktop Server based on Vino and XRDP'; 3. Added intro for Remmina; 4. Amended soft link to startplasma-x11: should typically be done as user; 5. Assumption stated that 'community' is enabled instead of using @community tag; 6. Style/grammar amendments.

These guides assume that the community repo [[Enable_Community_Repository|has been enabled]].

== Remote Desktop Server Based on XRDP and xorgxrdp ==

This was tested and works for v 3.17.2 with [[Xfce]] as the desktop.

First ensure that the desktop is working without remote access (if feasible).

Install {{Pkg|xrdp}} and {{Pkg|xorgxrdp}}:

{{Cmd|# apk add xrdp xorgxrdp}}

Start the necessary services:

{{Cmd|# rc-service xrdp start
# rc-service xrdp-sesman start}}

After testing that this works, you may set the services to start automatically:

{{Cmd|# rc-update add xrdp
# rc-update add xrdp-sesman}}

That should be all that is needed to connect from a Windows client with its default "Remote Desktop" client. The xrdp configuration file though will contain several services that will not work, so to remove them, edit {{Pkg|/etc/xrdp/xrdp.ini}} and remove all lines from, and including: {{ic|[Xvnc]}} to the end.

Note: If you are using KDE, please a link as follows so that there is no screen after logging in:

{{Cmd|$ ln -s /usr/bin/startplasma-x11 ~/.xinitrc}}

{{ic|doas}} should only be used for that command if {{Path|~/.xinitrc}} is owned by root or by another user, but that would be atypical for a user-specific configuration.

{{Note|From v3.22 upwards, xrdp is broken in combination with KDE, because only Wayland is supported with KDE: [[https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.22.0|since v3.22]]
}}

== Remote Desktop Server based on Vino and XRDP ==

'''THIS DOES NOT WORK on 3.17.2 with Xfce - Not Yet Deleted in Case it helps others'''

First of all, make sure that you have a desktop environment properly installed (See: [[Desktop environments and Window managers]]).

Next, install {{Pkg|vino}} and {{Pkg|xrdp}} with the following command:

{{Cmd|# apk add vino xrdp}}

Replace the {{Path|/etc/xrdp/xrdp.ini}} file's content with:

{{Cat|/etc/xrdp/xrdp.ini|<nowiki>[globals]
bitmap_cache=yes
bitmap_compression=yes
port=3389
crypt_level=low
channel_code=1
max_bpp=24

[xrdp1]
name=Vino
lib=libvnc.so
ip=127.0.0.1
port=5900
username=ask
password=ask</nowiki>}}

If you want the XRDP service to start automatically, add the services to the default runlevel:

{{Cmd|# rc-update add xrdp
# rc-update add xrdp-sesman
# rc-update add vino}}

To start:

{{Cmd|# rc-service xrdp start
# rc-service xrdp-sesman start
# rc-service vino start}}

=== Misc ===

==== Disabling XRDP Notification and Confirmation ====

If you do not want the client confirmation before the session being accepted:

<code>export DISPLAY=:0.0</code>

{{Cmd|gsettings set org.gnome.Vino notify-on-connect false
gsettings set org.gnome.Vino prompt-enabled false
}}

== X11vnc ==
{{Main|X11vnc}}
[[X11vnc]] enables connection to the active X11 session, so one sees what is on the physical display, to include login screens and onscreen applications. Unlike certain VNC servers that launch a virtual desktop, it does not create an additional X session and is therefore leaner.

== Remmina as client ==
{{Draft}}
Remmina is a remote desktop client that can connect to servers such as x11vnc, XRDP, and Windows RDP.

[[Category:System Administration]]
[[Category:Security]]