Alpine Linux - User contributions [en]

Alpine Linux in a chroot

2019-12-29T00:00:00Z

Hypocritus: /* Method 1.A fast way: using bind mount */ --- changed '/alpine' to '${chroot_dir}' for consistency, since the original variables are declared as such, in addition to many Alpine articles using '/mnt' instead of '/alpine' for the chroot mountpoint

{{TOC right}}

Inside the chroot environment, you can build, debug, and run alpine packages or develop things. It's the most known way to do so if one wants not to trash their main Alpine system.

This document explains how to set up an [[Alpine_newbie#Developer|Alpine build environment]] in a chroot under a host Linux distro, can also be used to install Alpine Linux from a non-Alpine Linux livecd.

== Requirements ==

* Working Linux instalation where to perform all the process
* Linux kernel 2.6.22, with <code>wget</code> and <code>chroot</code> installed
* target media with at least 100M, 900MB for more complete solution as minimum
* internet connection

== Prerequisites ==

The variables below:

*'''${chroot_dir}''' = Should point to the chroot directory where you
*'''${mirror}''' = Should be replaced with [http://nl.alpinelinux.org/alpine/MIRRORS.txt one of the available Alpine Linux mirrors].
*'''${arch}''' = Should be the cpu architecture like x86 (i386) or amd64(x86_64)..

== Set up APK ==

Download the latest apk static package (replace <tt>${version}</tt> with actual version):

{{Cmd|wget ${mirror}/latest-stable/main/${arch}/apk-tools-static-${version}.apk}}

.apk packages are just gzipped tarballs, unpack using:
{{Cmd|tar -xzf apk-tools-static-*.apk}}

== Install the alpine base installation onto the chroot ==

{{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted --root ${chroot_dir} --initdb add alpine-base}}

== Set up the chroot ==

Before made and enter into the chrooted system must be prepared with device nodes and tempfs :

===== Method 1.A fast way: using bind mount =====

{{Note|Mounts with bind, can mount in read-only the /dev at the alpine chroot so due limited will not touch the access time of the host system}}

{{Cmd|mount /dev/ ${chroot_dir}/dev/ --bind
mount -o remount,ro,bind ${chroot_dir}/dev
}}

If you need SCSI or R/W access only do the first command, mounting with "ro" makes more secure your chroot.

===== Method 1.B manual way: creating need nodes =====

{{Warning|Manually creating devices will only provide those representation that you have created.. for auto availability use bind mounts}}

{{Cmd|mknod -m 666 ${chroot_dir}/dev/full c 1 7
mknod -m 666 ${chroot_dir}/dev/ptmx c 5 2
mknod -m 644 ${chroot_dir}/dev/random c 1 8
mknod -m 644 ${chroot_dir}/dev/urandom c 1 9
mknod -m 666 ${chroot_dir}/dev/zero c 1 5
mknod -m 666 ${chroot_dir}/dev/tty c 5 0}}

If you need SCSI disc access:

{{Cmd|mknod -m 666 ${chroot_dir}/dev/sda b 8 0
mknod -m 666 ${chroot_dir}/dev/sda1 b 8 1
mknod -m 666 ${chroot_dir}/dev/sda2 b 8 2
mknod -m 666 ${chroot_dir}/dev/sda3 b 8 3
mknod -m 666 ${chroot_dir}/dev/sda4 b 8 4
mknod -m 666 ${chroot_dir}/dev/sda5 b 8 5
mknod -m 666 ${chroot_dir}/dev/sda6 b 8 6
mknod -m 666 ${chroot_dir}/dev/sdb b 8 16
mknod -m 666 ${chroot_dir}/dev/sdb1 b 8 17
mknod -m 666 ${chroot_dir}/dev/sdb2 b 8 18
mknod -m 666 ${chroot_dir}/dev/sdb3 b 8 19
mknod -m 666 ${chroot_dir}/dev/sdb4 b 8 20
mknod -m 666 ${chroot_dir}/dev/sdb5 b 8 21
mknod -m 666 ${chroot_dir}/dev/sdb6 b 8 22}}

==== Made available proc and sys fs ====

{{Cmd|mount -t proc none ${chroot_dir}/proc
mount -o bind /sys ${chroot_dir}/sys}}

==== Make networking resolution access ====

A resolv.conf is needed for name resolution:

{{Cmd|cp /etc/resolv.conf ${chroot_dir}/etc/
mkdir -p ${chroot_dir}/root}}

If you don't want to copy the resolv.conf from the local machine, you can create a new one using OpenDNS servers (or any other):
{{Cmd|echo -e 'nameserver 8.8.8.8\nnameserver 2620:0:ccc::2' > ${chroot_dir}/etc/resolv.conf}}

==== prepare the apk sources software ====

Set up APK mirror (replace <tt>${branch}</tt> with the latest stable branch name, e.g. v3.3):

{{Cmd|mkdir -p ${chroot_dir}/etc/apk
echo "${mirror}/${branch}/main" > ${chroot_dir}/etc/apk/repositories}}

== Entering your chroot ==

{{Warning|At this point, Alpine has been succesfully installed onto the chroot directory '''but still not able to boot it'''. }}

{{Cmd|chroot ${chroot_dir} /bin/bash -l}}

==== Perform init process ====

Need to add some minimal initscripts to appropriate runlevels:

{{Cmd|rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown}}

= Troubleshooting =

== hardened kernels or alpine as chroot host ==

If you are using Alpine as a Native build system you will have to make sure that chroot can run chmod. Add following to <code>/etc/sysctl.conf</code>

<code>kernel.grsecurity.chroot_deny_chmod = 0</code>

Then run the following command

<code>sysctl -p</code>

== chroot: cannot run command ' ... Exec format error ==

This usually indicates that you booted with one architecture (e.g. armf) and are trying to chroot into another (e.g. x86_64). If you plans to make chroot into another installation must use same arch for both host and hosted chrooted!

Note that with '''one exception you can run 32 bit x86 chroot in x86_64, but not viceversa'''!

== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==

Make sure <code>${chroot_dir}/etc/apk/repositories</code> is valid and inside the chroot run:

<code>apk update</code>

= External links =

* You can also use script [https://github.com/alpinelinux/alpine-chroot-install/ alpine-chroot-install]
* https://web.archive.org/web/20190808203313/https://isc.sans.edu/forums/diary/Forensic+use+of+mount+bind/22854/
* Alpine Linux in a chroot on Fedora : http://git.alpinelinux.org/cgit/user/fab/scripts/tree/alpine-chroot.sh script
* Alpine Linux aarch64 in a chroot on AWS Linux : https://gist.github.com/emolitor/0567e51c0ce04f4b025fc78d2cf0b4f1 script

[[Category:Installation]]
[[category: System Administration]]

Alpine Linux in a chroot

2019-12-23T12:29:23Z

Hypocritus: grammar correction

{{TOC right}}

Inside the chroot environment, you can build, debug, and run alpine packages or develop things. It's the most known way to do so if one wants not to trash their main Alpine system.

This document explains how to set up an [[Alpine_newbie#Developer|Alpine build environment]] in a chroot under a host Linux distro, can also be used to install Alpine Linux from a non-Alpine Linux livecd.

== Requirements ==

* Working Linux instalation where to perform all the process
* Linux kernel 2.6.22, with <code>wget</code> and <code>chroot</code> installed
* target media with at least 100M, 900MB for more complete solution as minimum
* internet connection

== Prerequisites ==

The variables below:

*'''${chroot_dir}''' = Should point to the chroot directory where you
*'''${mirror}''' = Should be replaced with [http://nl.alpinelinux.org/alpine/MIRRORS.txt one of the available Alpine Linux mirrors].
*'''${arch}''' = Should be the cpu architecture like x86 (i386) or amd64(x86_64)..

== Set up APK ==

Download the latest apk static package (replace <tt>${version}</tt> with actual version):

{{Cmd|wget ${mirror}/latest-stable/main/${arch}/apk-tools-static-${version}.apk}}

.apk packages are just gzipped tarballs, unpack using:
{{Cmd|tar -xzf apk-tools-static-*.apk}}

== Install the alpine base installation onto the chroot ==

{{Cmd|./sbin/apk.static -X ${mirror}/latest-stable/main -U --allow-untrusted --root ${chroot_dir} --initdb add alpine-base}}

== Set up the chroot ==

Before made and enter into the chrooted system must be prepared with device nodes and tempfs :

===== Method 1.A fast way: using bind mount =====

{{Note|Mounts with bind, can mount in read-only the /dev at the alpine chroot so due limited will not touch the access time of the host system}}

{{Cmd|mount /dev/ /alpine/dev/ --bind
mount -o remount,ro,bind /alpine/dev
}}

If you need SCSI or R/W access only do the first command, mounting with "ro" makes more secure your chroot.

===== Method 1.B manual way: creating need nodes =====

{{Warning|Manually creating devices will only provide those representation that you have created.. for auto availability use bind mounts}}

{{Cmd|mknod -m 666 ${chroot_dir}/dev/full c 1 7
mknod -m 666 ${chroot_dir}/dev/ptmx c 5 2
mknod -m 644 ${chroot_dir}/dev/random c 1 8
mknod -m 644 ${chroot_dir}/dev/urandom c 1 9
mknod -m 666 ${chroot_dir}/dev/zero c 1 5
mknod -m 666 ${chroot_dir}/dev/tty c 5 0}}

If you need SCSI disc access:

{{Cmd|mknod -m 666 ${chroot_dir}/dev/sda b 8 0
mknod -m 666 ${chroot_dir}/dev/sda1 b 8 1
mknod -m 666 ${chroot_dir}/dev/sda2 b 8 2
mknod -m 666 ${chroot_dir}/dev/sda3 b 8 3
mknod -m 666 ${chroot_dir}/dev/sda4 b 8 4
mknod -m 666 ${chroot_dir}/dev/sda5 b 8 5
mknod -m 666 ${chroot_dir}/dev/sda6 b 8 6
mknod -m 666 ${chroot_dir}/dev/sdb b 8 16
mknod -m 666 ${chroot_dir}/dev/sdb1 b 8 17
mknod -m 666 ${chroot_dir}/dev/sdb2 b 8 18
mknod -m 666 ${chroot_dir}/dev/sdb3 b 8 19
mknod -m 666 ${chroot_dir}/dev/sdb4 b 8 20
mknod -m 666 ${chroot_dir}/dev/sdb5 b 8 21
mknod -m 666 ${chroot_dir}/dev/sdb6 b 8 22}}

==== Made available proc and sys fs ====

{{Cmd|mount -t proc none ${chroot_dir}/proc
mount -o bind /sys ${chroot_dir}/sys}}

==== Make networking resolution access ====

A resolv.conf is needed for name resolution:

{{Cmd|cp /etc/resolv.conf ${chroot_dir}/etc/
mkdir -p ${chroot_dir}/root}}

If you don't want to copy the resolv.conf from the local machine, you can create a new one using OpenDNS servers (or any other):
{{Cmd|echo -e 'nameserver 8.8.8.8\nnameserver 2620:0:ccc::2' > ${chroot_dir}/etc/resolv.conf}}

==== prepare the apk sources software ====

Set up APK mirror (replace <tt>${branch}</tt> with the latest stable branch name, e.g. v3.3):

{{Cmd|mkdir -p ${chroot_dir}/etc/apk
echo "${mirror}/${branch}/main" > ${chroot_dir}/etc/apk/repositories}}

== Entering your chroot ==

{{Warning|At this point, Alpine has been succesfully installed onto the chroot directory '''but still not able to boot it'''. }}

{{Cmd|chroot ${chroot_dir} /bin/bash -l}}

==== Perform init process ====

Need to add some minimal initscripts to appropriate runlevels:

{{Cmd|rc-update add devfs sysinit
rc-update add dmesg sysinit
rc-update add mdev sysinit

rc-update add hwclock boot
rc-update add modules boot
rc-update add sysctl boot
rc-update add hostname boot
rc-update add bootmisc boot
rc-update add syslog boot

rc-update add mount-ro shutdown
rc-update add killprocs shutdown
rc-update add savecache shutdown}}

= Troubleshooting =

== hardened kernels or alpine as chroot host ==

If you are using Alpine as a Native build system you will have to make sure that chroot can run chmod. Add following to <code>/etc/sysctl.conf</code>

<code>kernel.grsecurity.chroot_deny_chmod = 0</code>

Then run the following command

<code>sysctl -p</code>

== chroot: cannot run command ' ... Exec format error ==

This usually indicates that you booted with one architecture (e.g. armf) and are trying to chroot into another (e.g. x86_64). If you plans to make chroot into another installation must use same arch for both host and hosted chrooted!

Note that with '''one exception you can run 32 bit x86 chroot in x86_64, but not viceversa'''!

== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==

Make sure <code>${chroot_dir}/etc/apk/repositories</code> is valid and inside the chroot run:

<code>apk update</code>

= External links =

* You can also use script [https://github.com/alpinelinux/alpine-chroot-install/ alpine-chroot-install]
* https://web.archive.org/web/20190808203313/https://isc.sans.edu/forums/diary/Forensic+use+of+mount+bind/22854/
* Alpine Linux in a chroot on Fedora : http://git.alpinelinux.org/cgit/user/fab/scripts/tree/alpine-chroot.sh script
* Alpine Linux aarch64 in a chroot on AWS Linux : https://gist.github.com/emolitor/0567e51c0ce04f4b025fc78d2cf0b4f1 script

[[Category:Installation]]
[[category: System Administration]]

Alpine configuration management scripts

2019-12-22T17:30:50Z

Hypocritus: /* setup-alpine */ clarified grammar

This page summarizes the low-level behavior of the {{Path|/sbin/setup-*}} scripts on the Alpine ISO (and in a normal Alpine install).

== setup-alpine ==

This is a low-level administrator command, for a higher-level walkthrough please use the [[Alpine_newbie_install_manual#Ways_to_install_Alpine_into_machines_or_virtuals|Alpine for new users install manuals]] (that use the "sys" install mode).

The [[Alpine_newbie_install_manual#Ways_to_install_Alpine_into_machines_or_virtuals|Alpine for new users install manuals]] page wiki also references this script, but is less technical.

This script accepts the following command-line switches (you can run <code>setup-alpine -h</code> to see a usage message).

{{Define|-a|Create an overlay file: this creates a temporary directory and saves its location in ROOT; however, the script doesn't export this variable so I think this feature isn't currently functional.}}
;-c <var>answerfile</var>
:Create a new "answerfile", with default choices. You can edit the file and then invoke <code>setup-alpine -f <var>answerfile</var></code>.
;-f <var>answerfile</var>
:Use an existing "answerfile", which may override some or all of the interactive prompts.
{{Define|-q|Run in "quick mode." See below for details.}}

The script's behavior is to do the following, in order. Bracketed options represent extra configuration choices that can be supplied when running the auxiliary setup scripts manually, or by supplying an "answerfile".

# <code>setup-keymap</code> [us us]
# [[#setup-hostname|setup-hostname]] [-n alpine-test]
# [[#setup-interfaces|setup-interfaces]] [-i < interfaces-file]
# <code>/etc/init.d/networking --quiet start &</code>
# if none of the networking interfaces were configured using dhcp, then: [[#setup-dns|setup-dns]] [-d example.com -n "8.8.8.8 [...]"]
# set the root password
# if not in quick mode, then: [[#setup-timezone|setup-timezone]] [-z UTC | -z America/New_York | -p EST+5]
# enable the new hostname (<code>/etc/init.d/hostname --quiet restart</code>)
# add <code>networking</code> and <code>urandom</code> to the '''boot''' rc level, and <code>acpid</code> and <code>cron</code> to the '''default''' rc level, and start the '''boot''' and '''default''' rc services
# extract the fully-qualified domain name and hostname from {{Path|/etc/resolv.conf}} and <code>hostname</code>, and update {{Path|/etc/hosts}}
# [[#setup-proxy|setup-proxy]] [-q <nowiki>"http://webproxy:8080"</nowiki>], and activate proxy if it was configured
# <code>setup-apkrepos</code> [-r (to select a mirror randomly)]
# if not in quick mode, then: [[#setup-sshd|setup-sshd]] [-c openssh | dropbear | none]
# if not in quick mode, then: <code>setup-ntp</code> [-c chrony | openntpd | busybox | none]
# if not in quick mode, then: <code>DEFAULT_DISK=none</code> [[#setup-disk|setup-disk]] <code>-q</code> [-m data /dev/sda]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-lbu</code> [/media/sdb1]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-apkcache</code> [/media/sdb1/cache | none]

== setup-hostname ==

:<code>setup-hostname</code> [-h] [-n hostname]

Options:

'''-h''' <var>Show help</var>

'''-n''' <var>Specify hostname</var>

This script allows quick and easy setup of the system hostname by writing it to {{Path|/etc/hostname}}. The script prevents you from writing an invalid hostname (such as one that used invalid characters or starts with a '-' or is too long).
The script can be invoked manually or is called as part of the <code>setup-alpine</code> script.

== setup-interfaces ==
{{Cmd|setup-interfaces [-i < <var>interfaces-file</var>]}}

Note that the contents of <var>interfaces-file</var> has to be supplied as stdin, rather than naming the file as an additional argument. The contents should have the format of {{Path|/etc/network/interfaces}}, such as:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
hostname alpine-test

== setup-dns ==

:<code>setup-dns</code> [-h] [-d domain name] [-n name server]

Options:

'''-h''' <var>Show help</var>

'''-d''' <var>specify search domain name</var>

'''-n''' <var>name server IP</var>

The setup-dns script is stored in {{Path|/sbin/setup-dns}} and allows quick and simple setup of DNS servers (and a DNS search domain if required). Simply running <code>setup-dns</code> will allow interactive use of the script, or the options can be specified.

The information fed to this script is written to {{Path|/etc/resolv.conf}}

Example usage: {{Cmd|setup-dns -d example.org -n 8.8.8.8}}

Example {{Path|/etc/resolv.conf}}:

search example.org
nameserver 8.8.8.8

It can be run manually but is also invoked in the <code>setup-alpine</code> script unless interfaces are configured for DHCP.

== setup-timezone ==
:<code>setup-timezone</code> [-z UTC | -z America/New_York | -p EST+5]

Can pre-select the timezone using either of these switches:

'''-z''' <var>subfolder of</var> {{Path|/usr/share/zoneinfo}}

'''-p''' <var>POSIX TZ format</var>

== setup-proxy ==
:<code>setup-proxy</code> [-hq] [PROXYURL]

Options:

'''-h''' <var>Show help</var>

'''-q''' <var>Quiet mode</var> prevents changes from taking effect until after reboot

This script requests the system proxy to use in the form <code>http://<proxyurl>:<port></code> for example:
<code>http://10.0.0.1:8080</code>

To set no system proxy use <code>none</code>.
This script exports the following environmental variables:

<code>http_proxy=$proxyurl</code>

<code>https_proxy=$proxyurl</code>

<code>ftp_proxy=$proxyurl</code>

where <code>$proxyurl</code> is the value input.
If <code>none</code> was chosen then the value it is set to a blank value (and so no proxy is used).

== setup-sshd ==

:<code>setup-sshd</code> [-h] [-c choice of SSH daemon]

Options:

'''-h''' <var>Show help</var>

'''-c''' <var>SSH daemon</var> where SSH daemon can be one of the following:

<code>openssh</code> install the {{Pkg|openSSH}} daemon

<code>dropbear</code> install the {{Pkg|dropbear}} daemon

<code>none</code> Do not install an SSH daemon

Example usage: {{Cmd|setup-sshd -c dropbear}}

The setup-sshd script is stored in {{Path|/sbin/setup-sshd}} and allows quick and simple setup of either the OpenSSH or Dropbear SSH daemon & client.
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

== setup-apkrepos ==
:<code>setup-apkrepos</code> [-fhr] [REPO...]

Setup <code>apk</code> repositories.

options:

'''-f''' <var>Detect and add fastest mirror</var>

'''-r''' <var>Add a random mirror and do not prompt</var>

'''-1''' <var>Add first mirror on the list (normally a CDN)</var>

This is run as part of the <code>setup-alpine</code> script.

== setup-disk ==

:<code>DEFAULT_DISK=none setup-disk -q</code> [-m data | sys] [<var>mountpoint directory</var> | /dev/sda ...]

In "sys" mode, it's an installer, it permanently installs Alpine on the disk, in "data" mode, it provides a larger and persistent /var volume.

This script accepts the following command-line switches:

;-k <var>kernel flavor</var>
;-o <var>apkovl file</var>
:Restore system from <var>apkovl file</var>
;-m data | sys
:Don't prompt for installation mode. With '''-m data''', the supplied devices are formatted to use as a {{Path|/var}} volume.
{{Define|-r|Use RAID1 with a single disk (degraded mode)}}
{{Define|-L|Create and use volumes in a LVM group}}
;-s <var>swap size in MB</var>
:Use 0 to disable swap
{{Define|-q|Exit quietly if no disks are found}}
{{Define|-v|Verbose mode}}

The script also honors the following environment variables:

<code>BOOT_SIZE</code>
:Size of the boot partition in MB; defaults to 100. Only used if '''-m sys''' is specified or interactively selected.

<code>SWAP_SIZE</code>
:Size of the swap volume in MB; set to 0 to disable swap. If not specified, will default to twice RAM, up to 4096, but won't be more than 1/3 the size of the smallest disk, and if less than 64 will just be 0. Only used if '''-m sys''' is specified or interactively selected.

<code>ROOTFS</code>
:Filesystem to use for the / volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs xfs.

<code>BOOTFS</code>
:Filesystem to use for the /boot volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs xfs.

<code>VARFS</code>
:Filesystem to use for the /var volume; defaults to ext4. Only used if '''-m data''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs xfs.

<code>SYSROOT</code>
:Mountpoint to use when creating volumes and doing traditional disk install ('''-m sys'''). Defaults to {{Path|/mnt}}.

<code>MBR</code>
:Path of MBR binary code, defaults to {{Path|/usr/share/syslinux/mbr.bin}}.

<code>BOOTLOADER</code>
:Bootloader to use, defaults to syslinux. Supported bootloaders are: grub syslinux zipl.

<code>DISKLABEL</code>
:Disklabel to use, defaults to dos. Supported disklabels are: dos gpt eckd.



=== Partitioning ===

If you have complex partitioning needs, you can partition, format, and mount your volumes manually, then just supply the root mountpoint to <code>setup-disk</code>. Doing so implicitly behaves as though '''-m sys''' had also been specified.

See [[Setting up disks manually]] for more information.

==== RAID ====
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device. The array will always be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_1 RAID1] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-0.90_Superblock_Format --metadata=0.90]) for the /boot volumes, but will be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_5 RAID5] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-1_Superblock_Format --metadata=1.2] for non-boot volumes when 3 or more devices are supplied.

If you instead want to build your RAID array manually, see [[Setting up a software RAID array]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.

==== LVM ====
<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch. The group and volumes created by the script will have the following names:

* volume group: '''vg0'''
* swap volume: '''lv_swap''' (only created when swap size > 0)
* root volume: '''lv_root''' (only created when '''-m sys''' is specified or interactively selected)
* var volume: '''lv_var''' (only created when '''-m data''' is specified or interactively selected)

The '''lv_var''' or '''lv_root''' volumes are created to occupy all remaining space in the volume group.

If you need to change any of these settings, you can use <code>vgrename</code>, <code>lvrename</code>, <code>lvreduce</code> or <code>lvresize</code>.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.



== setup-bootable ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Its purpose is to create media that boots into tmpfs by copying the contents of an ISO onto a USB key, CF, or similar media.

For a higher-level walkthrough, see [[Create a Bootable USB#Creating_a_bootable_Alpine_Linux_USB_Stick_from_the_command_line|Creating a bootable Alpine Linux USB Stick from the command line]].

This script accepts the following arguments and command-line switches (you can run <code>setup-bootable -h</code> to see a usage message).

{{Cmd|setup-bootable <var>source</var> [<var>dest</var>]}}

The argument <var>source</var> can be a directory or an ISO (will be mounted to <code>MNT</code> or {{Path|/mnt}}) or a URL (will be downloaded with <code>WGET</code> or <code>wget</code>). The argument <var>dest</var> can be a directory mountpoint, or will default to {{Path|/media/usb}} if not supplied.

{{Define|-k|Keep alpine_dev in {{Path|syslinux.cfg}}; otherwise, replace with UUID.}}
{{Define|-u|Upgrade mode: keep existing {{Path|syslinux.cfg}} and don't run <code>syslinux</code>}}
{{Define|-f|Overwrite {{Path|syslinux.cfg}} even if '''-u''' was specified.}}
{{Define|-s|Force the running of <code>syslinux</code> even if '''-u''' was specified.}}
{{Define|-v|Verbose mode}}

The script will ensure that <var>source</var> and <var>dest</var> are available; will copy the contents of <var>source</var> to <var>dest</var>, ensuring first that there's enough space; and unless '''-u''' was specified, will make <var>dest</var> bootable.



== setup-xorg-base ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Installs the following packages: <code>xorg-server xf86-video-vesa xf86-input-evdev xf86-input-mouse xf86-input-keyboard udev</code>.

Additional packages can be supplied as arguments to <code>setup-xorg-base</code>. You might need, for example, some of: <code>xf86-input-synaptics xf86-video-<var>something</var> xinit</code>. For Qemu, see [[Qemu#Using_Xorg_inside_Qemu|Qemu]]. For Intel GPUs, see [[Intel Video]].

== Documentation needed ==

=== setup-xen-dom0 ===

=== setup-gparted-desktop ===
Uses openbox.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

=== setup-mta ===
Uses ssmtp.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

=== setup-acf ===
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

This script was named <code>setup-webconf</code> before Alpine 1.9 beta 4.

See [[:Category:ACF|ACF pages]] for more information.

=== setup-ntp ===

= =
* [https://beta.docs.alpinelinux.org/ beta.docs.alpinelinux.org]

[[Category:Installation]]

Root on ZFS with native encryption

2019-12-22T17:17:46Z

Hypocritus: /* Installing Alpine Linux */ changed 'apk install...' to "apk add..."

= Introduction =

This documentation describes how to set up Alpine Linux using ZFS with a pool that uses ZFS' native encryption capabilities, which have been recently introduced in ZFS on Linux (ZoL) 0.8.0.

Note that you must install the <code>/boot/</code> directory on an unencrypted partition (either an unencrypted ZFS pool or any other FS of your choosing, if it's compatible with your bootloader) to boot correctly.

== Requirements ==

You'll need a medium to put a live image on. You can use any live medium that supports ZoL >=0.8.x, but as of writing this it's easiest to use [https://cdimage.debian.org/cdimage/weekly-live-builds/amd64/iso-hybrid/ Debian Buster's live images] for this.

== Hard Disk Device Name ==

The following documentation uses the <code>/dev/sda</code> device as installation destination. If your environment uses a different device name for your hard disk, use the corresponding device names in the examples. It also uses <code>rpool</code> as name of the root pool, you can change this at will, but be sure to change it everywhere it's mentioned.

= Setting up Alpine Linux Using ZFS with native encryption =

To install Alpine Linux in a ZFS pool with encryption enable, you cannot use the [[Installation|official installation]] procedure, so follow along this guide.

== Preparing the Installation Environment ==

This section assumes that you're using the previously mentioned Debian installation medium. If you're using a different medium feel free to skip this section.

After booting the Debian image you'll have to enable the <code>experimental</code> repos for the time being to be able to access ZFS 0.8. For this you'll have to edit <code>/etc/apt/sources.list</code>:

# sed 's/buster/experimental/' -i /etc/apt/sources.list
# echo 'deb http://deb.debian.org/debian experimental contrib' >> /etc/apk/repositories

Now install ZFS 0.8:

# apt update
# apt install libnvpair1linux libuutil1linux libzfs2linux libzpool2linux zfs-dkms zfsutils-linux zfs-zed

And load the ZFS module:

# modprobe zfs

== Creating the Partition Layout ==

Linux requires an unencrypted <code>/boot/</code> partition to boot. You can assign the remaining space for the encrypted ZFS pool.

* Start the <code>fdisk</code> utility to set up partitions:

# fdisk /dev/sda

:* Create the <code>/boot/</code> partition:
::* Enter <code>n</code> → <code>p</code> → <code>1</code> → <code>1</code> → <code>100m</code> to create a new 100 MB primary partition.

:* Set the <code>/boot/</code> partition active:
::* Enter <code>a</code> → <code>1</code>.

:* Create the ZFS partition:
::* Enter <code>n</code> → <code>p</code> → <code>2</code> to start creating the next partition. Press <code>Enter</code> to select the default start cylinder. Enter the size of partition. For example, <code>512m</code> for 512 MB or <code>5g</code> for 5 GB. Alternatively press <code>Enter</code> to set the maximum available size.

:* To verify the settings, press <code>p</code>. The output shows, for example:
<pre>
Device Boot Start End Sectors Size Id Type
/dev/sda1 * 2048 206847 204800 100M 83 Linux
/dev/sda2 206848 41943039 41736192 19.9G 83 Linux
</pre>
* Press <code>w</code> to save the changes.

== Setting up the root pool ==

You can create your rootpool with the following command:

# zpool create -o ashift=12 \
-O acltype=posixacl -O canmount=off -O compression=lz4 \
-O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \
-O encryption=aes-256-gcm -O keylocation=prompt -O keyformat=passphrase \
-O mountpoint=/ -R /mnt \
rpool /dev/sda2

You will have to enter your passphrase at this point. Choose wisely, as your passphrase is most likely [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects the weakest link in this setup].

A few notes on the options supplied to zpool:

* <code>ashift=12</code> is recommended here because many drives today have 4KiB (or larger) physical sectors, even though they present 512B logical sectors

* <code>acltype=posixacl</code> enables POSIX ACLs globally

* <code>normalization=formD</code> eliminates some corner cases relating to UTF-8 filename normalization. It also enables <code>utf8only=on</code>, meaning that only files with valid UTF-8 filenames will be accepted.

* <code>xattr=sa</code> vastly improves the performance of extended attributes, but is Linux-only. If you care about using this pool on other OpenZFS implementation don't specify this option.

After completing this, confirm that the pool has been created:

# zpool status

Should return something like:
<pre>
pool: rpool
state: ONLINE
scan: none requested
config:

NAME STATE READ WRITE CKSUM
rpool ONLINE 0 0 0
sda2 ONLINE 0 0 0

errors: No known data errors
</pre>

=== Creating the required datasets ===

# zfs create -o mountpoint=none -o canmount=off rpool/ROOT
# zfs create -o mountpoint=legacy rpool/ROOT/alpine
# mount -t zfs rpool/ROOT/alpine /mnt/

=== Creating optional datasets (feel free to add your own) ===

# zfs create -o mountpoint=/home rpool/HOME
# zfs create -o mountpoint=/var/log rpool/LOG

== Creating the <code>/boot</code> filesystem ==

# mkfs.ext4 /dev/sda1

== Mounting the <code>/boot</code> filesystem ==

* Create the <code>/mnt/boot/</code> directory and mount the <code>/dev/sda1</code> partition in this directory:

# mkdir /mnt/boot/
# mount -t ext4 /dev/sda1 /mnt/boot/

== Installing Alpine Linux ==

Please follow [[Installing_Alpine_Linux_in_a_chroot|Installing Alpine Linux in a chroot]] to setup a base install of Alpine Linux.

After you've followed that guide, you still have to do some additional setup for ZFS:

* As of the time of writing this ZFS 0.8.x is only available in [[Edge]], so you'll have to enable it in <code>/etc/apk/repositories</code>. Check [https://pkgs.alpinelinux.org/packages?name=zfs pkgs.alpinelinux.org] to see the status of this.

* Install the ZoL and linux-vanilla package: <code>apk add linux-vanilla zfs</code>

* Enable ZFS' services:

# rc-update add zfs-import sysinit
# rc-update add zfs-mount sysinit

* Edit the <code>/etc/mkinitfs/mkinitfs.conf</code> file and append <code>zfs</code> module to the <code>features</code> parameter:

features="ata base ide scsi usb virtio ext4 lvm zfs"

Be mindful to also include other modules which may be required for your setup, such as the <code>nvme</code> module.

* Rebuild the initial RAM disk:

# mkinitfs $(ls /lib/modules/)

* Edit the <code>/etc/update-extlinux.conf</code> file, set the root ZFS dataset and append the following kernel options to the <code>default_kernel_opts</code> parameter:

root=rpool/ROOT/alpine
default_kernel_opts="... rootfstype=zfs"

* Update extlinux's config (if you're not using a different bootloader)

# update-extlinux
# exit

: Ignore the errors the <code>update-extlinux</code> utility displays.

* Write the MBR to the <code>/dev/sda</code> device:

# dd bs=440 count=1 conv=notrunc if=/mnt/usr/share/syslinux/mbr.bin of=/dev/sda

== Unmounting the filesystems ==

* Unmount <code>/mnt/boot/</code>:

# umount /mnt/boot/

* Unmount all zfs filesystems:

# zfs unmount -a

* Reboot the system:

# reboot

== Booting the system ==

Right now mkinitfs doesn't support ZFS asking for passwords during boot, so it'll throw you into a rescue shell for you to enter the password during boot. You have to do the following things after pressing enter:

# zfs load-key -a
# mount -t zfs rpool/ROOT/alpine /sysroot
# exit

And your system should continue booting! :)

= Troubleshooting =

== General Procedure ==

In case your system fails to boot, you can verify the settings and fix incorrect configurations:

* [[#Preparing_the_Installation_Environment|Preparing the Installation Environment]]

* Load the ZFS kernel module:

# modprobe zfs

* [[#Mounting_the_File_Systems|Mount the file systems]]

# zpool import -R /mnt rpool
# mount -t ext4 /dev/sda1 /mnt/boot

* Verify that you run the steps described in the [[#Installing_Alpine_Linux|Installing Alpine Linux]] section correctly. Update the configuration if necessary.

[[Category:Storage]]
[[Category:Security]]

Root on ZFS with native encryption

2019-12-22T17:15:02Z

Hypocritus: /* Preparing the Installation Environment */ -- finished an incomplete repository edit command

= Introduction =

This documentation describes how to set up Alpine Linux using ZFS with a pool that uses ZFS' native encryption capabilities, which have been recently introduced in ZFS on Linux (ZoL) 0.8.0.

Note that you must install the <code>/boot/</code> directory on an unencrypted partition (either an unencrypted ZFS pool or any other FS of your choosing, if it's compatible with your bootloader) to boot correctly.

== Requirements ==

You'll need a medium to put a live image on. You can use any live medium that supports ZoL >=0.8.x, but as of writing this it's easiest to use [https://cdimage.debian.org/cdimage/weekly-live-builds/amd64/iso-hybrid/ Debian Buster's live images] for this.

== Hard Disk Device Name ==

The following documentation uses the <code>/dev/sda</code> device as installation destination. If your environment uses a different device name for your hard disk, use the corresponding device names in the examples. It also uses <code>rpool</code> as name of the root pool, you can change this at will, but be sure to change it everywhere it's mentioned.

= Setting up Alpine Linux Using ZFS with native encryption =

To install Alpine Linux in a ZFS pool with encryption enable, you cannot use the [[Installation|official installation]] procedure, so follow along this guide.

== Preparing the Installation Environment ==

This section assumes that you're using the previously mentioned Debian installation medium. If you're using a different medium feel free to skip this section.

After booting the Debian image you'll have to enable the <code>experimental</code> repos for the time being to be able to access ZFS 0.8. For this you'll have to edit <code>/etc/apt/sources.list</code>:

# sed 's/buster/experimental/' -i /etc/apt/sources.list
# echo 'deb http://deb.debian.org/debian experimental contrib' >> /etc/apk/repositories

Now install ZFS 0.8:

# apt update
# apt install libnvpair1linux libuutil1linux libzfs2linux libzpool2linux zfs-dkms zfsutils-linux zfs-zed

And load the ZFS module:

# modprobe zfs

== Creating the Partition Layout ==

Linux requires an unencrypted <code>/boot/</code> partition to boot. You can assign the remaining space for the encrypted ZFS pool.

* Start the <code>fdisk</code> utility to set up partitions:

# fdisk /dev/sda

:* Create the <code>/boot/</code> partition:
::* Enter <code>n</code> → <code>p</code> → <code>1</code> → <code>1</code> → <code>100m</code> to create a new 100 MB primary partition.

:* Set the <code>/boot/</code> partition active:
::* Enter <code>a</code> → <code>1</code>.

:* Create the ZFS partition:
::* Enter <code>n</code> → <code>p</code> → <code>2</code> to start creating the next partition. Press <code>Enter</code> to select the default start cylinder. Enter the size of partition. For example, <code>512m</code> for 512 MB or <code>5g</code> for 5 GB. Alternatively press <code>Enter</code> to set the maximum available size.

:* To verify the settings, press <code>p</code>. The output shows, for example:
<pre>
Device Boot Start End Sectors Size Id Type
/dev/sda1 * 2048 206847 204800 100M 83 Linux
/dev/sda2 206848 41943039 41736192 19.9G 83 Linux
</pre>
* Press <code>w</code> to save the changes.

== Setting up the root pool ==

You can create your rootpool with the following command:

# zpool create -o ashift=12 \
-O acltype=posixacl -O canmount=off -O compression=lz4 \
-O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \
-O encryption=aes-256-gcm -O keylocation=prompt -O keyformat=passphrase \
-O mountpoint=/ -R /mnt \
rpool /dev/sda2

You will have to enter your passphrase at this point. Choose wisely, as your passphrase is most likely [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects the weakest link in this setup].

A few notes on the options supplied to zpool:

* <code>ashift=12</code> is recommended here because many drives today have 4KiB (or larger) physical sectors, even though they present 512B logical sectors

* <code>acltype=posixacl</code> enables POSIX ACLs globally

* <code>normalization=formD</code> eliminates some corner cases relating to UTF-8 filename normalization. It also enables <code>utf8only=on</code>, meaning that only files with valid UTF-8 filenames will be accepted.

* <code>xattr=sa</code> vastly improves the performance of extended attributes, but is Linux-only. If you care about using this pool on other OpenZFS implementation don't specify this option.

After completing this, confirm that the pool has been created:

# zpool status

Should return something like:
<pre>
pool: rpool
state: ONLINE
scan: none requested
config:

NAME STATE READ WRITE CKSUM
rpool ONLINE 0 0 0
sda2 ONLINE 0 0 0

errors: No known data errors
</pre>

=== Creating the required datasets ===

# zfs create -o mountpoint=none -o canmount=off rpool/ROOT
# zfs create -o mountpoint=legacy rpool/ROOT/alpine
# mount -t zfs rpool/ROOT/alpine /mnt/

=== Creating optional datasets (feel free to add your own) ===

# zfs create -o mountpoint=/home rpool/HOME
# zfs create -o mountpoint=/var/log rpool/LOG

== Creating the <code>/boot</code> filesystem ==

# mkfs.ext4 /dev/sda1

== Mounting the <code>/boot</code> filesystem ==

* Create the <code>/mnt/boot/</code> directory and mount the <code>/dev/sda1</code> partition in this directory:

# mkdir /mnt/boot/
# mount -t ext4 /dev/sda1 /mnt/boot/

== Installing Alpine Linux ==

Please follow [[Installing_Alpine_Linux_in_a_chroot|Installing Alpine Linux in a chroot]] to setup a base install of Alpine Linux.

After you've followed that guide, you still have to do some additional setup for ZFS:

* As of the time of writing this ZFS 0.8.x is only available in [[Edge]], so you'll have to enable it in <code>/etc/apk/repositories</code>. Check [https://pkgs.alpinelinux.org/packages?name=zfs pkgs.alpinelinux.org] to see the status of this.

* Install the ZoL and linux-vanilla package: <code>apk install linux-vanilla zfs</code>

* Enable ZFS' services:

# rc-update add zfs-import sysinit
# rc-update add zfs-mount sysinit

* Edit the <code>/etc/mkinitfs/mkinitfs.conf</code> file and append <code>zfs</code> module to the <code>features</code> parameter:

features="ata base ide scsi usb virtio ext4 lvm zfs"

Be mindful to also include other modules which may be required for your setup, such as the <code>nvme</code> module.

* Rebuild the initial RAM disk:

# mkinitfs $(ls /lib/modules/)

* Edit the <code>/etc/update-extlinux.conf</code> file, set the root ZFS dataset and append the following kernel options to the <code>default_kernel_opts</code> parameter:

root=rpool/ROOT/alpine
default_kernel_opts="... rootfstype=zfs"

* Update extlinux's config (if you're not using a different bootloader)

# update-extlinux
# exit

: Ignore the errors the <code>update-extlinux</code> utility displays.

* Write the MBR to the <code>/dev/sda</code> device:

# dd bs=440 count=1 conv=notrunc if=/mnt/usr/share/syslinux/mbr.bin of=/dev/sda

== Unmounting the filesystems ==

* Unmount <code>/mnt/boot/</code>:

# umount /mnt/boot/

* Unmount all zfs filesystems:

# zfs unmount -a

* Reboot the system:

# reboot

== Booting the system ==

Right now mkinitfs doesn't support ZFS asking for passwords during boot, so it'll throw you into a rescue shell for you to enter the password during boot. You have to do the following things after pressing enter:

# zfs load-key -a
# mount -t zfs rpool/ROOT/alpine /sysroot
# exit

And your system should continue booting! :)

= Troubleshooting =

== General Procedure ==

In case your system fails to boot, you can verify the settings and fix incorrect configurations:

* [[#Preparing_the_Installation_Environment|Preparing the Installation Environment]]

* Load the ZFS kernel module:

# modprobe zfs

* [[#Mounting_the_File_Systems|Mount the file systems]]

# zpool import -R /mnt rpool
# mount -t ext4 /dev/sda1 /mnt/boot

* Verify that you run the steps described in the [[#Installing_Alpine_Linux|Installing Alpine Linux]] section correctly. Update the configuration if necessary.

[[Category:Storage]]
[[Category:Security]]