https://wiki.archlinux.org/api.php?action=feedcontributions&user=Zethex&feedformat=atomArchWiki - User contributions [en]2024-03-28T08:25:03ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Arch_boot_process&diff=584335Arch boot process2019-10-03T07:35:21Z<p>Zethex: /* Feature comparison */ As of grub-2.04, Zstd compression is supported, which has been in the Arch repos</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:About Arch]]<br />
[[ar:Arch boot process]]<br />
[[bs:Arch boot process]]<br />
[[cs:Arch boot process]]<br />
[[es:Arch boot process]]<br />
[[fr:Processus de boot]]<br />
[[it:Arch boot process]]<br />
[[ja:Arch ブートプロセス]]<br />
[[pt:Arch boot process]]<br />
[[ru:Arch boot process]]<br />
[[zh-hans:Arch boot process]]<br />
{{Related articles start}}<br />
{{Related|Master Boot Record}}<br />
{{Related|GUID Partition Table}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|mkinitcpio}}<br />
{{Related|init}}<br />
{{Related|systemd}}<br />
{{Related|fstab}}<br />
{{Related|Autostarting}}<br />
{{Related articles end}}<br />
<br />
In order to boot Arch Linux, a Linux-capable [[#Boot loader|boot loader]] must be set up. The boot loader is responsible for loading the kernel and [[initial ramdisk]] before initiating the boot process. The procedure is quite different for [[Wikipedia:BIOS|BIOS]] and [[UEFI]] systems, the detailed description is given on this or linked pages.<br />
<br />
== Firmware types ==<br />
<br />
=== BIOS ===<br />
<br />
A [[Wikipedia:BIOS|BIOS]] or Basic Input-Output System is the very first program (firmware) that is executed once the system is switched on. In most cases it is stored in a flash memory in the motherboard itself and independent of the system storage.<br />
<br />
=== UEFI ===<br />
<br />
[[Unified Extensible Firmware Interface]] has support for reading both the partition table as well as file systems. UEFI does not launch any [[Partitioning#Master Boot Record (bootstrap code)|boot code from the Master Boot Record (MBR)]] whether it exists or not, instead booting relies on boot entries in the [[Wikipedia:Non-volatile random-access memory|NVRAM]].<br />
<br />
The UEFI specification mandates support for the [[FAT|FAT12, FAT16, and FAT32]] file systems (see [https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf#G17.1019485 UEFI specification version 2.8, section 13.3.1.1]), but any conformant vendor can optionally add support for additional filesystems; for example, Apple [[Mac]]s support (and by default use) their own HFS+ filesystem drivers. UEFI implementations also support ISO-9660 for optical discs.<br />
<br />
UEFI launches EFI applications, e.g. [[#Boot loader|boot loaders]], boot managers, [[UEFI shell]], etc. These applications are usually stored as files in the [[EFI system partition]]. Each vendor can store its files in the EFI system partition under the {{ic|/EFI/''vendor_name''}} folder. The applications can be launched by adding a boot entry to the NVRAM or from the UEFI shell.<br />
<br />
The UEFI specification has support for legacy BIOS booting with its [[Wikipedia:Unified Extensible Firmware Interface#CSM booting|Compatibility Support Module (CSM)]]. If CSM is enabled in the UEFI, the UEFI will generate CSM boot entries for all drives. If a CSM boot entry is chosen to be booted from, the UEFI's CSM will attempt to boot from the drive's MBR bootstrap code.<br />
<br />
== System initialization ==<br />
<br />
=== Under BIOS ===<br />
<br />
# System switched on, the [[Wikipedia:Power-on self-test|power-on self-test (POST)]] is executed.<br />
# After POST, BIOS initializes the necessary system hardware for booting (disk, keyboard controllers etc.).<br />
# BIOS launches the first 440 bytes ([[Partitioning#Master Boot Record (bootstrap code)|the Master Boot Record bootstrap code area]]) of the first disk in the BIOS disk order.<br />
# The boot loader's first stage in the MBR boot code then launches its second stage code (if any) from either:<br />
#* next disk sectors after the MBR, i.e. the so called post-MBR gap (only on a MBR partition table).<br />
#* a partition's or a partitionless disk's [[Wikipedia:Volume boot record|volume boot record (VBR)]].<br />
#* the [[BIOS boot partition]] ([[GRUB]] on BIOS/GPT only).<br />
# The actual [[#Boot loader|boot loader]] is launched.<br />
# The boot loader then loads an operating system by either chain-loading or directly loading the operating system kernel.<br />
<br />
=== Under UEFI ===<br />
<br />
# System switched on, the [[Wikipedia:Power-on self-test|power-on self-test (POST)]] is executed.<br />
# UEFI initializes the hardware required for booting.<br />
# Firmware reads the boot entries in the NVRAM to determine which EFI application to launch and from where (e.g. from which disk and partition).<br />
#* A boot entry could simply be a disk. In this case the firmware looks for an [[EFI system partition]] on that disk and tries to find an EFI application in the fallback boot path {{ic|\EFI\BOOT\BOOTX64.EFI}} ({{ic|BOOTIA32.EFI}} on [[Unified Extensible Firmware Interface#UEFI firmware bitness|systems with a IA32 (32-bit) UEFI]]). This is how UEFI bootable removable media work.<br />
# Firmware launches the EFI application.<br />
#* This could be a [[#Boot loader|boot loader]] or the Arch [[kernel]] itself using [[EFISTUB]].<br />
#* It could be some other EFI application such as a UEFI shell or a [[#Boot loader|boot manager]] like [[systemd-boot]] or [[rEFInd]].<br />
<br />
If [[Secure Boot]] is enabled, the boot process will verify authenticity of the EFI binary by signature.<br />
<br />
{{Note|Some UEFI systems can only boot from the fallback boot path.}}<br />
<br />
=== Multibooting in UEFI ===<br />
<br />
Since each OS or vendor can maintain its own files within the [[EFI system partition]] without affecting the other, multi-booting using UEFI is just a matter of launching a different EFI application corresponding to the particular operating system's boot loader. This removes the need for relying on [[Wikipedia:Chain loading|chain loading]] mechanisms of one [[#Boot loader|boot loader]] to load another OS.<br />
<br />
See also [[Dual boot with Windows]].<br />
<br />
== Boot loader ==<br />
<br />
A boot loader is a piece of software started by the [[Wikipedia:BIOS|BIOS]] or [[UEFI]]. It is responsible for loading the kernel with the wanted [[kernel parameters]], and [[mkinitcpio|initial RAM disk]] based on configuration files. In the case of UEFI, the kernel itself can be directly launched by the UEFI using the EFI boot stub. A separate boot loader or boot manager can still be used for the purpose of editing kernel parameters before booting.<br />
<br />
{{Note|Loading [[Microcode]] updates requires adjustments in boot loader configuration. [https://www.archlinux.org/news/changes-to-intel-microcodeupdates/]}}<br />
<br />
=== Feature comparison ===<br />
<br />
{{Expansion|If {{ic|/boot}} is inside anything more complex than just a file system on a partition (e.g. LUKS, RAID, LVM), the boot loader needs drivers for those layers too.|Talk:EFI system partition#Preffered mount point for LVM users}}<br />
<br />
{{Note|<br />
* Boot loaders only need to support the file system on which kernel and initramfs reside (the file system on which {{ic|/boot}} is located).<br />
* As GPT is part of the UEFI specification, all UEFI boot loaders support GPT disks. GPT on BIOS systems is possible, using either "hybrid booting" with [https://www.rodsbooks.com/gdisk/hybrid.html Hybrid MBR], or the new [http://repo.or.cz/syslinux.git/blob/HEAD:/doc/gpt.txt GPT-only] protocol. This protocol may however cause issues with certain BIOS implementations; see [http://www.rodsbooks.com/gdisk/bios.html#bios rodsbooks] for details.<br />
* Encryption mentioned in file system support is [[wikipedia:Filesystem-level encryption|filesystem-level encryption]], it has no bearing on [[dm-crypt|block-level encryption]]. <br />
}}<br />
<br />
{| class="wikitable sortable"<br />
! rowspan="2"| Name<br />
! colspan="2"| Firmware<br />
! colspan="2"| [[Partition table]]<br />
! rowspan="2"| Multi-boot<br />
! colspan="5"| [[File systems]]<br />
! rowspan="2"| Notes<br />
|-<br />
! BIOS !! [[UEFI]]<br />
! [[MBR]] !! [[GPT]]<br />
! [[Btrfs]] !! [[ext4]] !! ReiserFS !! [[VFAT]] !! [[XFS]]<br />
|-<br />
! [[EFISTUB]]<br />
| {{-}} || {{Yes}}<br />
| {{Yes}} || {{Yes}}<br />
| {{-}}<br />
| {{-}} || {{-}} || {{-}} || {{Y|ESP only}} || {{-}}<br />
| Kernel turned into EFI executable to be loaded directly from [[UEFI]] firmware or another boot loader.<br />
|-<br />
! [[Clover]]<br />
| {{G|emulates UEFI}} || {{Yes}}<br />
| {{Yes}} || {{Yes}}<br />
| {{Yes}}<sup>1</sup><br />
| {{No}} || {{Y|without encryption}} || {{No}} || {{Yes}} || {{No}}<br />
| Fork of rEFIt modified to run [[wikipedia:Hackintosh|macOS on non-Apple hardware]].<br />
|-<br />
! [[GRUB]]<br />
| {{Yes}} || {{Yes}}<br />
| {{Yes}} || {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
| On BIOS/GPT configuration requires a [[BIOS boot partition]]. <br/>Supports RAID, LUKS1 and LVM (but not thin provisioned volumes).<br />
|-<br />
! [[rEFInd]]<br />
| {{No}} || {{Yes}}<br />
| {{Yes}} || {{Yes}}<br />
| {{Yes}}<sup>1</sup><br />
| {{Y|without: encryption, zstd compression}} || {{Y|without encryption}} || {{Y|without tail-packing feature}} || {{Yes}} || {{No}}<br />
| Supports auto-detecting kernels and parameters without explicit configuration.<br />
|-<br />
! [[Syslinux]]<br />
| {{Yes}} || {{Y|[[Syslinux#Limitations of UEFI Syslinux|Partial]]}}<br />
| {{Yes}} || {{Yes}}<br />
| {{Y|[[Syslinux#Chainloading|Partial]]}}<br />
| {{Y|without: multi-device volumes, compression, encryption}} || {{Y|without encryption}} || {{No}} || {{Yes}} || {{Y|MBR only; without sparse inodes}}<br />
| No support for certain [[file system]] features [https://wiki.syslinux.org/wiki/index.php?title=Filesystem] <br/>The boot loader can only access the file system it is installed to.[https://bugzilla.syslinux.org/show_bug.cgi?id=33]<br />
|-<br />
! [[systemd-boot]]<br />
| {{No}} || {{Yes}}<br />
| {{Y|[https://github.com/systemd/systemd/issues/1125 Manual install only]}} || {{Yes}}<br />
| {{Yes}}<sup>1</sup><br />
| {{No}} || {{No}} || {{No}} || {{Y|ESP only}} || {{No}}<br />
| Cannot launch binaries from partitions other than [[ESP]].<br />
|-<br />
! {{Grey|[[GRUB Legacy]]}}<br />
| {{Yes}} || {{No}}<br />
| {{Yes}} || {{No}}<br />
| {{Yes}}<br />
| {{No}} || {{No}} || {{Yes}} || {{Yes}} || {{Y|v4 only}}<br />
| [https://www.gnu.org/software/grub/grub-legacy.html Discontinued] in favor of [[GRUB]].<br />
|-<br />
! {{Grey|[[LILO]]}}<br />
| {{Yes}} || {{No}}<br />
| {{Yes}} || {{No}}<br />
| {{Yes}}<br />
| {{No}} || {{Y|without encryption}} || {{Yes}} || {{Yes}} || {{Yes|http://xfs.org/index.php/XFS_FAQ#Q:_Does_LILO_work_with_XFS.3F}}<br />
| [http://web.archive.org/web/20180323163248/http://lilo.alioth.debian.org/ Discontinued] due to limitations (e.g. with Btrfs, GPT, RAID).<br />
|}<br />
<br />
# A [https://www.rodsbooks.com/efi-bootloaders/principles.html boot manager]. It can only launch other EFI applications, for example, Linux kernel images built with {{ic|1=CONFIG_EFI_STUB=y}} and Windows {{ic|bootmgfw.efi}}.<br />
<br />
See also [[Wikipedia:Comparison of boot loaders]].<br />
<br />
== Kernel ==<br />
<br />
The [[kernel]] is the core of an operating system. It functions on a low level (''kernelspace'') interacting between the hardware of the machine and the programs which use the hardware to run. To make efficient use of the CPU, the kernel uses a scheduler to arbitrate which tasks take priority at any given moment, creating the illusion of many tasks being executed simultaneously.<br />
<br />
== initramfs ==<br />
<br />
After the [[#Boot loader|boot loader]] loads the [[kernel]] and possible initramfs files and executes the kernel, the kernel unpacks the initramfs (initial RAM filesystem) archives into the (then empty) rootfs (initial root filesystem, specifically a ramfs or tmpfs). The first extracted initramfs is the one embedded in the kernel binary during the kernel build, then possible external initramfs files are extracted. Thus files in the external initramfs overwrite files with the same name in the embedded initramfs. The kernel then executes {{ic|/init}} (in the rootfs) as the first process. The ''early userspace'' starts.<br />
<br />
Arch Linux uses an empty archive for the builtin initramfs (which is the default when building Linux). See [[mkinitcpio]] for more and Arch-specific info about the external initramfs.<br />
<br />
The purpose of the initramfs is to bootstrap the system to the point where it can access the root filesystem (see [[FHS]] for details). This means that any modules that are required for devices like IDE, SCSI, SATA, USB/FW (if booting from an external drive) must be loadable from the initramfs if not built into the kernel; once the proper modules are loaded (either explicitly via a program or script, or implicitly via [[udev]]), the boot process continues. For this reason, the initramfs only needs to contain the modules necessary to access the root filesystem; it does not need to contain every module one would ever want to use. The majority of modules will be loaded later on by udev, during the init process.<br />
<br />
== init process ==<br />
<br />
At the final stage of early userspace, the real root is mounted, and then replaces the initial root filesystem. {{ic|/sbin/init}} is executed, replacing the {{ic|/init}} process. Arch uses [[systemd]] as the default [[init]].<br />
<br />
== getty ==<br />
<br />
[[init]] calls [[getty]] once for each [[Wikipedia:Virtual console|virtual terminal]] (typically six of them), which initializes each tty and asks for a username and password. Once the username and password are provided, getty checks them against {{ic|/etc/passwd}} and {{ic|/etc/shadow}}, then calls [[#Login|login]]. Alternatively, getty may start a display manager if one is present on the system.<br />
<br />
== Display manager ==<br />
<br />
A [[display manager]] can be configured to replace the getty login prompt on a tty.<br />
<br />
In order to automatically initialize a display manager after booting, it is necessary to manually enable the service unit through [[systemd]]. For more information on enabling and starting service units, see [[systemd#Using units]]. <br />
<br />
== Login ==<br />
<br />
The ''login'' program begins a session for the user by setting environment variables and starting the user's shell, based on {{ic|/etc/passwd}}.<br />
<br />
The ''login'' program displays the contents of [[Wikipedia:motd (Unix)|/etc/motd]] (''m''essage ''o''f ''t''he ''d''ay) after a successful login, just before it executes the login shell. It is a good place to display your Terms of Service to remind users of your local policies or anything you wish to tell them.<br />
<br />
== Shell ==<br />
<br />
Once the user's [[shell]] is started, it will typically run a runtime configuration file, such as [[bashrc]], before presenting a prompt to the user. If the account is configured to [[Start X at login]], the runtime configuration file will call [[startx]] or [[xinit]].<br />
<br />
== GUI, xinit or wayland ==<br />
<br />
[[xinit]] runs the user's [[xinitrc]] runtime configuration file, which normally starts a [[window manager]]. When the user is finished and exits the window manager, ''xinit'', ''startx'', the shell, and login will terminate in that order, returning to [[#getty|getty]].<br />
<br />
== See also ==<br />
<br />
* [https://web.archive.org/web/20150430223035/http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ Early Userspace in Arch Linux]<br />
* [http://www.ibm.com/developerworks/linux/library/l-linuxboot/ Inside the Linux boot process]<br />
* [[Wikipedia:Linux startup process]]<br />
* [[Wikipedia:initrd]]<br />
* [http://www.cyberciti.biz/faq/grub-boot-into-single-user-mode/ Boot Linux Grub Into Single User Mode]<br />
* [https://neosmart.net/wiki/mbr-boot-process/ NeoSmart: The BIOS/MBR Boot Process]<br />
* [https://www.linux.com/learn/kernel-newbie-corner-initrd-and-initramfs-whats Kernel Newbie Corner: initrd and initramfs]<br />
* [http://www.rodsbooks.com/efi-bootloaders/ Rod Smith - Managing EFI Boot Loaders for Linux]</div>Zethexhttps://wiki.archlinux.org/index.php?title=Btrfs&diff=578951Btrfs2019-08-04T03:23:29Z<p>Zethex: /* Partitionless Btrfs disk */ Swap files are supported since kernel 5.0</p>
<hr />
<div>[[Category:File systems]]<br />
[[fr:Btrfs]]<br />
[[ja:Btrfs]]<br />
[[ru:Btrfs]]<br />
[[zh-hans:Btrfs]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|Snapper}}<br />
{{Related|dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap}}<br />
{{Related articles end}}<br />
<br />
From [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs Wiki]:<br />
<br />
:Btrfs is a modern copy on write (CoW) filesystem for Linux aimed at implementing advanced features while also focusing on fault tolerance, repair and easy administration. Jointly developed at multiple companies, Btrfs is licensed under the GPL and open for contribution from anyone.<br />
<br />
{{Warning| Btrfs has some features that are unstable. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/Status Status], [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_btrfs_stable.3F Is Btrfs stable?] and [https://btrfs.wiki.kernel.org/index.php/Getting_started Getting started] for more detailed information. See the [[#Known issues]] section.<br />
}}<br />
<br />
== Preparation ==<br />
<br />
For user space utilities [[install]] the {{Pkg|btrfs-progs}} package, which is not part of the {{grp|base}} group, and is required for basic operations.<br />
<br />
If you need to boot from a Btrfs file system (i.e., your kernel and initramfs reside on a Btrfs partition), check if your [[boot loader]] supports Btrfs.<br />
<br />
== File system creation ==<br />
<br />
The following shows how to create a new Btrfs [[file system]]. To convert an ext3/4 partition to Btrfs, see [[#Ext3/4 to Btrfs conversion]]. To use a partitionless setup, see [[#Partitionless Btrfs disk]].<br />
<br />
See {{man|8|mkfs.btrfs}} for more information.<br />
<br />
=== File system on a single device ===<br />
<br />
To create a Btrfs filesystem on partition {{ic|/dev/''partition''}}:<br />
<br />
# mkfs.btrfs -L ''mylabel'' /dev/''partition''<br />
<br />
The Btrfs default blocksize is 16KB. To use a larger blocksize for data/metadata, specify a value for the {{ic|nodesize}} via the {{ic|-n}} switch as shown in this example using 16KB blocks:<br />
<br />
# mkfs.btrfs -L ''mylabel'' -n 16k /dev/''partition''<br />
<br />
=== Multi-device file system ===<br />
<br />
{{Warning|The RAID 5 and RAID 6 modes of Btrfs are fatally flawed, and should not be used for "anything but testing with throw-away data." See [https://btrfs.wiki.kernel.org/index.php/RAID56 the Btrfs page on RAID5 and RAID6] for status updates.}}<br />
<br />
Multiple devices can be used to create a RAID. Supported RAID levels include RAID 0, RAID 1, RAID 10, RAID 5 and RAID 6. The RAID levels can be configured separately for data and metadata using the {{ic|-d}} and {{ic|-m}} options respectively. By default the data is striped ({{ic|raid0}}) and the metadata is mirrored ({{ic|raid1}}). See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Using Btrfs with Multiple Devices] for more information about how to create a Btrfs RAID volume.<br />
<br />
# mkfs.btrfs -d raid0 -m raid1 /dev/''part1'' /dev/''part2'' ...<br />
<br />
You can create a [[W:JBOD|JBOD configuration]], where disks are seen as one filesystem, but files are not duplicated, using {{ic|-d single -m raid1}}.<br />
<br />
You must include either the {{ic|udev}} hook or the {{ic|btrfs}} hook in {{ic|/etc/mkinitcpio.conf}} in order to use multiple Btrfs devices in a pool. See the [[Mkinitcpio#Common hooks]] article for more information.<br />
<br />
{{Note|<br />
* It is possible to add devices to a multiple-device filesystem later on. See the [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices Btrfs wiki article] for more information.<br />
* Devices can be of different sizes. However, if one drive in a RAID configuration is bigger than the others, this extra space will not be used. <br />
* Some [[boot loader]]s such as [[Syslinux]] do not support multi-device file systems.<br />
}}<br />
<br />
See [[#RAID]] for advice on maintenance specific to multi-device Btrfs file systems.<br />
<br />
== Configuring the file system ==<br />
<br />
=== Copy-on-Write (CoW) ===<br />
<br />
By default, Btrfs uses [[Wikipedia:copy-on-write|copy-on-write]] for all files all the time. See the [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Copy_on_Write_.28CoW.29 Btrfs Sysadmin Guide section] for implementation details, as well as advantages and disadvantages.<br />
<br />
==== Disabling CoW ====<br />
<br />
To disable copy-on-write for newly created files in a mounted subvolume, use the {{ic|nodatacow}} mount option. This will only affect newly created files. Copy-on-write will still happen for existing files. The {{ic|nodatacow}} option also disables compression. See {{man|5|btrfs}} for details.<br />
<br />
{{Note|From {{man|5|btrfs|MOUNT OPTIONS}}: "within a single file system, it is not possible to mount some subvolumes with {{ic|nodatacow}} and others with {{ic|datacow}}. The mount option of the first mounted subvolume applies to any other subvolumes."}}<br />
<br />
To disable copy-on-write for single files/directories do:<br />
<br />
$ chattr +C ''/dir/file''<br />
<br />
This will disable copy-on-write for those operation in which there is only one reference to the file. If there is more than one reference (e.g. through {{ic|1=cp --reflink=always}} or because of a filesystem snapshot), copy-on-write still occurs.<br />
<br />
{{Note|From chattr man page: "For btrfs, the 'C' flag should be set on new or empty files. If it is set on a file which already has data blocks, it is undefined when the blocks assigned to the file will be fully stable. If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute."}}<br />
<br />
{{Tip|In accordance with the note above, you can use the following trick to disable copy-on-write on existing files in a directory:<br />
$ mv ''/path/to/dir'' ''/path/to/dir''_old<br />
$ mkdir ''/path/to/dir''<br />
$ chattr +C ''/path/to/dir''<br />
$ cp -a ''/path/to/dir''_old/* ''/path/to/dir''<br />
$ rm -rf ''/path/to/dir''_old<br />
Make sure that the data are not used during this process. Also note that {{ic|mv}} or {{ic|cp --reflink}} as described below will not work.<br />
}}<br />
<br />
==== Creating lightweight copies ====<br />
<br />
By default, when copying files on a Btrfs filesystem with {{ic|cp}}, actual copies are created. To create a lightweight copy referencing to the original data, use the ''reflink'' option:<br />
<br />
$ cp --reflink ''source'' ''dest'' <br />
<br />
See the man page on {{man|1|cp}} for more details on the {{ic|--reflink}} flag.<br />
<br />
=== Compression ===<br />
<br />
Btrfs supports transparent compression, meaning every file on the partition is automatically compressed. This not only reduces the size of files, but can also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improve performance], in some specific use cases (e.g. single thread with heavy file I/O), while obviously harming performance in other cases (e.g. multithreaded and/or cpu intensive tasks with large file I/O). Better performance is generally achieved with the fastest compress algorithms, ''zstd'' and ''lzo'', and some [https://www.phoronix.com/scan.php?page=article&item=btrfs-zstd-compress benchmarks] provide detailed comparisons.<br />
<br />
Compression is enabled using the {{ic|compress}} mount option, which can be set to {{ic|zlib}}, {{ic|lzo}}, {{ic|zstd}}, or {{ic|no}} (for no compression). Only files created or modified after the mount option is added will be compressed.<br />
<br />
To apply compression to existing files, use the {{ic|btrfs filesystem defragment -c''alg''}} command, where {{ic|''alg''}} is either {{ic|zlib}}, {{ic|lzo}} or {{ic|zstd}}. For example, in order to re-compress the whole file system with {{pkg|zstd}}, run the following command:<br />
<br />
# btrfs filesystem defragment -r -v -czstd /<br />
<br />
To enable compression when installing Arch to an empty Btrfs partition, use the {{ic|compress}} option when [[mounting]] the file system: {{ic|1=mount -o compress=zstd /dev/sd''xY'' /mnt/}}. During configuration, add {{ic|1=compress=zstd}} to the mount options of the root file system in [[fstab]].<br />
<br />
{{Tip|Compression can also be enabled per-file without using the {{ic|compress}} mount option; to do so apply {{ic|chattr +c}} to the file. When applied to directories, it will cause new files to be automatically compressed as they come.}}<br />
<br />
{{Warning|<br />
* Systems using older kernels or {{pkg|btrfs-progs}} without {{ic|zstd}} support may be unable to read or repair your filesystem if you use this option.<br />
* Stable [[GRUB]] and [[rEFInd]] currently lack support for ''zstd'', either switch to {{AUR|grub-git}}, use a separate boot partition without ''zstd'' or reset compression of boot files to something supported using for example the command: {{bc|$ btrfs filesystem defragment -v -clzo /boot/*}}}}<br />
<br />
=== Subvolumes ===<br />
<br />
"A btrfs subvolume is not a block device (and cannot be treated as one) instead, a btrfs subvolume can be thought of as a POSIX file namespace. This namespace can be accessed via the top-level subvolume of the filesystem, or it can be mounted in its own right." [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes]<br />
<br />
Each Btrfs file system has a top-level subvolume with ID 5. It can be mounted as {{ic|/}} (by default), or another subvolume can be [[#Mounting subvolumes|mounted]] instead. Subvolumes can be moved around in the filesystem and are rather identified by their id than their path.<br />
<br />
See the following links for more details:<br />
* [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Subvolumes Btrfs Wiki SysadminGuide#Subvolumes]<br />
* [https://btrfs.wiki.kernel.org/index.php/Getting_started#Basic_Filesystem_Commands Btrfs Wiki Getting started#Basic Filesystem Commands]<br />
* [https://btrfs.wiki.kernel.org/index.php/Trees Btrfs Wiki Trees] <br />
<br />
==== Creating a subvolume ====<br />
<br />
To create a subvolume:<br />
<br />
# btrfs subvolume create ''/path/to/subvolume''<br />
<br />
==== Listing subvolumes ====<br />
<br />
To see a list of current subvolumes under {{ic|''path''}}:<br />
<br />
# btrfs subvolume list -p ''path''<br />
<br />
==== Deleting a subvolume ====<br />
<br />
To delete a subvolume:<br />
<br />
# btrfs subvolume delete ''/path/to/subvolume''<br />
<br />
Attempting to remove the directory {{ic|''/path/to/subvolume''}} without using the above command will not delete the subvolume.<br />
<br />
==== Mounting subvolumes ====<br />
<br />
Subvolumes can be mounted like file system partitions using the {{ic|1=subvol=''/path/to/subvolume''}} or {{ic|1=subvolid=''objectid''}} mount flags. For example, you could have a subvolume named {{ic|subvol_root}} and mount it as {{ic|/}}. One can mimic traditional file system partitions by creating various subvolumes under the top level of the file system and then mounting them at the appropriate mount points. Thus one can easily restore a file system (or part of it) to a previous state using [[#Snapshots]].<br />
<br />
{{Tip|1= Changing subvolume layouts is made simpler by not using the toplevel subvolume (ID=5) as {{ic|/}} (which is done by default). Instead, consider creating a subvolume to house your actual data and mounting it as {{ic|/}}.}}<br />
<br />
{{Note|From {{man|5|btrfs|MOUNT OPTIONS}}: "Most mount options apply to the '''whole filesystem''', and only the options for the first subvolume to be mounted will take effect. This is due to lack of implementation and may change in the future.". See the [https://btrfs.wiki.kernel.org/index.php/FAQ#Can_I_mount_subvolumes_with_different_mount_options.3F Btrfs Wiki FAQ] for which mount options can be used per subvolume.}}<br />
<br />
See [[Snapper#Suggested filesystem layout]], [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Managing_Snapshots Btrfs SysadminGuide#Managing Snapshots], and [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs SysadminGuide#Layout] for example file system layouts using subvolumes.<br />
<br />
See {{man|5|btrfs}} for a full list of btrfs-specific mount options.<br />
<br />
==== Changing the default sub-volume ====<br />
<br />
The default sub-volume is mounted if no {{ic|1=subvol=}} mount option is provided. To change the default subvolume, do:<br />
<br />
# btrfs subvolume set-default ''subvolume-id'' /<br />
<br />
where ''subvolume-id'' can be found by [[#Listing subvolumes|listing]].<br />
<br />
{{Note|1=After changing the default subvolume on a system with [[GRUB]], you should run {{ic|grub-install}} again to notify the bootloader of the changes. See [https://bbs.archlinux.org/viewtopic.php?pid=1615373 this forum thread].}}<br />
<br />
Changing the default subvolume with {{ic|btrfs subvolume set-default}} will make the top level of the filesystem inaccessible, except by use of the {{ic|<nowiki>subvol=/</nowiki>}} or {{ic|<nowiki>subvolid=5</nowiki>}} mount options [https://btrfs.wiki.kernel.org/index.php/SysadminGuide].<br />
<br />
=== Quota ===<br />
<br />
{{warning|Qgroup is not stable yet and combining quota with (too many) snapshots of subvolumes can cause performance problems, for example when deleting snapshots. Plus there are several more [https://btrfs.wiki.kernel.org/index.php/Quota_support#Known_issues known issues].}}<br />
<br />
Quota support in Btrfs is implemented at a subvolume level by the use of quota groups or qgroup: Each subvolume is assigned a quota groups in the form of ''0/<subvolume id>'' by default. However it is possible to create a quota group using any number if desired.<br />
<br />
To use qgroups you need to enable quota first using<br />
<br />
# btrfs quota enable <path><br />
<br />
From this point onwards newly created subvolumes will be controlled by those groups.<br />
In order to retrospectively enable them for already existing subvolumes, enable quota normally, then create a qgroup (quota group) for each of those subvolume using their ''<subvolume id>'' and rescan them:<br />
<br />
# btrfs subvolume list <path> | cut -d' ' -f2 | xargs -I{} -n1 btrfs qgroup create 0/{} <path><br />
# btrfs quota rescan <path><br />
<br />
Quota groups in Btrfs form a tree hierarchy, whereby qgroups are attached to subvolumes. The size limits are set per qgroup and apply when any limit is reached in tree that contains a given subvolume.<br />
<br />
Limits on quota groups can be applied either to the total data usage, un-shared data usage, compressed data usage or both. File copy and file deletion may both affect limits since the unshared limit of another qgroup can change if the original volume's files are deleted and only one copy is remaining. For example a fresh snapshot shares almost all the blocks with the original subvolume, new writes to either subvolume will raise towards the exclusive limit, deletions of common data in one volume raises towards the exclusive limit in the other one.<br />
<br />
To apply a limit to a qgroup, use the command {{ic|btrfs qgroup limit}}. Depending on your usage either use a total limit, unshared limit ({{ic|-e}}) or compressed limit ({{ic|-c}}).<br />
To show usage and limits for a given path within a filesystem use<br />
<br />
# btrfs qgroup show -reF <path><br />
<br />
=== Commit Interval ===<br />
<br />
The resolution at which data are written to the filesystem is dictated by Btrfs itself and by system-wide settings. Btrfs defaults to a 30 seconds checkpoint interval in which new data are committed to the filesystem. This can be changed by appending the {{ic|commit}} mount option in {{ic|/etc/fstab}} for the btrfs partition.<br />
<br />
LABEL=arch64 / btrfs defaults,noatime,compress=lzo,commit=120 0 0<br />
<br />
System-wide settings also affect commit intervals. They include the files under {{ic|/proc/sys/vm/*}} and are out-of-scope of this wiki article. The kernel documentation for them resides in {{ic|Documentation/sysctl/vm.txt}}.<br />
<br />
=== SSD TRIM ===<br />
A Btrfs filesystem is able to free unused blocks from an SSD drive supporting the TRIM command.<br />
<br />
More information about enabling and using TRIM can be found in [[Solid State Drives#TRIM]].<br />
<br />
== Usage ==<br />
<br />
=== Swap file ===<br />
<br />
[[Swap file]]s in Btrfs are supported since Linux kernel 5.0.[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ed46ff3d423780fa5173b38a844bf0fdb210a2a7]. The proper way to initialize a swapfile is described in [[Swap file#Swap file creation]].<br />
<br />
{{Note|For kernels version 5.0+, Btfrs has native swap file support with some limitations:<br />
* The swap file cannot be on a snapshotted subvolume. The proper procedure is to create a new subvolume to place the swap file in.<br />
* It does not support swap files on file systems that span multiple devices. See [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F Btrfs wiki: Does btrfs support swap files?] and [https://bbs.archlinux.org/viewtopic.php?pid&#61;1849371#p1849371 Arch forums discussion].<br />
* Hibernation onto a swapfile is currently not supported by {{pkg|systemd}} [https://github.com/systemd/systemd/issues/11939].<br />
}}<br />
<br />
{{Warning|Linux kernels before version 5.0, including {{pkg|linux-lts}}, do not support swap files. Using a swap file with Btrfs and a kernel prior to 5.0 can lead to file system corruption.}}<br />
<br />
=== Displaying used/free space ===<br />
<br />
General linux userspace tools such as {{ic|df}} will inaccurately report free space on a Btrfs partition. It is recommended to use {{ic|btrfs filesystem usage}} to query Btrfs partitions. For example:<br />
<br />
# btrfs filesystem usage /<br />
<br />
{{Note|1=The {{ic|btrfs filesystem usage}} command does not currently work correctly with {{ic|RAID5/RAID6}} RAID levels.}}<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/FAQ#How_much_free_space_do_I_have.3F] for more information.<br />
<br />
=== Defragmentation ===<br />
<br />
Btrfs supports online defragmentation through the mount option {{ic|autodefrag}}, see {{man|5|btrfs|MOUNT OPTIONS}}. To manually defragment your root, use:<br />
<br />
# btrfs filesystem defragment -r /<br />
<br />
Using the above command without the {{ic|-r}} switch will result in only the metadata held by the subvolume containing the directory being defragmented. This allows for single file defragmentation by simply specifying the path.<br />
<br />
Defragmenting a file which has a COW copy (either a snapshot copy or one made with {{ic|cp --reflink}} or bcp) plus using the {{ic|-c}} switch with a compression algorithm may result in two unrelated files effectively increasing the disk usage.<br />
<br />
=== RAID ===<br />
<br />
Btrfs offers native "RAID" for [[#Multi-device file system]]s. Notable features which set btrfs RAID apart from [[mdadm]] are self-healing redundant arrays and online balancing. See [https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices the Btrfs wiki page] for more information. The Btrfs sysadmin page also [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#RAID_and_data_replication has a section] with some more technical background.<br />
<br />
{{Warning| Parity RAID (RAID 5/6) code has multiple serious data-loss bugs in it. See the Btrfs Wiki's [https://btrfs.wiki.kernel.org/index.php/RAID56 RAID5/6 page] and a bug report on [https://www.mail-archive.com/linux-btrfs@vger.kernel.org/msg55161.html linux-btrfs mailing list] for more detailed information.}}<br />
<br />
=== Scrub ===<br />
<br />
The [https://btrfs.wiki.kernel.org/index.php/Glossary Btrfs Wiki Glossary] says that Btrfs scrub is "[a]n online filesystem checking tool. Reads all the data and metadata on the filesystem, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data."<br />
<br />
{{Warning|A running scrub process will prevent the system from suspending, see [http://comments.gmane.org/gmane.comp.file-systems.btrfs/33106 this thread] for details.}}<br />
<br />
===== Start manually =====<br />
<br />
To start a (background) scrub on the filesystem which contains {{ic|/}}:<br />
<br />
# btrfs scrub start /<br />
<br />
To check the status of a running scrub:<br />
<br />
# btrfs scrub status /<br />
<br />
===== Start with a service or timer =====<br />
<br />
The {{Pkg|btrfs-progs}} package brings the {{ic|btrfs-scrub@.timer}} unit for monthly scrubbing the specified mountpoint. [[Enable]] the timer with an escaped path, e.g. {{ic|btrfs-scrub@-.timer}} for {{ic|/}} and {{ic|btrfs-scrub@home.timer}} for {{ic|/home}}. You can use {{ic|systemd-escape -p ''/path/to/mountpoint''}} to escape the path, see {{man|1|systemd-escape}} for details.<br />
<br />
You can also run the scrub by [[starting]] {{ic|btrfs-scrub@.service}} (with the same encoded path). The advantage of this over {{ic|# btrfs scrub}} is that the results of the scrub will be logged in the [[systemd journal]].<br />
<br />
=== Balance ===<br />
<br />
"A balance passes all data in the filesystem through the allocator again. It is primarily intended to rebalance the data in the filesystem across the devices when a device is added or removed. A balance will regenerate missing copies for the redundant RAID levels, if a device has failed." [https://btrfs.wiki.kernel.org/index.php/Glossary] See [https://btrfs.wiki.kernel.org/index.php/FAQ#What_does_.22balance.22_do.3F Upstream FAQ page].<br />
<br />
On a single-device filesystem a balance may be also useful for (temporarily) reducing the amount of allocated but unused (meta)data chunks. Sometimes this is needed for fixing [https://btrfs.wiki.kernel.org/index.php/FAQ#Help.21_Btrfs_claims_I.27m_out_of_space.2C_but_it_looks_like_I_should_have_lots_left.21 "filesystem full" issues].<br />
<br />
# btrfs balance start /<br />
# btrfs balance status /<br />
<br />
=== Snapshots ===<br />
<br />
"A snapshot is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities." See [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Snapshots Btrfs Wiki SysadminGuide#Snapshots] for details.<br />
<br />
To create a snapshot:<br />
<br />
# btrfs subvolume snapshot ''source'' [''dest''/]''name''<br />
<br />
To create a readonly snapshot add the {{ic|-r}} flag. To create writable version of a readonly snapshot, simply create a snapshot of it.<br />
<br />
{{Note|Snapshots are not recursive. Every nested subvolume will be an empty directory inside the snapshot.}}<br />
<br />
=== Send/receive ===<br />
<br />
A subvolume can be sent to stdout or a file using the {{ic|send}} command. This is usually most useful when piped to a Btrfs {{ic|receive}} command. For example, to send a snapshot named {{ic|/root_backup}} (perhaps of a snapshot you made of {{ic|/}} earlier) to {{ic|/backup}} you would do the following:<br />
<br />
# btrfs send /root_backup | btrfs receive /backup<br />
<br />
The snapshot that is sent ''must'' be readonly. The above command is useful for copying a subvolume to an external device (e.g. a USB disk mounted at {{ic|/backup}} above).<br />
<br />
You can also send only the difference between two snapshots. For example, if you have already sent a copy of {{ic|root_backup}} above and have made a new readonly snapshot on your system named {{ic|root_backup_new}}, then to send only the incremental difference to {{ic|/backup}} do:<br />
<br />
# btrfs send -p /root_backup /root_backup_new | btrfs receive /backup<br />
<br />
Now a new subvolume named {{ic|root_backup_new}} will be present in {{ic|/backup}}.<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Incremental_Backup Btrfs Wiki's Incremental Backup page] on how to use this for incremental backups and for tools that automate the process.<br />
<br />
=== Deduplication ===<br />
<br />
Using copy-on-write, Btrfs is able to copy files or whole subvolumes without actually copying the data. However whenever a file is altered a new ''proper'' copy is created. Deduplication takes this a step further, by actively identifying blocks of data which share common sequences and combining them into an extent with the same copy-on-write semantics.<br />
<br />
Tools dedicated to deduplicate a Btrfs formatted partition include {{aur|duperemove}}, {{aur|bedup}} and ''btrfs-dedup''. One may also want to merely deduplicate data on a file based level instead using e.g. {{pkg|rmlint}} or {{aur|jdupes}}. For an overview of available features of those programs and additional information have a look at the [https://btrfs.wiki.kernel.org/index.php/Deduplication#Batch upstream Wiki entry].<br />
<br />
Furthermore Btrfs developers are working on inband (also known as synchronous or inline) deduplication, meaning deduplication done when writing new data to the filesystem. Currently it is still an experiment which is developed out-of-tree. Users willing to test the new feature should read the [https://btrfs.wiki.kernel.org/index.php/User_notes_on_dedupe appropriate kernel wiki page].<br />
<br />
== Known issues ==<br />
<br />
A few limitations should be known before trying.<br />
<br />
=== Encryption ===<br />
<br />
Btrfs has no built-in encryption support, but this [https://lwn.net/Articles/700487/ may] come in the future. Users can encrypt the partition before running {{ic|mkfs.btrfs}}. See [[dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap]]. <br />
<br />
Existing Btrfs file systems can use something like [[EncFS]] or [[TrueCrypt]], though perhaps without some of Btrfs' features.<br />
<br />
=== TLP ===<br />
<br />
Using TLP requires special precautions in order to avoid filesystem corruption. Refer to the [[TLP#Btrfs|according TLP section]] for more information.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Partitionless Btrfs disk ===<br />
<br />
{{Warning|Most users do not want this type of setup and instead should install Btrfs on a regular partition. Furthermore, GRUB strongly discourages installation to a partitionless disk. Consider using {{ic|--alloc-start}} for mkfs.btrfs to give larger space to GRUB. }}<br />
<br />
Btrfs can occupy an entire data storage device, replacing the [[MBR]] or [[GPT]] partitioning schemes, using [[#Subvolumes|subvolumes]] to simulate partitions. However, using a partitionless setup is not required to simply [[#File system creation|create a Btrfs filesystem]] on an existing [[partition]] that was created using another method. There are some limitations to partitionless single disk setups:<br />
<br />
* Cannot use different [[file systems]] for different [[fstab|mount points]].<br />
* If using a Linux kernel version before 5.0, you cannot use [[Swap|swap area]] as Btrfs did not support [[Swap#Swap_file|swap files]] pre-5.0 and there is no place to create [[Swap#Swap_partition|swap partition]]. This also limits the use of hibernation/resume, which needs a swap area to store the hibernation image. This includes the current LTS version of Linux which is on 4.xx.<br />
* Cannot use [[UEFI]] to boot.<br />
<br />
To overwrite the existing partition table with Btrfs, run the following command:<br />
<br />
# mkfs.btrfs /dev/sd''X''<br />
<br />
For example, use {{ic|/dev/sda}} rather than {{ic|/dev/sda1}}. The latter would format an existing partition instead of replacing the entire partitioning scheme. Because the root partition is Btrfs, make sure {{ic|btrfs}} is compiled into the kernel, or put {{ic|btrfs}} into [[mkinitcpio.conf#MODULES]] and activate.<br />
<br />
Install the [[boot loader]] like you would for a data storage device with a [[Master Boot Record]]. See [[Syslinux#Manual install]] or [[GRUB/Tips and tricks#Install to partition or partitionless disk]]. If your kernel does not boot due to {{ic|Failed to mount /sysroot.}}, please add {{ic|1=GRUB_PRELOAD_MODULES="btrfs"}} in {{ic|/etc/default/grub}} and generate the grub configuration ([[GRUB#Generate the main configuration file]]).<br />
<br />
=== Ext3/4 to Btrfs conversion ===<br />
<br />
{{Warning|There are many reports on the btrfs mailing list about incomplete/corrupt/broken conversions. Make sure you have ''working'' backups of any data you cannot afford to lose. See [https://btrfs.wiki.kernel.org/index.php/Conversion_from_Ext3 Conversion from Ext3] on the btrfs wiki for more information.}}<br />
<br />
Boot from an install CD, then convert by doing:<br />
<br />
# btrfs-convert /dev/''partition''<br />
<br />
Mount the partion and test the conversion by checking the files. Be sure to change the {{ic|/etc/fstab}} to reflect the change ('''type''' to {{ic|btrfs}} and '''fs_passno''' [the last field] to {{ic|0}} as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. {{ic|chroot}} into the system and rebuild the GRUB menu list (see [[Install from existing Linux]] and [[GRUB]] articles). If converting a root filesystem, while still chrooted run {{ic|mkinitcpio -p linux}} to regenerate the initramfs or the system will not successfully boot. If you get stuck in grub with 'unknown filesystem' try reinstalling grub with {{ic|grub-install /dev/''partition''}} and regenerate the config as well {{ic|grub-mkconfig -o /boot/grub/grub.cfg}}.<br />
<br />
After confirming that there are no problems, complete the conversion by deleting the backup {{ic|ext2_saved}} sub-volume. Note that you cannot revert back to ext3/4 without it.<br />
<br />
# btrfs subvolume delete /ext2_saved<br />
<br />
Finally [[#Balance|balance]] the file system to reclaim the space.<br />
<br />
Remember that some applications which were installed prior have to be adapted to Btrfs. Notably [[TLP#Btrfs]] needs special care to avoid filesystem corruption but other applications may profit from certain features as well.<br />
<br />
=== Checksum hardware acceleration ===<br />
<br />
To verify if Btrfs checksum is hardware accelerated:<br />
{{hc|<nowiki>$ dmesg | grep crc32c</nowiki>|<nowiki>Btrfs loaded, crc32c=crc32c-intel</nowiki>}}<br />
<br />
If you see {{ic|<nowiki>crc32c=crc32c-generic</nowiki>}}, it is probably because your root partition is Btrfs, and you will have to compile {{ic|crc32c-intel}} into the kernel to make it work. Putting {{ic|crc32c-intel}} into [[mkinitcpio.conf]] does ''not'' work.<br />
<br />
=== Corruption recovery ===<br />
<br />
''btrfs-check'' cannot be used on a mounted file system. To be able to use ''btrfs-check'' without booting from a live USB, add it to the initial ramdisk:<br />
<br />
{{hc|/etc/mkinitcpio.conf|output=<br />
BINARIES=("/usr/bin/btrfs")<br />
}}<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
Then if there is a problem booting, the utility is available for repair.<br />
<br />
{{Note|If the fsck process has to invalidate the space cache (and/or other caches?) then it is normal for a subsequent boot to hang up for a while (it may give console messages about btrfs-transaction being hung). The system should recover from this after a while.}}<br />
<br />
See the [https://btrfs.wiki.kernel.org/index.php/Btrfsck Btrfs Wiki page] for more information.<br />
<br />
=== Booting into snapshots ===<br />
<br />
In order to boot into a snapshot you must specify the subvolume via a [[Kernel parameters#Configuration|kernel parameter]] using {{ic|1=rootflags=subvol=''/path/to/subvolume''}} and alter your {{ic|/etc/fstab}} to point to the same subvolume using {{ic|1=subvol=}}. Alternatively the subvolume can be specified with its id - retrievable with e.g. {{ic|btrfs subvolume list ''/root/path''}} - and {{ic|1=rootflags=subvolid=''objectid''}} as kernel parameter respectively {{ic|1=subvolid=''objectid''}} as mount option in {{ic|/etc/fstab}}.<br />
<br />
If using GRUB you can automatically populate your boot menu with btrfs snapshots when regenerating the configuration file with the help of {{Pkg|grub-btrfs}} or {{AUR|grub-btrfs-git}}.<br />
<br />
=== Use Btrfs subvolumes with systemd-nspawn ===<br />
<br />
See the [[Systemd-nspawn#Use Btrfs subvolume as container root]] and [[Systemd-nspawn#Use temporary Btrfs snapshot of container]] articles.<br />
<br />
== Troubleshooting ==<br />
<br />
See the [https://btrfs.wiki.kernel.org/index.php/Problem_FAQ Btrfs Problem FAQ] for general troubleshooting.<br />
<br />
=== GRUB ===<br />
<br />
==== Partition offset ====<br />
<br />
The offset problem may happen when you try to embed {{ic|core.img}} into a partitioned disk. It means that [https://wiki.archlinux.org/index.php?title=Talk:Btrfs&diff=319474&oldid=292530 it is OK] to embed grub's {{ic|core.img}} into a Btrfs pool on a partitionless disk (e.g. {{ic|/dev/sd''X''}}) directly.<br />
<br />
[[GRUB]] can boot Btrfs partitions, however the module may be larger than other [[file systems]]. And the {{ic|core.img}} file made by {{ic|grub-install}} may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as {{ic|fdisk}} and {{ic|gdisk}} avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.<br />
<br />
==== Missing root ====<br />
<br />
{{Accuracy|Suggests editing a non-configuration file manually.|Talk:Btrfs#Should not suggest to edit files in /usr/share}}<br />
<br />
Users experiencing the following: {{ic|1=error no such device: root}} when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line {{ic|1=echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}"}}. Regenerate the config for grub and the system should boot without an error.<br />
<br />
=== BTRFS: open_ctree failed ===<br />
<br />
As of November 2014 there seems to be a bug in [[systemd]] or [[mkinitcpio]] causing the following error on systems with multi-device Btrfs filesystem using the {{ic|btrfs}} hook in {{ic|mkinitcpio.conf}}:<br />
<br />
{{bc|<nowiki><br />
BTRFS: open_ctree failed<br />
mount: wrong fs type, bad option, bad superblock on /dev/sdb2, missing codepage or helper program, or other error<br />
<br />
In some cases useful info is found in syslog - try dmesg|tail or so.<br />
<br />
You are now being dropped into an emergency shell.<br />
</nowiki>}}<br />
<br />
A workaround is to remove {{ic|btrfs}} from the {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}} and instead add {{ic|btrfs}} to the {{ic|MODULES}} array. Then regenerate the initramfs with {{ic|mkinitcpio -p linux}} (adjust the preset if needed) and reboot.<br />
<br />
You will get the same error if you try to mount a raid array without one of the devices. In that case you must add the {{ic|degraded}} mount option to {{ic|/etc/fstab}}. If your root resides on the array, you must also add {{ic|1=rootflags=degraded}} to your [[kernel parameters]].<br />
<br />
As of August 2016, a potential workaround for this bug is to mount the array by a single drive only in {{ic|/etc/fstab}}, and allow btrfs to discover and append the other drives automatically. Group-based identifiers such as UUID and LABEL appear to contribute to the failure. For example, a two-device RAID1 array consisting of 'disk1' and disk2' will have a UUID allocated to it, but instead of using the UUID, use only {{ic|/dev/mapper/disk1}} in {{ic|/etc/fstab}}. For a more detailed explanation, see the following [https://blog.samcater.com/fix-for-btrfs-open_ctree-failed-when-running-root-fs-on-raid-1-or-raid10-arch-linux/ blog post].<br />
<br />
Another possible workaround is to remove the {{ic|udev}} hook in [[mkinitcpio.conf]] and replace it with the {{ic|systemd}} hook. In this case, {{ic|btrfs}} should ''not'' be in the {{ic|HOOKS}} or {{ic|MODULES}} arrays.<br />
<br />
See the [https://bbs.archlinux.org/viewtopic.php?id=189845 original forums thread] and {{Bug|42884}} for further information and discussion.<br />
<br />
=== btrfs check ===<br />
{{Warning|Since Btrfs is under heavy development, especially the {{ic|btrfs check}} command, it is highly recommended to create a '''backup''' and consult the following Btfrs documentation before executing {{ic|btrfs check}} with the {{ic|--repair}} switch.}}<br />
<br />
The ''[https://btrfs.wiki.kernel.org/index.php/Manpage/btrfs-check btrfs check]'' command can be used to check or repair an unmounted Btrfs filesystem. However, this repair tool is still immature and not able to repair certain filesystem errors even those that do not render the filesystem unmountable.<br />
<br />
See [https://btrfs.wiki.kernel.org/index.php/Btrfsck Btrfsck] for more information.<br />
<br />
== See also ==<br />
<br />
* '''Official site'''<br />
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]<br />
* '''Performance related'''<br />
** [http://superuser.com/questions/432188/should-i-put-my-multi-device-btrfs-filesystem-on-disk-partitions-or-raw-devices Btrfs on raw disks?]<br />
** [https://www.spinics.net/lists/linux-btrfs/msg18652.html Varying leafsize and nodesize in Btrfs]<br />
** [http://comments.gmane.org/gmane.comp.file-systems.btrfs/15646 Btrfs support for efficient SSD operation (data blocks alignment)]<br />
** [https://btrfs.wiki.kernel.org/index.php/FAQ#Is_Btrfs_optimized_for_SSD.3F Is Btrfs optimized for SSDs?]<br />
** '''Phoronix mount option benchmarking'''<br />
*** [http://www.phoronix.com/scan.php?page=article&item=btrfs-mount-linux49 Linux 4.9]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_314_btrfs Linux 3.14]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_311&num=1 Linux 3.11]<br />
*** [http://www.phoronix.com/scan.php?page=news_item&px=MTM0OTU Linux 3.9]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=btrfs_linux37_mounts&num=1 Linux 3.7]<br />
*** [http://www.phoronix.com/scan.php?page=article&item=linux_btrfs_options&num=1 Linux 3.2]<br />
** [http://blog.erdemagaoglu.com/post/4605524309/lzo-vs-snappy-vs-lzf-vs-zlib-a-comparison-of Lzo vs. zLib]<br />
* '''Miscellaneous'''<br />
** [http://www.funtoo.org/wiki/BTRFS_Fun Funtoo Wiki Btrfs Fun]<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA0ODU Avi Miller presenting Btrfs] at SCALE 10x, January 2012.<br />
** [http://www.phoronix.com/scan.php?page=news_item&px=MTA4Mzc Summary of Chris Mason's talk] from LFCS 2012<br />
** [http://git.kernel.org/?p&#61;linux/kernel/git/torvalds/linux-2.6.git;a&#61;commit;h&#61;35054394c4b3cecd52577c2662c84da1f3e73525 Btrfs: stop providing a bmap operation to avoid swapfile corruptions] 2009-01-21<br />
** [http://marc.merlins.org/perso/btrfs/post_2014-03-22_Btrfs-Tips_-Doing-Fast-Incremental-Backups-With-Btrfs-Send-and-Receive.html Doing Fast Incremental Backups With Btrfs Send and Receive]</div>Zethexhttps://wiki.archlinux.org/index.php?title=Backlight&diff=577155Backlight2019-07-09T01:13:08Z<p>Zethex: /* xbacklight */ Added to the "No outputs have backlight property" error part for Intel Fastboot, as it may also cause that error.</p>
<hr />
<div>[[Category:Laptops]]<br />
[[Category:Power management]]<br />
[[ru:Backlight]]<br />
[[ja:バックライト]]<br />
Screen brightness might be tricky to control. On some machines physical hardware switches are missing and software solutions may not work well. However, it is generally possible to find a functional method for a given hardware. This article aims to summarize all possible ways to adjust the backlight.<br />
<br />
== Overview ==<br />
<br />
There are many ways to control brightness of a monitor, laptop or integrated panel (such as the iMac). According to [https://bugs.launchpad.net/ubuntu/+source/xserver-xorg-video-intel/+bug/397617 these] [https://lore.kernel.org/patchwork/patch/528936/#708706 discussions] and this [https://wiki.ubuntu.com/Kernel/Debugging/Backlight wiki page] the control method can be divided into these categories:<br />
<br />
* brightness is controlled by vendor-specified hotkey and there is no interface for the OS to adjust the brightness.<br />
* brightness is controlled by either the ACPI, graphic or platform driver.<br />
* brightness is controlled by HW register through setpci.<br />
<br />
All methods are exposed to the user through {{ic|/sys/class/backlight}} and xrandr/xbacklight can choose one method to control brightness. It is still not very clear which one xbacklight prefers by default.<br />
<br />
== ACPI ==<br />
<br />
The brightness of the screen backlight is adjusted by setting the power level of the backlight LEDs or cathodes. The power level can often be controlled using the ACPI kernel module for video. An interface to this module is provided via a sysfs directory at {{ic|/sys/class/backlight/}}.<br />
<br />
The name of the folder depends on the graphics card model.<br />
<br />
{{hc|$ ls /sys/class/backlight/|<br />
acpi_video0<br />
}}<br />
<br />
In this case, the backlight is managed by an ATI graphics card. In the case of an Intel card it is called {{ic|intel_backlight}}. In the following example, {{ic|acpi_video0}} is used.<br />
<br />
The directory contains the following files and folders:<br />
<br />
{{hc|$ ls /sys/class/backlight/acpi_video0/|<br />
actual_brightness brightness max_brightness subsystem/ uevent <br />
bl_power device/ power/ type<br />
}}<br />
<br />
The maximum brightness can be found by reading from {{ic|max_brightness}}, which is often 15.<br />
<br />
{{hc|$ cat /sys/class/backlight/acpi_video0/max_brightness|<br />
15<br />
}}<br />
<br />
The brightness can be set by writing a number to {{ic|brightness}}. Attempting to set a brightness greater than the maximum results in an error.<br />
<br />
# echo 5 > /sys/class/backlight/acpi_video0/brightness<br />
<br />
By default, only {{ic|root}} can change the brightness by this method. To allow users in the {{ic|video}} group to change the brightness, a [[udev]] rule such as the following can be used:<br />
<br />
{{hc|/etc/udev/rules.d/backlight.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="acpi_video0", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"<br />
ACTION=="add", SUBSYSTEM=="backlight", KERNEL=="acpi_video0", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"<br />
</nowiki>}}<br />
<br />
=== Kernel command-line options ===<br />
<br />
Sometimes, ACPI does not work well due to different motherboard implementations and ACPI quirks, resulting in, for instance, inaccurate brightness notifications. This includes some laptops with dual graphics (e.g. Nvidia/Radeon dedicated GPU with Intel/AMD integrated GPU). Additionally, ACPI sometimes needs to register its own {{ic|acpi_video0}} backlight even if one already exists (such as {{ic|intel_backlight}}), which can be done by adding one of the following [[kernel parameters]]:<br />
<br />
acpi_backlight=video<br />
acpi_backlight=vendor<br />
acpi_backlight=native<br />
<br />
If you find that changing the {{ic|acpi_video0}} backlight does not actually change the brightness, you may need to use {{ic|1=acpi_backlight=none}}.<br />
<br />
{{Tip|<br />
* On Nvidia Optimus laptops, the kernel parameter {{ic|nomodeset}} can interfere with the ability to adjust the backlight.<br />
* On an Asus notebooks you might also need to load the {{ic|asus-nb-wmi}} [[kernel module]].<br />
* Disabling legacy boot on Dell XPS13 breaks backlight support.<br />
}}<br />
<br />
=== Udev rule ===<br />
<br />
If the ACPI interface is available, the backlight level can be set at boot using a [[udev]] rule:<br />
<br />
{{hc|/etc/udev/rules.d/81-backlight.rules|<nowiki><br />
# Set backlight level to 8<br />
SUBSYSTEM=="backlight", ACTION=="add", KERNEL=="acpi_video0", ATTR{brightness}="8"</nowiki>}}<br />
<br />
{{Note|The systemd-backlight service restores the previous backlight brightness level at boot. To prevent conflicts for the above rules, see [[#systemd-backlight service]]{{Broken section link}}.}}<br />
<br />
{{Tip|To set the backlight depending on power state, see [[Power management#Using a script and an udev rule]] and use your favourite [[#Backlight utilities|backlight utility]] in the script.}}<br />
<br />
== Switch off the backlight ==<br />
<br />
Switching off the backlight (for example when one locks a notebook) can be useful to conserve battery energy. Ideally the following command should work for any [[Xorg]] graphical session:<br />
<br />
xset dpms force off<br />
<br />
The backlight should switch on again on mouse movement or keyboard input. Alternately {{ic|xset s}} could be used.<br />
<br />
The following example will toggle the screen saver timeout for a similar result (should be bound to a key):<br />
<br />
{{hc|~/.local/bin/xlcd.sh|<br />
#!/usr/bin/dash<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
xset s<br />
echo 1 > /tmp/lcd<br />
sleep 1<br />
notify-send -t 2000 LCD\ ON<br />
else<br />
xset s 3<br />
echo 0 > /tmp/lcd<br />
notify-send -t 2000 LCD\ OFF<br />
fi<br />
}}<br />
<br />
If the previous commands do not work, there is a chance that ''vbetool'' may work. Note, however, that in this case the backlight must be manually activated again. The command is as follows:<br />
<br />
$ vbetool dpms off<br />
<br />
To activate the backlight again:<br />
<br />
$ vbetool dpms on<br />
<br />
For example, this can be put to use when closing the notebook lid using [[Acpid]].<br />
<br />
== Save/Restore functionality ==<br />
<br />
The [[systemd]] package includes the service {{ic|systemd-backlight@.service}}, which is enabled by default and "static". It saves the backlight brightness level at shutdown and restores it at boot. The service uses the ACPI method described in [[#ACPI]], generating services for each folder found in {{ic|/sys/class/backlight/}}. For example, if there is a folder named {{ic|acpi_video0}}, it generates a service called {{ic|systemd-backlight@backlight:acpi_video0.service}}. When using other methods of setting the backlight at boot, it is recommended to stop systemd-backlight from restoring the backlight by setting the [[kernel parameters]] parameter {{ic|1=systemd.restore_state=0}}. See {{man|8|systemd-backlight@.service}} for details.<br />
<br />
{{Note|Some laptops have multiple video cards (e.g. Optimus) and the backlight restoration fails. Try [[systemd#Using units|masking]] an instance of the service (e.g. {{ic|systemd-backlight@backlight:acpi_video1}} for {{ic|acpi_video1}}).}}<br />
<br />
The {{AUR|relight}} package provides an alternative systemd-based method of saving and restoring screen brightness.<br />
<br />
Additionally, the {{AUR|brillo}} and {{Pkg|light}} utilities support save/restore functionality. These two may be more useful if one wishes to restore the screen brightness on a per-user basis, however no systemd units are provided to accomplish this.<br />
<br />
== Backlight utilities ==<br />
<br />
The utilities in the following table can be used to control screen brightness. All of them are compatible with Wayland and do not require X.<br />
<br />
{| class="wikitable sortable"<br />
!| Name<br />
! Controls keyboard backlights<br />
! Reacts to ambient brightness<br />
! Language<br />
! License<br />
! Notes<br />
! Package<br />
! Homepage<br />
|-<br />
| acpilight<br />
| {{Yes}}<br />
| {{No}}<br />
| Python3<br />
| GPL-3.0-or-later<br />
| "xbacklight" compatible<br />
| {{Pkg|acpilight}}<br />
| https://gitlab.com/wavexx/acpilight<br />
|-<br />
| brightd<br />
| {{No}}<br />
| {{No}}<br />
| C<br />
| GPL-2.0<br />
| Dims the screen when there is no user input for some time.<br />
| {{AUR|brightd}}<br />
| http://www.pberndt.com/Programme/Linux/brightd<br />
|-<br />
| brillo<br />
| {{Yes}}<br />
| {{No}}<br />
| C<br />
| GPL-3.0-only<br />
| Supports smooth and relative adjustments.<br />
| {{AUR|brillo}}<br />
| https://gitlab.com/cameronnemo/brillo<br />
|-<br />
| brightnessctl<br />
| {{Yes}}<br />
| {{No}}<br />
| C<br />
| MIT<br />
| {{Y|Binary is setuid unless otherwise configured.}}<br />
| {{AUR|brightnessctl}}<br />
| https://github.com/Hummer12007/brightnessctl<br />
|-<br />
| Calise<br />
| {{No}}<br />
| {{Yes}}<br />
| Python2<br />
| GPL-3.0<br />
| -<br />
| {{AUR|calise}}<br />
| http://calise.sourceforge.net<br />
|-<br />
| Clight<br />
| {{Yes}}<br />
| {{Yes}}<br />
| C<br />
| GPL-3.0-or-later<br />
| Manages screen temperature and smoothly dims brightness after a timeout. Turns webcam into an ambient light sensor.<br />
| {{AUR|clight}}<br />
| https://github.com/FedeDP/Clight<br />
|-<br />
| macbook-lighter<br />
| {{Yes}}<br />
| {{Yes}}<br />
| Bash,Perl<br />
| GPL<br />
| Macbook screen/keyboard backlight CLI and auto-adjust on ambient light.<br />
| {{AUR|macbook-lighter}}<br />
| https://github.com/harttle/macbook-lighter<br />
|-<br />
| enlighten<br />
| {{No}}<br />
| {{No}}<br />
| C<br />
| GPL-3.0-or-later<br />
| -<br />
| {{AUR|enlighten-git}}<br />
| https://github.com/HalosGhost/enlighten<br />
|-<br />
| illum<br />
| {{No}}<br />
| {{No}}<br />
| C<br />
| AGPL-3.0<br />
| Reacts to key presses.<br />
| {{AUR|illum-git}}<br />
| https://github.com/jmesmon/illum<br />
|-<br />
| Light<br />
| {{Yes}}<br />
| {{No}}<br />
| C<br />
| GPL-3.0-only<br />
| {{Y|Binary is setuid unless otherwise configured.}}<br />
| {{Pkg|light}}<br />
| https://haikarainen.github.io/light<br />
|-<br />
| Lux<br />
| {{No}}<br />
| {{No}}<br />
| Shell<br />
| MIT<br />
| -<br />
| {{AUR|lux}}<br />
| https://github.com/Ventto/lux<br />
|}<br />
<br />
=== xbacklight ===<br />
<br />
Brightness can be set using the {{Pkg|xorg-xbacklight}} package.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* xbacklight only works with [[Intel]]. Other drivers (e.g. [[Radeon]]) did not add support for the RandR backlight property. <br />
* xbacklight currently does not work with the modesetting driver [https://gitlab.freedesktop.org/xorg/xserver/issues/47].<br />
}}<br />
<br />
To set brightness to 50% of maximum:<br />
<br />
$ xbacklight -set 50<br />
<br />
Increments can be used instead of absolute values, for example to increase or decrease brightness by 10%:<br />
<br />
$ xbacklight -inc 10<br />
$ xbacklight -dec 10<br />
<br />
Gamma can be set using either the {{Pkg|xorg-xrandr}} or {{Pkg|xorg-xgamma}} package. The following commands create the same effect:<br />
<br />
$ xrandr --output LVDS1 --gamma 1.0:1.0:1.0<br />
$ xgamma -rgamma 1 -ggamma 1 -bgamma 1<br />
<br />
{{Tip|These commands can be bound to keyboard keys as described in [[Keyboard shortcuts#Xorg]].}}<br />
<br />
If you get the "No outputs have backlight property" error, it is because xrandr/xbacklight does not choose the right directory in {{ic|/sys/class/backlight}}. You can specify the directory by setting the {{ic|Backlight}} option of the device section in {{ic|/etc/X11/xorg.conf.d/20-''video''.conf}}. For instance, if the name of the directory is {{ic|intel_backlight}} and using the [[Intel]] driver, the device section may be configured as follows:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics" <br />
Driver "intel"<br />
Option "Backlight" "intel_backlight"<br />
EndSection}}<br />
<br />
See {{Bug|27677}} and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=651741 for details.<br />
<br />
If you have enabled [https://wiki.archlinux.org/index.php/Intel_graphics#Fastboot Intel Fastboot] you might also get the "No outputs have backlight property" error. In this case, trying the above method may cause Xorg may crash on start up. You should disable it to fix the issue. It's [https://bugs.freedesktop.org/show_bug.cgi?id=108225 known] to cause issues with brightness control.<br />
<br />
=== setpci ===<br />
<br />
It is possible to set the register of the graphic card to adjust the backlight. It means you adjust the backlight by manipulating the hardware directly, which can be risky and generally is not a good idea. Not all of the graphic cards support this method.<br />
<br />
When using this method, you need to use {{ic|lspci}} first to find out where your graphic card is.<br />
# setpci -s 00:02.0 F4.B=0<br />
<br />
=== Using DBus with Gnome ===<br />
<br />
Brightness can also be adjusted as the gnome controls do. Changes are reflected in the gnome UI using this method.<br />
gdbus call --session --dest org.gnome.SettingsDaemon.Power --object-path /org/gnome/SettingsDaemon/Power --method org.freedesktop.DBus.Properties.Set org.gnome.SettingsDaemon.Power.Screen Brightness "<int32 50>"<br />
<br />
Steps in brightness for keyboard contol can be implemented with this method as well.<br />
gdbus call --session --dest org.gnome.SettingsDaemon.Power --object-path /org/gnome/SettingsDaemon/Power --method org.gnome.SettingsDaemon.Power.Screen.StepUp<br />
gdbus call --session --dest org.gnome.SettingsDaemon.Power --object-path /org/gnome/SettingsDaemon/Power --method org.gnome.SettingsDaemon.Power.Screen.StepDown<br />
<br />
== Color correction ==<br />
<br />
* {{App|Clight|User daemon utility that aims to fully manage your display. It can manage the screen temperature depending on the current time of the day, just like redshift does. It tries to use {{Pkg|geoclue}} to retrieve the user position if neither latitude or longitude are set in the configuration file. It also supports fixed times for sunrise and sunset.|https://github.com/FedeDP/Clight|{{AUR|clight-git}}}}<br />
* {{App|Monica|Monitor calibration tool. It works as frontend to xgamma to alter the gamma correction.|https://web.archive.org/web/20090815224839/http://www.pcbypaul.com/software/monica.html|{{Pkg|monica}}}}<br />
* {{App|[[Redshift]]|Color temperature adjustment tool. It adjusts the color temperature of your screen according to your surroundings. This may help your eyes hurt less if you are working in front of the screen at night. This program is inspired by [[Wikipedia:f.lux|f.lux]].|http://jonls.dk/redshift/|{{Pkg|redshift}}}}<br />
* {{App|xcalib|Lightweight monitor calibration loader which can load an ICC monitor profile to be shared across desktop applications.|https://github.com/OpenICC/xcalib|{{AUR|xcalib}}}}<br />
* {{App|xgamma|Alter a monitor's gamma correction.|https://xorg.freedesktop.org/|{{Pkg|xorg-xgamma}}}}<br />
<br />
=== xcalib ===<br />
<br />
{{Note|''xcalib'' does ''not'' change the backlight power, it just modifies the video LUT table: this means that your battery life will be unaffected by the change. Nevertheless, it could be useful when no backlight control is available (Desktop PCs). Use {{ic|xcalib -clear}} to reset the LUT.}}<br />
<br />
The package {{AUR|xcalib}} ([http://xcalib.sourceforge.net/ upstream URL]) is available in the [[AUR]] and can be used to dim the screen. A demonstration video is available on [https://www.youtube.com/watch?v=A9xsvntT6i4 YouTube]. This program can correct gamma, invert colors, and reduce contrast, the latter of which we use in this case. For example, to dim down:<br />
<br />
$ xcalib -co 40 -a<br />
<br />
This program uses ICC technology to interact with X11 and while the screen is dimmed, you may find that the mouse cursor is just as bright as before.<br />
<br />
=== NVIDIA settings ===<br />
<br />
Users of [[NVIDIA|NVIDIA's proprietary drivers]] users can change display brightness via the nvidia-settings utility under "X Server Color Correction." However, note that this has absolutely nothing to do with backlight (intensity), it merely adjusts the color output. (Reducing brightness this way is a power-inefficient last resort when all other options fail; increasing brightness spoils your color output completely, in a way similar to overexposed photos.)<br />
<br />
=== Increase brightness above maximum level ===<br />
<br />
You can use [[xrandr]] to increase perceived brightness above its maximum level (the same caveats mentioned above for Nvidia apply):<br />
<br />
$ xrandr --output ''output_name'' --brightness 2<br />
<br />
This should roughly double luma in the image. It will sacrifice color quality for brightness, nevertheless it is particularly suited for situations where the ambient light is very bright (e.g. sunlight).<br />
<br />
== External monitors ==<br />
<br />
DDC/CI (Display Data Channel Command Interface) can be used to communicate with external monitors implementing MCCS (Monitor Control Command Set) over I2C. DDC can control brightness, contrast, inputs, etc on supported monitors. Settings available via the OSD (On-Screen Display) panel can usually also be managed via DDC. The [[kernel module]] {{ic|i2c-dev}} may need to be loaded if the {{ic|/dev/i2c-*}} devices do not exist.<br />
<br />
[http://www.ddcutil.com/ ddcutil] can be used to query and set brightness settings:<br />
<br />
{{hc|# ddcutil capabilities {{!}} grep "Feature: 10"|<br />
Feature: 10 (Brightness)<br />
}}<br />
<br />
{{hc|1=# ddcutil getvcp 10|2=<br />
VCP code 0x10 (Brightness ): current value = 60, max value = 100<br />
}}<br />
<br />
# ddcutil setvcp 10 70<br />
<br />
Alternatively, one may use {{AUR|ddcci-driver-linux-dkms}} to expose external monitors in sysfs. Then, after loading the {{ic|ddcci}} [[kernel module]], one can use any [[#Backlight utilities|backlight utility]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Backlight PWM modulation frequency (Intel i915 only) ===<br />
<br />
Laptops with LED backlight are known to have screen flicker sometimes. This is because the most efficient way of controlling LED backlight brightness is by turning the LED's on and off very quickly varying the amount of time they are on. <br />
<br />
However, the frequency of the switching, so-called PWM (pulse-width modulation) frequency, may not be high enough for the eye to perceive it as a single brightness and instead see flickering. This causes some people to have symptoms such as headaches and eyestrain.<br />
<br />
If you have an Intel i915 GPU, then it may be possible to adjust PWM frequency to eliminate flicker.<br />
<br />
Period of PWM (inverse to frequency) is stored in 2 higher bytes of {{ic|0xC8254}} register (if you are using the Intel GM45 chipset use address {{ic|0x61254}} instead). To manipulate registers values install {{Pkg|intel-gpu-tools}} from the official repositories.<br />
<br />
To increase the frequency, period must be reduced. For example:<br />
<br />
{{hc|# intel_reg read 0xC8254|<br />
0xC8254 : 0x12281228|<br />
}}<br />
<br />
Then to double PWM frequency divide 2 higher bytes (4 higher hex digits) by 2 and write back resulting value, keeping lower bytes unchanged:<br />
<br />
# intel_reg write 0xC8254 0x09141228<br />
<br />
You can use online calculator to calculate desired value http://devbraindom.blogspot.com/2013/03/eliminate-led-screen-flicker-with-intel.html<br />
<br />
To set new frequency automatically, consider writing an udev rule or install {{AUR|intelpwm-udev}}.<br />
<br />
=== Inverted Brightness (Intel i915 only) ===<br />
<br />
Symptoms:<br />
* after installing {{ic|xf86-video-intel}} systemd-backlight.service turns off the backlight during boot<br />
** possible solution: mask systemd-backlight.service<br />
* switching from X to another VT turns the backlight off<br />
* the brightness keys are inverted (i.e. turning up the brightness makes the screen darker)<br />
<br />
This problem may be solved by adding {{ic|i915.invert_brightness&#61;1}} to the list of [[kernel parameters]].<br />
<br />
=== Unable to control eDP Panel brightness (Intel i915 only) ===<br />
<br />
Embedded Display Port (eDP) v1.2 introduced a new display panel control protocol for backlight and other controls that works through the AUX channel.[https://www.vesa.org/wp-content/uploads/2010/12/DisplayPort-DevCon-Presentation-eDP-Dec-2010-v3.pdf]<br />
<br />
By default the i915 driver tries to use PWM to control backlight brightness, which might not work.<br />
<br />
To set the backlight through writes to DPCD registers using the AUX channel set {{ic|1=i915.enable_dpcd_backlight}} as [[kernel parameter]] or set in {{ic|/etc/modprobe.d/i915.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|<nowiki><br />
options i915 enable_dpcd_backlight<br />
</nowiki>}}<br />
<br />
=== sysfs modified but no brightness change ===<br />
<br />
{{Note|This behavior and their workarounds have been confirmed on the Dell M6700 with Nvidia K5000m (BIOS version prior to A10) and Clevo P750ZM (Eurocom P5 Pro Extreme) with Nvidia 980m.}}<br />
<br />
On some systems, the brightness hotkeys on your keyboard correctly modify the values of the acpi interface in {{ic|/sys/class/backlight/acpi_video0/actual_brightness}} but the brightness of the screen is not changed. Brightness applets from [[desktop environments]] may also show changes to no effect.<br />
<br />
If you have tested the recommended kernel parameters and only {{ic|xbacklight}} works, then you may be facing an incompatibility between your BIOS and kernel driver.<br />
<br />
In this case the only solution is to wait for a fix either from the BIOS or GPU driver manufacturer.<br />
<br />
A workaround is to use the inotify kernel api to trigger {{ic|xbacklight}} each time the value of {{ic|/sys/class/backlight/acpi_video0/actual_brightness}} changes.<br />
<br />
First [[install]] {{Pkg|inotify-tools}}. Then create a script around inotify that will be launched upon each boot or through [[autostart]].<br />
<br />
{{hc|/usr/local/bin/xbacklightmon|<nowiki><br />
#!/bin/sh<br />
<br />
path=/sys/class/backlight/acpi_video0<br />
<br />
luminance() {<br />
read -r level < "$path"/actual_brightness<br />
factor=$((100 / max))<br />
printf '%d\n' "$((level * factor))"<br />
}<br />
<br />
read -r max < "$path"/max_brightness<br />
<br />
xbacklight -set "$(luminance)"<br />
<br />
inotifywait -me modify --format '' "$path"/actual_brightness | while read; do<br />
xbacklight -set "$(luminance)"<br />
done<br />
</nowiki>}}</div>Zethexhttps://wiki.archlinux.org/index.php?title=Power_management/Suspend_and_hibernate&diff=576560Power management/Suspend and hibernate2019-06-29T12:34:35Z<p>Zethex: /* Hibernation into swap file on BTRFS */ Fix formatting issue</p>
<hr />
<div>[[Category:Power management]]<br />
[[es:Power management/Suspend and hibernate]]<br />
[[ja:サスペンドとハイバネート]]<br />
[[ru:Power management/Suspend and hibernate]]<br />
[[zh-hans:Power management/Suspend and hibernate]]<br />
{{Related articles start}}<br />
{{Related|Uswsusp}}<br />
{{Related|systemd}}<br />
{{Related|Power management}}<br />
{{Related articles end}}<br />
<br />
Currently there are three methods of suspending available: '''suspend to RAM''' (usually called just '''suspend'''), '''suspend to disk''' (usually known as '''hibernate'''), and '''hybrid suspend''' (sometimes aptly called '''suspend to both'''):<br />
<br />
* '''Suspend to RAM''' method cuts power to most parts of the machine aside from the RAM, which is required to restore the machine's state. Because of the large power savings, it is advisable for laptops to automatically enter this mode when the computer is running on batteries and the lid is closed (or the user is inactive for some time).<br />
<br />
* '''Suspend to disk''' method saves the machine's state into [[swap space]] and completely powers off the machine. When the machine is powered on, the state is restored. Until then, there is [[Wikipedia:Standby power|zero]] power consumption.<br />
<br />
* '''Suspend to both''' method saves the machine's state into swap space, but does not power off the machine. Instead, it invokes usual suspend to RAM. Therefore, if the battery is not depleted, the system can resume from RAM. If the battery is depleted, the system can be resumed from disk, which is much slower than resuming from RAM, but the machine's state has not been lost.<br />
<br />
There are multiple low level interfaces (backends) providing basic functionality, and some high level interfaces providing tweaks to handle problematic hardware drivers/kernel modules (e.g. video card re-initialization).<br />
<br />
== Low level interfaces ==<br />
<br />
Though these interfaces can be used directly, it is advisable to use some of [[#High level interfaces|high level interfaces]] to suspend/hibernate. Using low level interfaces directly is significantly faster than using any high level interface, since running all the pre- and post-suspend hooks takes time, but hooks can properly set hardware clock, restore wireless etc.<br />
<br />
=== kernel (swsusp) ===<br />
<br />
The most straightforward approach is to directly inform the in-kernel software suspend code (swsusp) to enter a suspended state; the exact method and state depends on the level of hardware support. On modern kernels, writing appropriate strings to {{ic|/sys/power/state}} is the primary mechanism to trigger this suspend.<br />
<br />
See [https://www.kernel.org/doc/Documentation/power/states.txt kernel documentation] for details.<br />
<br />
=== uswsusp ===<br />
<br />
The uswsusp ('Userspace Software Suspend') is a wrapper around the kernel's suspend-to-RAM mechanism, which performs some graphics adapter manipulations from userspace before suspending and after resuming.<br />
<br />
See main article [[Uswsusp]].<br />
<br />
== High level interfaces ==<br />
<br />
The end goal of these packages is to provide binaries/scripts that can be invoked to perform suspend/hibernate. Actually hooking them up to power buttons or menu clicks or laptop lid events is usually left to other tools. To automatically suspend/hibernate on certain power events, such as laptop lid close or battery depletion percentage, you may want to look into running [[Acpid]].<br />
<br />
=== systemd ===<br />
<br />
[[systemd]] provides native commands for suspend, hibernate and a hybrid suspend, see [[Power management#Power management with systemd]] for details. This is the default interface used in Arch Linux.<br />
<br />
See [[Power management#Sleep hooks]] for additional information on configuring suspend/hibernate hooks. Also see {{man|1|systemctl}}, {{man|8|systemd-sleep}}, and {{man|7|systemd.special}}.<br />
<br />
== Hibernation ==<br />
<br />
In order to use hibernation, you need to create a [[swap]] partition or file. You will need to point the kernel to your swap using the {{ic|1=resume=}} kernel parameter, which is configured via the boot loader. You will also need to [[#Configure the initramfs|configure the initramfs]]. This tells the kernel to attempt resuming from the specified swap in early userspace. These three steps are described in detail below.<br />
<br />
{{Note|See [[Dm-crypt/Swap encryption#With suspend-to-disk support]] when using [[encryption]].}}<br />
<br />
=== About swap partition/file size ===<br />
<br />
Even if your swap partition is smaller than RAM, you still have a big chance of hibernating successfully. According to [https://www.kernel.org/doc/Documentation/power/interface.txt kernel documentation]:<br />
<br />
: ''{{ic|/sys/power/image_size}} controls the size of the image created by the suspend-to-disk mechanism. It can be written a string representing a non-negative integer that will be used as an upper limit of the image size, in bytes. The suspend-to-disk mechanism will do its best to ensure the image size will not exceed that number. However, if this turns out to be impossible, it will try to suspend anyway using the smallest image possible. In particular, if "0" is written to this file, the suspend image will be as small as possible. Reading from this file will display the current image size limit, which is set to 2/5 of available RAM by default.''<br />
<br />
You may either decrease the value of {{ic|/sys/power/image_size}} to make the suspend image as small as possible (for small swap partitions), or increase it to possibly speed up the hibernation process.<br />
<br />
See [[Systemd#Temporary files]] to make this change persistent.<br />
<br />
=== Required kernel parameters ===<br />
<br />
The kernel parameter {{ic|1=resume=''swap_partition''}} has to be used. Either the name the kernel assigns to the partition or its [[UUID]] can be used as {{ic|''swap_partition''}}. For example:<br />
<br />
* {{ic|1=resume=/dev/sda1}}<br />
* {{ic|1=resume=UUID=4209c845-f495-4c43-8a03-5363dd433153}}<br />
* {{ic|1=resume=/dev/archVolumeGroup/archLogicVolume}} -- example if using LVM<br />
<br />
Generally, the naming method used for the {{ic|resume}} parameter should be the same as used for the {{ic|root}} parameter.<br />
<br />
The configuration depends on the used [[boot loader]], refer to [[Kernel parameters]] for details.<br />
<br />
==== Hibernation into swap file ====<br />
<br />
{{Warning|<br />
<br />
* [[Btrfs#Swap file|Btrfs]] on Linux kernel before version 5.0 does not support swap files. Failure to heed this warning may result in file system corruption. While a swap file may be used on Btrfs when mounted through a loop device, this will result in severely degraded swap performance.<br />
* {{pkg|systemd}} does not currently support hibernating into a swap file on Btrfs, even with Linux 5.0. Fortunately, there is an alternate method: [[Power_management/Suspend_and_hibernate#Hibernation_into_swap_file_on_Btrfs]]. For more information, see [https://github.com/systemd/systemd/issues/11939 systemd issue 11939].<br />
}}<br />
<br />
Using a swap file instead of a swap partition requires an additional kernel parameter {{ic|1=resume_offset=''swap_file_offset''}}. Note that the {{ic|1=resume}} keyword should still point to the partition where your swapfile resides as described above.<br />
<br />
The value of {{ic|''swap_file_offset''}} can be obtained by running {{ic|filefrag -v ''swap_file''}}, the output is in a table format and the required value is located in the first row of the {{ic|physical_offset}} column. For example:<br />
<br />
{{hc|# filefrag -v /swapfile|<nowiki><br />
Filesystem type is: ef53<br />
File size of /swapfile is 4294967296 (1048576 blocks of 4096 bytes)<br />
ext: logical_offset: physical_offset: length: expected: flags:<br />
0: 0.. 0: 38912.. 38912: 1: <br />
1: 1.. 22527: 38913.. 61439: 22527: unwritten<br />
2: 22528.. 53247: 899072.. 929791: 30720: 61440: unwritten<br />
...<br />
</nowiki>}}<br />
<br />
In the example the value of {{ic|''swap_file_offset''}} is the first {{ic|38912}} with the two periods.<br />
<br />
{{Tip|The following command may be used to identify {{ic|''swap_file_offset''}}: {{ic|1=filefrag -v /swapfile {{!}} awk '{ if($1=="0:"){print $4} }'}}.}}<br />
<br />
==== Hibernation into swap file on BTRFS ====<br />
<br />
On Btrfs, the "physical" offset you get from filefrag isn't the real physical offset on disk; there is a virtual disk address space in order to support multiple devices. Due to this the above method will not work for a swap file from a Btrfs file system.<br />
<br />
An alternate method is to use [https://raw.githubusercontent.com/osandov/osandov-linux/master/scripts/btrfs_map_physical.c this tool] instead of filefrag.<br />
<br />
Download or copy the text into a file named `btrfs_map_physical.c`.], then compile it:<br />
{{bc|gcc -O2 -o btrfs_map_physical btrfs_map_physical.c}}<br />
<br />
Run it. For example:<br />
{{hc|# ./btrfs_map_physical /.swapfile/swapfile |<br />
FILE OFFSET EXTENT TYPE LOGICAL SIZE LOGICAL OFFSET PHYSICAL SIZE DEVID PHYSICAL OFFSET<br />
0 regular 4096 2927632384 268435456 1 4009762816<br />
4096 prealloc 268431360 2927636480 268431360 1 4009766912<br />
268435456 prealloc 268435456 3251634176 268435456 1 4333764608<br />
536870912 prealloc 268435456 3520069632 268435456 1 4602200064<br />
805306368 prealloc 268435456 3788505088 268435456 1 4870635520<br />
1073741824 prealloc 268435456 4056940544 268435456 1 5139070976<br />
1342177280 prealloc 268435456 4325376000 268435456 1 5407506432<br />
1610612736 prealloc 268435456 4593811456 268435456 1 5675941888<br />
1879048192 prealloc 268435456 4862246912 268435456 1 5944377344<br />
2147483648 prealloc 268435456 5130682368 268435456 1 6212812800<br />
2415919104 prealloc 268435456 5399117824 268435456 1 6481248256<br />
2684354560 prealloc 268435456 5667553280 268435456 1 6749683712<br />
2952790016 prealloc 268435456 5935988736 268435456 1 7018119168<br />
3221225472 prealloc 268435456 6204424192 268435456 1 7286554624<br />
3489660928 prealloc 268435456 6472859648 268435456 1 7554990080<br />
3758096384 prealloc 268435456 6741295104 268435456 1 7823425536<br />
4026531840 prealloc 268435456 7009730560 268435456 1 8091860992<br />
4294967296 prealloc 268435456 7278166016 268435456 1 8360296448<br />
4563402752 prealloc 268435456 7546601472 268435456 1 8628731904<br />
4831838208 prealloc 268435456 7815036928 268435456 1 8897167360<br />
5100273664 prealloc 268435456 8083472384 268435456 1 9165602816<br />
5368709120 prealloc 268435456 8351907840 268435456 1 9434038272<br />
5637144576 prealloc 268435456 8620343296 268435456 1 9702473728<br />
5905580032 prealloc 268435456 8888778752 268435456 1 9970909184<br />
6174015488 prealloc 268435456 9157214208 268435456 1 10239344640<br />
6442450944 prealloc 268435456 9425649664 268435456 1 10507780096<br />
6710886400 prealloc 268435456 9694085120 268435456 1 10776215552<br />
6979321856 prealloc 268435456 9962520576 268435456 1 11044651008<br />
7247757312 prealloc 268435456 10230956032 268435456 1 11313086464<br />
7516192768 prealloc 268435456 10499391488 268435456 1 11581521920<br />
7784628224 prealloc 268435456 10767826944 268435456 1 11849957376<br />
8053063680 prealloc 268435456 11036262400 268435456 1 12118392832<br />
8321499136 prealloc 268435456 11304697856 268435456 1 12386828288<br />
|}}<br />
<br />
The first physical offset should be the one. In this example, we will use {{ic|4009762816}}.<br />
Divide that by 4096 and you have your resume_offset value. In this example, it is {{ic|978946}}.<br />
<br />
Systemd overrides those settings incorrectly. Instead of using {{ic|systemctl hibernate}} to hibernate, use {{ic|# echo disk > /sys/power/state}}. As a regular user you could use {{ic|<nowiki> $ echo disk | sudo tee /sys/power/state</nowiki>}} instead.<br />
<br />
{{Note|<br />
* Before the first hibernation, a reboot is required to activate the feature.<br />
* The value of {{ic|''swap_file_offset''}} can also be obtained by running {{ic|swap-offset ''swap_file''}}. The ''swap-offset'' binary is provided within the set of tools [[uswsusp]]. If using this method, then these two parameters have to be provided in {{ic|/etc/suspend.conf}} via the keys {{ic|resume device}} and {{ic|resume offset}}. No reboot is required in this case.<br />
<br />
}}<br />
<br />
{{Tip|You might want to decrease the [[Swap#Swappiness]] for your swapfile if the only purpose is to be able to hibernate and not expand RAM.}}<br />
<br />
=== Configure the initramfs ===<br />
<br />
* When an [[initramfs]] with the {{ic|base}} hook is used, which is the default, the {{ic|resume}} hook is required in {{ic|/etc/mkinitcpio.conf}}. Whether by label or by UUID, the swap partition is referred to with a udev device node, so the {{ic|resume}} hook must go ''after'' the {{ic|udev}} hook. This example was made starting from the default hook configuration:<br />
<br />
:{{bc|1=HOOKS=(base udev autodetect keyboard modconf block filesystems '''resume''' fsck)}}<br />
<br />
:Remember to [[regenerate the initramfs]] for these changes to take effect.<br />
<br />
:{{Note|[[LVM]] users should add the {{ic|resume}} hook after {{ic|lvm2}}.}}<br />
<br />
* When an initramfs with the {{ic|systemd}} hook is used, a resume mechanism is already provided, and no further hooks need to be added.<br />
<br />
== Troubleshooting ==<br />
<br />
=== ACPI_OS_NAME ===<br />
<br />
You might want to tweak your '''DSDT table''' to make it work. See [[DSDT]] article<br />
<br />
=== VAIO users ===<br />
<br />
{{Move|Laptop/Sony|Hardware specific problem.}}<br />
<br />
Add the [[kernel parameter]] {{ic|1=acpi_sleep=nonvs}} to your bootloader.<br />
<br />
=== Suspend/hibernate doesn't work, or not consistently ===<br />
<br />
There have been many reports about the screen going black without easily viewable errors or the ability to do anything when going into and coming back from suspend and/or hibernate. These problems have been seen on both laptops and desktops. This is not an official solution, but switching to an older kernel, especially the LTS-kernel, will probably fix this.<br />
<br />
Also problem may arise when using hardware watchdog timer (disabled by default, see {{ic|1=RuntimeWatchdogSec=}} in {{man|5|systemd-system.conf|OPTIONS}}). Bugged watchdog timer may reset the computer before the system finished creating the hibernation image.<br />
<br />
Sometimes the screen goes black due to device initialization from within the initramfs. Removing any modules you might have in [[Mkinitcpio#MODULES]] and rebuilding the initramfs, can possibly solve this issue, specially graphics drivers for [[Kernel_mode_setting#Early_KMS_start|early KMS]]. Initializing such devices before resuming can cause inconsistencies that prevents the system resuming from hibernation. This does not affect resuming from RAM. Also, check the blog article [https://01.org/blogs/rzhang/2015/best-practice-debug-linux-suspend/hibernate-issues best practices to debug suspend issues].<br />
<br />
For Intel graphics drivers, enabling early KMS may help to solve the blank screen issue. Refer to [[Kernel mode setting#Early KMS start]] for details.<br />
<br />
After upgrading to kernel 4.15.3, resume may fail with a static (non-blinking) cursor on a black screen. [[Blacklisting]] the module {{ic|nvidiafb}} might help. [https://bbs.archlinux.org/viewtopic.php?id=234646]<br />
<br />
=== Wake-on-LAN ===<br />
<br />
If [[Wake-on-LAN]] is active, the network interface card will consume power even if the computer is hibernated.<br />
<br />
=== Instantaneous wakeups from suspend ===<br />
<br />
For some Intel Haswell systems with the LynxPoint and LynxPoint-LP chipset, instantaneous wakeups after suspend are reported. They are linked to erroneous BIOS ACPI implementations and how the {{ic|xhci_hcd}} module interprets it during boot. As a work-around reported affected systems are added to a blacklist (named {{ic|XHCI_SPURIOUS_WAKEUP}}) by the kernel case-by-case.[https://bugzilla.kernel.org/show_bug.cgi?id=66171#c6] <br />
<br />
Instantaneous resume may happen, for example, if a USB device is plugged during suspend and ACPI wakeup triggers are enabled. A viable work-around for such a system, if it is not on the blacklist yet, is to disable the wakeup triggers. An example to disable wakeup through USB is described as follows.[https://bbs.archlinux.org/viewtopic.php?pid=1575617] <br />
<br />
To view the current configuration:<br />
<br />
{{hc|$ cat /proc/acpi/wakeup|<br />
Device S-state Status Sysfs node<br />
...<br />
EHC1 S3 *enabled pci:0000:00:1d.0<br />
EHC2 S3 *enabled pci:0000:00:1a.0<br />
XHC S3 *enabled pci:0000:00:14.0<br />
...<br />
}}<br />
<br />
The relevant devices are {{ic|EHC1}}, {{ic|EHC2}} and {{ic|XHC}} (for USB 3.0). To toggle their state you have to echo the device name to the file as root.<br />
<br />
# echo EHC1 > /proc/acpi/wakeup<br />
# echo EHC2 > /proc/acpi/wakeup<br />
# echo XHC > /proc/acpi/wakeup<br />
<br />
This should result in suspension working again. However, this settings are only temporary and would have to be set at every reboot. To automate this take a look at [[systemd#Writing unit files]]. See [https://bbs.archlinux.org/viewtopic.php?pid=1575617#p1575617 BBS thread] for a possible solution and more information.<br />
<br />
If you use {{ic|nouveau}} driver, the reason of instantaneous wakeup may be a bug in that driver, which sometimes prevents graphics card from suspension. One possible workaround is unloading {{ic|nouveau}} kernel module right before going to sleep and loading it back after wakeup. To do this, create the following script:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/10-nouveau.sh|2=<br />
#!/bin/bash<br />
<br />
case $1/$2 in<br />
pre/*)<br />
# echo "Going to $2..."<br />
/usr/bin/echo "0" > /sys/class/vtconsole/vtcon1/bind<br />
/usr/bin/rmmod nouveau<br />
;;<br />
post/*)<br />
# echo "Waking up from $2..."<br />
/usr/bin/modprobe nouveau<br />
/usr/bin/echo "1" > /sys/class/vtconsole/vtcon1/bind<br />
;;<br />
esac<br />
}}<br />
<br />
The first echo line unbinds nouveaufb from the framebuffer console driver (fbcon). Usually it is {{ic|vtcon1}} as in this example, but it may also be another {{ic|vtcon*}}. See {{ic|/sys/class/vtconsole/vtcon*/name}} which one of them is a "frame buffer device" [https://nouveau.freedesktop.org/wiki/KernelModeSetting/].<br />
<br />
=== System does not power off when hibernating ===<br />
<br />
When you hibernate your system, the system should power off (after saving the state on the disk). Sometimes, you might see the power LED is still glowing. If that happens, it might be instructive to set the {{ic|HibernateMode}} to {{ic|shutdown}} in {{man|5|sleep.conf.d}}:<br />
<br />
{{hc|/etc/systemd/sleep.conf.d/hibernatemode.conf|2=<br />
[Sleep]<br />
HibernateMode=shutdown<br />
}}<br />
<br />
With the above configuration, if every thing else is setup correctly, on invocation of a {{ic|systemctl hibernate}} the machine will shutdown saving state to disk as it does so.</div>Zethexhttps://wiki.archlinux.org/index.php?title=Power_management/Suspend_and_hibernate&diff=576559Power management/Suspend and hibernate2019-06-29T12:33:56Z<p>Zethex: /* Hibernation into swap file */ Added link to alternate method for swap file under Btrfs</p>
<hr />
<div>[[Category:Power management]]<br />
[[es:Power management/Suspend and hibernate]]<br />
[[ja:サスペンドとハイバネート]]<br />
[[ru:Power management/Suspend and hibernate]]<br />
[[zh-hans:Power management/Suspend and hibernate]]<br />
{{Related articles start}}<br />
{{Related|Uswsusp}}<br />
{{Related|systemd}}<br />
{{Related|Power management}}<br />
{{Related articles end}}<br />
<br />
Currently there are three methods of suspending available: '''suspend to RAM''' (usually called just '''suspend'''), '''suspend to disk''' (usually known as '''hibernate'''), and '''hybrid suspend''' (sometimes aptly called '''suspend to both'''):<br />
<br />
* '''Suspend to RAM''' method cuts power to most parts of the machine aside from the RAM, which is required to restore the machine's state. Because of the large power savings, it is advisable for laptops to automatically enter this mode when the computer is running on batteries and the lid is closed (or the user is inactive for some time).<br />
<br />
* '''Suspend to disk''' method saves the machine's state into [[swap space]] and completely powers off the machine. When the machine is powered on, the state is restored. Until then, there is [[Wikipedia:Standby power|zero]] power consumption.<br />
<br />
* '''Suspend to both''' method saves the machine's state into swap space, but does not power off the machine. Instead, it invokes usual suspend to RAM. Therefore, if the battery is not depleted, the system can resume from RAM. If the battery is depleted, the system can be resumed from disk, which is much slower than resuming from RAM, but the machine's state has not been lost.<br />
<br />
There are multiple low level interfaces (backends) providing basic functionality, and some high level interfaces providing tweaks to handle problematic hardware drivers/kernel modules (e.g. video card re-initialization).<br />
<br />
== Low level interfaces ==<br />
<br />
Though these interfaces can be used directly, it is advisable to use some of [[#High level interfaces|high level interfaces]] to suspend/hibernate. Using low level interfaces directly is significantly faster than using any high level interface, since running all the pre- and post-suspend hooks takes time, but hooks can properly set hardware clock, restore wireless etc.<br />
<br />
=== kernel (swsusp) ===<br />
<br />
The most straightforward approach is to directly inform the in-kernel software suspend code (swsusp) to enter a suspended state; the exact method and state depends on the level of hardware support. On modern kernels, writing appropriate strings to {{ic|/sys/power/state}} is the primary mechanism to trigger this suspend.<br />
<br />
See [https://www.kernel.org/doc/Documentation/power/states.txt kernel documentation] for details.<br />
<br />
=== uswsusp ===<br />
<br />
The uswsusp ('Userspace Software Suspend') is a wrapper around the kernel's suspend-to-RAM mechanism, which performs some graphics adapter manipulations from userspace before suspending and after resuming.<br />
<br />
See main article [[Uswsusp]].<br />
<br />
== High level interfaces ==<br />
<br />
The end goal of these packages is to provide binaries/scripts that can be invoked to perform suspend/hibernate. Actually hooking them up to power buttons or menu clicks or laptop lid events is usually left to other tools. To automatically suspend/hibernate on certain power events, such as laptop lid close or battery depletion percentage, you may want to look into running [[Acpid]].<br />
<br />
=== systemd ===<br />
<br />
[[systemd]] provides native commands for suspend, hibernate and a hybrid suspend, see [[Power management#Power management with systemd]] for details. This is the default interface used in Arch Linux.<br />
<br />
See [[Power management#Sleep hooks]] for additional information on configuring suspend/hibernate hooks. Also see {{man|1|systemctl}}, {{man|8|systemd-sleep}}, and {{man|7|systemd.special}}.<br />
<br />
== Hibernation ==<br />
<br />
In order to use hibernation, you need to create a [[swap]] partition or file. You will need to point the kernel to your swap using the {{ic|1=resume=}} kernel parameter, which is configured via the boot loader. You will also need to [[#Configure the initramfs|configure the initramfs]]. This tells the kernel to attempt resuming from the specified swap in early userspace. These three steps are described in detail below.<br />
<br />
{{Note|See [[Dm-crypt/Swap encryption#With suspend-to-disk support]] when using [[encryption]].}}<br />
<br />
=== About swap partition/file size ===<br />
<br />
Even if your swap partition is smaller than RAM, you still have a big chance of hibernating successfully. According to [https://www.kernel.org/doc/Documentation/power/interface.txt kernel documentation]:<br />
<br />
: ''{{ic|/sys/power/image_size}} controls the size of the image created by the suspend-to-disk mechanism. It can be written a string representing a non-negative integer that will be used as an upper limit of the image size, in bytes. The suspend-to-disk mechanism will do its best to ensure the image size will not exceed that number. However, if this turns out to be impossible, it will try to suspend anyway using the smallest image possible. In particular, if "0" is written to this file, the suspend image will be as small as possible. Reading from this file will display the current image size limit, which is set to 2/5 of available RAM by default.''<br />
<br />
You may either decrease the value of {{ic|/sys/power/image_size}} to make the suspend image as small as possible (for small swap partitions), or increase it to possibly speed up the hibernation process.<br />
<br />
See [[Systemd#Temporary files]] to make this change persistent.<br />
<br />
=== Required kernel parameters ===<br />
<br />
The kernel parameter {{ic|1=resume=''swap_partition''}} has to be used. Either the name the kernel assigns to the partition or its [[UUID]] can be used as {{ic|''swap_partition''}}. For example:<br />
<br />
* {{ic|1=resume=/dev/sda1}}<br />
* {{ic|1=resume=UUID=4209c845-f495-4c43-8a03-5363dd433153}}<br />
* {{ic|1=resume=/dev/archVolumeGroup/archLogicVolume}} -- example if using LVM<br />
<br />
Generally, the naming method used for the {{ic|resume}} parameter should be the same as used for the {{ic|root}} parameter.<br />
<br />
The configuration depends on the used [[boot loader]], refer to [[Kernel parameters]] for details.<br />
<br />
==== Hibernation into swap file ====<br />
<br />
{{Warning|<br />
<br />
* [[Btrfs#Swap file|Btrfs]] on Linux kernel before version 5.0 does not support swap files. Failure to heed this warning may result in file system corruption. While a swap file may be used on Btrfs when mounted through a loop device, this will result in severely degraded swap performance.<br />
* {{pkg|systemd}} does not currently support hibernating into a swap file on Btrfs, even with Linux 5.0. Fortunately, there is an alternate method: [[Power_management/Suspend_and_hibernate#Hibernation_into_swap_file_on_Btrfs]]. For more information, see [https://github.com/systemd/systemd/issues/11939 systemd issue 11939].<br />
}}<br />
<br />
Using a swap file instead of a swap partition requires an additional kernel parameter {{ic|1=resume_offset=''swap_file_offset''}}. Note that the {{ic|1=resume}} keyword should still point to the partition where your swapfile resides as described above.<br />
<br />
The value of {{ic|''swap_file_offset''}} can be obtained by running {{ic|filefrag -v ''swap_file''}}, the output is in a table format and the required value is located in the first row of the {{ic|physical_offset}} column. For example:<br />
<br />
{{hc|# filefrag -v /swapfile|<nowiki><br />
Filesystem type is: ef53<br />
File size of /swapfile is 4294967296 (1048576 blocks of 4096 bytes)<br />
ext: logical_offset: physical_offset: length: expected: flags:<br />
0: 0.. 0: 38912.. 38912: 1: <br />
1: 1.. 22527: 38913.. 61439: 22527: unwritten<br />
2: 22528.. 53247: 899072.. 929791: 30720: 61440: unwritten<br />
...<br />
</nowiki>}}<br />
<br />
In the example the value of {{ic|''swap_file_offset''}} is the first {{ic|38912}} with the two periods.<br />
<br />
{{Tip|The following command may be used to identify {{ic|''swap_file_offset''}}: {{ic|1=filefrag -v /swapfile {{!}} awk '{ if($1=="0:"){print $4} }'}}.}}<br />
<br />
==== Hibernation into swap file on BTRFS ====<br />
<br />
On Btrfs, the "physical" offset you get from filefrag isn't the real physical offset on disk; there is a virtual disk address space in order to support multiple devices. Due to this the above method will not work for a swap file from a Btrfs file system.<br />
<br />
An alternate method is to use [https://raw.githubusercontent.com/osandov/osandov-linux/master/scripts/btrfs_map_physical.c this tool] instead of filefrag.<br />
<br />
Download or copy the text into a file named `btrfs_map_physical.c`.], then compile it:<br />
{{bc|gcc -O2 -o btrfs_map_physical btrfs_map_physical.c}}<br />
<br />
Run it. For example:<br />
{{hc|# ./btrfs_map_physical /.swapfile/swapfile |<br />
FILE OFFSET EXTENT TYPE LOGICAL SIZE LOGICAL OFFSET PHYSICAL SIZE DEVID PHYSICAL OFFSET<br />
0 regular 4096 2927632384 268435456 1 4009762816<br />
4096 prealloc 268431360 2927636480 268431360 1 4009766912<br />
268435456 prealloc 268435456 3251634176 268435456 1 4333764608<br />
536870912 prealloc 268435456 3520069632 268435456 1 4602200064<br />
805306368 prealloc 268435456 3788505088 268435456 1 4870635520<br />
1073741824 prealloc 268435456 4056940544 268435456 1 5139070976<br />
1342177280 prealloc 268435456 4325376000 268435456 1 5407506432<br />
1610612736 prealloc 268435456 4593811456 268435456 1 5675941888<br />
1879048192 prealloc 268435456 4862246912 268435456 1 5944377344<br />
2147483648 prealloc 268435456 5130682368 268435456 1 6212812800<br />
2415919104 prealloc 268435456 5399117824 268435456 1 6481248256<br />
2684354560 prealloc 268435456 5667553280 268435456 1 6749683712<br />
2952790016 prealloc 268435456 5935988736 268435456 1 7018119168<br />
3221225472 prealloc 268435456 6204424192 268435456 1 7286554624<br />
3489660928 prealloc 268435456 6472859648 268435456 1 7554990080<br />
3758096384 prealloc 268435456 6741295104 268435456 1 7823425536<br />
4026531840 prealloc 268435456 7009730560 268435456 1 8091860992<br />
4294967296 prealloc 268435456 7278166016 268435456 1 8360296448<br />
4563402752 prealloc 268435456 7546601472 268435456 1 8628731904<br />
4831838208 prealloc 268435456 7815036928 268435456 1 8897167360<br />
5100273664 prealloc 268435456 8083472384 268435456 1 9165602816<br />
5368709120 prealloc 268435456 8351907840 268435456 1 9434038272<br />
5637144576 prealloc 268435456 8620343296 268435456 1 9702473728<br />
5905580032 prealloc 268435456 8888778752 268435456 1 9970909184<br />
6174015488 prealloc 268435456 9157214208 268435456 1 10239344640<br />
6442450944 prealloc 268435456 9425649664 268435456 1 10507780096<br />
6710886400 prealloc 268435456 9694085120 268435456 1 10776215552<br />
6979321856 prealloc 268435456 9962520576 268435456 1 11044651008<br />
7247757312 prealloc 268435456 10230956032 268435456 1 11313086464<br />
7516192768 prealloc 268435456 10499391488 268435456 1 11581521920<br />
7784628224 prealloc 268435456 10767826944 268435456 1 11849957376<br />
8053063680 prealloc 268435456 11036262400 268435456 1 12118392832<br />
8321499136 prealloc 268435456 11304697856 268435456 1 12386828288<br />
|}}<br />
<br />
The first physical offset should be the one. In this example, we will use {{ic|`4009762816`}}.<br />
Divide that by 4096 and you have your resume_offset value. In this example, it is {{ic|`978946`}}.<br />
<br />
Systemd overrides those settings incorrectly. Instead of using {{ic|systemctl hibernate}} to hibernate, use {{ic|# echo disk > /sys/power/state}}. As a regular user you could use {{ic|<nowiki> $ echo disk | sudo tee /sys/power/state</nowiki>}} instead.<br />
<br />
{{Note|<br />
* Before the first hibernation, a reboot is required to activate the feature.<br />
* The value of {{ic|''swap_file_offset''}} can also be obtained by running {{ic|swap-offset ''swap_file''}}. The ''swap-offset'' binary is provided within the set of tools [[uswsusp]]. If using this method, then these two parameters have to be provided in {{ic|/etc/suspend.conf}} via the keys {{ic|resume device}} and {{ic|resume offset}}. No reboot is required in this case.<br />
<br />
}}<br />
<br />
{{Tip|You might want to decrease the [[Swap#Swappiness]] for your swapfile if the only purpose is to be able to hibernate and not expand RAM.}}<br />
<br />
=== Configure the initramfs ===<br />
<br />
* When an [[initramfs]] with the {{ic|base}} hook is used, which is the default, the {{ic|resume}} hook is required in {{ic|/etc/mkinitcpio.conf}}. Whether by label or by UUID, the swap partition is referred to with a udev device node, so the {{ic|resume}} hook must go ''after'' the {{ic|udev}} hook. This example was made starting from the default hook configuration:<br />
<br />
:{{bc|1=HOOKS=(base udev autodetect keyboard modconf block filesystems '''resume''' fsck)}}<br />
<br />
:Remember to [[regenerate the initramfs]] for these changes to take effect.<br />
<br />
:{{Note|[[LVM]] users should add the {{ic|resume}} hook after {{ic|lvm2}}.}}<br />
<br />
* When an initramfs with the {{ic|systemd}} hook is used, a resume mechanism is already provided, and no further hooks need to be added.<br />
<br />
== Troubleshooting ==<br />
<br />
=== ACPI_OS_NAME ===<br />
<br />
You might want to tweak your '''DSDT table''' to make it work. See [[DSDT]] article<br />
<br />
=== VAIO users ===<br />
<br />
{{Move|Laptop/Sony|Hardware specific problem.}}<br />
<br />
Add the [[kernel parameter]] {{ic|1=acpi_sleep=nonvs}} to your bootloader.<br />
<br />
=== Suspend/hibernate doesn't work, or not consistently ===<br />
<br />
There have been many reports about the screen going black without easily viewable errors or the ability to do anything when going into and coming back from suspend and/or hibernate. These problems have been seen on both laptops and desktops. This is not an official solution, but switching to an older kernel, especially the LTS-kernel, will probably fix this.<br />
<br />
Also problem may arise when using hardware watchdog timer (disabled by default, see {{ic|1=RuntimeWatchdogSec=}} in {{man|5|systemd-system.conf|OPTIONS}}). Bugged watchdog timer may reset the computer before the system finished creating the hibernation image.<br />
<br />
Sometimes the screen goes black due to device initialization from within the initramfs. Removing any modules you might have in [[Mkinitcpio#MODULES]] and rebuilding the initramfs, can possibly solve this issue, specially graphics drivers for [[Kernel_mode_setting#Early_KMS_start|early KMS]]. Initializing such devices before resuming can cause inconsistencies that prevents the system resuming from hibernation. This does not affect resuming from RAM. Also, check the blog article [https://01.org/blogs/rzhang/2015/best-practice-debug-linux-suspend/hibernate-issues best practices to debug suspend issues].<br />
<br />
For Intel graphics drivers, enabling early KMS may help to solve the blank screen issue. Refer to [[Kernel mode setting#Early KMS start]] for details.<br />
<br />
After upgrading to kernel 4.15.3, resume may fail with a static (non-blinking) cursor on a black screen. [[Blacklisting]] the module {{ic|nvidiafb}} might help. [https://bbs.archlinux.org/viewtopic.php?id=234646]<br />
<br />
=== Wake-on-LAN ===<br />
<br />
If [[Wake-on-LAN]] is active, the network interface card will consume power even if the computer is hibernated.<br />
<br />
=== Instantaneous wakeups from suspend ===<br />
<br />
For some Intel Haswell systems with the LynxPoint and LynxPoint-LP chipset, instantaneous wakeups after suspend are reported. They are linked to erroneous BIOS ACPI implementations and how the {{ic|xhci_hcd}} module interprets it during boot. As a work-around reported affected systems are added to a blacklist (named {{ic|XHCI_SPURIOUS_WAKEUP}}) by the kernel case-by-case.[https://bugzilla.kernel.org/show_bug.cgi?id=66171#c6] <br />
<br />
Instantaneous resume may happen, for example, if a USB device is plugged during suspend and ACPI wakeup triggers are enabled. A viable work-around for such a system, if it is not on the blacklist yet, is to disable the wakeup triggers. An example to disable wakeup through USB is described as follows.[https://bbs.archlinux.org/viewtopic.php?pid=1575617] <br />
<br />
To view the current configuration:<br />
<br />
{{hc|$ cat /proc/acpi/wakeup|<br />
Device S-state Status Sysfs node<br />
...<br />
EHC1 S3 *enabled pci:0000:00:1d.0<br />
EHC2 S3 *enabled pci:0000:00:1a.0<br />
XHC S3 *enabled pci:0000:00:14.0<br />
...<br />
}}<br />
<br />
The relevant devices are {{ic|EHC1}}, {{ic|EHC2}} and {{ic|XHC}} (for USB 3.0). To toggle their state you have to echo the device name to the file as root.<br />
<br />
# echo EHC1 > /proc/acpi/wakeup<br />
# echo EHC2 > /proc/acpi/wakeup<br />
# echo XHC > /proc/acpi/wakeup<br />
<br />
This should result in suspension working again. However, this settings are only temporary and would have to be set at every reboot. To automate this take a look at [[systemd#Writing unit files]]. See [https://bbs.archlinux.org/viewtopic.php?pid=1575617#p1575617 BBS thread] for a possible solution and more information.<br />
<br />
If you use {{ic|nouveau}} driver, the reason of instantaneous wakeup may be a bug in that driver, which sometimes prevents graphics card from suspension. One possible workaround is unloading {{ic|nouveau}} kernel module right before going to sleep and loading it back after wakeup. To do this, create the following script:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/10-nouveau.sh|2=<br />
#!/bin/bash<br />
<br />
case $1/$2 in<br />
pre/*)<br />
# echo "Going to $2..."<br />
/usr/bin/echo "0" > /sys/class/vtconsole/vtcon1/bind<br />
/usr/bin/rmmod nouveau<br />
;;<br />
post/*)<br />
# echo "Waking up from $2..."<br />
/usr/bin/modprobe nouveau<br />
/usr/bin/echo "1" > /sys/class/vtconsole/vtcon1/bind<br />
;;<br />
esac<br />
}}<br />
<br />
The first echo line unbinds nouveaufb from the framebuffer console driver (fbcon). Usually it is {{ic|vtcon1}} as in this example, but it may also be another {{ic|vtcon*}}. See {{ic|/sys/class/vtconsole/vtcon*/name}} which one of them is a "frame buffer device" [https://nouveau.freedesktop.org/wiki/KernelModeSetting/].<br />
<br />
=== System does not power off when hibernating ===<br />
<br />
When you hibernate your system, the system should power off (after saving the state on the disk). Sometimes, you might see the power LED is still glowing. If that happens, it might be instructive to set the {{ic|HibernateMode}} to {{ic|shutdown}} in {{man|5|sleep.conf.d}}:<br />
<br />
{{hc|/etc/systemd/sleep.conf.d/hibernatemode.conf|2=<br />
[Sleep]<br />
HibernateMode=shutdown<br />
}}<br />
<br />
With the above configuration, if every thing else is setup correctly, on invocation of a {{ic|systemctl hibernate}} the machine will shutdown saving state to disk as it does so.</div>Zethexhttps://wiki.archlinux.org/index.php?title=Power_management/Suspend_and_hibernate&diff=576558Power management/Suspend and hibernate2019-06-29T12:26:18Z<p>Zethex: Clearly showed and gave an alternative to using filefrag and systemctl hibernate, for those using swap files under Btrfs, to make it clear and easy for someone to use.</p>
<hr />
<div>[[Category:Power management]]<br />
[[es:Power management/Suspend and hibernate]]<br />
[[ja:サスペンドとハイバネート]]<br />
[[ru:Power management/Suspend and hibernate]]<br />
[[zh-hans:Power management/Suspend and hibernate]]<br />
{{Related articles start}}<br />
{{Related|Uswsusp}}<br />
{{Related|systemd}}<br />
{{Related|Power management}}<br />
{{Related articles end}}<br />
<br />
Currently there are three methods of suspending available: '''suspend to RAM''' (usually called just '''suspend'''), '''suspend to disk''' (usually known as '''hibernate'''), and '''hybrid suspend''' (sometimes aptly called '''suspend to both'''):<br />
<br />
* '''Suspend to RAM''' method cuts power to most parts of the machine aside from the RAM, which is required to restore the machine's state. Because of the large power savings, it is advisable for laptops to automatically enter this mode when the computer is running on batteries and the lid is closed (or the user is inactive for some time).<br />
<br />
* '''Suspend to disk''' method saves the machine's state into [[swap space]] and completely powers off the machine. When the machine is powered on, the state is restored. Until then, there is [[Wikipedia:Standby power|zero]] power consumption.<br />
<br />
* '''Suspend to both''' method saves the machine's state into swap space, but does not power off the machine. Instead, it invokes usual suspend to RAM. Therefore, if the battery is not depleted, the system can resume from RAM. If the battery is depleted, the system can be resumed from disk, which is much slower than resuming from RAM, but the machine's state has not been lost.<br />
<br />
There are multiple low level interfaces (backends) providing basic functionality, and some high level interfaces providing tweaks to handle problematic hardware drivers/kernel modules (e.g. video card re-initialization).<br />
<br />
== Low level interfaces ==<br />
<br />
Though these interfaces can be used directly, it is advisable to use some of [[#High level interfaces|high level interfaces]] to suspend/hibernate. Using low level interfaces directly is significantly faster than using any high level interface, since running all the pre- and post-suspend hooks takes time, but hooks can properly set hardware clock, restore wireless etc.<br />
<br />
=== kernel (swsusp) ===<br />
<br />
The most straightforward approach is to directly inform the in-kernel software suspend code (swsusp) to enter a suspended state; the exact method and state depends on the level of hardware support. On modern kernels, writing appropriate strings to {{ic|/sys/power/state}} is the primary mechanism to trigger this suspend.<br />
<br />
See [https://www.kernel.org/doc/Documentation/power/states.txt kernel documentation] for details.<br />
<br />
=== uswsusp ===<br />
<br />
The uswsusp ('Userspace Software Suspend') is a wrapper around the kernel's suspend-to-RAM mechanism, which performs some graphics adapter manipulations from userspace before suspending and after resuming.<br />
<br />
See main article [[Uswsusp]].<br />
<br />
== High level interfaces ==<br />
<br />
The end goal of these packages is to provide binaries/scripts that can be invoked to perform suspend/hibernate. Actually hooking them up to power buttons or menu clicks or laptop lid events is usually left to other tools. To automatically suspend/hibernate on certain power events, such as laptop lid close or battery depletion percentage, you may want to look into running [[Acpid]].<br />
<br />
=== systemd ===<br />
<br />
[[systemd]] provides native commands for suspend, hibernate and a hybrid suspend, see [[Power management#Power management with systemd]] for details. This is the default interface used in Arch Linux.<br />
<br />
See [[Power management#Sleep hooks]] for additional information on configuring suspend/hibernate hooks. Also see {{man|1|systemctl}}, {{man|8|systemd-sleep}}, and {{man|7|systemd.special}}.<br />
<br />
== Hibernation ==<br />
<br />
In order to use hibernation, you need to create a [[swap]] partition or file. You will need to point the kernel to your swap using the {{ic|1=resume=}} kernel parameter, which is configured via the boot loader. You will also need to [[#Configure the initramfs|configure the initramfs]]. This tells the kernel to attempt resuming from the specified swap in early userspace. These three steps are described in detail below.<br />
<br />
{{Note|See [[Dm-crypt/Swap encryption#With suspend-to-disk support]] when using [[encryption]].}}<br />
<br />
=== About swap partition/file size ===<br />
<br />
Even if your swap partition is smaller than RAM, you still have a big chance of hibernating successfully. According to [https://www.kernel.org/doc/Documentation/power/interface.txt kernel documentation]:<br />
<br />
: ''{{ic|/sys/power/image_size}} controls the size of the image created by the suspend-to-disk mechanism. It can be written a string representing a non-negative integer that will be used as an upper limit of the image size, in bytes. The suspend-to-disk mechanism will do its best to ensure the image size will not exceed that number. However, if this turns out to be impossible, it will try to suspend anyway using the smallest image possible. In particular, if "0" is written to this file, the suspend image will be as small as possible. Reading from this file will display the current image size limit, which is set to 2/5 of available RAM by default.''<br />
<br />
You may either decrease the value of {{ic|/sys/power/image_size}} to make the suspend image as small as possible (for small swap partitions), or increase it to possibly speed up the hibernation process.<br />
<br />
See [[Systemd#Temporary files]] to make this change persistent.<br />
<br />
=== Required kernel parameters ===<br />
<br />
The kernel parameter {{ic|1=resume=''swap_partition''}} has to be used. Either the name the kernel assigns to the partition or its [[UUID]] can be used as {{ic|''swap_partition''}}. For example:<br />
<br />
* {{ic|1=resume=/dev/sda1}}<br />
* {{ic|1=resume=UUID=4209c845-f495-4c43-8a03-5363dd433153}}<br />
* {{ic|1=resume=/dev/archVolumeGroup/archLogicVolume}} -- example if using LVM<br />
<br />
Generally, the naming method used for the {{ic|resume}} parameter should be the same as used for the {{ic|root}} parameter.<br />
<br />
The configuration depends on the used [[boot loader]], refer to [[Kernel parameters]] for details.<br />
<br />
==== Hibernation into swap file ====<br />
<br />
{{Warning|<br />
<br />
* [[Btrfs#Swap file|Btrfs]] on Linux kernel before version 5.0 does not support swap files. Failure to heed this warning may result in file system corruption. While a swap file may be used on Btrfs when mounted through a loop device, this will result in severely degraded swap performance.<br />
* {{pkg|systemd}} does not currently support hibernating into a swap file on Btrfs, even with Linux 5.0.See [https://github.com/systemd/systemd/issues/11939 systemd issue 11939].<br />
}}<br />
<br />
Using a swap file instead of a swap partition requires an additional kernel parameter {{ic|1=resume_offset=''swap_file_offset''}}. Note that the {{ic|1=resume}} keyword should still point to the partition where your swapfile resides as described above.<br />
<br />
The value of {{ic|''swap_file_offset''}} can be obtained by running {{ic|filefrag -v ''swap_file''}}, the output is in a table format and the required value is located in the first row of the {{ic|physical_offset}} column. For example:<br />
<br />
{{hc|# filefrag -v /swapfile|<nowiki><br />
Filesystem type is: ef53<br />
File size of /swapfile is 4294967296 (1048576 blocks of 4096 bytes)<br />
ext: logical_offset: physical_offset: length: expected: flags:<br />
0: 0.. 0: 38912.. 38912: 1: <br />
1: 1.. 22527: 38913.. 61439: 22527: unwritten<br />
2: 22528.. 53247: 899072.. 929791: 30720: 61440: unwritten<br />
...<br />
</nowiki>}}<br />
<br />
In the example the value of {{ic|''swap_file_offset''}} is the first {{ic|38912}} with the two periods.<br />
<br />
{{Tip|The following command may be used to identify {{ic|''swap_file_offset''}}: {{ic|1=filefrag -v /swapfile {{!}} awk '{ if($1=="0:"){print $4} }'}}.}}<br />
<br />
==== Hibernation into swap file on BTRFS ====<br />
<br />
On Btrfs, the "physical" offset you get from filefrag isn't the real physical offset on disk; there is a virtual disk address space in order to support multiple devices. Due to this the above method will not work for a swap file from a Btrfs file system.<br />
<br />
An alternate method is to use [https://raw.githubusercontent.com/osandov/osandov-linux/master/scripts/btrfs_map_physical.c this tool] instead of filefrag.<br />
<br />
Download or copy the text into a file named `btrfs_map_physical.c`.], then compile it:<br />
{{bc|gcc -O2 -o btrfs_map_physical btrfs_map_physical.c}}<br />
<br />
Run it. For example:<br />
{{hc|# ./btrfs_map_physical /.swapfile/swapfile |<br />
FILE OFFSET EXTENT TYPE LOGICAL SIZE LOGICAL OFFSET PHYSICAL SIZE DEVID PHYSICAL OFFSET<br />
0 regular 4096 2927632384 268435456 1 4009762816<br />
4096 prealloc 268431360 2927636480 268431360 1 4009766912<br />
268435456 prealloc 268435456 3251634176 268435456 1 4333764608<br />
536870912 prealloc 268435456 3520069632 268435456 1 4602200064<br />
805306368 prealloc 268435456 3788505088 268435456 1 4870635520<br />
1073741824 prealloc 268435456 4056940544 268435456 1 5139070976<br />
1342177280 prealloc 268435456 4325376000 268435456 1 5407506432<br />
1610612736 prealloc 268435456 4593811456 268435456 1 5675941888<br />
1879048192 prealloc 268435456 4862246912 268435456 1 5944377344<br />
2147483648 prealloc 268435456 5130682368 268435456 1 6212812800<br />
2415919104 prealloc 268435456 5399117824 268435456 1 6481248256<br />
2684354560 prealloc 268435456 5667553280 268435456 1 6749683712<br />
2952790016 prealloc 268435456 5935988736 268435456 1 7018119168<br />
3221225472 prealloc 268435456 6204424192 268435456 1 7286554624<br />
3489660928 prealloc 268435456 6472859648 268435456 1 7554990080<br />
3758096384 prealloc 268435456 6741295104 268435456 1 7823425536<br />
4026531840 prealloc 268435456 7009730560 268435456 1 8091860992<br />
4294967296 prealloc 268435456 7278166016 268435456 1 8360296448<br />
4563402752 prealloc 268435456 7546601472 268435456 1 8628731904<br />
4831838208 prealloc 268435456 7815036928 268435456 1 8897167360<br />
5100273664 prealloc 268435456 8083472384 268435456 1 9165602816<br />
5368709120 prealloc 268435456 8351907840 268435456 1 9434038272<br />
5637144576 prealloc 268435456 8620343296 268435456 1 9702473728<br />
5905580032 prealloc 268435456 8888778752 268435456 1 9970909184<br />
6174015488 prealloc 268435456 9157214208 268435456 1 10239344640<br />
6442450944 prealloc 268435456 9425649664 268435456 1 10507780096<br />
6710886400 prealloc 268435456 9694085120 268435456 1 10776215552<br />
6979321856 prealloc 268435456 9962520576 268435456 1 11044651008<br />
7247757312 prealloc 268435456 10230956032 268435456 1 11313086464<br />
7516192768 prealloc 268435456 10499391488 268435456 1 11581521920<br />
7784628224 prealloc 268435456 10767826944 268435456 1 11849957376<br />
8053063680 prealloc 268435456 11036262400 268435456 1 12118392832<br />
8321499136 prealloc 268435456 11304697856 268435456 1 12386828288<br />
|}}<br />
<br />
The first physical offset should be the one. In this example, we will use {{ic|`4009762816`}}.<br />
Divide that by 4096 and you have your resume_offset value. In this example, it is {{ic|`978946`}}.<br />
<br />
Systemd overrides those settings incorrectly. Instead of using {{ic|systemctl hibernate}} to hibernate, use {{ic|# echo disk > /sys/power/state}}. As a regular user you could use {{ic|<nowiki> $ echo disk | sudo tee /sys/power/state</nowiki>}} instead.<br />
<br />
{{Note|<br />
* Before the first hibernation, a reboot is required to activate the feature.<br />
* The value of {{ic|''swap_file_offset''}} can also be obtained by running {{ic|swap-offset ''swap_file''}}. The ''swap-offset'' binary is provided within the set of tools [[uswsusp]]. If using this method, then these two parameters have to be provided in {{ic|/etc/suspend.conf}} via the keys {{ic|resume device}} and {{ic|resume offset}}. No reboot is required in this case.<br />
<br />
}}<br />
<br />
{{Tip|You might want to decrease the [[Swap#Swappiness]] for your swapfile if the only purpose is to be able to hibernate and not expand RAM.}}<br />
<br />
=== Configure the initramfs ===<br />
<br />
* When an [[initramfs]] with the {{ic|base}} hook is used, which is the default, the {{ic|resume}} hook is required in {{ic|/etc/mkinitcpio.conf}}. Whether by label or by UUID, the swap partition is referred to with a udev device node, so the {{ic|resume}} hook must go ''after'' the {{ic|udev}} hook. This example was made starting from the default hook configuration:<br />
<br />
:{{bc|1=HOOKS=(base udev autodetect keyboard modconf block filesystems '''resume''' fsck)}}<br />
<br />
:Remember to [[regenerate the initramfs]] for these changes to take effect.<br />
<br />
:{{Note|[[LVM]] users should add the {{ic|resume}} hook after {{ic|lvm2}}.}}<br />
<br />
* When an initramfs with the {{ic|systemd}} hook is used, a resume mechanism is already provided, and no further hooks need to be added.<br />
<br />
== Troubleshooting ==<br />
<br />
=== ACPI_OS_NAME ===<br />
<br />
You might want to tweak your '''DSDT table''' to make it work. See [[DSDT]] article<br />
<br />
=== VAIO users ===<br />
<br />
{{Move|Laptop/Sony|Hardware specific problem.}}<br />
<br />
Add the [[kernel parameter]] {{ic|1=acpi_sleep=nonvs}} to your bootloader.<br />
<br />
=== Suspend/hibernate doesn't work, or not consistently ===<br />
<br />
There have been many reports about the screen going black without easily viewable errors or the ability to do anything when going into and coming back from suspend and/or hibernate. These problems have been seen on both laptops and desktops. This is not an official solution, but switching to an older kernel, especially the LTS-kernel, will probably fix this.<br />
<br />
Also problem may arise when using hardware watchdog timer (disabled by default, see {{ic|1=RuntimeWatchdogSec=}} in {{man|5|systemd-system.conf|OPTIONS}}). Bugged watchdog timer may reset the computer before the system finished creating the hibernation image.<br />
<br />
Sometimes the screen goes black due to device initialization from within the initramfs. Removing any modules you might have in [[Mkinitcpio#MODULES]] and rebuilding the initramfs, can possibly solve this issue, specially graphics drivers for [[Kernel_mode_setting#Early_KMS_start|early KMS]]. Initializing such devices before resuming can cause inconsistencies that prevents the system resuming from hibernation. This does not affect resuming from RAM. Also, check the blog article [https://01.org/blogs/rzhang/2015/best-practice-debug-linux-suspend/hibernate-issues best practices to debug suspend issues].<br />
<br />
For Intel graphics drivers, enabling early KMS may help to solve the blank screen issue. Refer to [[Kernel mode setting#Early KMS start]] for details.<br />
<br />
After upgrading to kernel 4.15.3, resume may fail with a static (non-blinking) cursor on a black screen. [[Blacklisting]] the module {{ic|nvidiafb}} might help. [https://bbs.archlinux.org/viewtopic.php?id=234646]<br />
<br />
=== Wake-on-LAN ===<br />
<br />
If [[Wake-on-LAN]] is active, the network interface card will consume power even if the computer is hibernated.<br />
<br />
=== Instantaneous wakeups from suspend ===<br />
<br />
For some Intel Haswell systems with the LynxPoint and LynxPoint-LP chipset, instantaneous wakeups after suspend are reported. They are linked to erroneous BIOS ACPI implementations and how the {{ic|xhci_hcd}} module interprets it during boot. As a work-around reported affected systems are added to a blacklist (named {{ic|XHCI_SPURIOUS_WAKEUP}}) by the kernel case-by-case.[https://bugzilla.kernel.org/show_bug.cgi?id=66171#c6] <br />
<br />
Instantaneous resume may happen, for example, if a USB device is plugged during suspend and ACPI wakeup triggers are enabled. A viable work-around for such a system, if it is not on the blacklist yet, is to disable the wakeup triggers. An example to disable wakeup through USB is described as follows.[https://bbs.archlinux.org/viewtopic.php?pid=1575617] <br />
<br />
To view the current configuration:<br />
<br />
{{hc|$ cat /proc/acpi/wakeup|<br />
Device S-state Status Sysfs node<br />
...<br />
EHC1 S3 *enabled pci:0000:00:1d.0<br />
EHC2 S3 *enabled pci:0000:00:1a.0<br />
XHC S3 *enabled pci:0000:00:14.0<br />
...<br />
}}<br />
<br />
The relevant devices are {{ic|EHC1}}, {{ic|EHC2}} and {{ic|XHC}} (for USB 3.0). To toggle their state you have to echo the device name to the file as root.<br />
<br />
# echo EHC1 > /proc/acpi/wakeup<br />
# echo EHC2 > /proc/acpi/wakeup<br />
# echo XHC > /proc/acpi/wakeup<br />
<br />
This should result in suspension working again. However, this settings are only temporary and would have to be set at every reboot. To automate this take a look at [[systemd#Writing unit files]]. See [https://bbs.archlinux.org/viewtopic.php?pid=1575617#p1575617 BBS thread] for a possible solution and more information.<br />
<br />
If you use {{ic|nouveau}} driver, the reason of instantaneous wakeup may be a bug in that driver, which sometimes prevents graphics card from suspension. One possible workaround is unloading {{ic|nouveau}} kernel module right before going to sleep and loading it back after wakeup. To do this, create the following script:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/10-nouveau.sh|2=<br />
#!/bin/bash<br />
<br />
case $1/$2 in<br />
pre/*)<br />
# echo "Going to $2..."<br />
/usr/bin/echo "0" > /sys/class/vtconsole/vtcon1/bind<br />
/usr/bin/rmmod nouveau<br />
;;<br />
post/*)<br />
# echo "Waking up from $2..."<br />
/usr/bin/modprobe nouveau<br />
/usr/bin/echo "1" > /sys/class/vtconsole/vtcon1/bind<br />
;;<br />
esac<br />
}}<br />
<br />
The first echo line unbinds nouveaufb from the framebuffer console driver (fbcon). Usually it is {{ic|vtcon1}} as in this example, but it may also be another {{ic|vtcon*}}. See {{ic|/sys/class/vtconsole/vtcon*/name}} which one of them is a "frame buffer device" [https://nouveau.freedesktop.org/wiki/KernelModeSetting/].<br />
<br />
=== System does not power off when hibernating ===<br />
<br />
When you hibernate your system, the system should power off (after saving the state on the disk). Sometimes, you might see the power LED is still glowing. If that happens, it might be instructive to set the {{ic|HibernateMode}} to {{ic|shutdown}} in {{man|5|sleep.conf.d}}:<br />
<br />
{{hc|/etc/systemd/sleep.conf.d/hibernatemode.conf|2=<br />
[Sleep]<br />
HibernateMode=shutdown<br />
}}<br />
<br />
With the above configuration, if every thing else is setup correctly, on invocation of a {{ic|systemctl hibernate}} the machine will shutdown saving state to disk as it does so.</div>Zethexhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=572982Dm-crypt/Encrypting an entire system2019-05-12T05:54:22Z<p>Zethex: /* Linux kernel v5.0 and above allow swap file support. */</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[Category:Installation process]]<br />
[[de:Systemverschlüsselung mit dm-crypt]]<br />
[[es:Dm-crypt/Encrypting an entire system]]<br />
[[ja:Dm-crypt/システム全体の暗号化]]<br />
[[pl:Dm-crypt/Encrypting an entire system]]<br />
<br />
The following are examples of common scenarios of full system encryption with ''dm-crypt''. They explain all the adaptations that need to be done to the normal [[Installation guide|installation procedure]]. All the necessary tools are on the [https://www.archlinux.org/download/ installation image].<br />
<br />
== Overview ==<br />
<br />
Securing a root filesystem is where ''dm-crypt'' excels, feature and performance-wise. Unlike selectively encrypting non-root filesystems, an encrypted root filesystem can conceal information such as which programs are installed, the usernames of all user accounts, and common data-leakage vectors such as [[mlocate]] and {{ic|/var/log/}}. Furthermore, an encrypted root filesystem makes tampering with the system far more difficult, as everything except the [[boot loader]] and (usually) the kernel is encrypted.<br />
<br />
All scenarios illustrated in the following share these advantages, other pros and cons differentiating them are summarized below:<br />
<br />
{| class="wikitable"<br />
! Scenarios<br />
! Advantages<br />
! Disadvantages<br />
|----------------------------------------------------------<br />
| [[#LUKS on a partition]]<br />
shows a basic and straight-forward set-up for a fully LUKS encrypted root.<br />
|<br />
* Simple partitioning and setup<br />
|<br />
* Inflexible; disk-space to be encrypted has to be pre-allocated<br />
|----------------------------------------------------------<br />
| [[#LVM on LUKS]]<br />
achieves partitioning flexibility by using LVM inside a single LUKS encrypted partition.<br />
|<br />
* Simple partitioning with knowledge of LVM<br />
* Only one key required to unlock all volumes (e.g. easy resume-from-disk setup)<br />
* Volume layout not transparent when locked<br />
* Easiest method to allow [[dm-crypt/Swap encryption#With suspend-to-disk support|suspension to disk]]<br />
|<br />
* LVM adds an additional mapping layer and hook<br />
* Less useful, if a singular volume should receive a separate key<br />
|----------------------------------------------------------<br />
| [[#LUKS on LVM]]<br />
uses dm-crypt only after the LVM is setup.<br />
|<br />
* LVM can be used to have encrypted volumes span multiple disks<br />
* Easy mix of un-/encrypted volume groups<br />
|<br />
* Complex; changing volumes requires changing encryption mappers too<br />
* Volumes require individual keys<br />
* LVM layout is transparent when locked<br />
|----------------------------------------------------------<br />
| [[#LUKS on software RAID]]<br />
uses dm-crypt only after RAID is setup.<br />
|<br />
* Analogous to LUKS on LVM<br />
|<br />
* Analogous to LUKS on LVM<br />
|----------------------------------------------------------<br />
| [[#Plain dm-crypt]]<br />
uses dm-crypt plain mode, i.e. without a LUKS header and its options for multiple keys. <br>This scenario also employs USB devices for {{ic|/boot}} and key storage, which may be applied to the other scenarios.<br />
|<br />
* Data resilience for cases where a LUKS header may be damaged<br />
* Allows [[Wikipedia:Disk encryption#Full disk encryption|Full Disk Encryption]]<br />
* Helps addressing [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)|problems]] with SSDs<br />
|<br />
* High care to all encryption parameters is required<br />
* Single encryption key and no option to change it<br />
|----------------------------------------------------------<br />
| [[#Encrypted boot partition (GRUB)]]<br />
shows how to encrypt the boot partition using the GRUB bootloader. <br> This scenario also employs an EFI system partition, which may be applied to the other scenarios.<br />
|<br />
* Same advantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* Less data is left unencrypted, i.e. the boot loader and the EFI system partition, if present<br />
|<br />
* Same disadvantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* More complicated configuration<br />
* Not supported by other boot loaders<br />
|----------------------------------------------------------<br />
| [[#Btrfs subvolumes with swap]]<br />
shows how to encrypt a [[Btrfs]] system, including the {{ic|/boot}} directory, also adding a partition for swap, on UEFI hardware.<br />
|<br />
* Similar advantages as [[#Encrypted boot partition (GRUB)]]<br />
* Availability of Btrfs' features<br />
|<br />
* Similar disadvantages as [[#Encrypted boot partition (GRUB)]]<br />
|}<br />
<br />
While all above scenarios provide much greater protection from outside threats than encrypted secondary filesystems, they also share a common disadvantage: any user in possession of the encryption key is able to decrypt the entire drive, and therefore can access other users' data. If that is of concern, it is possible to use a combination of blockdevice and stacked filesystem encryption and reap the advantages of both. See [[Disk encryption]] to plan ahead.<br />
<br />
See [[dm-crypt/Drive preparation#Partitioning]] for a general overview of the partitioning strategies used in the scenarios.<br />
<br />
Another area to consider is whether to set up an encrypted swap partition and what kind. See [[dm-crypt/Swap encryption]] for alternatives.<br />
<br />
If you anticipate to protect the system's data not only against physical theft, but also have a requirement of precautions against logical tampering, see [[dm-crypt/Specialties#Securing the unencrypted boot partition]] for further possibilities after following one of the scenarios.<br />
<br />
For [[solid state drive]]s you might want to consider enabling TRIM support, but be warned, there are potential security implications. See [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]] for more information.<br />
<br />
{{Warning|<br />
* In any scenario, never use file system repair software such as [[fsck]] directly on an encrypted volume, or it will destroy any means to recover the key used to decrypt your files. Such tools must be used on the decrypted (opened) device instead.<br />
* For the LUKS2 format:<br />
** [[GRUB]] does not support LUKS2.[https://savannah.gnu.org/bugs/?55093] Use LUKS1 on partitions that GRUB needs to access.<br />
** The LUKS2 format has a high RAM usage per design, defaulting to 1GB per encrypted mapper. Machines with low RAM and/or multiple LUKS2 partitions unlocked in parallel may error on boot. See the {{ic|--pbkdf-memory}} option to control memory usage.[https://gitlab.com/cryptsetup/cryptsetup/issues/372]<br />
}}<br />
<br />
== LUKS on a partition ==<br />
<br />
This example covers a full system encryption with ''dm-crypt'' + LUKS in a simple partition layout:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------+------------------------+-----------------------+<br />
| Boot partition | LUKS2 encrypted system | Optional free space |<br />
| | partition | for additional |<br />
| | | partitions or swap |<br />
| /boot | / | to be setup later |<br />
| | | |<br />
| | /dev/mapper/cryptroot | |<br />
| |------------------------| |<br />
| /dev/sda1 | /dev/sda2 | |<br />
+-----------------------+------------------------+-----------------------+<br />
</nowiki>}}<br />
<br />
The first steps can be performed directly after booting the Arch Linux install image.<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
Then create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}) and {{ic|/boot}} ({{ic|/dev/sda1}}). See [[Partitioning]].<br />
<br />
=== Preparing non-boot partitions ===<br />
<br />
The following commands create and mount the encrypted root partition. They correspond to the procedure described in detail in [[dm-crypt/Encrypting a non-root file system#Partition]] (which, despite the title, ''can'' be applied to root partitions, as long as [[#Configuring mkinitcpio|mkinitcpio]] and the [[#Configuring the boot loader|boot loader]] are correctly configured).<br />
If you want to use particular non-default encryption options (e.g. cipher, key length), see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|encryption options]] before executing the first command:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sda2<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
Check the mapping works as intended:<br />
<br />
# umount /mnt<br />
# cryptsetup close cryptroot<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
If you created separate partitions (e.g. {{ic|/home}}), these steps have to be adapted and repeated for all of them, ''except'' for {{ic|/boot}}. See [[dm-crypt/Encrypting a non-root file system#Automated unlocking and mounting]] on how to handle additional partitions at boot.<br />
<br />
Note that each blockdevice requires its own passphrase. This may be inconvenient, because it results in a separate passphrase to be input during boot. An alternative is to use a keyfile stored in the system partition to unlock the separate partition via {{ic|crypttab}}. See [[dm-crypt/Device encryption#Using LUKS to format partitions with a keyfile]] for instructions.<br />
<br />
=== Preparing the boot partition ===<br />
<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a encrypted root. For a standard [[EFI|MBR/non-EFI]] {{ic|/boot}} partition, for example, execute:<br />
<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Mounting the devices ===<br />
<br />
At [[Installation guide#Mount the file systems]] you will have to mount the mapped devices, not the actual partitions. Of course {{ic|/boot}}, which is not encrypted, will still have to be mounted directly.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|keymap}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]. If the default US keymap is fine for you, you can omit the {{ic|keymap}} hook.<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' filesystems fsck)<br />
<br />
Depending on which other hooks are used, the order may be relevant. See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameters need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptroot root=/dev/mapper/cryptroot<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptroot root=/dev/mapper/cryptroot<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda2}}. See [[Persistent block device naming]] for details.<br />
<br />
== LVM on LUKS ==<br />
<br />
The straight-forward method is to set up [[LVM]] on top of the encrypted partition instead of the other way round. Technically the LVM is setup inside one big encrypted blockdevice. Hence, the LVM is not transparent until the blockdevice is unlocked and the underlying volume structure is scanned and mounted during boot.<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------------------------------------------------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot partition |<br />
| | | | | |<br />
| [SWAP] | / | /home | | /boot |<br />
| | | | | |<br />
| /dev/MyVolGroup/swap | /dev/MyVolGroup/root | /dev/MyVolGroup/home | | |<br />
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _| | (may be on |<br />
| | | other device) |<br />
| LUKS2 encrypted partition | | |<br />
| /dev/sda1 | | /dev/sdb1 |<br />
+-----------------------------------------------------------------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Note|While using the {{ic|encrypt}} hook this method does not allow you to span the logical volumes over multiple disks; either use the [[sd-encrypt]] or see [[dm-crypt/Specialties#Modifying the encrypt hook for multiple partitions]].}}<br />
<br />
{{Tip|Three variants of this setup:<br />
* Instructions at [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] use this setup with a detached LUKS header on a USB device to achieve a two factor authentication with it.<br />
* Instructions at [https://www.pavelkogan.com/2014/05/23/luks-full-disk-encryption/ Pavel Kogan's blog] show how to encrypt the {{ic|/boot}} partition while keeping it on the main LUKS partition when using GRUB.<br />
* Instructions at [[dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB]] use this setup with a detached LUKS header, encrypted {{ic|/boot}} partition, and encrypted keyfile all on a USB device.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
{{Tip|When using the [[GRUB]] boot loader for BIOS booting from a [[GPT]] disk, create a [[BIOS boot partition]].}}<br />
<br />
Create a partition to be mounted at {{ic|/boot}} with a size of 200 MiB or more.<br />
<br />
{{Tip|UEFI systems can use the [[EFI system partition]] for {{ic|/boot}}.}}<br />
<br />
Create a partition which will later contain the encrypted container.<br />
<br />
Create the LUKS encrypted container at the "system" partition. Enter the chosen password twice.<br />
<br />
# cryptsetup luksFormat /dev/sda1<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda1 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
Create a physical volume on top of the opened LUKS container:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
<br />
Create the volume group named {{ic|MyVolGroup}} (or whatever you want), adding the previously created physical volume to it:<br />
<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
<br />
Create all your logical volumes on the volume group:<br />
<br />
# lvcreate -L 8G MyVolGroup -n swap<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
Format your filesystems on each logical volume:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mkswap /dev/MyVolGroup/swap<br />
<br />
Mount your filesystems:<br />
<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The bootloader loads the kernel, [[initramfs]], and its own configuration files from the {{ic|/boot}} directory. Any filesystem on a disk that can be read by the bootloader is eligible.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
<br />
{{Tip|When opting to keep {{ic|/boot}} on an [[EFI system partition]] the recommended formatting is<br />
<br />
# mkfs.fat -F32 /dev/sdb1<br />
<br />
}}<br />
<br />
Create the directory {{ic|/mnt/boot}}:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Mount the partition to {{ic|/mnt/boot}}:<br />
<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameter needs to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptlvm root=/dev/MyVolGroup/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptlvm root=/dev/MyVolGroup/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda1}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
== LUKS on LVM ==<br />
<br />
To use encryption on top of [[LVM]], the LVM volumes are set up first and then used as the base for the encrypted partitions. This way, a mixture of encrypted and non-encrypted volumes/partitions is possible as well.<br />
{{tip|Unlike [[#LVM on LUKS]], this method allows normally spanning the logical volumes over multiple disks. }}<br />
<br />
The following short example creates a LUKS on LVM setup and mixes in the use of a key-file for the /home partition and temporary crypt volumes for {{ic|/tmp}} and {{ic|/swap}}. The latter is considered desirable from a security perspective, because no potentially sensitive temporary data survives the reboot, when the encryption is re-initialised. If you are experienced with LVM, you will be able to ignore/replace LVM and other specifics according to your plan.<br />
<br />
If you want to span a logical volume over multiple disks that have already been set up, or expand the logical volume for {{ic|/home}} (or any other volume), a procedure to do so is described in [[dm-crypt/Specialties#Expanding LVM on multiple disks]]. It is important to note that the LUKS encrypted container has to be resized as well.<br />
<br />
{{Expansion|The intro of this scenario needs some adjustment now that a comparison has been added to [[#Overview]]. A suggested structure is to make it similar to the [[#LUKS on a partition]] intro.}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Partitioning scheme:<br />
<br />
{{Text art|<nowiki><br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
| Boot partition | dm-crypt plain encrypted volume | LUKS2 encrypted volume | LUKS2 encrypted volume |<br />
| | | | |<br />
| /boot | [SWAP] | / | /home |<br />
| | | | |<br />
| | /dev/mapper/swap | /dev/mapper/root | /dev/mapper/home |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | /dev/MyVolGroup/cryptswap | /dev/MyVolGroup/cryptroot | /dev/MyVolGroup/crypthome |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | |<br />
| /dev/sda1 | /dev/sda2 |<br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
Randomise {{ic|/dev/sda2}} according to [[dm-crypt/Drive preparation#dm-crypt wipe on an empty disk or partition]].<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
# pvcreate /dev/sda2<br />
# vgcreate MyVolGroup /dev/sda2<br />
# lvcreate -L 32G -n cryptroot MyVolGroup<br />
# lvcreate -L 500M -n cryptswap MyVolGroup<br />
# lvcreate -L 500M -n crypttmp MyVolGroup<br />
# lvcreate -l 100%FREE -n crypthome MyVolGroup<br />
<br />
# cryptsetup luksFormat /dev/MyVolGroup/cryptroot<br />
# cryptsetup open /dev/MyVolGroup/cryptroot root<br />
# mkfs.ext4 /dev/mapper/root<br />
# mount /dev/mapper/root /mnt<br />
<br />
More information about the encryption options can be found in [[dm-crypt/Device encryption#Encryption options for LUKS mode]].<br />
Note that {{ic|/home}} will be encrypted in [[#Encrypting logical volume /home]].<br />
<br />
{{Tip|If you ever have to access the encrypted root from the Arch-ISO, the above {{ic|open}} action will allow you to after the [[LVM#Logical Volumes do not show up|LVM shows up]].}}<br />
<br />
=== Preparing the boot partition ===<br />
<br />
# dd if=/dev/zero of=/dev/sda1 bs=1M status=progress<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|lvm2}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''lvm2''' '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameters need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':root root=/dev/mapper/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=root root=/dev/mapper/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/MyVolGroup/cryptroot}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
=== Configuring fstab and crypttab ===<br />
<br />
Both [[crypttab]] and [[fstab]] entries are required to both unlock the device and mount the filesystems, respectively. The following lines will re-encrypt the temporary filesystems on each reboot:<br />
<br />
{{hc|/etc/crypttab|2=<br />
swap /dev/MyVolGroup/cryptswap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
tmp /dev/MyVolGroup/crypttmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/root / ext4 defaults 0 1<br />
/dev/sda1 /boot ext4 defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
}}<br />
<br />
=== Encrypting logical volume /home ===<br />
<br />
Since this scenario uses LVM as the primary and dm-crypt as secondary mapper, each encrypted logical volume requires its own encryption. Yet, unlike the temporary filesystems configured with volatile encryption above, the logical volume for {{ic|/home}} should of course be persistent. The following assumes you have rebooted into the installed system, otherwise you have to adjust paths.<br />
To save on entering a second passphrase at boot, a [[dm-crypt/Device encryption#Keyfiles|keyfile]] is created:<br />
<br />
# mkdir -m 700 /etc/luks-keys<br />
# dd if=/dev/random of=/etc/luks-keys/home bs=1 count=256 status=progress<br />
<br />
The logical volume is encrypted with it:<br />
<br />
# cryptsetup luksFormat -v /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
# cryptsetup -d /etc/luks-keys/home open /dev/MyVolGroup/crypthome home<br />
# mkfs.ext4 /dev/mapper/home<br />
# mount /dev/mapper/home /home<br />
<br />
The encrypted mount is configured in both [[crypttab]] and [[fstab]]:<br />
<br />
{{hc|/etc/crypttab|<br />
home /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home /home ext4 defaults 0 2<br />
}}<br />
<br />
== LUKS on software RAID ==<br />
<br />
This example is based on a real-world setup for a workstation class laptop equipped with two SSDs of equal size, and an additional HDD for bulk storage. The end result is LUKS1 based full disk encryption (including {{ic|/boot}}) for all drives, with the SSDs in a [[RAID|RAID0]] array, and keyfiles used to unlock all encryption after [[GRUB]] is given a correct passphrase at boot.<br />
<br />
This setup utilizes a very simplistic partitioning scheme, with all the available RAID storage being mounted at {{ic|/}} (no separate {{ic|/boot}} partition), and the decrypted HDD being mounted at {{ic|/data}}.<br />
<br />
Please note that regular [[System backup|backups]] are very important in this setup. If either of the SSDs fail, the data contained in the RAID array will be practically impossible to recover. You may wish to select a different [[RAID#Standard RAID levels|RAID level]] if fault tolerance is important to you. <br />
<br />
The encryption is not deniable in this setup.<br />
<br />
For the sake of the instructions below, the following block devices are used:<br />
<br />
/dev/sda = first SSD<br />
/dev/sdb = second SSD<br />
/dev/sdc = HDD<br />
<br />
{{Text art|<nowiki><br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
| BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | LUKS2 encrypted volume |<br />
| | | | | | | | | |<br />
| | /efi | / | | | /efi | / | | /data |<br />
| | | | | | | | | |<br />
| | | /dev/mapper/cryptroot | | | | /dev/mapper/cryptroot | | |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ | |<br />
| | RAID1 array (part 1 of 2) | RAID0 array (part 1 of 2) | | | RAID1 array (part 2 of 2) | RAID0 array (part 2 of 2) | | |<br />
| | | | | | | | | |<br />
| | /dev/md/ESP | /dev/md/root | | | /dev/md/ESP | /dev/md/root | | /dev/mapper/cryptroot |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ +---------------------------+<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 | | /dev/sdb1 | /dev/sdb2 | /dev/sdb3 | | /dev/sdc1 |<br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
</nowiki>}}<br />
<br />
Be sure to substitute them with the appropriate device designations for your setup, as they may be different.<br />
<br />
=== Preparing the disks ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] with GPT, create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
In the remaining space on the drive create a partition ({{ic|/dev/sda3}} in this example) for "Linux RAID". Choose partition type ID {{ic|fd}} for MBR or partition type GUID {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} for GPT.<br />
<br />
Once partitions have been created on {{ic|/dev/sda}}, the following commands can be used to clone them to {{ic|/dev/sdb}}.<br />
<br />
# sfdisk -d /dev/sda > sda.dump<br />
# sfdisk /dev/sdb < sda.dump<br />
<br />
The HDD is prepared with a single Linux partition covering the whole drive at {{ic|/dev/sdc1}}.<br />
<br />
=== Building the RAID array ===<br />
<br />
Create the RAID array for the SSDs.<br />
<br />
{{Note|<br />
* All parts of an EFI system partition RAID array must be individually usable, that means that ESP can only placed in a RAID1 array.<br />
* The RAID superblock must be placed at the end of the EFI system partition using {{ic|1=--metadata=1.0}}, otherwise the firmware will not be able to access the partition.<br />
}}<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.0 --raid-devices=2 /dev/md/ESP /dev/sda2 /dev/sdb2<br />
<br />
This example utilizes RAID0 for root, you may wish to substitute a different level based on your preferences or requirements.<br />
<br />
# mdadm --create --verbose --level=0 --metadata=1.2 --raid-devices=2 /dev/md/root /dev/sda3 /dev/sdb3<br />
<br />
=== Preparing the block devices ===<br />
<br />
As explained in [[dm-crypt/Drive preparation]], the devices are wiped with random data utilizing {{ic|/dev/zero}} and a crypt device with a random key. Alternatively, you could use {{ic|dd}} with {{ic|/dev/random}} or {{ic|/dev/urandom}}, though it will be much slower.<br />
<br />
# cryptsetup open --type plain /dev/md/root container --key-file /dev/random<br />
# dd if=/dev/zero of=/dev/mapper/container bs=1M status=progress<br />
# cryptsetup close container<br />
<br />
And repeat above for the HDD ({{ic|/dev/sdc1}} in this example).<br />
<br />
Set up encryption for {{ic|/dev/md/root}}:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup -y -v luksFormat --type luks1 /dev/md/root<br />
# cryptsetup open /dev/md/root cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
And repeat for the HDD:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sdc1<br />
# cryptsetup open /dev/sdc1 cryptdata<br />
# mkfs.ext4 /dev/mapper/cryptdata<br />
# mkdir /mnt/data<br />
# mount /dev/mapper/cryptdata /mnt/data<br />
<br />
For UEFI systems, set up the EFI system partition:<br />
<br />
# mkfs.fat -F32 /dev/md/ESP<br />
# mount /dev/md/ESP /mnt/efi<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure [[GRUB]] for the LUKS1 encrypted system by editing {{ic|/etc/default/grub}} with the following:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/md/root:cryptroot"<br />
GRUB_ENABLE_CRYPTODISK=y<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details.<br />
<br />
Complete the GRUB install to both SSDs (in reality, installing only to {{ic|/dev/sda}} will work).<br />
<br />
# grub-install --target=i386-pc /dev/sda<br />
# grub-install --target=i386-pc /dev/sdb<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Creating the keyfiles ===<br />
<br />
The next steps save you from entering your passphrase twice when you boot the system (once so GRUB can unlock the LUKS1 device, and second time once the initramfs assumes control of the system). This is done by creating a [[dm-crypt/Device encryption#Keyfiles|keyfile]] for the encryption and adding it to the initramfs image to allow the encrypt hook to unlock the root device. See [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] for details.<br />
<br />
* Create the [[dm-crypt/Device encryption#Keyfiles|keyfile]] and add the key to {{ic|/dev/md/root}}.<br />
* Create another keyfile for the HDD ({{ic|/dev/sdc1}}) so it can also be unlocked at boot. For convenience, leave the passphrase created above in place as this can make recovery easier if you ever need it. Edit {{ic|/etc/crypttab}} to decrypt the HDD at boot. See [[dm-crypt/Device encryption#Unlocking a secondary partition at boot]].<br />
<br />
=== Configuring the system ===<br />
<br />
Edit [[fstab]] to mount the cryptroot and cryptdata block devices and the ESP:<br />
<br />
/dev/mapper/cryptroot / ext4 rw,noatime 0 1<br />
/dev/mapper/cryptdata /data ext4 defaults 0 2<br />
/dev/md/ESP /efi vfat rw,relatime,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,tz=UTC,errors=remount-ro 0 2<br />
<br />
Save the RAID configuration:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
Edit [[mkinitcpio.conf]] to include your keyfile and add the proper hooks:<br />
<br />
FILES=(/crypto_keyfile.bin)<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''mdadm_udev''' '''encrypt''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details.<br />
<br />
== Plain dm-crypt ==<br />
<br />
Contrary to LUKS, dm-crypt ''plain'' mode does not require a header on the encrypted device: this scenario exploits this feature to set up a system on an unpartitioned, encrypted disk that will be indistinguishable from a disk filled with random data, which could allow [[Wikipedia:Deniable encryption|deniable encryption]]. See also [[wikipedia:Disk encryption#Full disk encryption]].<br />
<br />
Note that if full-disk encryption is not required, the methods using LUKS described in the sections above are better options for both system encryption and encrypted partitions. LUKS features like key management with multiple passphrases/key-files or re-encrypting a device in-place are unavailable with ''plain'' mode.<br />
<br />
''Plain'' dm-crypt encryption can be more resilient to damage than LUKS, because it does not rely on an encryption master-key which can be a single-point of failure if damaged. However, using ''plain'' mode also requires more manual configuration of encryption options to achieve the same cryptographic strength. See also [[Disk encryption#Cryptographic metadata]]. Using ''plain'' mode could also be considered if concerned with the problems explained in [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]].<br />
<br />
{{Tip|If headerless encryption is your goal but you are unsure about the lack of key-derivation with ''plain'' mode, then two alternatives are:<br />
* [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|dm-crypt LUKS mode with a detached header]] by using the ''cryptsetup'' {{ic|--header}} option. It cannot be used with the standard ''encrypt'' hook, but the hook may be modified.<br />
* [[tcplay]] which offers headerless encryption but with the PBKDF2 function.<br />
}}<br />
<br />
The scenario uses two USB sticks:<br />
<br />
* one for the boot device, which also allows storing the options required to open/unlock the plain encrypted device in the boot loader configuration, since typing them on each boot would be error prone;<br />
* another for the encryption key file, assuming it stored as raw bits so that to the eyes of an unaware attacker who might get the usbkey the encryption key will appear as random data instead of being visible as a normal file. See also [[Wikipedia:Security through obscurity]], follow [[dm-crypt/Device encryption#Keyfiles]] to prepare the keyfile.<br />
<br />
The disk layout is:<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+ +----------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot device | | Encryption key |<br />
| | | | | | | file storage |<br />
| / | [SWAP] | /home | | /boot | | (unpartitioned |<br />
| | | | | | | in example) |<br />
| /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home | | /dev/sdb1 | | /dev/sdc |<br />
|----------------------+----------------------+----------------------| |----------------| |----------------|<br />
| disk drive /dev/sda encrypted using plain mode and LVM | | USB stick 1 | | USB stick 2 |<br />
+--------------------------------------------------------------------+ +----------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* It is also possible to use a single USB key physical device:<br />
** By putting the key on another partition (/dev/sdb2) of the USB storage device (/dev/sdb).<br />
** By copying the keyfile to the initramfs directly. An example keyfile {{ic|/etc/keyfile}} gets copied to the initramfs image by setting {{ic|1=FILES=(/etc/keyfile)}} in {{ic|/etc/mkinitcpio.conf}}. The way to instruct the {{ic|encrypt}} hook to read the keyfile in the initramfs image is using {{ic|rootfs:}} prefix before the filename, e.g. {{ic|1=cryptkey=rootfs:/etc/keyfile}}.<br />
* Another option is using a passphrase with good [[Disk encryption#Choosing a strong passphrase|entropy]].<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
It is vital that the mapped device is filled with random data. In particular this applies to the scenario use case we apply here.<br />
<br />
See [[dm-crypt/Drive preparation]] and [[dm-crypt/Drive preparation#dm-crypt specific methods]]<br />
<br />
=== Preparing the non-boot partitions ===<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for plain mode]] for details.<br />
<br />
Using the device {{ic|/dev/sda}}, with the aes-xts cipher with a 512 bit key size and using a keyfile we have the following options for this scenario:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sdc --key-size=512 open --type plain /dev/sda cryptlvm<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, and key file details.<br />
<br />
We can now check a mapping entry has been made for {{ic|/dev/mapper/cryptlvm}}:<br />
<br />
# fdisk -l<br />
<br />
{{Tip|A simpler alternative to using LVM, advocated in the cryptsetup FAQ for cases where LVM is not necessary, is to just create a filesystem on the entirety of the mapped dm-crypt device.}} <br />
<br />
Next, we setup [[LVM]] logical volumes on the mapped device. See [[LVM#Installing Arch Linux on LVM]] for further details:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -L 10G MyVolGroup -n swap<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
We format and mount them and activate swap. See [[File systems#Create a file system]] for further details:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# mkswap /dev/MyVolGroup/swap<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The {{ic|/boot}} partition can be installed on the standard vfat partition of a USB stick, if required. But if manual partitioning is needed, then a small 200 MiB partition is all that is required. Create the partition using a [[Partitioning#Partitioning tools|partitioning tool]] of your choice.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}, if it is not already formatted as vfat:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
# mkdir /mnt/boot<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to boot the encrypted root partition, the following kernel parameters need to be set by the boot loader (note that 64 is the number of bytes in 512 bits):<br />
<br />
cryptdevice=/dev/disk/by-id/''disk-ID-of-sda'':cryptlvm cryptkey=/dev/disk/by-id/''disk-ID-of-sdc'':0:64 crypto=:aes-xts-plain64:512:0:<br />
<br />
The {{ic|''disk-ID-of-'''disk'''''}} refers to the id of the referenced disk. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details and other parameters that you may need.<br />
<br />
{{Tip|If using GRUB, you can install it on the same USB as the {{ic|/boot}} partition with:<br />
<br />
# grub-install --recheck /dev/sdb<br />
<br />
}}<br />
<br />
=== Post-installation ===<br />
<br />
You may wish to remove the USB sticks after booting. Since the {{ic|/boot}} partition is not usually needed, the {{ic|noauto}} option can be added to the relevant line in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
# /dev/sdb1<br />
/dev/sdb1 /boot ext4 '''noauto''',rw,noatime 0 2<br />
}}<br />
<br />
However, when an update to anything used in the initramfs, or a kernel, or the bootloader is required; the {{ic|/boot}} partition must be present and mounted. As the entry in {{ic|fstab}} already exists, it can be mounted simply with:<br />
<br />
# mount /boot<br />
<br />
== Encrypted boot partition (GRUB) ==<br />
<br />
This setup utilizes the same partition layout and configuration for the system's root partition as the previous [[#LVM on LUKS]] section, with the difference that a special feature of the [[GRUB]] bootloader is used to additionally encrypt the boot partition {{ic|/boot}}. See also [[GRUB#Encrypted /boot]].<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+---------------------+----------------------+----------------------+----------------------+----------------------+<br />
| BIOS boot partition | EFI system partition | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | | | | |<br />
| | /efi | / | [SWAP] | /home |<br />
| | | | | |<br />
| | | /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home |<br />
| /dev/sda1 | /dev/sda2 |----------------------+----------------------+----------------------+<br />
| unencrypted | unencrypted | /dev/sda3 encrypted using LVM on LUKS1 |<br />
+---------------------+----------------------+--------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* All scenarios are intended as examples. It is, of course, possible to apply both of the two above distinct installation steps with the other scenarios as well. See also the variants linked in [[#LVM on LUKS]].<br />
* You can use {{ic|cryptboot}} script from {{AUR|cryptboot}} package for simplified encrypted boot management (mounting, unmounting, upgrading packages) and as a defense against [https://www.schneier.com/blog/archives/2009/10/evil_maid_attac.html Evil Maid] attacks with [[Secure Boot#Using your own keys|UEFI Secure Boot]]. For more information and limitations see [https://github.com/xmikos/cryptboot cryptboot project] page.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
Create a partition of type {{ic|8309}}, which will later contain the encrypted container for the LVM.<br />
<br />
Create the LUKS encrypted container:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup luksFormat --type luks1 /dev/sda3<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Your partition layout should look similar to this:<br />
<br />
{{hc|# gdisk -l /dev/sda|<br />
...<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 4095 1024.0 KiB EF02 BIOS boot partition<br />
2 4096 1130495 550.0 MiB EF00 EFI System<br />
3 1130496 68239360 32.0 GiB 8309 Linux LUKS<br />
}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda3 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
The LVM logical volumes of this example follow the exact layout as the [[#LVM on LUKS]] scenario. Therefore, please follow [[#Preparing the logical volumes]] above and adjust as required.<br />
<br />
If you plan to boot in UEFI mode, create a mountpoint for the [[EFI system partition]] at {{ic|/efi}} for compatibility with {{ic|grub-install}} and mount it:<br />
<br />
# mkdir /mnt/efi<br />
# mount /dev/sda2 /mnt/efi<br />
<br />
At this point, you should have the following partitions and logical volumes inside of {{ic|/mnt}}:<br />
<br />
{{hc|$ lsblk|<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 200G 0 disk<br />
├─sda1 8:1 0 1M 0 part<br />
├─sda2 8:2 0 550M 0 part /efi<br />
└─sda3 8:3 0 100G 0 part<br />
└─cryptlvm 254:0 0 100G 0 crypt<br />
├─MyVolGroup-swap 254:1 0 8G 0 lvm [SWAP]<br />
├─MyVolGroup-root 254:2 0 32G 0 lvm /<br />
└─MyVolGroup-home 254:3 0 60G 0 lvm /home<br />
}}<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure GRUB to allow booting from {{ic|/boot}} on a LUKS1 encrypted partition:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_ENABLE_CRYPTODISK=y<br />
}}<br />
<br />
Set the kernel parameters, so that the initramfs can unlock the encrypted root partition. Using the {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... cryptdevice=UUID=''device-UUID'':cryptlvm ..."<br />
}}<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... rd.luks.name=''device-UUID''=cryptlvm" ...<br />
}}<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details. The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda3}} (the partition which holds the lvm containing the root filesystem). See [[Persistent block device naming]].<br />
<br />
[[GRUB#Installation_2|install GRUB]] to the mounted ESP for UEFI booting:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB --recheck<br />
<br />
[[GRUB#Installation|install GRUB]] to the disk for BIOS booting:<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
<br />
Generate GRUB's [[GRUB#Generate the main configuration file|configuration]] file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If all commands finished without errors, GRUB should prompt for the passphrase to unlock the {{ic|/dev/sda3}} partition after the next reboot.<br />
<br />
=== Avoiding having to enter the passphrase twice ===<br />
<br />
While GRUB asks for a passphrase to unlock the LUKS1 encrypted partition after above instructions, the partition unlock is not passed on to the initramfs. Hence, you have to enter the passphrase twice at boot: once for GRUB and once for the initramfs.<br />
<br />
This section deals with extra configuration to let the system boot by only entering the passphrase once, in GRUB. This is accomplished by [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs|with a keyfile embedded in the initramfs]].<br />
<br />
First create a keyfile and add it as LUKS key:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/root/cryptlvm.keyfile iflag=fullblock<br />
# chmod 000 /root/cryptlvm.keyfile<br />
# cryptsetup -v luksAddKey /dev/sda3 /root/cryptlvm.keyfile<br />
<br />
Add the keyfile to the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/root/cryptlvm.keyfile)<br />
}}<br />
<br />
Set the following kernel parameters to unlock the LUKS partition with the keyfile. Using the {{ic|encrypt}} hook:<br />
<br />
GRUB_CMDLINE_LINUX="... cryptkey=rootfs:/root/cryptlvm.keyfile"<br />
<br />
Or, using the [[sd-encrypt]] hook:<br />
<br />
GRUB_CMDLINE_LINUX="... rd.luks.key=''device-UUID''=/root/cryptlvm.keyfile"<br />
<br />
If for some reason the keyfile fails to unlock the boot partition, systemd will fallback to ask for a passphrase to unlock and, in case that is correct, continue booting.<br />
<br />
{{Tip|If you want to encrypt the {{ic|/boot}} partition to protect against offline tampering threats, the [[dm-crypt/Specialties#mkinitcpio-chkcryptoboot|mkinitcpio-chkcryptoboot]] hook has been contributed to help.}}<br />
<br />
== Btrfs subvolumes with swap ==<br />
<br />
The following example creates a full system encryption with LUKS1 using [[Btrfs]] subvolumes to [[Btrfs#Mounting subvolumes|simulate partitions]].<br />
<br />
If using UEFI, an [[EFI system partition]] (ESP) is required. {{ic|/boot}} itself may reside on {{ic|/}} and be encrypted; however, the ESP itself cannot be encrypted. In this example layout, the ESP is {{ic|/dev/sda1}} and is mounted at {{ic|/efi}}. {{ic|/boot}} itself is located on the system partition, {{ic|/dev/sda2}}.<br />
<br />
Since {{ic|/boot}} resides on the LUKS1 encrypted {{ic|/}}, [[GRUB]] must be used as the bootloader because only GRUB can load modules necessary to decrypt {{ic|/boot}} (e.g., crypto.mod, cryptodisk.mod and luks.mod) [http://www.pavelkogan.com/2014/05/23/luks-full-disk-encryption/].<br />
<br />
Additionally an optional plain-encrypted [[swap]] partition is shown.<br />
<br />
{{Warning|Do not use a [[swap file]] instead of a separate partition on Linux kernels before v5.0, because this may result in data loss. See [[Btrfs#Swap file]].}}<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+<br />
| EFI system partition | System partition | Swap partition |<br />
| unencrypted | LUKS1-encrypted | plain-encrypted |<br />
| | | |<br />
| /efi | / | [SWAP] |<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 |<br />
|----------------------+----------------------+----------------------+<br />
</nowiki>}}<br />
<br />
=== Preparing the disk ===<br />
<br />
{{Note|It is not possible to use btrfs partitioning as described in [[Btrfs#Partitionless Btrfs disk]] when using LUKS. Traditional partitioning must be used, even if it is just to create one partition.}}<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]]. If you are using [[UEFI]] create an [[EFI system partition]] with an appropriate size. It will later be mounted at {{ic|/efi}}. If you are going to create an encrypted swap partition, create the partition for it, but do '''not''' mark it as swap, since plain ''dm-crypt'' will be used with the partition.<br />
<br />
Create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}). See the [[Partitioning]] article.<br />
<br />
=== Preparing the system partition ===<br />
<br />
==== Create LUKS container ====<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
Follow [[dm-crypt/Device encryption#Encrypting devices with LUKS mode]] to setup {{ic|/dev/sda2}} for LUKS. See the [[dm-crypt/Device encryption#Encryption options for LUKS mode]] before doing so for a list of encryption options.<br />
<br />
==== Unlock LUKS container ====<br />
<br />
Now follow [[dm-crypt/Device encryption#Unlocking/Mapping LUKS partitions with the device mapper]] to unlock the LUKS container and map it.<br />
<br />
==== Format mapped device ====<br />
<br />
Proceed to format the mapped device as described in [[Btrfs#File system on a single device]], where {{ic|''/dev/partition''}} is the name of the mapped device (i.e., {{ic|cryptroot}}) and '''not''' {{ic|/dev/sda2}}.<br />
<br />
==== Mount mapped device ====<br />
<br />
Finally, [[mount]] the now-formatted mapped device (i.e., {{ic|/dev/mapper/cryptroot}}) to {{ic|/mnt}}.<br />
<br />
{{Tip|You may want to use the {{ic|1=compress=lzo}} mount option. See [[Btrfs#Compression]] for more information.}}<br />
<br />
=== Creating btrfs subvolumes ===<br />
<br />
{{Merge|Btrfs|The subvolume layout is not specific to an encrypted system.}}<br />
<br />
==== Layout ====<br />
<br />
[[Btrfs#Subvolumes|Subvolumes]] will be used to simulate partitions, but other (nested) subvolumes will also be created. Here is a partial representation of what the following example will generate:<br />
<br />
{{Text art|<nowiki><br />
subvolid=5 (/dev/sda2)<br />
|<br />
├── @ (mounted as /)<br />
| |<br />
| ├── /bin (directory)<br />
| |<br />
| ├── /home (mounted @home subvolume)<br />
| |<br />
| ├── /usr (directory)<br />
| |<br />
| ├── /.snapshots (mounted @snapshots subvolume)<br />
| |<br />
| ├── /var/cache/pacman/pkg (nested subvolume)<br />
| |<br />
| ├── ... (other directories and nested subvolumes)<br />
|<br />
├── @snapshots (mounted as /.snapshots)<br />
|<br />
├── @home (mounted as /home)<br />
|<br />
└── @... (additional subvolumes you wish to use as mount points)<br />
</nowiki>}}<br />
<br />
This section follows the [[Snapper#Suggested filesystem layout]], which is most useful when used with [[Snapper]]. You should also consult [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs Wiki SysadminGuide#Layout].<br />
<br />
==== Create top-level subvolumes ====<br />
<br />
Here we are using the convention of prefixing {{ic|@}} to subvolume names that will be used as mount points, and {{ic|@}} will be the subvolume that is mounted as {{ic|/}}.<br />
<br />
Following the [[Btrfs#Creating a subvolume]] article, create subvolumes at {{ic|/mnt/@}}, {{ic|/mnt/@snapshots}}, and {{ic|/mnt/@home}}.<br />
<br />
Create any additional subvolumes you wish to use as mount points now.<br />
<br />
==== Mount top-level subvolumes ====<br />
<br />
Unmount the system partition at {{ic|/mnt}}.<br />
<br />
Now mount the newly created {{ic|@}} subvolume which will serve as {{ic|/}} to {{ic|/mnt}} using the {{ic|1=subvol=}} mount option. Assuming the mapped device is named {{ic|cryptroot}}, the command would look like:<br />
<br />
# mount -o compress=lzo,subvol=@ /dev/mapper/cryptroot /mnt<br />
<br />
See [[Btrfs#Mounting subvolumes]] for more details.<br />
<br />
Also mount the other subvolumes to their respective mount points: {{ic|@home}} to {{ic|/mnt/home}} and {{ic|@snapshots}} to {{ic|/mnt/.snapshots}}.<br />
<br />
==== Create nested subvolumes ====<br />
<br />
Create any subvolumes you do '''not''' want to have snapshots of when taking a snapshot of {{ic|/}}. For example, you probably do not want to take snapshots of {{ic|/var/cache/pacman/pkg}}. These subvolumes will be nested under the {{ic|@}} subvolume, but just as easily could have been created earlier at the same level as {{ic|@}} according to your preference.<br />
<br />
Since the {{ic|@}} subvolume is mounted at {{ic|/mnt}} you will need to [[create a subvolume]] at {{ic|/mnt/var/cache/pacman/pkg}} for this example. You may have to create any parent directories first.<br />
<br />
Other directories you may wish to do this with are {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.<br />
<br />
==== Mount ESP ====<br />
<br />
If you prepared an EFI system partition earlier, create its mount point and mount it now.<br />
<br />
{{Note|Btrfs snapshots will exclude {{ic|/efi}}, since it is not a btrfs file system.}}<br />
<br />
At the [[Installation guide#Install the base packages|pacstrap]] installation step, the {{Pkg|btrfs-progs}} must be installed in addition to the base group.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
==== Create keyfile ====<br />
<br />
In order for GRUB to open the LUKS partition without having the user enter his passphrase twice, we will use a keyfile embedded in the initramfs. Follow [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] making sure to add the key to {{ic|/dev/sda2}} at the ''luksAddKey'' step.<br />
<br />
==== Edit mkinitcpio.conf ====<br />
<br />
After creating, adding, and embedding the key as described above, add the {{ic|encrypt}} hook to [[mkinitcpio.conf]] as well as any other hooks you require. See [[dm-crypt/System configuration#mkinitcpio]] for detailed information.<br />
<br />
{{Tip|You may want to add {{ic|1=BINARIES=(/usr/bin/btrfs)}} to your {{ic|mkinitcpio.conf}}. See the [[Btrfs#Corruption recovery]] article.}}<br />
<br />
=== Configuring the boot loader ===<br />
<br />
Install [[GRUB]] to {{ic|/dev/sda}}. Then, edit {{ic|/etc/default/grub}} as instructed in the [[GRUB#Additional arguments]] and [[GRUB#Encrypted /boot]], following both the instructions for an encrypted root and boot partition. Finally, generate the GRUB configuration file.<br />
<br />
=== Configuring swap ===<br />
<br />
If you created a partition to be used for encrypted swap, now is the time to configure it. Follow the instructions at [[dm-crypt/Swap encryption]].</div>Zethex