Alpine Linux - User contributions [en]

LXC

2020-03-01T13:58:18Z

Llnu: /* Installation */

[https://linuxcontainers.org/ Linux Containers (LXC)] provides containers similar BSD Jails, Linux VServer and Solaris Zones. It gives the impression of virtualization, but shares the kernel and resources with the "host".

== Installation ==
Install the required packages:
{{Cmd|apk add lxc bridge lxcfs}}

If you want to create containers other than alpine you will need lxc-templates:

{{Cmd|apk add lxc-templates}}

== Upgrading from 2.x ==

Since Alpine 3.9 we ship LXC version 3.1.
LXC 3.x has major changes which will/can break your current setup.
LXC 3.x will NOT ship with legacy container templates. Check your current container configs to see if you have any includes pointing to files that don't exist (shipped by legacy templates).
For example if you use Alpine containers created with the alpine template you will need to install:

apk add lxc-templates-legacy-alpine

Also make sure you convert your LXC config files to the new 2.x format (this is now required).

lxc-update-config -c /var/lib/lxc/container-name/config

Make sure you have removed '''cgroup_enable''' from your cmdline as this will fail to mount cgroups and fail LXC service.

== Prepare network on host ==
Set up a [[bridge]] on the host. Example ''/etc/network/interfaces'':
<pre>
auto br0
iface br0 inet dhcp
bridge-ports eth0
</pre>

Create a network configuration template for the guests, ''/etc/lxc/default.conf'':
<pre>
lxc.net.0.type = veth
lxc.net.0.link = br0
lxc.net.0.flags = up
lxc.net.0.hwaddr = fe:xx:xx:xx:xx:xx
</pre>

== Grsecurity restrictions ==

'''NOTE''': since alpine 3.8 we no longer ship grsecurity and it should not be used in lxc setup.

Some restrictions will be applied when using a grsecurity kernel (Alpine Linux default kernel).
The most notable is the use of lxc-attach which will not be allowed because of GRKERNSEC_CHROOT_CAPS.
To solve this we will have to disable this grsec restriction by creating a sysctl profile for lxc.
Create the following file ''/etc/sysctl.d/10-lxc.conf'' and add:
<pre>
kernel.grsecurity.chroot_caps = 0
</pre>

There are a few other restrictions that can prevent proper container functionality.
When things do not work as expected always check the kernel log with dmesg to see if grsec prevented things from happening.

Other possible restrictions are:

<pre>
kernel.grsecurity.chroot_deny_chroot = 0
kernel.grsecurity.chroot_deny_mount = 0
kernel.grsecurity.chroot_deny_mknod = 0
kernel.grsecurity.chroot_deny_chmod = 0
</pre>

When you finished creating your new sysctl profile you can apply it by restarting sysctl service

<pre>
rc-service sysctl restart
</pre>

NOTE: Always consult the [https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options Grsecurity documentation] before applying these settings.

== Create a guest ==

=== Alpine Template ===

{{Cmd|lxc-create -n guest1 -f /etc/lxc/lxc.conf -t alpine}}

This will create a ''/var/lib/lxc/guest1'' directory with a ''config'' file and a ''rootfs'' directory.

Note that by default alpine template '''does not have networking service on''', you will need to add it using lxc-console

If running on x86_64 architecture, it is possible to create a 32bit guest:

{{Cmd|lxc-create -n guest1 -f /etc/lxc/lxc.conf -t alpine -- --arch x86}}

=== Debian template ===

In order to create a debian template container you will need to install some packages:

{{Cmd|apk add debootstrap rsync}}

Also you will need to turn off some grsecurity chroot options otherwise the debootstrap will fail:

{{Cmd|echo 0 > /proc/sys/kernel/grsecurity/chroot_caps
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chroot
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mount
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mknod
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chmod
}}

Please remember to turn them back on, or just simply reboot the system.

Now you can run:
{{Cmd|SUITE{{=}}wheezy lxc-create -n guest1 -f /etc/lxc/lxc.conf -t debian}}

=== Ubuntu template ===

In order to create an ubuntu template container you will need to turn off some grsecurity chroot options:

{{Cmd|echo 0 > /proc/sys/kernel/grsecurity/chroot_caps
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chroot
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mount
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_mknod
echo 0 > /proc/sys/kernel/grsecurity/chroot_deny_chmod
}}

Please remember to turn them back on, or just simply reboot the system.

Now you can run (replace %MIRROR% with the actual hostname, for example: http://us.archive.ubuntu.com/ubuntu/)

{{Cmd|lxc-create -n guest2 -f /etc/lxc/default.conf -t ubuntu -- -r xenial -a amd64 -u user --password secretpassword --mirror $MIRROR }}

{{Warning|Be sure to set systemd_container to yes in /etc/conf.d/lxc.CONTAINER. Otherwise most functionality will be broken}}

=== Unprivileged LXC images (Debian / Ubuntu / Centos etc..) ===

{{Cmd|apk add gnupg xz
lxc-create -n container-name -t download}}
& choose the Distribution | Release | Architecture.

To be able to login to a Debian container you currently need to:
{{Cmd|rm /lib/systemd/system/container-getty\@.service}}

You can also [http://without-systemd.org/wiki/index.php/How_to_remove_systemd_from_a_Debian_jessie/sid_installationers remove Systemd from the container].

== Starting/Stopping the guest ==
Create a symlink to the ''/etc/init.d/lxc'' script for your guest.
{{Cmd|ln -s lxc /etc/init.d/lxc.guest1}}

You can start your guest with:
{{Cmd|/etc/init.d/lxc.guest1 start}}

Stop it with:
{{Cmd|/etc/init.d/lxc.guest1 stop}}

Make it autostart on boot up with:
{{Cmd| rc-update add lxc.guest1}}

You can also add to the container config: <code>lxc.start.auto = 1</code>

& {{Cmd|rc-update add lxc}}

to autostart containers by the lxc service only.

== Connecting to the guest ==
By default sshd is not installed, so you will have to attach to the container or connect to the virtual console. This is done with:

=== Attach to container ===

{{Cmd|lxc-attach -n guest1}}

Just type exit to detach the container again (please do check the grsec notes above)

=== Connect to virtual console ===

{{Cmd|lxc-console -n guest1}}

To disconnect from it, press {{key|Ctrl}}+{{key|a}} {{key|q}}

== Deleting a guest ==
Make sure the guest is stopped and run:
{{Cmd|lxc-destroy -n guest1}}
This will erase everything, without asking any questions. It is equivalent to: {{Cmd|rm -r /var/lib/lxc/guest1}}

== Advanced ==

=== Creating a LXC container without modifying your network interfaces ===

The problem with bridging is that the interface you bridge gets replaced with your new bridge interface.
That is to say that say you have an interface eth0 that you want to bridge, your eth0 interface gets replaced with the br0 interface that you create. It also means that the interface you use needs to be placed into promiscuous mode to catch all the traffic that could de destined to the other side of the bridge, which again may not be what you want.

The solution is to create a dummy network interface, bridge that, and set up NAT so that traffic out of your bridge interface gets pushed through the interface of your choice.

So, first, lets create that dummy interface (thanks to ncopa for talking me out of macvlan and pointing out the dummy interface kernel module)

{{Cmd|modprobe dummy}}

This will create a dummy interface called dummy0 on your host. To create this interface on every boot, you may need to create a /etc/modprobe.d/dummy.conf with:
{{Cmd |# Load dummy.ko at boot
dummy }}

Now we will create a bridge called br0

{{Cmd |brctl addbr br0
brctl setfd br0 0 }}

and then make that dummy interface one end of the bridge

{{Cmd | brctl addif br0 dummy0 }}

Next, let's give that bridged interface a reason to exists

{{ Cmd | ifconfig br0 192.168.1.1 netmask 255.255.255.0 up}}

Create a file for your container, let's say /etc/lxc/bridgenat.conf, with the following settings.

<pre>
lxc.net.0.type = veth
lxc.net.0.flags = up
lxc.net.0.link = br0
lxc.net.0.name = eth1
lxc.net.0.ipv4.address = 192.168.1.2/24 192.168.1.255
lxc.net.0.ipv4.gateway = 192.168.1.1
lxc.net.0.veth.pair = veth-if-0
</pre>

and build your container with that file

{{ Cmd | lxc-create -n alpine -f /etc/lxc/bridgenat.conf -t alpine }}

You should now be able to ping your container from your hosts, and your host from your container.

Your container needs to know where to push traffic that isn't within it's subnet. To do so, we tell the container to route through the bridge interface br0
From inside the container run

{{ Cmd | route add default gw 192.168.1.1 }}

The next step is you push the traffic coming from your private subnet over br0 out through your internet facing interface, or any interface you chose

We are messing with your IP tables here, so make sure these settings don't conflict with anything you may have already set up, obviously.

Say eth0 was your internet facing network interface, and br0 is the name of the bridge you made earlier, we'd do this:

{{ Cmd | echo 1 > /proc/sys/net/ipv4/ip_forward
iptables --table nat --append POSTROUTING --out-interface eth0 -j MASQUERADE
iptables --append FORWARD --in-interface br0 -j ACCEPT
}}

Now you should be able to route through your bridge interface to the internet facing interface of your host from your container, just like at home!

You could also have a dhcp server running on your host, and set it up to give IP addresses from your private subnet to any container that requests it, and then have one template for multiple alpine LXC containers, perfect for alpine development :)

=== Using static IP ===

If you're using static IP, you need to configure this properly on guest's /etc/network/interfaces. To stay on the above example, modify ''/var/lib/lxc/guest1/rootfs/etc/network/interfaces''

from

#auto lo
iface lo inet loopback
auto eth0
iface eth0 inet '''dhcp'''

to

#auto lo
iface lo inet loopback
auto eth0
iface eth0 inet '''static'''
address <lxc-container-ip> # IP which the lxc container should use
gateway <gateway-ip> # IP of gateway to use, mostly same as on lxc-host
netmask <netmask>

=== mem and swap ===

{{Cmd|vim /boot/extlinux.conf}}

{{Cmd|
APPEND initrd{{=}}initramfs-3.10.13-1-grsec root{{=}}UUID{{=}}7cd8789f-5659-40f8-9548-ae8f89c918ab modules{{=}}sd-mod,usb-storage,ext4 quiet cgroup_enable{{=}}memory swapaccount{{=}}1
}}

=== checkconfig ===
{{Cmd|lxc-checkconfig}}

{{Cmd|
Kernel configuration not found at /proc/config.gz; searching...
Kernel configuration found at /boot/config-3.10.13-1-grsec
--- Namespaces ---
Namespaces: enabled
Utsname namespace: enabled
Ipc namespace: enabled
Pid namespace: enabled
User namespace: missing
Network namespace: enabled
Multiple /dev/pts instances: enabled

--- Control groups ---
Cgroup: enabled
Cgroup clone_children flag: enabled
Cgroup device: enabled
Cgroup sched: enabled
Cgroup cpu account: enabled
Cgroup memory controller: missing
Cgroup cpuset: enabled

--- Misc ---
Veth pair device: enabled
Macvlan: enabled
Vlan: enabled
File capabilities: enabled

Note : Before booting a new kernel, you can check its configuration
usage : CONFIG{{=}}/path/to/config /usr/bin/lxc-checkconfig

}}

=== VirtualBox ===

In order for network to work on containers you need to set "Promiscuous Mode" to "Allow All" in VirtualBox settings for the network adapter.

[[File:VirtualBoxNetworkAdapter.jpg]]

[[Category:Virtualization]]

=== postgreSQL ===

Inside the container run: {{Cmd|chmod go+w /dev/null}} to fix {{Cmd|rc-service postgresql start}}

=== openVPN ===

see [[Setting_up_a_OpenVPN_server#openVPN_and_LXC]]

== LXC 1.0 Additional information ==

Some info regarding new features in LXC 1.0

https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/

== See also ==
* [[Howto-lxc-simple]]

Setting up ZFS on LUKS

2019-08-23T20:56:08Z

Llnu: typo

= Introduction =

This documentation describes how to set up Alpine Linux using ZFS with a pool that is located in an encrypted partition. To encrypt the partition the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.

Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly.

We'll be using the syslinux bootloader and traditional BIOS booting.

== Requirements ==

* An already installed Alpine on a medium other than the one you'll boot from, see [[Installation|official installation guide.]]
{{Note|We can't use the live environment from the installation isos, because we'll install the ZFS kernel module and that isn't possible with a read-only /boot (as provided by the iso).}}

== 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.

= Setting up Alpine Linux Using ZFS on Top of a LUKS Partition =

To install Alpine Linux in a ZFS pool on top of a LUKS encrypted partition, you cannot use the [[Installation|official installation]] procedure. The installation requires several manual steps you must run in the Alpine Linux Live CD environment.

== Preparing the Installation Environment ==

Before you begin to install Alpine Linux on the medium you intend to boot from, prepare the installation you already have:

* Update the <code>apk</code> cache:

# apk update

* Install the following packages required to set up ZFS and LUKS:

# apk add haveged cryptsetup e2fsprogs syslinux zfs zfs-$(uname -r | rev | cut -d'-' -f1 | rev)
# modprobe zfs

* Optionally, start the <code>haveged</code> service for unpredictable random numbers used for encryption:

# rc-service haveged start

== 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 LUKS 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.

* Optionally, wipe the LUKS partition with random values:

# haveged -n 0 | dd of=/dev/sda2

{{Note|Depending on the size of the partition, this process can take several minutes to hours.}}

== Encrypting the ZFS Partition ==

* To encrypt the partition which will later contain the LVM PV:

# cryptsetup luksFormat /dev/sda2

:{{Note|Alpine Linux uses the <code>en-us</code> keyboard mapping when prompting for the password to encrypt the partition at boot time. If you changed the keyboard map in the temporary environment, the password you enter during encrypting the partition in this step, may not match the password you will enter during the system boots.}}
: If you prefer setting an individual hashing algorithm and hashing schema:
:* To run a benchmark:

# cryptsetup benchmark

:* To encrypt the partition using individual settings, enter, for example:

# cryptsetup -v -c serpent-xts-plain64 -s 512 --hash whirlpool --iter-time 5000 --use-random luksFormat /dev/sda2

== Creating the filesystems ==

* Open the LUKS partition:

# cryptsetup open --type luks /dev/sda2 crypt

=== Creating the ZFS pool ===

# zpool create -o ashift=12 -O normalization=formD -O atime=off -m none -R /mnt -O compression=lz4 tank /dev/mapper/crypt

Meaning of the <code>zpool create</code> options:

{| cellpadding="5" border="1" class="wikitable"
|-
! Option
! Meaning
|-
| zpool create
| Creating the zpool
|-
| -o ashift=12
| 4K blocks
|-
| -O normalization=formD
| Set the default Unicode (UTF-8) normalization to 'formD'
|-
| -O atime=off
| Disabling updates to file access time. This reduces writes to disk, but might cause issues with mailers, like <code>mutt</code>.
|-
| -m none
| No mountpoint, as we'll handle this later.
|-
| -R /mnt
| Set the altroot to <code>/mnt</code>. It's like a temporary mountpoint for the pool.
|-
| -O compression=lz4
| Use lz4 compression for the pool. Is generally recommended.
|-
| tank
| The pool name. <code>tank</code> will be used in throughout this guide.
|-
| /dev/mapper/crypt
| The path to the block device ZFS will use.
|}

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

# zpool status

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

NAME STATE READ WRITE CKSUM
tank ONLINE 0 0 0
crypt ONLINE 0 0 0

errors: No known data errors
</pre>

=== Creating the required datasets ===

# zfs create -o mountpoint=none -o canmount=off tank/ROOT
# zfs create -o mountpoint=/ tank/ROOT/alpine

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

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

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

# mkfs.ext4 /dev/sda1

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

* Create <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 ==

In this step you will install Alpine Linux in the <code>/mnt/</code> directory, which contains the mounted file system structure.

* Install Alpine Linux:

# setup-disk -m sys /mnt/

: The installer downloads the latest packages to install the base installation. Additionally, the installer automatically creates the entries for the mount points in the <code>fstab</code> file (but we'll have to edit it manually later), which are currently mounted in the <code>/mnt/</code> directory.

: {{Note|The automatic writing of the master boot record (MBR) fails in this step. You will write the MBR later manually to the disk.}}

* To enable the operating system to decrypt the LUKS partition at boot time, create the <code>/mnt/etc/crypttab</code> file. Enter the following line into the file to decrypt the <code>/dev/sda2</code> partition using the <code>luks</code> module and map it to the <code>lvmcrypt</code> name:

crypt /dev/sda2 none luks

* Delete the zfs entries in <code>/mnt/etc/fstab</code> as ZFS mounts them automagically, your fstab should look like this:

UUID=6b4f2c9c-0a0f-4a8c-a73b-d2b47920ad6f /boot ext4 rw,relatime,stripe=4,data=ordered 0 2

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

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

* Rebuild the initial RAM disk:

# mkinitfs -c /mnt/etc/mkinitfs/mkinitfs.conf -b /mnt/ $(ls /mnt/lib/modules/)

: The command uses the settings from the <code>mkinitfs.conf</code> file set in the <code>-c</code> parameter to generate the RAM disk. The command is executed in the <code>/mnt/</code> directory and the RAM disk is generated using the modules for the installed kernel. Without setting the kernel version using the <code>$(ls /mnt/lib/modules/</code>) option, <code>mkinitfs</code> tries to generate the RAM disk using the kernel version installed in the temporary environment, which can differ from the latest one installed by the <code>setup-disk</code> utility.

* Edit the <code>/mnt/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=tank/ROOT/alpine
default_kernel_opts="... cryptroot=/dev/sda2 cryptdm=crypt rootfstype=zfs"

: The <code>cryptroot</code> parameter sets the name of the device that contains the root file system. The <code>cryptdm</code> parameter sets the name of the mapping previously set in the <code>crypttab</code> file. The <code>rootfstype</code> option sets the root filesystem type to zfs.

* Because the <code>update-extlinux</code> utility operators only on the <code>/boot/</code> directory, temporarily change the root to the <code>/mnt/</code> directory and update the boot loader configuration:

# chroot /mnt/
# 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

* Export all zfs pools:

# zpool export -a

* Close the <code>lvmcrypt</code> device:

# cryptsetup luksClose crypt

* Reboot the system:

# reboot

= Troubleshooting =

== General Procedure ==

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

* [[#Preparing_the_Temporary_Installation_Environment|Prepare the temporary installation environment]]

* Load the ZFS kernel module:

# modprobe zfs

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

# zpool import -R /mnt tank
# 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.

* [[#Unmounting_the_Volumes_and_Partitions|Unmount the volumes and partitions]]

{{Todo|Multiple Disk ZFS on LUKS?}}

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

Setting up ZFS on LUKS

2019-08-23T20:55:24Z

Llnu: without exporting zfs pools i got an error message: "device-mapper: remove ioctl on crypt failed: Resource busy"

= Introduction =

This documentation describes how to set up Alpine Linux using ZFS with a pool that is located in an encrypted partition. To encrypt the partition the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.

Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly.

We'll be using the syslinux bootloader and traditional BIOS booting.

== Requirements ==

* An already installed Alpine on a medium other than the one you'll boot from, see [[Installation|official installation guide.]]
{{Note|We can't use the live environment from the installation isos, because we'll install the ZFS kernel module and that isn't possible with a read-only /boot (as provided by the iso).}}

== 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.

= Setting up Alpine Linux Using ZFS on Top of a LUKS Partition =

To install Alpine Linux in a ZFS pool on top of a LUKS encrypted partition, you cannot use the [[Installation|official installation]] procedure. The installation requires several manual steps you must run in the Alpine Linux Live CD environment.

== Preparing the Installation Environment ==

Before you begin to install Alpine Linux on the medium you intend to boot from, prepare the installation you already have:

* Update the <code>apk</code> cache:

# apk update

* Install the following packages required to set up ZFS and LUKS:

# apk add haveged cryptsetup e2fsprogs syslinux zfs zfs-$(uname -r | rev | cut -d'-' -f1 | rev)
# modprobe zfs

* Optionally, start the <code>haveged</code> service for unpredictable random numbers used for encryption:

# rc-service haveged start

== 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 LUKS 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.

* Optionally, wipe the LUKS partition with random values:

# haveged -n 0 | dd of=/dev/sda2

{{Note|Depending on the size of the partition, this process can take several minutes to hours.}}

== Encrypting the ZFS Partition ==

* To encrypt the partition which will later contain the LVM PV:

# cryptsetup luksFormat /dev/sda2

:{{Note|Alpine Linux uses the <code>en-us</code> keyboard mapping when prompting for the password to encrypt the partition at boot time. If you changed the keyboard map in the temporary environment, the password you enter during encrypting the partition in this step, may not match the password you will enter during the system boots.}}
: If you prefer setting an individual hashing algorithm and hashing schema:
:* To run a benchmark:

# cryptsetup benchmark

:* To encrypt the partition using individual settings, enter, for example:

# cryptsetup -v -c serpent-xts-plain64 -s 512 --hash whirlpool --iter-time 5000 --use-random luksFormat /dev/sda2

== Creating the filesystems ==

* Open the LUKS partition:

# cryptsetup open --type luks /dev/sda2 crypt

=== Creating the ZFS pool ===

# zpool create -o ashift=12 -O normalization=formD -O atime=off -m none -R /mnt -O compression=lz4 tank /dev/mapper/crypt

Meaning of the <code>zpool create</code> options:

{| cellpadding="5" border="1" class="wikitable"
|-
! Option
! Meaning
|-
| zpool create
| Creating the zpool
|-
| -o ashift=12
| 4K blocks
|-
| -O normalization=formD
| Set the default Unicode (UTF-8) normalization to 'formD'
|-
| -O atime=off
| Disabling updates to file access time. This reduces writes to disk, but might cause issues with mailers, like <code>mutt</code>.
|-
| -m none
| No mountpoint, as we'll handle this later.
|-
| -R /mnt
| Set the altroot to <code>/mnt</code>. It's like a temporary mountpoint for the pool.
|-
| -O compression=lz4
| Use lz4 compression for the pool. Is generally recommended.
|-
| tank
| The pool name. <code>tank</code> will be used in throughout this guide.
|-
| /dev/mapper/crypt
| The path to the block device ZFS will use.
|}

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

# zpool status

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

NAME STATE READ WRITE CKSUM
tank ONLINE 0 0 0
crypt ONLINE 0 0 0

errors: No known data errors
</pre>

=== Creating the required datasets ===

# zfs create -o mountpoint=none -o canmount=off tank/ROOT
# zfs create -o mountpoint=/ tank/ROOT/alpine

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

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

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

# mkfs.ext4 /dev/sda1

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

* Create <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 ==

In this step you will install Alpine Linux in the <code>/mnt/</code> directory, which contains the mounted file system structure.

* Install Alpine Linux:

# setup-disk -m sys /mnt/

: The installer downloads the latest packages to install the base installation. Additionally, the installer automatically creates the entries for the mount points in the <code>fstab</code> file (but we'll have to edit it manually later), which are currently mounted in the <code>/mnt/</code> directory.

: {{Note|The automatic writing of the master boot record (MBR) fails in this step. You will write the MBR later manually to the disk.}}

* To enable the operating system to decrypt the LUKS partition at boot time, create the <code>/mnt/etc/crypttab</code> file. Enter the following line into the file to decrypt the <code>/dev/sda2</code> partition using the <code>luks</code> module and map it to the <code>lvmcrypt</code> name:

crypt /dev/sda2 none luks

* Delete the zfs entries in <code>/mnt/etc/fstab</code> as ZFS mounts them automagically, your fstab should look like this:

UUID=6b4f2c9c-0a0f-4a8c-a73b-d2b47920ad6f /boot ext4 rw,relatime,stripe=4,data=ordered 0 2

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

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

* Rebuild the initial RAM disk:

# mkinitfs -c /mnt/etc/mkinitfs/mkinitfs.conf -b /mnt/ $(ls /mnt/lib/modules/)

: The command uses the settings from the <code>mkinitfs.conf</code> file set in the <code>-c</code> parameter to generate the RAM disk. The command is executed in the <code>/mnt/</code> directory and the RAM disk is generated using the modules for the installed kernel. Without setting the kernel version using the <code>$(ls /mnt/lib/modules/</code>) option, <code>mkinitfs</code> tries to generate the RAM disk using the kernel version installed in the temporary environment, which can differ from the latest one installed by the <code>setup-disk</code> utility.

* Edit the <code>/mnt/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=tank/ROOT/alpine
default_kernel_opts="... cryptroot=/dev/sda2 cryptdm=crypt rootfstype=zfs"

: The <code>cryptroot</code> parameter sets the name of the device that contains the root file system. The <code>cryptdm</code> parameter sets the name of the mapping previously set in the <code>crypttab</code> file. The <code>rootfstype</code> option sets the root filesystem type to zfs.

* Because the <code>update-extlinux</code> utility operators only on the <code>/boot/</code> directory, temporarily change the root to the <code>/mnt/</code> directory and update the boot loader configuration:

# chroot /mnt/
# 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

* Export all zfs pools

# zpool export -a

* Close the <code>lvmcrypt</code> device:

# cryptsetup luksClose crypt

* Reboot the system:

# reboot

= Troubleshooting =

== General Procedure ==

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

* [[#Preparing_the_Temporary_Installation_Environment|Prepare the temporary installation environment]]

* Load the ZFS kernel module:

# modprobe zfs

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

# zpool import -R /mnt tank
# 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.

* [[#Unmounting_the_Volumes_and_Partitions|Unmount the volumes and partitions]]

{{Todo|Multiple Disk ZFS on LUKS?}}

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