Alpine Linux - User contributions [en]

User:Vixalien/Clevis

2025-01-12T22:45:06Z

Vixalien:

[https://github.com/latchset/clevis/ Clevis] is a tool that allows, among many other things, to automatically decrypt LUKS volume at boot-time automatically using the TPM without requiring the manual input of a password.

{{Warning|If you use Clevis to automatically decrypt your disk at boot, your computer will unlock automatically, and this can be a security issue}}

== Installation ==

To use clevis install the {{pkg|clevis}} package.

If you need the TPM functionality, you will also need to install {{pkg|tpm2-tools}} and {{pkg|tpm2-tss-tcti-device}}. See [https://gitlab.alpinelinux.org/alpine/aports/-/issues/15985 See issue]:

# apk add -t clevis-tpm tpm2-tools clevis tpm2-tss-tcti-device

== Testing ==

You may wish to encrypt some data using your TPM with clevis:

# echo 'hello, world' | clevis encrypt tpm2 '{}'

eyJhbGciOiJkaXIiLCJjbGV2aXMiOnsicGluIjoidHBtMiIsInRwbTIiOnsiaGFzaCI6InNoYTI1NiIsImp3a19wcml2IjoiQU80QUlETDZOQlp1dFktZUg2YjdNUUFtazNxNE5MTGRDYWFrM2tJUHBsOWtRUmlxQUJEaFFGSks0MWVWQXMtUElKbmsxUW9MS0hVVnhoQmM5RVlZZ1hfc1MzaS1EYUQ1aXZQdmZybUxSY25TZGxYRWtvSE1qN0lMekFvY29ZQ2FnRGNxczBYcVFCRkhqTkxFaW5PM3NySjAxTlo3QkExX2tnR0t1THVISC1pVUpESGZNQklnUFFsMzUyb3dSeFdPVUhuWnFiRk5rTU9WekVRS1ZTYUlUUlZtMEhnZHEwTWtpYV9HSjB2bGFXYkJtUE45SU1weGZXTTU3dGdGSnBRYXBobkNoZUsyLUkzeHNnY01rb2N3eUNnTzRZUnlZOXcxZGx4aVhxYURoc0xpcnJMV3E3SFFuZkRCVXlvU2hTWC0iLCJqd2tfcHViIjoiQUM0QUNBQUxBQUFFMGdBQUFCQUFJTlBYYkNWd3BNRUVnUkRGVF9VVVZ6c3Flb3dpWW5PSEZiVmZfV3ZHTUFTOCIsImtleSI6ImVjYyJ9fSwiZW5jIjoiQTI1NkdDTSJ9..F117H8zDNXxuOzxr.KCPhBegjQRx3Sv6uFg.yC9EbXhI8twv48oohl3KOw

The result will be a base-64 encoded string encrypted with your computer's TPM2 key. This means that the message can only be decoded from this current computer (or more precisely, the same TPM2 chip that encoded it).

# echo "eyJhbGciOiJkaXIiLCJjbGV2aXMiOnsicGluIjoidHBtMiIsInRwbTIiOnsiaGFzaCI6InNoYTI1NiIsImp3a19wcml2IjoiQU80QUlETDZOQlp1dFktZUg2YjdNUUFtazNxNE5MTGRDYWFrM2tJUHBsOWtRUmlxQUJEaFFGSks0MWVWQXMtUElKbmsxUW9MS0hVVnhoQmM5RVlZZ1hfc1MzaS1EYUQ1aXZQdmZybUxSY25TZGxYRWtvSE1qN0lMekFvY29ZQ2FnRGNxczBYcVFCRkhqTkxFaW5PM3NySjAxTlo3QkExX2tnR0t1THVISC1pVUpESGZNQklnUFFsMzUyb3dSeFdPVUhuWnFiRk5rTU9WekVRS1ZTYUlUUlZtMEhnZHEwTWtpYV9HSjB2bGFXYkJtUE45SU1weGZXTTU3dGdGSnBRYXBobkNoZUsyLUkzeHNnY01rb2N3eUNnTzRZUnlZOXcxZGx4aVhxYURoc0xpcnJMV3E3SFFuZkRCVXlvU2hTWC0iLCJqd2tfcHViIjoiQUM0QUNBQUxBQUFFMGdBQUFCQUFJTlBYYkNWd3BNRUVnUkRGVF9VVVZ6c3Flb3dpWW5PSEZiVmZfV3ZHTUFTOCIsImtleSI6ImVjYyJ9fSwiZW5jIjoiQTI1NkdDTSJ9..F117H8zDNXxuOzxr.KCPhBegjQRx3Sv6uFg.yC9EbXhI8twv48oohl3KOw" | clevis decrypt tpm2 '{}'

hello, world

== Encrypt a LUKS volume ==

{{Warning|Remember to add a backup password in case TPM unlocking fails using:

# cryptsetup luksAddKey /dev/sda1

}}

Use the following command to bind a LUKS volume to your TPM:

# clevis luks bind -d /dev/sda1 tpm2 '{}'

The {{ic|'{}'|}} contains the configuration. For example, you can use the following command to seal the LUKS key against UEFI settings AND the [[Secure Boot]] policy, meaning clevis will be unable to unlock the device if either the UEFI settings changes or the SecureBoot keys are changed, and you'll need to rebind the volume after inputting your backup password

'{"pcr_ids":"1,7"}'

See {{ic|'man 1 clevis-encrypt-tpm2'|}} for all possible configuration options.

== mkinitfs hook ==

After binding your LVM volume to your TPM, you may wish for it to be unlocked automatically when your device boots. Currently, this process is a bit tedious, but will hopefully be improved in the future.

=== mkinitfs feature ===

First, create the following files with the following content. They allow all the kernel modules and files needed to unlock LUKS devices with the TPM to be copied to the initramfs.

{{Cat|/etc/mkinitfs/features.d/clevis-tpm.modules|kernel/drivers/char/tpm
}}

{{Cat|/etc/mkinitfs/features.d/clevis-tpm.files|/bin/bash
/usr/bin/clevis
/usr/bin/clevis-decrypt
/usr/bin/clevis-decrypt-tpm2
/usr/bin/clevis-luks-unlock
/usr/bin/clevis-luks-common-functions
/usr/bin/jose
/usr/bin/tpm2_createprimary
/usr/bin/tpm2_unseal
/usr/bin/tpm2_load
/usr/bin/tpm2_flushcontext
/usr/lib/libjansson.so.4
/usr/lib/libjose.so.0
/usr/lib/libtss2-tcti-device.so.0
}}

Then, add the <code>clevis-tpm</code> feature to {{path|/etc/mkinitfs/mkinitfs.conf}}:

features="ata base cdrom ext4 keymap kms mmc nvme raid scsi usb virtio '''clevis-tpm'''"

Don't forgot to regenerate your initramfs

# apk fix kernel-hooks

=== init script ===

Now, everything that's needed to unbind the LUKS device with the TPM is now included in the initramfs. All that's needed is to actually unlock the device in the initramfs. Since [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/issues/18 it's currently not possible to run custom scripts in the init], you will need to manually edit the init and allow it to decrypt the disk with clevis if possible.

{{Warning|This part of the guide has not been tested yet. You have been warned!}}

Edit the file {{path|/usr/share/mkinitfs/initramfs-init}}, and replace the text:

<pre>
if [ -n "$KOPT_cryptroot" ]; then
cryptopts="-c ${KOPT_cryptroot}"
if [ "$KOPT_cryptdiscards" = "yes" ]; then
cryptopts="$cryptopts -D"
fi
if [ -n "$KOPT_cryptdm" ]; then
cryptopts="$cryptopts -m ${KOPT_cryptdm}"
fi
if [ -n "$KOPT_cryptheader" ]; then
cryptopts="$cryptopts -H ${KOPT_cryptheader}"
fi
if [ -n "$KOPT_cryptoffset" ]; then
cryptopts="$cryptopts -o ${KOPT_cryptoffset}"
fi
if [ "$KOPT_cryptkey" = "yes" ]; then
cryptopts="$cryptopts -k /crypto_keyfile.bin"
elif [ -n "$KOPT_cryptkey" ]; then
cryptopts="$cryptopts -k ${KOPT_cryptkey}"
fi
fi
</pre>

And replace it with:

<pre>
if [ -n "$KOPT_cryptroot" ]; then
cryptopts="-c ${KOPT_cryptroot}"
clevisopts="-d ${KOPT_cryptroot}"
if [ "$KOPT_cryptdiscards" = "yes" ]; then
cryptopts="$cryptopts -D"
fi
if [ -n "$KOPT_cryptdm" ]; then
cryptopts="$cryptopts -m ${KOPT_cryptdm}"
clevisopts="-n ${KOPT_cryptopts}"
fi
if [ -n "$KOPT_cryptheader" ]; then
cryptopts="$cryptopts -H ${KOPT_cryptheader}"
fi
if [ -n "$KOPT_cryptoffset" ]; then
cryptopts="$cryptopts -o ${KOPT_cryptoffset}"
fi
if [ "$KOPT_cryptkey" = "yes" ]; then
cryptopts="$cryptopts -k /crypto_keyfile.bin"
elif [ -n "$KOPT_cryptkey" ]; then
cryptopts="$cryptopts -k ${KOPT_cryptkey}"
fi
fi

if [ -n "$clevisopts" ]; then
clevis luks unlock $clevisopts
fi
</pre>

== See also ==

* [https://github.com/latchset/clevis/ Project homepage]
* [https://wiki.archlinux.org/title/Clevis Clevis on ArchWiki]
* [https://github.com/latchset/clevis/blob/master/src/initramfs-tools/hooks/clevis.in clevis initramfs-tools hook]
* [https://github.com/kishorv06/arch-mkinitcpio-clevis-hook mkinitcpio-clevis-hook's homepage]

User:Vixalien/Clevis

2025-01-12T22:26:07Z

Vixalien:

[https://github.com/latchset/clevis/ Clevis] is a tool that allows, among many other things, to automatically decrypt LUKS volume at boot-time automatically using the TPM without requiring the manual input of a password.

{{Warning|If you use Clevis to automatically decrypt your disk at boot, your computer will unlock automatically, and this can be a security issue}}

== Installation ==

To use clevis install the {{pkg|clevis}} package.

If you need the TPM functionality, you will also need to install {{pkg|tpm2-tools}} and {{pkg|tpm2-tss-tcti-device}}. See [https://gitlab.alpinelinux.org/alpine/aports/-/issues/15985 See issue]:

# apk add -t clevis-tpm clevis tpm2-tss-tcti-device

== Testing ==

You may wish to encrypt some data using your TPM with clevis:

# echo 'hello, world' | clevis encrypt tpm2 '{}'

eyJhbGciOiJkaXIiLCJjbGV2aXMiOnsicGluIjoidHBtMiIsInRwbTIiOnsiaGFzaCI6InNoYTI1NiIsImp3a19wcml2IjoiQU80QUlETDZOQlp1dFktZUg2YjdNUUFtazNxNE5MTGRDYWFrM2tJUHBsOWtRUmlxQUJEaFFGSks0MWVWQXMtUElKbmsxUW9MS0hVVnhoQmM5RVlZZ1hfc1MzaS1EYUQ1aXZQdmZybUxSY25TZGxYRWtvSE1qN0lMekFvY29ZQ2FnRGNxczBYcVFCRkhqTkxFaW5PM3NySjAxTlo3QkExX2tnR0t1THVISC1pVUpESGZNQklnUFFsMzUyb3dSeFdPVUhuWnFiRk5rTU9WekVRS1ZTYUlUUlZtMEhnZHEwTWtpYV9HSjB2bGFXYkJtUE45SU1weGZXTTU3dGdGSnBRYXBobkNoZUsyLUkzeHNnY01rb2N3eUNnTzRZUnlZOXcxZGx4aVhxYURoc0xpcnJMV3E3SFFuZkRCVXlvU2hTWC0iLCJqd2tfcHViIjoiQUM0QUNBQUxBQUFFMGdBQUFCQUFJTlBYYkNWd3BNRUVnUkRGVF9VVVZ6c3Flb3dpWW5PSEZiVmZfV3ZHTUFTOCIsImtleSI6ImVjYyJ9fSwiZW5jIjoiQTI1NkdDTSJ9..F117H8zDNXxuOzxr.KCPhBegjQRx3Sv6uFg.yC9EbXhI8twv48oohl3KOw

The result will be a base-64 encoded string encrypted with your computer's TPM2 key. This means that the message can only be decoded from this current computer (or more precisely, the same TPM2 chip that encoded it).

# echo "eyJhbGciOiJkaXIiLCJjbGV2aXMiOnsicGluIjoidHBtMiIsInRwbTIiOnsiaGFzaCI6InNoYTI1NiIsImp3a19wcml2IjoiQU80QUlETDZOQlp1dFktZUg2YjdNUUFtazNxNE5MTGRDYWFrM2tJUHBsOWtRUmlxQUJEaFFGSks0MWVWQXMtUElKbmsxUW9MS0hVVnhoQmM5RVlZZ1hfc1MzaS1EYUQ1aXZQdmZybUxSY25TZGxYRWtvSE1qN0lMekFvY29ZQ2FnRGNxczBYcVFCRkhqTkxFaW5PM3NySjAxTlo3QkExX2tnR0t1THVISC1pVUpESGZNQklnUFFsMzUyb3dSeFdPVUhuWnFiRk5rTU9WekVRS1ZTYUlUUlZtMEhnZHEwTWtpYV9HSjB2bGFXYkJtUE45SU1weGZXTTU3dGdGSnBRYXBobkNoZUsyLUkzeHNnY01rb2N3eUNnTzRZUnlZOXcxZGx4aVhxYURoc0xpcnJMV3E3SFFuZkRCVXlvU2hTWC0iLCJqd2tfcHViIjoiQUM0QUNBQUxBQUFFMGdBQUFCQUFJTlBYYkNWd3BNRUVnUkRGVF9VVVZ6c3Flb3dpWW5PSEZiVmZfV3ZHTUFTOCIsImtleSI6ImVjYyJ9fSwiZW5jIjoiQTI1NkdDTSJ9..F117H8zDNXxuOzxr.KCPhBegjQRx3Sv6uFg.yC9EbXhI8twv48oohl3KOw" | clevis decrypt tpm2 '{}'

hello, world

== Encrypt a LUKS volume ==

{{Warning|Remember to add a backup password in case TPM unlocking fails using:

# cryptsetup luksAddKey /dev/sda1

}}

Use the following command to bind a LUKS volume to your TPM:

# clevis luks bind -d /dev/sda1 tpm2 '{}'

The {{ic|'{}'|}} contains the configuration. For example, you can use the following command to seal the LUKS key against UEFI settings AND the [[Secure Boot]] policy, meaning clevis will be unable to unlock the device if either the UEFI settings changes or the SecureBoot keys are changed, and you'll need to rebind the volume after inputting your backup password

'{"pcr_ids":"1,7"}'

See {{ic|'man 1 clevis-encrypt-tpm2'|}} for all possible configuration options.

== mkinitfs hook ==

After binding your LVM volume to your TPM, you may wish for it to be unlocked automatically when your device boots. Currently, this process is a bit tedious, but will hopefully be improved in the future.

=== mkinitfs feature ===

First, create the following files with the following content. They allow all the kernel modules and files needed to unlock LUKS devices with the TPM to be copied to the initramfs.

{{Cat|/etc/mkinitfs/features.d/clevis-tpm.modules|kernel/drivers/char/tpm
}}

{{Cat|/etc/mkinitfs/features.d/clevis-tpm.files|/bin/bash
/usr/bin/clevis
/usr/bin/clevis-decrypt
/usr/bin/clevis-decrypt-tpm2
/usr/bin/clevis-luks-unlock
/usr/bin/clevis-luks-common-functions
/usr/bin/jose
/usr/bin/tpm2_createprimary
/usr/bin/tpm2_unseal
/usr/bin/tpm2_load
/usr/bin/tpm2_flushcontext
/usr/lib/libjansson.so.4
/usr/lib/libjose.so.0
/usr/lib/libtss2-tcti-device.so.0
}}

Then, add the <code>clevis-tpm</code> feature to {{path|/etc/mkinitfs/mkinitfs.conf}}:

features="ata base cdrom ext4 keymap kms mmc nvme raid scsi usb virtio '''clevis-tpm'''"

Don't forgot to regenerate your initramfs

# apk fix kernel-hooks

=== init script ===

Now, everything that's needed to unbind the LUKS device with the TPM is now included in the initramfs. All that's needed is to actually unlock the device in the initramfs. Since [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/issues/18 it's currently not possible to run custom scripts in the init], you will need to manually edit the init and allow it to decrypt the disk with clevis if possible.

{{Warning|This part of the guide has not been tested yet. You have been warned!}}

Edit the file {{path|/usr/share/mkinitfs/initramfs-init}}, and replace the text:

<pre>
if [ -n "$KOPT_cryptroot" ]; then
cryptopts="-c ${KOPT_cryptroot}"
if [ "$KOPT_cryptdiscards" = "yes" ]; then
cryptopts="$cryptopts -D"
fi
if [ -n "$KOPT_cryptdm" ]; then
cryptopts="$cryptopts -m ${KOPT_cryptdm}"
fi
if [ -n "$KOPT_cryptheader" ]; then
cryptopts="$cryptopts -H ${KOPT_cryptheader}"
fi
if [ -n "$KOPT_cryptoffset" ]; then
cryptopts="$cryptopts -o ${KOPT_cryptoffset}"
fi
if [ "$KOPT_cryptkey" = "yes" ]; then
cryptopts="$cryptopts -k /crypto_keyfile.bin"
elif [ -n "$KOPT_cryptkey" ]; then
cryptopts="$cryptopts -k ${KOPT_cryptkey}"
fi
fi
</pre>

And replace it with:

<pre>
if [ -n "$KOPT_cryptroot" ]; then
cryptopts="-c ${KOPT_cryptroot}"
clevisopts="-d ${KOPT_cryptroot}"
if [ "$KOPT_cryptdiscards" = "yes" ]; then
cryptopts="$cryptopts -D"
fi
if [ -n "$KOPT_cryptdm" ]; then
cryptopts="$cryptopts -m ${KOPT_cryptdm}"
clevisopts="-n ${KOPT_cryptopts}"
fi
if [ -n "$KOPT_cryptheader" ]; then
cryptopts="$cryptopts -H ${KOPT_cryptheader}"
fi
if [ -n "$KOPT_cryptoffset" ]; then
cryptopts="$cryptopts -o ${KOPT_cryptoffset}"
fi
if [ "$KOPT_cryptkey" = "yes" ]; then
cryptopts="$cryptopts -k /crypto_keyfile.bin"
elif [ -n "$KOPT_cryptkey" ]; then
cryptopts="$cryptopts -k ${KOPT_cryptkey}"
fi
fi

if [ -n "$clevisopts" ]; then
clevis luks unlock $clevisopts
fi
</pre>

== See also ==

* [https://github.com/latchset/clevis/ Project homepage]
* [https://wiki.archlinux.org/title/Clevis Clevis on ArchWiki]
* [https://github.com/latchset/clevis/blob/master/src/initramfs-tools/hooks/clevis.in clevis initramfs-tools hook]
* [https://github.com/kishorv06/arch-mkinitcpio-clevis-hook mkinitcpio-clevis-hook's homepage]

User:Vixalien/Clevis

2024-11-18T02:14:36Z

Vixalien: Added the Clevis page

[https://github.com/latchset/clevis/ Clevis] is a tool that allows, among many other things, to automatically decrypt LUKS volume at boot-time automatically using the TPM without requiring the manual input of a password.

{{Warning|If you use Clevis to automatically decrypt your disk at boot, your computer will unlock automatically, and this can be a security issue}}

== Installation ==

To use clevis install the {{pkg|clevis}} package.

If you need the TPM functionality, you will also need to install {{pkg|tpm2-tools}} and {{pkg|tpm2-tss-tcti-device}}. See [https://gitlab.alpinelinux.org/alpine/aports/-/issues/15985 See issue]:

# apk add -t clevis-tpm clevis tpm2-tools tpm2-tss-tcti-device

== Testing ==

You may wish to encrypt some data using your TPM with clevis:

# echo 'hello, world' | clevis encrypt tpm2 '{}

eyJhbGciOiJkaXIiLCJjbGV2aXMiOnsicGluIjoidHBtMiIsInRwbTIiOnsiaGFzaCI6InNoYTI1NiIsImp3a19wcml2IjoiQU80QUlETDZOQlp1dFktZUg2YjdNUUFtazNxNE5MTGRDYWFrM2tJUHBsOWtRUmlxQUJEaFFGSks0MWVWQXMtUElKbmsxUW9MS0hVVnhoQmM5RVlZZ1hfc1MzaS1EYUQ1aXZQdmZybUxSY25TZGxYRWtvSE1qN0lMekFvY29ZQ2FnRGNxczBYcVFCRkhqTkxFaW5PM3NySjAxTlo3QkExX2tnR0t1THVISC1pVUpESGZNQklnUFFsMzUyb3dSeFdPVUhuWnFiRk5rTU9WekVRS1ZTYUlUUlZtMEhnZHEwTWtpYV9HSjB2bGFXYkJtUE45SU1weGZXTTU3dGdGSnBRYXBobkNoZUsyLUkzeHNnY01rb2N3eUNnTzRZUnlZOXcxZGx4aVhxYURoc0xpcnJMV3E3SFFuZkRCVXlvU2hTWC0iLCJqd2tfcHViIjoiQUM0QUNBQUxBQUFFMGdBQUFCQUFJTlBYYkNWd3BNRUVnUkRGVF9VVVZ6c3Flb3dpWW5PSEZiVmZfV3ZHTUFTOCIsImtleSI6ImVjYyJ9fSwiZW5jIjoiQTI1NkdDTSJ9..F117H8zDNXxuOzxr.KCPhBegjQRx3Sv6uFg.yC9EbXhI8twv48oohl3KOw

The result will be a base-64 encoded string encrypted with your computer's TPM2 key. This means that the message can only be decoded from this current computer (or more precisely, the same TPM2 chip that encoded it).

# echo "eyJhbGciOiJkaXIiLCJjbGV2aXMiOnsicGluIjoidHBtMiIsInRwbTIiOnsiaGFzaCI6InNoYTI1NiIsImp3a19wcml2IjoiQU80QUlETDZOQlp1dFktZUg2YjdNUUFtazNxNE5MTGRDYWFrM2tJUHBsOWtRUmlxQUJEaFFGSks0MWVWQXMtUElKbmsxUW9MS0hVVnhoQmM5RVlZZ1hfc1MzaS1EYUQ1aXZQdmZybUxSY25TZGxYRWtvSE1qN0lMekFvY29ZQ2FnRGNxczBYcVFCRkhqTkxFaW5PM3NySjAxTlo3QkExX2tnR0t1THVISC1pVUpESGZNQklnUFFsMzUyb3dSeFdPVUhuWnFiRk5rTU9WekVRS1ZTYUlUUlZtMEhnZHEwTWtpYV9HSjB2bGFXYkJtUE45SU1weGZXTTU3dGdGSnBRYXBobkNoZUsyLUkzeHNnY01rb2N3eUNnTzRZUnlZOXcxZGx4aVhxYURoc0xpcnJMV3E3SFFuZkRCVXlvU2hTWC0iLCJqd2tfcHViIjoiQUM0QUNBQUxBQUFFMGdBQUFCQUFJTlBYYkNWd3BNRUVnUkRGVF9VVVZ6c3Flb3dpWW5PSEZiVmZfV3ZHTUFTOCIsImtleSI6ImVjYyJ9fSwiZW5jIjoiQTI1NkdDTSJ9..F117H8zDNXxuOzxr.KCPhBegjQRx3Sv6uFg.yC9EbXhI8twv48oohl3KOw" | clevis decrypt tpm2 '{}'

hello, world

== Encrypt a LUKS volume ==

{{Warning|Remember to add a backup password in case TPM unlocking fails using:

# cryptsetup luksAddKey /dev/sda1

}}

Use the following command to bind a LUKS volume to your TPM:

# clevis luks bind -d /dev/sda1 tpm2 '{}'

The {{ic|'{}'|}} contains the configuration. For example, you can use the following command to seal the LUKS key against UEFI settings AND the [[Secure Boot]] policy, meaning clevis will be unable to unlock the device if either the UEFI settings changes or the SecureBoot keys are changed, and you'll need to rebind the volume after inputting your backup password

'{"pcr_ids":"1,7"}'

See {{ic|'man 1 clevis-encrypt-tpm2'|}} for all possible configuration options.

== mkinitfs hook ==

After binding your LVM volume to your TPM, you may wish for it to be unlocked automatically when your device boots. Currently, this process is a bit tedious, but will hopefully be improved in the future.

=== mkinitfs feature ===

First, create the following files with the following content. They allow all the kernel modules and files needed to unlock LUKS devices with the TPM to be copied to the initramfs.

{{Cat|/etc/mkinitfs/features.d/clevis-tpm.modules|kernel/drivers/char/tpm
}}

{{Cat|/etc/mkinitfs/features.d/clevis-tpm.files|/bin/bash
/usr/bin/clevis
/usr/bin/clevis-decrypt
/usr/bin/clevis-decrypt-tpm2
/usr/bin/clevis-luks-unlock
/usr/bin/clevis-luks-common-functions
/usr/bin/jose
/usr/bin/tpm2_createprimary
/usr/bin/tpm2_unseal
/usr/bin/tpm2_load
/usr/bin/tpm2_flushcontext
/usr/lib/libjansson.so.4
/usr/lib/libjose.so.0
/usr/lib/libtss2-tcti-device.so.0
}}

Then, add the <code>clevis-tpm</code> feature to {{path|/etc/mkinitfs/mkinitfs.conf}}:

features="ata base cdrom ext4 keymap kms mmc nvme raid scsi usb virtio '''clevis-tpm'''"

Don't forgot to regenerate your initramfs

# apk fix kernel-hooks

=== init script ===

Now, everything that's needed to unbind the LUKS device with the TPM is now included in the initramfs. All that's needed is to actually unlock the device in the initramfs. Since [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/issues/18 it's currently not possible to run custom scripts in the init], you will need to manually edit the init and allow it to decrypt the disk with clevis if possible.

{{Warning|This part of the guide has not been tested yet. You have been warned!}}

Edit the file {{path|/usr/share/mkinitfs/initramfs-init}}, and replace the text:

<pre>
if [ -n "$KOPT_cryptroot" ]; then
cryptopts="-c ${KOPT_cryptroot}"
if [ "$KOPT_cryptdiscards" = "yes" ]; then
cryptopts="$cryptopts -D"
fi
if [ -n "$KOPT_cryptdm" ]; then
cryptopts="$cryptopts -m ${KOPT_cryptdm}"
fi
if [ -n "$KOPT_cryptheader" ]; then
cryptopts="$cryptopts -H ${KOPT_cryptheader}"
fi
if [ -n "$KOPT_cryptoffset" ]; then
cryptopts="$cryptopts -o ${KOPT_cryptoffset}"
fi
if [ "$KOPT_cryptkey" = "yes" ]; then
cryptopts="$cryptopts -k /crypto_keyfile.bin"
elif [ -n "$KOPT_cryptkey" ]; then
cryptopts="$cryptopts -k ${KOPT_cryptkey}"
fi
fi
</pre>

And replace it with:

<pre>
if [ -n "$KOPT_cryptroot" ]; then
cryptopts="-c ${KOPT_cryptroot}"
clevisopts="-d ${KOPT_cryptroot}"
if [ "$KOPT_cryptdiscards" = "yes" ]; then
cryptopts="$cryptopts -D"
fi
if [ -n "$KOPT_cryptdm" ]; then
cryptopts="$cryptopts -m ${KOPT_cryptdm}"
clevisopts="-n ${KOPT_cryptopts}"
fi
if [ -n "$KOPT_cryptheader" ]; then
cryptopts="$cryptopts -H ${KOPT_cryptheader}"
fi
if [ -n "$KOPT_cryptoffset" ]; then
cryptopts="$cryptopts -o ${KOPT_cryptoffset}"
fi
if [ "$KOPT_cryptkey" = "yes" ]; then
cryptopts="$cryptopts -k /crypto_keyfile.bin"
elif [ -n "$KOPT_cryptkey" ]; then
cryptopts="$cryptopts -k ${KOPT_cryptkey}"
fi
fi

if [ -n "$clevisopts" ]; then
clevis luks unlock $clevisopts
fi
</pre>

== See also ==

* [https://github.com/latchset/clevis/ Project homepage]
* [https://wiki.archlinux.org/title/Clevis Clevis on ArchWiki]
* [https://github.com/latchset/clevis/blob/master/src/initramfs-tools/hooks/clevis.in clevis initramfs-tools hook]
* [https://github.com/kishorv06/arch-mkinitcpio-clevis-hook mkinitcpio-clevis-hook's homepage]

Diskless Mode

2024-11-05T15:34:52Z

Vixalien: Expanded a bit on diskless mode

In Diskless mode, the entire operating system with all applications are first loaded into RAM and then only run from there. This is also the method used to boot the Alpine Linux <Code>iso</Code> installation media. Alpine Linux can be installed and configured so that the system continue to boot like this if "disk=none" is specified while running the <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> script.

The mode is extremely fast and can save on unnecessary disk spin-ups, power, and wear and suitable for servers. It is similar to what other linux distributions may call a "frugal" install or boot using a "toram" option.

You can continue using your [[Installation#Preparing_installation_media|installation media]] as a [[#Boot Device|boot device]] without installing alpine to the device's internal disk, but it is also possible to install Alpine Linux to a device's internal disk and configure it so that it boots into "diskless mode" .

== Apkovl ==
{{Seealso|Alpine local backup}}

When you boot an alpine installation into diskless mode, it will initialize a fresh new root (<Code>/</Code>) and any customisations you make (such as changing the password, adding users, etc.) will be lost when you reboot. However, any custom configurations may be preserved or "persist" across reboots by using the Alpine Linux tool named <code>[[Alpine_local_backup|Local Backup Utility]](lbu)</code>. The initial and possibly read-only installation media can remain the only boot device for the "diskless" system by saving the running state to an [[#Apkovl|<Code>.apkovl</Code>]] file, and have these automatically loaded when booting from the boot device.

An '''Apkovl''' (APK Overlay file) is a file used for storing local configuration state when running Alpine Linux in [[Diskless Mode]]. It stores all configuration files that have changed from the default ones. The filename is <Code><hostname>.apkovl.tar.gz</Code> and is stored in a location whose path is defined in {{Path|/etc/lbu/lbu.conf}}. The contents from the Apkovl file are overlaid on top of the contents of the apks that are loaded on boot.

The backup tool <code>[[Alpine_local_backup|lbu]]</code> enables committing and reverting local configuration system state by using '''.apkovl''' files that are saved to a backup location and loaded when booting. In Diskless mode, for every change made to the running system to persist across reboot, the command <code>[[Alpine_local_backup|lbu commit]]</code> must be issued before rebooting the system to update the .apkovl file.

== Local Package Cache ==

When Alpine Linux boots in Diskless Mode, the remote repositories will not be available until after networking has started. That means extra packages newer not in your local boot media would not be available after a reboot, unless they were made to persistent [[Alpine_Package_Keeper#Local_Cache|local package cache]] available on a local, writable, storage device. The local package cache can be stored on the same partition as the .apkovl file.

== Installation ==
{{Seealso|Create_a_Bootable_Device}}

Alpine Linux setup script <code>setup-alpine</code> uses <code>[[Alpine_setup_scripts#setup-lbu|setup-lbu]]</code> script to save the config and package cache to any available writable filesystem on any media other than the read-only [[Installation#Preparing_installation_media|installation media]].

Due to Bug: [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10473 #10473] storing local configs and package cache on '''internal disks''' requires manual steps, i.e making an entry in {{Path|/etc/fstab}}, create mountpoint, and mount the partition before running <code>setup-alpine</code> script.

# In this case, boot the target diskless system from the [[Installation#Preparing_installation_media|installation media]] and do not proceed after the [[Installation#Boot_Process|boot process]] stage.
# If necessary partition(s) are unavailable, manually [[Setting_up_disks_manually#Creating_partitions|create]] a partition using <Code>fdisk</Code>. In the below steps, we will use /dev/sdXY as partition number. Adjust the partition identifier as per the output of {{Codeline|<Code>blkid</Code>}}<br>
#* Due to Bug: {{Issue|11589|The APKOVL loading of diskless setups doesn't work on btrfs and xfs filesystems, or nvme-based devices}}. So use only ext4 filesystem partitions on classic drives to store diskless mode states.
#* mkfs.ext4 creates ext4 filesystem with 64bit feature enabled by default, but extlinux may not be able to boot with that due to Issue {{Issue|14895}}. You may need to add "-O ^64bit" to mkfs.ext4 to circumvent this. The below command creates an ext4 partition with disabled journaling, to reduce write operations and allow the disk to spin down after the .apkovl and the packages have been read from the partition during the boot. Install package {{pkg|<Code>e2fsprogs</code>}} using command {{Codeline|<Code>apk add e2fsprogs</Code>}}, if the command <Code>mkfs.ext4</Code> is not available.
#: {{Cmd|mkfs.ext4 -O ^has_journal,^64bit /dev/sdXY}}
# Due to a [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/issues/5 bug], the partition can not be mounted to /boot. Configure the /etc/fstab to mount the writable partition to /media/sdXY instead of /boot i.e. conforming to the hot/cold-plug mountpoints.
#: {{Cmd|mkdir /media/sdXY}}
#: {{cmd|echo "/dev/sdXY /media/sdXY ext4 noatime,ro 0 0" >> /etc/fstab}}

# Mount the partitions listed in {{Path|/etc/fstab}}.
#: {{Cmd|<code>mount -a</code>}} Look at the output of {{Codeline|<code>mount</code>}} to verify that the changes have been applied correctly.<br>
# If <code>Setup-alpine</code> has not run before, follow the [[Installation#Installation_Step_Details|Installation steps]] to complete the [[Installation#Base_configuration|base configuration]]. The above changes should now enable you to choose the partition for saving the local configs and package cache. If asked, there is no need to first unmount the partition, that would only be needed to allow installing on its parent disk.
# If <code>Setup-alpine</code> has already been used to configure the diskless system, the storage settings may be modified directly with
#: {{cmd|setup-lbu sdXY}}
# [[Alpine_Package_Keeper#Local_Cache|Local package cache]] can be enabled as follows:
#: {{cmd|mkdir /media/sdXY/cache}}
#: {{cmd|setup-apkcache /media/sdXY/cache}}
# If the partition is large enough, it can be useful to edit {{Path|lbu.conf}} to uncomment and set {{Codeline|BACKUP_LIMIT{{=}}3}}. For example, to allow reverting to a previous, working state if needed.
#: {{cmd|apk add nano}}
#: {{cmd|nano /etc/lbu/lbu.conf }}
# Finally, generate the first .apkovl file containing all the previous changes by executing <code>lbu commit</code>, so the customizations that were just made will persist a reboot.
#: {{cmd|lbu commit}}
# From now on, whenever packages are installed or newly configured, and the changes should be kept, execute <code>lbu commit</code>.

== Boot Device ==

{{Main|Create a Bootable Device}}

The initial ISO9660 filesystem based read-only [[Installation#Preparing_installation_media|installation media]] may remain the only boot device for the newly configured Alpine Linux '''Diskless''' system.

Alpine Linux running Diskless mode can also boot from a partition with a writable filesystem on USB-Stick/CompactFlash/SDCard or SSD/NVMe harddisk. This boot device is known as [[Create_a_Bootable_Device|customizable boot device]] to differentiate against [[Installation#Preparing_installation_media|installation media]]. Local customizations like apkovl files and cached packages can be stored in this customizable boot device, which also allows to upgrade the kernel with its modules and firmware with the <code>update-kernel</Code> script.

== Loading apkovl from webserver ==

Alpine's "diskless mode" ISO boot images support boot parameters to load customizations files i.e [[Alpine_local_backup#Creating_and_saving_an_apkovl_from_a_remote_host|apkovl from a webserver]].

It's possible to load an APKOVL file from a webserver, by supplying a custom url with the <code>APKOVL</code> kernel boot parameter. If you don't have a web server you can run busybox's httpd temporarily to serve an .apkovl - <code>busybox httpd -p 127.0.0.1:80</code>.

== Upgrading a Diskless System ==

When Alping Linux runs in "diskless" or "data" disk mode, Upgrading requires few extra steps in addition to the regular [[Alpine_Package_Keeper#Upgrade_a_Running_System|upgrade steps]].

If booting a "diskless" system from a read-only device, or as an iso image on writable media, it's not possible to update the boot files (kernel, modules, firmware, ...) that reside on that device.

For [[Create_a_Bootable_Device|customizable boot device]], It is possible to update the boot files. However, even then, the kernel, with its modules and firmware files, can still not be updated directly through regular packages updates. Instead, there is the <code>update-kernel</code> script that can generate initfs images and install them together with upgraded kernels.

Upgrading can be done as follows.
{{cmd|apk add mkinitfs
}}
This package is required for the generation of the initial filesystem used during boot.
* Additional initfs features that are missing in the default configuration, like the [[Btrfs|btrfs]] filesystem support (at the time of writing, to allow loading .apkovl configs and package cache during boot), may be enabled in <code>/etc/mkinitfs/mkinitfs.conf</code>.
* Available initfs features may be listed with <code>ls /etc/mkinitfs/features.d</code>
{{cmd|ls /etc/mkinitfs/features.d
apk add nano
nano /etc/mkinitfs/mkinitfs.conf
lbu commit
}}
Finally update the kernel and its boot environment.
{{cmd|update-kernel /media/sdXY/boot/
}}
* An <code>update-kernel</code> run needs at least 8 GB free ram memory to avoid a broken modloop-image.
* See <code>update-kernel --help</code> for options to manually add additional module or firmware packages.

== Kernel Options ==

Documentation about kernel command line options regarding diskless mode will be available after installing the documentation sub-package {{Pkg|mkinitfs-doc}}:

{{Cmd|man mkinitfs-bootparam}} <Pre>
If no root= parameter is given, the initramfs will build a live system
in memory from scratch. This is also called diskless mode.

When booting in diskless mode, the following options are also
available:

alpine_repo=(URL | PATH)
If set, /etc/apk/repositories will be filled with this. May be a
comma-separated list of URLs.

apkovl=(URL | [DEVICE[:FS_TYPE]:]PATH)
A HTTP, HTTPS or FTP URL to an apkovl.tar.gz file which will be
retrieved and applied. Can also be a filesystem path, optionally
prepended with the device name without the /dev/ prefix.

autodetect_serial=no
Disable automatic detection and setup of serial console.

ds=OPTIONS
Data source for tiny-cloud. If OPTIONS starts with nocloud,
tiny-cloud will be enabled.

nokeep_apk_new
Setup a fresh system, ignore any apkovl.

pkgs=PACKAGE{,PACKAGE}
Comma-separated list of packages to be installed.
ssh_key=(URL | SSH_KEY)
This setting installs openssh and places the public key given as
value in /root/.ssh/authorized_keys. If the value is an HTTP or
FTP url, its fetches the key(s) from there.

splash Enable splash screen.

usbdelay=NUMBER
Wait NUMBER seconds for USB devices to show up before searching
for boot media.

wireguard=INTERFACE;IP_ADDRESS{,IP_ADDRESS,...}[;WG_CONFIG_FILE]
Set up a wireguard interface named INTERFACE with the addresses
IP_ADDRESS and use /etc/wireguard/initrd.conf or WG_CONFIG_FILE
as a classic wg (not wg-quick) config.

zfs_force=NUMBER
Enable force importing the root zpool on boot, even if it was
previously mounted from a different system/OS.
</Pre>
== See Also ==
* [[Alpine_local_backup|Alpine Local backup Utility - ''lbu''']]
* [[Alpine_Package_Keeper#Local_Cache|Local package cache]]
* [[Manually editing a existing apkovl]]
* [[Back Up a Flash Memory Installation]]
* [[Upgrading_Alpine#Upgrading_Alpine_Linux_on_other_removable_media_(such_as_CF/USB)|Upgrading Diskless to New Alpine Linux Release]]
* [[PXE boot#Specifying an apkovl|Diskless PXE Boot]]
* [[How to make a custom ISO image with mkimage]]
* [[QEMU#Live_mode|QEMU Diskless example]]
* [[Alpine local backup#Include special files.2Ffolders to the apkovl|Include special files section]] - To include custom files outside of <code>/etc</code> in .apkovl file.

[[Category:Diskless]] [[Category:LBU]]

MDNS

2024-09-13T15:51:24Z

Vixalien: Add setup instructions for NetworkManager and dnsmasq

{{DISPLAYTITLE:mDNS}}
[https://en.wikipedia.org/wiki/Multicast_DNS Multicast DNS] is a protocol that is normally used for the discovery of printers. It is implemented by Avahi, but more setup is needed for the regular name resolution to see the results.

== Setup avahi ==

Install, enable and start avahi with:

{{cmd|doas apk add {{pkg|avahi}}
doas rc-update add avahi-daemon
doas rc-service avahi-daemon start}}

It should now be possible to browse results. To look for a printer, use:

{{cmd|doas apk add {{pkg|avahi-tools}}
avahi-browse --resolve --terminate _ipp._tcp}}

Make note of the hostname, as we will use it afterwards.

== Setup avahi2dns ==

Name resolution is implemented by musl, and it only supports DNS, so we have to map the avahi results to a regular DNS server. This is done by avahi2dns.

{{cmd|doas apk add {{pkg|avahi2dns}}}}

since we will want a full DNS server running at port 53, we need to configure avahi2dns to use another port. This is done by default with {{path|/etc/conf.d/avahi2dns}} containing:

command_args="-p 5354"

Enable and start avahi2dns with

{{cmd|doas rc-update add avahi2dns
doas rc-service avahi2dns start}}

It should now be possible to use DNS to query the address of the printer.

{{cmd|drill -p 5354 @127.0.0.1 <printer_name>.local}}

Where printer_name is the hostname given by avahi-browse.

== Setup Networkmanager ==

If you are already using networkmanager, you can leverage {{pkg|dnsmasq}} as your DNS server which can easily forward mDNS requests to another server.

Install the {{pkg|networkmanager-dnsmasq}} package:

{{cmd|doas apk add {{pkg|networkmanager-dnsmasq}}}}

Configure networkmanager to use dnsmasq as it's dns server by editing {{path|/etc/NetworkManager/NetworkManager.conf}}

[main]
dhcp=internal
dns=dnsmasq

Then we need to tell dnsmasq to forward all mDNS queries to avahidns {{path|/etc/NetworkManager/dnsmasq.d/mdns.conf}}:

# Forward queries for the "local" domain to 127.0.0.1 port 5354
server=/local/127.0.0.1#5354

Restart networkmanager:

{{cmd|doas rc-service networkmanager restart}}

== Without NetworkManager ==

=== Setup DNS resolver ===

If you are not using NetworkManager, you will need to setup a DNS resolver that will forward request of .local domain to avahi2dns and handle other requests normally. There is more than one way to do it, but we document an option that is probably most convenient for a laptop: using the DHCP provided server for the regular DNS requests. We will use unbound as the server and resolvconf to inform unbound about the DHCP results.

Install the programs:

{{cmd|doas apk add {{pkg|openresolv}} {{pkg|unbound}}}}

Create {{path|/etc/resolvconf.conf}}:

name_servers=127.0.0.1
unbound_conf=/etc/unbound/unbound.conf.d/resolvconf.conf

This tells resolveconf to use a local nameserver and pass the DHCP provided DNS server to unbound

Create {{path|/etc/unbound/unbound.conf.d/avahi-local.conf}}:

forward-zone:
name: "local"
forward-addr: 127.0.0.1@5354
server:
do-not-query-localhost: no
domain-insecure: "local"

This reads the information provided by resolvconf, but forwards .local requests to avahi2dns. We also need to disable dnssec for .local and tell unbound that it is OK to query localhost.

Enable and start unbound

{{cmd|doas rc-update add unbound
doas rc-service unbound start}}

=== Setup DHCP client ===

How send the DHCP provided DNS to resolvconf depends on the DHCP client being used.

==== udhcpc ====

This is the DHCP client in busybox, and will work for both wired and wireless interfaces.

Create {{path|/etc/udhcpc/udhcpc.conf}}:

RESOLV_CONF="/etc/udhcpc-resolv.conf"

Create {{path|/etc/udhcpc/post-bound/resolvconf}}:

#!/bin/sh
cat /etc/udhcpc-resolv.conf | resolvconf -a $interface

and make it executable

{{cmd|chmod 755 /etc/udhcpc/post-bound/resolvconf}}

An inconvenience of this setup is that udhcpc will not reconfigure the interface when connecting to other wifi networks. For that to happen one has to run

{{cmd|iwctl station wlan0 connect <network_name>
doas kill -USR2 $(cat /run/udhcpc.wlan0.pid)
doas kill -USR1 $(cat /run/udhcpc.wlan0.pid)}}

==== iwd ====

To avoid having to manually reconfigure the wifi interface, we can configure iwd to use DHCP internally and forward DNS server info to resolveconf. To do that create {{path|/etc/iwd/main.conf}}:

[General]
EnableNetworkConfiguration=True

[Network]
NameResolvingService=resolvconf

== Test the setup ==

You should now be able to query for both the printer address and regular addresses with

{{cmd|drill @127.0.0.1 <printer_name>.local
drill @127.0.0.1 alpinelinux.org}}

Your {{path|/etc/resolv.conf}} should also contain

nameserver 127.0.0.1

Printer discovery should now be working.

[[Category:Networking]]

Talk:Flatpak

2024-02-22T21:08:23Z

Vixalien:

Guest09248, why did you delete the link to flatpak's page on alpine:* [https://flatpak.org/setup/Alpine/ Alpine Quick Setup. Follow these simple steps to start using Flatpak]
And other links. This information is valid alpine specific info and your edits appear to be vandalism.
[[User:Alpineuser|Alpineuser]] ([[User talk:Alpineuser|talk]]) 06:08, 8 December 2021 (UTC)

:The page contains important information. Specifically, it also shows the packages to install for GNOME Software and KDE Discover --[[User:Vixalien|Vixalien]] ([[User talk:Vixalien|talk]]) 21:08, 22 February 2024 (UTC)

Talk:Directly booting an ISO file

2024-02-22T03:11:14Z

Vixalien: /* Ventoy */ new section

::::: I've given up. Couldn't make the intended setup work with my meager Linux knowledge. I did find a page here at the wiki, under the heading '[[Replacing_non-Alpine_Linux_with_Alpine_remotely|Install Alpine cd-rom image on hard disk]]' where a somewhat related solution is provided, but it involves extracting the distro files from the iso, something that [https://unetbootin.sourceforge.net/ unetbootin] does in a rather more easy and straightforward way -- at least, that's what I used to get Alpine to boot from a USB pendrive (plenty of recipes for that around). However, I still believe a simple 'boot from iso' procedure could do wonders for Alpine, so I'm leaving this here for future reference. Should anyone disagree, do feel free to delete. [[User:Pnin|Pnin]] 05:43, 8 February 2011 (UTC)

Current system is a 2.8 Prescott Pentium IV with 2MB RAM, booting from a 1GB CF plugged into the IDE interface, with an attached 500GB SATA HDD for data. When I tried to install Alpine from the LiveCD to this card, which is listed as a hard drive by the BIOS, it complained of insufficient space. Fair enough. Next I tried to follow [https://www.pendrivelinux.com/boot-multiple-iso-from-usb-via-grub2-using-linux/ this recipe] to boot from Alpine 2.1.4 iso. At the end, you find this tip:

:''Adding an Unlisted ISO: To try ISO Files that are not yet listed, use the existing menu entry examples in /boot/grub/grub.cfg and append any options normally found in the distribution's syslinux.cfg file on the "append" line, to the "linux" line of the menu entry.''

So I downloaded the latest Alpine iso via wget and modified the relevant ''grub.cfg'' lines to:

linux (loop)/boot/grsec initrd=/boot/grsec.gz iso-scan/filename=/alpine214.iso alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
initrd (loop)/boot/grsec.gz

All I got when I tried to boot this was the following error:

'''Alpine Init 2.1.2'''
'''/init: eval: line 1: syntax error: unexpected "("'''
'''kernel panic - not syncing: attempted to kill init!'''
'''Pid: 1, comm: init Not tainted 2.6.35.10-grsec #1-Alpine'''
[...]

I must say all went well with the Linux Mint 10.10 and the TinyCore isos, into which I'm able to boot with no issues. Anyone care to advise?

[[User:Pnin|Pnin]]

----

Hi, that "linux (loop)/boot/...." thing looks funny to me.

According to: https://help.ubuntu.com/community/Grub2

Could you try:

set root=(loop0)
linux /boot/grsec initrd=/boot/grsec.gz iso-scan/filename=/alpine214.iso alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
initrd /boot/grsec.gz

[[User:Nangel|Nangel]] 13:49, 6 February 2011 (UTC)

----

Hi & thanks, Nangel.

Tried that and got this error:

error: no such disk.
error: you need to load the kernel first.
press any key to continue...

Pressing any key returns to the grub menu. Maybe the full ''grub.cfg'' entry should be reported here:

menuentry "Alpine Linux" {
loopback loop /alpine214.iso
linux (loop)/boot/grsec initrd=/boot/grsec.gz iso-scan/filename=/alpine214.iso alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
initrd (loop)/boot/grsec.gz
}

It should also be noted that the LiveCD used to perform the [https://www.pendrivelinux.com/boot-multiple-iso-from-usb-via-grub2-using-linux/ recipe] was "Linux Mint 9 LXDE", which caused Grub 1.98-1ubuntu5-1mint2 to be installed, not Grub2. And that (loop) part is present in every other successful menu entry.

[EDIT: Just to add that IMHO coupled with the [[Alpine_local_backup|Alpine Local Backup Utility]] (lbu), booting from iso would be a killer feature for Alpine, making systems really easy to troubleshoot (delete local backup) and upgrade (replace iso).]

[[User:Pnin|Pnin]] 14:34, 6 February 2011 (UTC)

----

Suppose alpine-extended-3.14.0-x86_64.iso is stored in directory boot in partition 1 on disk.
GRUB2 can be caused to load kernel and initramfs by entering:

grub> loopback lb /boot/alpine-extended-3.14.0-x86_64.iso
grub> linux (lb)/boot/vmlinuz-lts
grub> initrd (lb)/boot/initramfs-lts
grub> boot

A menu entry for GRUB2 can be created with these statements.

Initialising Alpine will then be aborted with messages:

Mounting boot media: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot

To mount the filesystem where alpine-extended-3.14.0-x86_64.iso is stored, enter:

# mount /dev/sda1 /media/sda1

To mount the ISO image, enter:

# mount -o loop -t iso9660 /media/sda1/boot/alpine-extended-3.14.0-x86_64.iso /media/cdrom

Continue initialisation with:

# exit

At last these messages will be displayed:

/lib/rc/sh/openrc-run.sh: eval: line 1: syntax error: unexpected "("
* ERROR: firstboot failed to start

but login root works and Alpine can be configured using

# alpine-setup

[[User:HGT|HGT]] 2021-07-08

----

== Ventoy ==

This is now possible and easy using [https://wiki.archlinux.org/title/Ventoy Ventoy] --[[User:Vixalien|Vixalien]] ([[User talk:Vixalien|talk]]) 03:11, 22 February 2024 (UTC)

Talk:Directly booting an ISO file

2024-02-22T03:10:31Z

Vixalien: Undo revision 26454 by Vixalien (talk)

Talk:Directly booting an ISO file

2024-02-22T03:04:26Z

Vixalien:

This is now easily possible with [https://wiki.archlinux.org/title/Ventoy Ventoy]. I use it all the time!

[[User:Vixalien|Vixalien]] 05:02, 22 February 2023 (GMT+2)

----

::::: I've given up. Couldn't make the intended setup work with my meager Linux knowledge. I did find a page here at the wiki, under the heading '[[Replacing_non-Alpine_Linux_with_Alpine_remotely|Install Alpine cd-rom image on hard disk]]' where a somewhat related solution is provided, but it involves extracting the distro files from the iso, something that [https://unetbootin.sourceforge.net/ unetbootin] does in a rather more easy and straightforward way -- at least, that's what I used to get Alpine to boot from a USB pendrive (plenty of recipes for that around). However, I still believe a simple 'boot from iso' procedure could do wonders for Alpine, so I'm leaving this here for future reference. Should anyone disagree, do feel free to delete. [[User:Pnin|Pnin]] 05:43, 8 February 2011 (UTC)

Current system is a 2.8 Prescott Pentium IV with 2MB RAM, booting from a 1GB CF plugged into the IDE interface, with an attached 500GB SATA HDD for data. When I tried to install Alpine from the LiveCD to this card, which is listed as a hard drive by the BIOS, it complained of insufficient space. Fair enough. Next I tried to follow [https://www.pendrivelinux.com/boot-multiple-iso-from-usb-via-grub2-using-linux/ this recipe] to boot from Alpine 2.1.4 iso. At the end, you find this tip:

:''Adding an Unlisted ISO: To try ISO Files that are not yet listed, use the existing menu entry examples in /boot/grub/grub.cfg and append any options normally found in the distribution's syslinux.cfg file on the "append" line, to the "linux" line of the menu entry.''

So I downloaded the latest Alpine iso via wget and modified the relevant ''grub.cfg'' lines to:

linux (loop)/boot/grsec initrd=/boot/grsec.gz iso-scan/filename=/alpine214.iso alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
initrd (loop)/boot/grsec.gz

All I got when I tried to boot this was the following error:

'''Alpine Init 2.1.2'''
'''/init: eval: line 1: syntax error: unexpected "("'''
'''kernel panic - not syncing: attempted to kill init!'''
'''Pid: 1, comm: init Not tainted 2.6.35.10-grsec #1-Alpine'''
[...]

I must say all went well with the Linux Mint 10.10 and the TinyCore isos, into which I'm able to boot with no issues. Anyone care to advise?

[[User:Pnin|Pnin]]

----

Hi, that "linux (loop)/boot/...." thing looks funny to me.

According to: https://help.ubuntu.com/community/Grub2

Could you try:

set root=(loop0)
linux /boot/grsec initrd=/boot/grsec.gz iso-scan/filename=/alpine214.iso alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
initrd /boot/grsec.gz

[[User:Nangel|Nangel]] 13:49, 6 February 2011 (UTC)

----

Hi & thanks, Nangel.

Tried that and got this error:

error: no such disk.
error: you need to load the kernel first.
press any key to continue...

Pressing any key returns to the grub menu. Maybe the full ''grub.cfg'' entry should be reported here:

menuentry "Alpine Linux" {
loopback loop /alpine214.iso
linux (loop)/boot/grsec initrd=/boot/grsec.gz iso-scan/filename=/alpine214.iso alpine_dev=usbdisk:vfat modules=loop,cramfs,sd-mod,usb-storage quiet
initrd (loop)/boot/grsec.gz
}

It should also be noted that the LiveCD used to perform the [https://www.pendrivelinux.com/boot-multiple-iso-from-usb-via-grub2-using-linux/ recipe] was "Linux Mint 9 LXDE", which caused Grub 1.98-1ubuntu5-1mint2 to be installed, not Grub2. And that (loop) part is present in every other successful menu entry.

[EDIT: Just to add that IMHO coupled with the [[Alpine_local_backup|Alpine Local Backup Utility]] (lbu), booting from iso would be a killer feature for Alpine, making systems really easy to troubleshoot (delete local backup) and upgrade (replace iso).]

[[User:Pnin|Pnin]] 14:34, 6 February 2011 (UTC)

----

Suppose alpine-extended-3.14.0-x86_64.iso is stored in directory boot in partition 1 on disk.
GRUB2 can be caused to load kernel and initramfs by entering:

grub> loopback lb /boot/alpine-extended-3.14.0-x86_64.iso
grub> linux (lb)/boot/vmlinuz-lts
grub> initrd (lb)/boot/initramfs-lts
grub> boot

A menu entry for GRUB2 can be created with these statements.

Initialising Alpine will then be aborted with messages:

Mounting boot media: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot

To mount the filesystem where alpine-extended-3.14.0-x86_64.iso is stored, enter:

# mount /dev/sda1 /media/sda1

To mount the ISO image, enter:

# mount -o loop -t iso9660 /media/sda1/boot/alpine-extended-3.14.0-x86_64.iso /media/cdrom

Continue initialisation with:

# exit

At last these messages will be displayed:

/lib/rc/sh/openrc-run.sh: eval: line 1: syntax error: unexpected "("
* ERROR: firstboot failed to start

but login root works and Alpine can be configured using

# alpine-setup

[[User:HGT|HGT]] 2021-07-08

----

Talk:Full disk encryption secure boot

2024-02-18T00:13:56Z

Vixalien: Created page with "> Using luks2 (unsupported by GRUB at the moment): luks2 is now partially supported by GRUB. > cryptsetup -v -c aes-xts-plain64 -s 512 --hash sha512 --pbkdf pbkdf2 --iter-time 1000 --use-random luksFormat /dev/nvme0n1p2 The options are too many and confusing, and most of them have been made default in cryptsetup 2.4.0, according to https://wiki.archlinux.org/title/Dm-crypt/Device_encryption#Encryption_options_for_LUKS_mode."

> Using luks2 (unsupported by GRUB at the moment):

luks2 is now partially supported by GRUB.

> cryptsetup -v -c aes-xts-plain64 -s 512 --hash sha512 --pbkdf pbkdf2 --iter-time 1000 --use-random luksFormat /dev/nvme0n1p2

The options are too many and confusing, and most of them have been made default in cryptsetup 2.4.0, according to https://wiki.archlinux.org/title/Dm-crypt/Device_encryption#Encryption_options_for_LUKS_mode.

Release Notes for Alpine 3.16.0

2024-02-15T02:36:45Z

Vixalien: Fix broadband typo

== Important changes ==

=== Python 2 has been removed ===

Stable alpine releases do not have python 2 anymore.

=== /tmp mounted as tmpfs ===

Previously <code>/tmp</code> was part of the root filesystem and was cleaned on boot via the bootmisc openrc service script. In v3.16, new installations will mount <code>/tmp</code> as tmpfs.

The bootmisc script no longer wipes /tmp on boot. If you want the previous behaviour, set <code>wipe_tmp</code> to YES in /etc/conf.d/bootmisc

=== ICU data split ===

The icu package has been split into:

* {{pkg|icu-data-en}} (2.6 MiB) - Stripped down ICU data with only en_US/GB locale and no legacy charset converters.
* {{pkg|icu-data-full}} (29 MiB) - Full ICU data.

{{pkg|icu-libs}} only installs icu-data-en. If additional language support is required, {{pkg|icu-data-full}} needs to be installed manually.

{{pkg|nodejs}} is now compiled with system ICU.

=== NetworkManager plugins ===

NetworkManager plugins (e.g. WiFi or ADSL support) have been moved into subpackages and are not installed by default. If you use some of them, install the corresponding packages:

* WiFi: {{pkg|networkmanager-wifi}}
* ADSL: {{pkg|networkmanager-adsl}}
* Mobile broadband: {{pkg|networkmanager-wwan}}
* BlueTooth: {{pkg|networkmanager-bluetooth}}
* PPP: {{pkg|networkmanager-ppp}}
* Open vSwitch: {{pkg|networkmanager-ovs}}

=== xen-qemu split ===

The qemu components of xen were split into a new subpackage, {{pkg|xen-qemu}}. If you were using the qemu- xen binaries or the xenqemu service or firmware such as qemu/bios.bin / edk2-* files, you might need to install this.

=== Nextcloud 24 ===

Nextcloud can only be upgraded one major version at a time. However, in Alpine 3.15 the version was 22, and in 3.16 it is 24. To upgrade between them, make use of the {{pkg|nextcloud23}} package to satisfy this limitation.

== New features and noteworthy new packages ==

=== Fixed not showing boot output using consoles with drivers compiled as modules ===

OpenRC output is now shown on VirtIO serial consoles.

=== SDL 1.2 migrated to SDL 1.2 compat ===

The old sdl package (SDL 1.2) has been moved from community to testing and as such won't be part of Alpine 3.16. Applications that use sdl instead use sdl12-compat, which is based on the much more well-maintained sdl2 (SDL 2.0). This results in various improvements such as support for Wayland, PipeWire, and more gamepads.

=== utmp ===

The following packages are built with [https://skarnet.org/software/utmps/ utmps]:

* busybox
* dropbear
* mingetty
* openssh
* util-linux

=== login-utils ===

{{pkg|util-linux-login}} has been added as a provider of the <code>login</code> command. If <code>cmd:login</code> has been added to world, then the util-linux implementation will be preferred over the shadow implementation. If the shadow implementation is required, then {{pkg|shadow-login}} must be manually selected.

=== Zsh - modular zshrc and plugins support ===

=== doas-sudo-shim ===

If you are hesitant to switch to {{pkg|doas}} because you have <code>sudo</code> too deep in your muscle memory, hesitant no more! Just install {{pkg|doas-sudo-shim}} and you can continue to use the <code>sudo</code> command, but without its security issues and bloat.

== Significant updates ==

* GNOME 42
* LLVM 13
* PHP 8.0 and 8.1 both shipped
* Python 3.10
* QEMU 7
* R 4.2
* Ruby 3.1
* Rust 1.60
* Sway 1.7
* Xen 4.16.1

=== KDE ===

Plasma has been upgraded from 5.23 to 5.24.

KDE applications (the release service) have been upgraded from 21.08 to 22.04 and KDE Frameworks have been upgraded from 5.88 to 5.93.

Plasma Mobile Gear have been upgraded from 21.12 to 22.04.

=== Python upgraded to 3.10 ===

Python has been upgraded to version 3.10, and all modules have been rebuilt against python 3.10. Manually-installed Python modules must be recompiled against 3.10.

== Deprecations / Removals ==

=== php7 moved to testing ===

The {{pkg|php7}} package has been moved to testing, as no more packages in community depend on it and php 7.4 will be EOL soon. {{pkg|php8}} has taken it's place, which is php 8.0. Additionally 8.1 is shipped via community

[[Category:News]]

Creating an Alpine package

2024-02-15T02:21:06Z

Vixalien: Add links to alpine's gitlab instance and setting up the aports build environment

{{TOC right}}
== Overview ==

This is a brief list of the steps to add a new package. Details are below, but a NB can miss a few steps.

# Create an account on https://gitlab.alpinelinux.org
# [[Abuild_and_Helpers#Setting_up_the_build_environment|Setup the build environment for aports]].
# Fork the [https://gitlab.alpinelinux.org/alpine/aports aports repository].
# Clone your new fork.
# Set git pull.rebase=true, set your username and email.
# Create and switch to a new branch (don't use master).
# Add a new directory under testing that is your new package name.
# Add your APKBUILD file.
# Run abuild checksum
# Make sure you run the apkbuild-lint and aport -r and there are no warnings.
# Commit your APKBUILD with the commit message: 'testing/packagename: new aport'
# Push your changes to your fork on https://gitlab.alpinelinux.org/alpine.
# Create a merge request.

Please see the rest of this wiki for details on the steps above.

== Requirements ==

To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.

== Setup your system and account ==
{{:Setup_your_system_and_account_for_building_packages}}

== Getting some help ==

It might be wise to start by checking what the [[Abuild and Helpers|abuild]] program can/cannot do.

{{Cmd|abuild -h}}

For real help, you can also go on #alpine-devel on [[IRC]].

A reference for APKBUILD files is available as [[APKBUILD Reference]] wiki page or a man page in the 'abuild-doc' package:

{{Cmd|man APKBUILD}}

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the [[Package_policies| package policies]] page about naming details.

If you doubt to which repository your package belongs to you can safely use '''testing'''. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

{{:Abuild and Helpers}}

{{Note|On older Alpine systems, abuild -c -n ''packagename'' was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters. }}

[[Abuild_and_Helpers#apkbuild-cpan|apkbuild-cpan]] simplifies the creation of perl packages from CPAN and [[Abuild_and_Helpers#apkbuild-pypi|apkbuild-pypi]] ease the generation of APKBUILD files for python packages from PyPi.

If you are creating a daemon package which needs initd scripts you can add the -c making it:

{{Cmd|newapkbuild -c ''packagename''}}

This will copy the sample initd and confd files to the build directory.<BR>
A third file sample.install file will be copied as well (we will discuss this later on).

=== Modify your APKBUILD ===
Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

{{Note|If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.}}

=== APKBUILD variables/functions ===

==== source ====

The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[Creating an Alpine package#install|install variable]]), patches, and all other necessary files.

Here are few things to note:

* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
: {{cmd|abuild checksum}}
: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
: <pre>http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* When the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
: You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
: <pre>source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"</pre>
: This causes the file to be saved as ''software-1.0.tar.gz'' where abuild can use it, instead of ''?get=software&ver=1.0'', where abuild cannot use it.

* Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide ''stable'' tarballs, so when you point source to an tarball like <tt>https://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</tt>, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide ''stable'' tarballs.

* abuild currently supports the following protocols for remote file retrieval:
** http
** https
** ftp



* abuild currently supports the following archive types/archive file extensions:
** .tar
** .tar.gz / .tgz
** .tar.bz2
** .tar.lz (only in Alpine >=3.7)
** .tar.lzma
** .tar.xz
** .zip

==== depends & makedepends ====

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package in depends, you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to [https://en.wikipedia.org/wiki/Rtfm RTFM].

No kidding, lots of important information can be found in the package INSTALL and README files (or the likes). Another good way is the run <code>./configure --help</code> from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

{{Cmd|abuild unpack}}

Running <code>configure</code> will also show you how you can disable a specific option for this package. For instance, a good example is "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided by the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

* [https://gitweb.gentoo.org/repo/gentoo.git/tree/ Gentoo Ebuilds]
* [https://archlinux.org/packages/?q=search Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]

==== license ====

The '''license''' tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details.

If the license is on the [https://spdx.org/licenses/ SPDX License List] or [https://spdx.org/licenses/exceptions-index.html SPDX License Exceptions], use the identifier specified by SPDX.

Note that some licenses have additional requirements that should be adhered to. The <code>MIT</code> license for example has the requirement:

<blockquote>
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
</blockquote>

This means that we need to include the license as shipped with the project.

If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved], use the identifier "custom". In that case we need to provide the license file with the package as well.

Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

{{Cmd|install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING}}

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

{{Warning|It is not acceptable to package software with "unknown" license! If you can't find the license of the source code, please contact the author and ask them to specify the license. }}

==== arch ====

The package architecture(s) to build for. This can be one of: ''x86, x86_64, all,'' or ''noarch'', where ''all'' means all architectures, and ''noarch'' means it's architecture-independent (e.g., a pure-python package).
{{Tip|To determine if your APKBUILD can use ''noarch'', build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ''./pkg'' directory. If you do NOT get output from this, then ''noarch'' can be used.}}

==== url ====

Website address for the program. This is useful later on when either finding documentation or other information about the package.

==== pkgdesc ====

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does '''not''' end with a period.

Here is an example from apk_info for the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

==== pkgver ====

Provide the release number of the package you are building.

==== pkgrel ====

The $pkgrel versioning is made so that if you change something in your APKBUILD file without changing the actual $pkgver, you can increment pkgrel so apk tools will detect it as an update. For instance, if you forget to add a dependency, you can add it afterward and you can +1 pkgver so apk finds this update and adds the missing dependency. When there's an upstream version change, we reset the pkgrel to 0.

==== pkgname ====

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

==== install ====

There are 6 different kinds of install scripts. Each script is called with the $pkgname.''<action>'' where ''<action>'' is one of the following:

<dl>
<dt>$pkgname.pre-install
<dd>This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
<pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
Note the ''exit 0'' at the end. If the script exits with failure (if the user already exist), the package will not be installed and <code>apk add</code> will exit with failure.

<dt>$pkgname.post-install
<dd>This script is executed after the package is installed.

<dt>$pkgname.pre-upgrade
<dd>Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

<dt>$pkgname.post-upgrade
<dd>Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

<dt>$pkgname.pre-deinstall
<dd>This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

<dt>$pkgname.post-deinstall
<dd>This script is executed after a package have been uninstalled. For example, can be used to restore busybox links:
<pre>
#!/bin/sh
busybox --install -s
</pre>

</dl>

If the package has a pre-install and post-install script the APKBUILD should have the ''install'' variable defined:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"

...
</pre>

==== subpackages ====

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

{{Cmd|find pkg/usr/ -name '*.[acho]' -o -name '*.la'}}

If this returns any files you need to include the -dev package.

<br> To see if you need the -doc package you can run the following cmd:

{{Cmd|find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses}}

If this returns any directories you need to include the -doc package.

===== Custom subpackages =====

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
# or amove usr/package-test
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

==== Patches ====

Please make sure you always submit human readable patches. Ways to create them are:

directory compare:

{{Cmd|diff -Nurp original_directory new_directory > filename.patch}}

file compare:

{{Cmd|diff -up original.file new.file > filename.patch}}

If a patch contains a completely new file but not *.rej or *.orig file, you need to add -N option to diff, but you may need to add exclusions with <code>--exclude PATTERN</code> so that you do not inadvertently add files. You may need to manually delete unwanted files inside the patch file.

Because multiple patches can patch the same file, they can change the offsets required by subsequent patches. To make sure we always patch in a specific way, we should number the patches as follows:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure that patch 1 is applied first, and if we want to add additional patches between them we can use appropriate indexes (e.g. 11, 12, 21, 22).

Add the names of the patch files to the ''source'' variable. If you haven't declared a custom ''prepare'' function, no further action is necessary. Otherwise, be sure to call ''default_prepare'' in your ''prepare'' function. For example:

prepare() {
default_prepare

# do your stuff
}

Note: Some older packages contain a ''for'' loop in the ''prepare'' function to apply patches. This is not needed anymore, as patches are handled by ''default_prepare''.

In Alpine >=3.4 you can define patch_args to supply the patch level. This only works if all the patches have the same patch level. If there are a lot of patches from different sources, there is a good chance that you may need to edit them, as discussed below.

To automatically patch the package (available only in Alpine >=3.4) if it uses a patch level (-pX) other than the default (-p1), you need to carefully modify the patch. First, you'll need a text editor that does not automatically convert between Windows and Unix new lines (or, disable this feature) so that it preserves the old code. The next thing you'll need to do is modify the paths on "+++" and "---" lines in the .patch file. You can begin the path with a/ and b/ like shown below. Next, you need to adjust the paths so that the relative base path is from inside $builddir. Anything to the left of $builddir, including $builddir itself, needs to be removed from the path. So, if $builddir is /home/USER/aports/community/chromium/src/chromium-65, you need to erase it on the "+++" and "---" lines. Inside the chromium-65 folder you can see a src folder that has 3rdparty as a descendant. If a patch originally has a deeper patch level, you may need to fill in the missing portion of the path. For example, use the <code>find . -name "Assertions.cpp"</code> command to find the full path to the file relative to the base.

{{Cat|example.patch|<nowiki>
Author: John Doe <johndoe@mail.com>
URL: http://.....
Summary: Fixes musl compatibility
----
--- a/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp.orig
+++ b/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp
@@ -142,7 +142,7 @@
};

FrameToNameScope::FrameToNameScope(void* addr) : m_name(0), m_cxaDemangled(0) {
-#if OS(MACOSX) || (OS(LINUX) && !defined(__UCLIBC__))
+#if OS(MACOSX) || (OS(LINUX) && defined(__GLIBC__))
Dl_info info;
if (!dladdr(addr, &info) || !info.dli_sname)
return;
</nowiki>}}

Portions of the patch may be outdated, removed completely as in the source code file completely removed, or moved or renamed files. You need to delete that section of the patch or find where that section of code changed and re-diff it.

It is good etiquette to give credit at the top and the location of where you originally found them with notes.

Excluding patches with global variable resembling patch_opts is not available on Alpine. To exclude patches you need to create your own custom prepare().

If you have a monolithic patch where there are a bunch of patches in one big patch, you could use filterdiff which is available in the patchutils package.

Just do something like:

<pre>
makedepends="patchutils"

prepare() {
...
cd "$builddir"
filterdiff -x '*drivers/video/logo*' "$srcdir"/original.patch > "$builddir"/modified.patch
patch -p1 -i "$builddir"/modified.patch
}
</pre>

You need to put the wildcard pattern in single quotes for it to work.

==== Configure options ====

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run {{Cmd|./configure --help}} and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

==== Make options ====

If you notice weird problems when compiling or installing the package with make/make install you could try to disable [https://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:

{{Cmd|make}}

To disable parallel we use:

{{Cmd|make -j1}}

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

{{Cmd|make DESTDIR{{=}}"$pkgdir" install}}

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and doas when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

==== builddir ====
If you used <tt>newapkbuild</tt> to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process ''builddir'' is used. Most of the time a combination of ''$srcdir'' and ''$pkgname-$pkgver'' will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

<pre>
builddir="$srcdir"/$pkgname-$pkgver
</pre>

==== Additional files ====

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

{{Cmd|install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf}}

== Build the package ==

If you did not already create the checksums as mentioned above you can do so now:

{{Cmd|cd $pkgname
abuild checksum}}

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the '''-r''' switch. It will install all dependencies from your repository and builds it, afterwards it will uninstall all those depending packages again.

{{Cmd|abuild -r}}

See also [[Abuild_and_Helpers|Abuild and Helpers]].

== Testing the package locally ==

When it completes, your package will be found in a subfolder of <code>~/packages</code>. You may want to test it on your machine but only if the package is not a critical system package like musl or apk-tools package. To avoid borking your system (as in making it impossible to use <code>apk add</code> or to restore back the system and the compiler toolchain) for a critical system package, you should test on a chroot first before using it live.

The best way to test a package locally is to modify your <code>/etc/apk/repositories</code> so that it includes the indexes to your locally built packages - the directories that contain <code>ARCH/APKINDEX.tar.gz</code>. For example the <code>/etc/apk/repositories</code> below includes locally built packages in testing, community and main. To use this example change <code>USER</code> to your login name.

{{Cat|/etc/apk/repositories|/home/USER/packages/testing/
/home/USER/packages/main/
/home/USER/packages/community/
https://dl-cdn.alpinelinux.org/alpine/edge/main
https://dl-cdn.alpinelinux.org/alpine/edge/community
https://dl-cdn.alpinelinux.org/alpine/edge/testing
}}

If you prefer to test a package without changing any other configuration you can use the <code>-X, --repository</code> option to <code>apk</code>:

{{Cmd|doas apk add --repository /home/USER/packages/testing $pkgname}}

== Code review ==

To successfully have your package pass through code reviewers (as of Feb 18, 2018 are nmeum and jirutka on GitHub) and possible increased acceptance, the following conventions need to be followed:

# Custom global variables should be prefixed with underscore (_).
# Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
# Versioning is done properly. For details see [[APKBUILD_Reference#pkgver]].
# Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
# Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
# Indent with tabs not spaces.
# Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
# Disabling check() requires either (1) a comment (#) stating next to options="!check" that there is no test suite/unit tests or (2) functioning working check() function.
# Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
# Ideally, lines should be no more than 80 columns wide

Additionally, make sure to run the linter on your package:
{{Cmd|doas apk add atools
apkbuild-lint APKBUILD}}

For more information see [[Development using git:Quality assurance]] and [[Package_policies]].
Also check out [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/COMMITSTYLE.md?ref_type=heads aports/COMMITSTYLE.md] and [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/CODINGSTYLE.md?ref_type=heads aports/CODINGSTYLE.md]

== Commit your work ==

After you successfully build your package and properly followed the conventions and requirements in the code review section, you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

{{Cmd|cd $aportsdir
git pull}}

This should pull all the changes made by others into your local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our Gitlab instance, you can create MR's for each package. Please squash all commits related to the same package into a single one per MR.

{{Cmd|cd $aportsdir
git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...)
git commit}}

Use the following commit message template for new aports (without the comments):

{{Cat|template|testing/$pkgname: new aport # this will be the subject line
# a blank line
$url # project homepage
$pkgdesc # one line description}}

Or you could add the following and <code>chmod +x ports/.git/hooks/prepare-commit-msg</code> to automatically generate commit message which the default aports/.githooks/ does not:

{{Cat|aports/.git/hooks/prepare-commit-msg|<nowiki>#!/bin/sh
case "$2,$3" in
,|template,)
if git diff-index --diff-filter=A --name-only --cached HEAD \
| grep -q '/APKBUILD$'; then
meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
printf 'testing/%s: new aport\n\n%s\n%s\n' "$(meta pkgname)" \
"$(meta url)" "$(meta pkgdesc)" "$(cat $1)" > "$1"
else
printf '%s\n\n%s' `git diff-index --name-only --cached HEAD \
| sed -n 's/\/APKBUILD$//p;q'` "$(cat $1)" > "$1"
fi;;
esac</nowiki>}}

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a merge request to [https://gitlab.alpinelinux.org/alpine/aports Alpine's GitLab instance].

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the
[https://lists.alpinelinux.org/~alpine/aports alpine-aports mailinglist].

To create a diff patch:

{{Cmd|git format-patch HEAD^}}

or if you have sprunge, you can create a link to your patch for convenience

{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}

== Automated flagging of outdated ports ==
Consider adding your port to [https://release-monitoring.org/ Anitya], so it will be flagged as outdated
as soon as a new stable version is released by upstream.

== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]

[[category: Package Manager]]