https://wiki.archlinux.org/api.php?action=feedcontributions&user=Kwehmu&feedformat=atomArchWiki - User contributions [en]2024-03-28T21:36:56ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Btrfs&diff=654841Btrfs2021-03-14T02:14:20Z<p>Kwehmu: Mention the IOReadBandwidthMax option, which allows limiting the rate of scrubbing. This is useful if scrubbing without a rate limit gets the drive too hot.</p>
<hr />
<div>[[Category:File systems]]<br />
[[de:Arch_auf_BtrFS]]<br />
[[fr:Btrfs]]<br />
[[ja:Btrfs]]<br />
[[pt: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 />
== Preparation ==<br />
<br />
For user space utilities [[install]] the {{Pkg|btrfs-progs}} package, which 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 nodesize for metadata is 16KB, while the default sectorsize for data is equal to page size and autodetected. To use a larger nodesize for metadata (must be a multiple of sectorsize, up to 64KB is allowed), specify a value for the {{ic|nodesize}} via the {{ic|-n}} switch as shown in this example using 32KB blocks:<br />
<br />
# mkfs.btrfs -L ''mylabel'' -n 32k /dev/''partition''<br />
<br />
{{Note|According to {{man|8|mkfs.btrfs|OPTIONS}}, "[a] smaller node size increases fragmentation but leads to taller b-trees which in turn leads to lower locking contention. Higher node sizes give better packing and less fragmentation at the cost of more expensive memory operations while updating the metadata blocks".}}<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." [https://lore.kernel.org/linux-btrfs/20200627032414.GX10769@hungrycats.org/ List of known problems and partial workarounds.] See [https://btrfs.wiki.kernel.org/index.php/RAID56 the Btrfs page on RAID5 and RAID6] for status updates (seems to not be updated).}}<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. Starting from kernel 5.5 RAID1c3 and RAID1c4 for 3- and 4- copies of RAID 1 level. The RAID levels can be configured separately for data and metadata using the {{ic|-d}} and {{ic|-m}} options respectively. By default the data has one copy ({{ic|single}}) and the metadata is mirrored ({{ic|raid1}}). This is similar to <br />
creating a [[W:JBOD|JBOD configuration]], where disks are seen as one filesystem, but files are not duplicated. 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 single -m raid1 /dev/''part1'' /dev/''part2'' ...<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 />
* Btrfs does not automatically read from the fastest device, so mixing different kinds of disks results in inconsistent performance. See [https://stackoverflow.com/a/55408367 this Stack Overflow answer] for details.<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 />
<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 />
<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 [https://btrfs.wiki.kernel.org/index.php/Compression transparent and automatic compression]. This reduces the size of files as well as significantly increases the lifespan of flash-based media by reducing write amplification. [https://fedoraproject.org/wiki/Changes/BtrfsByDefault#Compression][https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/NTV77NFF6NDZM3QTPUM2TQZ5PCM6GOO2/][https://pagure.io/fedora-btrfs/project/issue/36#comment-701551] It can also [http://www.phoronix.com/scan.php?page=article&item=btrfs_compress_2635&num=1 improve performance], in some cases (e.g. single thread with heavy file I/O), while obviously harming performance in other cases (e.g. multi-threaded 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 />
The {{ic|1=compress=''alg''}} mount option enables automatically considering every file for compression, where {{ic|''alg''}} is either {{ic|zlib}}, {{ic|lzo}}, {{ic|zstd}}, or {{ic|no}} (for no compression). Using this option, btrfs will check if compressing the first portion of the data shrinks it. If it does, the entire write to that file will be compressed. If it does not, none of it is compressed. With this option, if the first portion of the write does not shrink, no compression will be applied to the write even if the rest of the data would shrink tremendously. [https://btrfs.wiki.kernel.org/index.php/Compression#What_happens_to_incompressible_files.3F] This is done to prevent making the disk wait to start writing until all of the data to be written is fully given to btrfs and compressed.<br />
<br />
The {{ic|1=compress-force=''alg''}} mount option can be used instead, which makes btrfs skip checking if compression shrinks the first portion, and enables automatic compression try for every file. In a worst-case scenario, this can cause (slightly) more CPU usage for no purpose. However, empirical testing on multiple mixed-use systems showed a significant improvement of about 10% disk compression from using {{ic|1=compress-force=''zstd''}} over just {{ic|1=compress=''zstd''}}, which also had 10% disk compression.<br />
<br />
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 />
* [[GRUB]] introduced ''zstd'' support in 2.04. Make sure you have actually upgraded the bootloader installed in your MBR/ESP since then, by running {{ic|grub-install}} with the appropriate options for your BIOS/UEFI setup, since that is not done automatically. See {{Bug|63235}}.<br />
}}<br />
<br />
==== View compression types and ratios ====<br />
<br />
{{pkg|compsize}} takes a list of files (or an entire btrfs filesystem) and measures compression types used and effective compression ratios. Uncompressed size may not match the number given by other programs such as {{ic|du}}, because every extent is counted once, even if it is reflinked several times, and even if part of it is no longer used anywhere but has not been garbage collected. The {{ic|-x}} option keeps it on a single filesystem, which is useful in situations like {{ic|compsize -x /}} to avoid it from attempting to look in non-btrfs subdirectories and fail the entire run.<br />
<br />
=== Subvolumes ===<br />
{{Merge|User:I2Oc9/Btrfs_subvolumes|A more straightforward introduction}}<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 />
<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 and their ids 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 />
Since Linux 4.18, one can also delete a subvolume like a regular directory ({{ic|<nowiki>rm -r</nowiki>}}, {{ic|<nowiki>rmdir</nowiki>}}).<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 />
==== Mounting subvolume as root ====<br />
<br />
To use a subvolume as the root mountpoint specify the subvolume via a [[Kernel parameters#Configuration|kernel parameter]] using {{ic|1=rootflags=subvol=''/path/to/subvolume''}}. Edit the root mountpoint in {{ic|/etc/fstab}} and specify the mount option {{ic|1=subvol=}}. Alternatively the subvolume can be specified with its id, {{ic|1=rootflags=subvolid=''objectid''}} as kernel parameter and {{ic|1=subvolid=''objectid''}} as mount option in {{ic|/etc/fstab}}.<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|1=subvol=/}} or {{ic|1=subvolid=5}} 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 />
<br />
A Btrfs filesystem is able to free unused blocks from an SSD drive supporting the TRIM command. Starting with kernel version 5.6 there is asynchronous discard support, enabled with mount option {{ic|1=discard=async}}. Freed extents are not discarded immediately, but grouped together and trimmed later by a separate worker thread, improving commit latency.<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 swap file is to first create a non-compressed, non-snapshotted subvolume to host the file, ''cd'' into its directory, then create a zero length file, set the {{ic|No_COW}} attribute on it with [[chattr]], and make sure compression is disabled:<br />
<br />
# cd ''/path/to/swapfile''<br />
# truncate -s 0 ./swapfile<br />
# chattr +C ./swapfile<br />
# btrfs property set ./swapfile compression none<br />
<br />
See [[Swap file#Swap file creation]] for further configuration. Configuring hibernation to a swap file is described in [[Power management/Suspend and hibernate#Hibernation into swap file on Btrfs]].<br />
<br />
{{Note|1=Since Linux kernel 5.0, Btrfs 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=1849371#p1849371 Arch forums discussion].<br />
}}<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|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. In June 2020, somebody posted a [https://lore.kernel.org/linux-btrfs/20200627030614.GW10769@hungrycats.org/ comprehensive list of current issues] and a [https://lore.kernel.org/linux-btrfs/20200627032414.GX10769@hungrycats.org/ helpful recovery guide]. }}<br />
<br />
=== Scrub ===<br />
<br />
{{Expansion|[https://unix.stackexchange.com/questions/556816/does-btrfs-scrub-examine-subvolume-or-the-device-that-subvolume-resides-on Does Btrfs scrub examine subvolume or the device that subvolume resides on?]}}<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 />
{{Note|A running scrub process will prevent the system from suspending, see [https://web.archive.org/web/20160723034801/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}} (as the root user) is that the results of the scrub will be logged in the [[systemd journal]].<br />
<br />
On large NVMe drives with insufficient cooling (e.g. in a laptop), scrubbing can read the drive fast enough and long enough to get it very hot. If you're running scrubs with systemd, you can easily limit the rate of scrubbing with the {{ic|IOReadBandwidthMax}} option described in {{man|5|systemd.resource-control}} by using a [[Systemd#Drop-in_files|drop-in file]].<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 {{Pkg|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}}, {{aur|jdupes}} or {{aur|dduper-git}}. 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 />
=== btrfs check issues ===<br />
The tool {{ic|btrfs check}} has known issues and should not be run without further reading, see section [[#btrfs check]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Partitionless Btrfs disk ===<br />
<br />
{{Warning|<br />
* 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. <br />
* Since {{Pkg|grub}} 2.04, GRUB's {{ic|core.img}} is too big to fit in Btrfs VBR. See {{Bug|63656}}.<br />
}}<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 place other [[file systems]] on another partition on the same disk.<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]]<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 [[regenerate the initramfs]].<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 />
{{Warning|There is a bug in btrfs-progs 5.6.1 and before, that will yield a btrfs filesystem with wrong size for the last block group, thus preventing to mount the newly converted btrfs. This bug is fixed in btrfs-progs 5.7 in [https://github.com/kdave/btrfs-progs/commit/0ff7a9b5210723bd4ad0d9d78dbbb18ee8fdd2b1#diff-31168275dcaac634489082b54c4c66d0 this commit]. Please use btrfs-convert from btrfs-progs 5.7-1 and above.}}<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 />
{{Note| If there is anything wrong, either unable to mount or write files to the newly converted btrfs, there is always the option to rollback as long as the backup subvolume {{ic|/ext2_saved}} is still there. Use {{ic|btrfs-convert -r /dev/''partition''}} command to rollback, this will discard any modifications to the newly converted btrfs filesystem.}}<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.<br />
<br />
=== Checksum hardware acceleration ===<br />
<br />
{{Accuracy|1=According to [https://bugzilla.redhat.com/show_bug.cgi?id=1874808#c4], the CRC algorithm printed by the following command simply matches "''whatever crypto library is currently loaded at the time''", and "''can change arbitrarily while the file system is loaded''". So this method should not be relied upon in order to determine which CRC algorithm Btrfs is currently using.}}<br />
<br />
CRC32 is a new instruction in Intel SSE4.2. To verify if Btrfs checksum is hardware accelerated:<br />
<br />
{{hc|$ dmesg {{!}} grep crc32c|2=<br />
Btrfs loaded, crc32c=crc32c-intel<br />
}}<br />
<br />
If you see {{ic|1=crc32c=crc32c-generic}}, 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 />
{{Warning|The tool {{ic|btrfs check}} has known issues, see section [[#btrfs check]]}}<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, the same procedure applies as for mounting a subvolume as your root parition, as given in section [[#Mounting subvolume as root|mounting a subvolume as your root partition]], because snapshots can be mounted like subvolumes.<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 />
* If using [[rEFInd]] you can automatically populate your boot menu with btrfs snapshots with the help of {{AUR|refind-btrfs}}, after [[enabling]] {{ic|refind-btrfs.service}}.<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 [[Special:Diff/319474|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 />
=== Mounting timed out ===<br />
<br />
Sometimes, especially with large RAID1 arrays, mounting might time out during boot with a journal message such as:<br />
<br />
{{bc|1=<br />
Jan 25 18:05:12 host systemd[1]: storage.mount: Mounting timed out. Terminating.<br />
Jan 25 18:05:46 host systemd[1]: storage.mount: Mount process exited, code=killed, status=15/TERM<br />
Jan 25 18:05:46 host systemd[1]: storage.mount: Failed with result 'timeout'.<br />
Jan 25 18:05:46 host systemd[1]: Failed to mount /storage.<br />
Jan 25 18:05:46 host systemd[1]: Startup finished in 32.943s (firmware) + 3.097s (loader) + 7.247s (kernel)><br />
Jan 25 18:05:46 host kernel: BTRFS error (device sda): open_ctree failed<br />
}}<br />
<br />
This can easily be worked around by providing a longer timeout via the systemd-specific mount option {{ic|x-systemd.mount-timeout}} in [[fstab]]. For example:<br />
<br />
/dev/sda /storage btrfs rw,relatime,x-systemd.mount-timeout=5min 0 0<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]] 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://web.archive.org/web/20161108175034/http://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 />
<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 [https://btrfs.wiki.kernel.org/index.php/Btrfsck Btrfsck 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 also ==<br />
<br />
* '''Official site'''<br />
** [https://btrfs.wiki.kernel.org/ Btrfs Wiki]<br />
* '''Performance related'''<br />
** [https://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 />
** [https://web.archive.org/web/20150717135111/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 />
** [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=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>Kwehmuhttps://wiki.archlinux.org/index.php?title=I3wm&diff=290507I3wm2013-12-26T22:28:12Z<p>Kwehmu: Redirect 'i3wm' to 'i3'</p>
<hr />
<div>#REDIRECT [[i3]]</div>Kwehmuhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=279468GnuPG2013-10-23T16:04:26Z<p>Kwehmu: /* Keysigning-Partys */ Improve spelling, wording, grammar</p>
<hr />
<div>[[Category:Security]]<br />
GnuPG can be used to sign and encrypt files or mails.<br />
<br />
== Installation ==<br />
<br />
[[pacman|Install]] {{Pkg|gnupg}}, available in the [[official repositories]].<br />
<br />
== Basic keys management ==<br />
<br />
=== Create key ===<br />
<br />
* Generate a private key by typing in a terminal: <br />
# gpg --gen-key<br />
<br />
You’ll have to answer a bunch of questions but generally, you can accept the defaults.<br />
<br />
While having an expiration date for subkeys isn't technically necessary, it is considered good practice. A period of a year is generally good enough for the average user. This way even if you lose access to your keyring, it will allow others to know that it is no longer valid.<br />
<br />
* Set expiration date (repeat for both/all subkeys)<br />
# gpg --edit-key 'Your Name'<br />
# key [number]<br />
# expire<br />
# save<br />
<br />
* Generate an ASCII version of your public key (e.g. to distribute it by e-mail):<br />
# gpg --armor --output public.key --export 'Your Name'<br />
<br />
* Register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly.:<br />
# gpg --keyserver hkp://subkeys.pgp.net --send-keys ''Key Id''<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you will have to create new ones. Do this a few weeks in advanced to allow others to update their keyring.<br />
<br />
* Create new subkey (repeat for both signing and encrypting key)<br />
# gpg --edit-key 'Your Name'<br />
# addkey<br />
<br />
And answer the following questions it asks.<br />
<br />
* Save changes<br />
# save<br />
<br />
* Update it to a keyserver.<br />
# gpg --keyserver hkp://subkeys.pgp.net --send-keys ''Key Id''<br />
<br />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Import key ===<br />
<br />
* Import a public key to your public key ring:<br />
# gpg --import public.key<br />
<br />
* Import a private key to your secret key ring:<br />
# gpg --import private.key<br />
<br />
=== List keys ===<br />
<br />
* Keys in your public key ring:<br />
# gpg --list-keys<br />
<br />
* Keys in your secret key ring:<br />
# gpg --list-secret-keys<br />
<br />
== Basic usage ==<br />
<br />
You can use gnupg to encrypt your sensitive documents, but only individual files at a time.<br />
<br />
For example, to decrypt a file data, use:<br />
# gpg -d secret.tar.gpg<br />
<br />
You'll be prompted to enter your passphrase.<br />
<br />
If you want to encrypt directories or a whole file-system you should consider use [[truecrypt|Truecrypt]], though you can always tarball various files and then encrypt them.<br />
<br />
=== Symmetric Encryption ===<br />
<br />
== gpg-agent ==<br />
<br />
{{Ic|gpg-agent}} is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. It can be activated by adding following line in {{ic|~/.gnupg/gpg.conf}}:<br />
use-agent<br />
<br />
This tells GnuPG to use the agent whenever it needs the password. However, the agent needs to run already. To autostart it, create the following file and make it executable:<br />
{{hc|/etc/profile.d/gpg-agent.sh|2=<nowiki><br />
#!/bin/sh<br />
<br />
envfile="${HOME}/.gnupg/gpg-agent.env"<br />
if test -f "$envfile" && kill -0 $(grep GPG_AGENT_INFO "$envfile" | cut -d: -f 2) 2>/dev/null; then<br />
eval "$(cat "$envfile")"<br />
else<br />
eval "$(gpg-agent --daemon --write-env-file "$envfile")"<br />
fi<br />
export GPG_AGENT_INFO # the env file does not contain the export statement<br />
</nowiki>}}<br />
<br />
Add an entry in your {{Ic|.xinitrc}}<br />
eval $(gpg-agent --daemon) &<br />
<br />
Log out your Xsession and login. Check {{Ic|gpg-agent}} is actived<br />
# ps aux | grep agent<br />
<br />
If you would like to use {{Ic|gpg-agent}} to manage your SSH keys see [[SSH Keys#GnuPG Agent]].<br />
<br />
==== Pinentry ====<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in {{ic|~/.gnupg/gpg-agent.conf}}<br />
<br />
The default uses a gtk dialog. To change it to ncurses or qt, set the following in the above file<br />
<br />
pinentry-program /usr/bin/pinentry-curses<br />
<br />
or<br />
<br />
pinentry-program /usr/bin/pinentry-qt4<br />
<br />
For more options see {{Ic|man gpg-agent}} and {{ic|info pinentry}}.<br />
<br />
== Keysigning-Partys ==<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses a so-called "Web of Trust". To build this Web of Trust, many hackerevents include keysigning parties.<br />
<br />
The Zimmermann–Sassaman key-signing protocol is a way of making these very effective. See the [https://en.wikipedia.org/wiki/Zimmermann%E2%80%93Sassaman_key-signing_protocol Wikipedia article] for an description. [http://cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you'll find an How-To-article.<br />
<br />
=== Caff ===<br />
For an easier process of signing keys an sending the signatures to the owner, after a keysigning-party, you can use the tool 'caff'. It cam be installed from the AUR ether with the package {{AUR|caff-svn}} or better together with some other useful tools as the package {{AUR|signing-party-svn}}.<br />
In both ways there will be a lot of dependencies to install from the AUR, alternately you can install them with<br />
cpanm Any:Moose<br />
cpanm GnuPG::Interface <br />
<br />
To send the signatures to its owner you need an working [https://en.wikipedia.org/wiki/Message_transfer_agent MTA], if you don't have already one install [[SSMTP]].<br />
<br />
== Smartcards ==<br />
GnuPG uses scdaemon as an interface to your smartcard reader, please refer to {{Ic|scdaemon}} man page for details.<br />
<br />
=== GnuPG only setups===<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG together with OpenSC ===<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together.<br />
In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/gnupg/scdaemon.conf}}, specify the location to libpcsclite.so library and disable ccid so we make sure that we use pcscd.<br />
<br />
{{hc|~/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so <br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permisions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with {{Ic|su}} (or {{Ic|sudo}}), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg<br />
chown root /dev/ttyN # where N is the current tty<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}. <br />
<br />
{{Note|being part of the group {{Ic|tty}} '''does not''' seem to alleviate the issue, at least as root. (Please confirm with non-superusers)}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General Troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively you can use the qt pinentry.<br />
<br />
# ln -sf /usr/bin/pinentry-qt4 /usr/bin/pinentry<br />
<br />
== See also ==<br />
<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]</div>Kwehmuhttps://wiki.archlinux.org/index.php?title=Acpid&diff=277906Acpid2013-10-06T23:13:46Z<p>Kwehmu: Remove outdated warning about poweroff; this was fixed on 2012-10-14 in response to FS#31937 - see https://projects.archlinux.org/svntogit/community.git/commit/?h=packages/acpid&id=a47dc77fd0c00e476ae64a6aa3fde0cb9abc0a1f</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Power management]]<br />
[[es:Acpid]]<br />
[[it:Acpid]]<br />
[[zh-CN:Acpid]]<br />
{{Article summary start}}<br />
{{Article summary text|Describes acpid daemon.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|ACPI modules}}<br />
{{Article summary wiki|DSDT}}<br />
{{Article summary end}}<br />
[http://acpid.sourceforge.net/ acpid] is a flexible and extensible daemon for delivering [[ACPI modules|ACPI events]]. It listens on {{ic|/proc/acpi/event}} and when an event occurs, executes programs to handle the event. These events are triggered by certain actions, such as:<br />
* Pressing special keys, including the Power/Sleep/Suspend button<br />
* Closing a notebook lid<br />
* (Un)Plugging an AC power adapter from a notebook<br />
* (Un)Plugging phone jack etc.<br />
<br />
{{Note | [[Desktop Environment|desktop environments]], such as [[GNOME]], [[Systemd#ACPI power management|systemd]] login manager and some [[Extra Keyboard Keys|extra key handling]] daemons may implement own event handling schemes, independent of acpid. Running more than one system at the same time may lead to unexpected behaviour, such as suspending two times in a row after one sleep button press. You should be aware of this and only activate desirable handlers.}}<br />
<br />
== Installation ==<br />
<br />
[[pacman|Install]] the {{Pkg|acpid}} package, available in the [[Official Repositories|official repositories]].<br />
<br />
To have ''acpid'' started on boot, [[systemd#Using units|enable]] {{ic|acpid.service}}.<br />
<br />
== Configuration ==<br />
<br />
{{Pkg|acpid}} comes with a number of predefined actions for triggered events, such as what should happen when you press the Power button on your machine. By default, these actions are defined in {{ic|/etc/acpi/handler.sh}}, which is executed after any ACPI events are detected (as determined by {{ic|/etc/acpi/events/anything}}).<br />
<br />
The following is a brief example of one such action. In this case, when the Sleep button is pressed, acpid runs the command {{ic|echo -n mem >/sys/power/state}} which ''should'' place the computer into a sleep (suspend) state:<br />
<br />
button/sleep)<br />
case "$2" in<br />
SLPB) echo -n mem >/sys/power/state ;;<br />
*) logger "ACPI action undefined: $2" ;;<br />
esac<br />
;;<br />
<br />
Unfortunately, not every computer labels ACPI events in the same way. For example, the Sleep button may be identified on one machine as ''SLPB'' and on another as ''SBTN''. <br />
<br />
To determine how your buttons or {{ic|Fn}} shortcuts are recognized, run the following command from a terminal as root:<br />
# tail -f /var/log/messages.log<br />
<br />
Now press the Power button and/or Sleep button (e.g. {{ic|Fn+Esc}}) on your machine. The result should look something this:<br />
logger: ACPI action undefined: PBTN<br />
logger: ACPI action undefined: SBTN<br />
<br />
If that does not work, run:<br />
# acpi_listen<br />
<br />
Then press the power button and you will see something like this:<br />
power/button PBTN 00000000 00000b31<br />
<br />
The output of {{ic|acpi_listen}} is sent to {{ic|/etc/acpi/handler.sh}} as $1, $2 , $3 & $4 parameters.<br />
Example:<br />
$1 power/button<br />
$2 PBTN<br />
$3 00000000<br />
$4 00000b31<br />
<br />
As you might have noticed, the Sleep button in the sample output is actually recognized as ''SBTN'', rather than the ''SLPB'' label specified in the default {{ic|/etc/acpi/handler.sh}}. In order for Sleep function to work properly on this machine, we would need to replace ''SLPB)'' with ''SBTN)''.<br />
<br />
Using this information as a base, you can easily customize the {{ic|/etc/acpi/handler.sh}} file to execute a variety of commands depending on which event is triggered. See the [[Acpid#Tips & Tricks | Tips & Tricks]] section below for other commonly used commands.<br />
<br />
=== Alternative configuration ===<br />
<br />
By default, all ACPI events are passed through the {{ic|/etc/acpi/handler.sh}} script. This is due to the ruleset outlined in {{ic|/etc/acpi/events/anything}}:<br />
# Pass all events to our one handler script<br />
event=.*<br />
action=/etc/acpi/handler.sh %e<br />
<br />
While this works just fine as it is, some users may prefer to define event rules and actions in their own self-contained scripts. The following is an example of how to use an individual event file and corresponding action script:<br />
<br />
As root, create the following file:<br />
{{hc|/etc/acpi/events/sleep-button|<nowiki><br />
event=button sleep.*<br />
action=/etc/acpi/actions/sleep-button.sh "%e"<br />
</nowiki>}}<br />
<br />
Now create the following file:<br />
{{hc|/etc/acpi/actions/sleep-button.sh|<nowiki><br />
#!/bin/sh<br />
case "$2" in<br />
SLPB) echo -n mem >/sys/power/state ;;<br />
*) logger "ACPI action undefined: $2" ;;<br />
esac<br />
</nowiki>}}<br />
<br />
Finally, make the script executable: <br />
# chmod +x /etc/acpi/actions/sleep-button.sh<br />
<br />
Using this method, it is easy to create any number of individual event/action scripts.<br />
<br />
==Tips and tricks==<br />
{{Tip|Some of actions, described here, such as Wi-Fi toggle and backlight control, may already be managed directly by driver. You should consult documentation of corresponding kernel modules, when this is the case.}}<br />
<br />
===Example Events===<br />
<br />
The following are examples of events that can be used in the {{ic|/etc/acpi/handler.sh}} script. These examples should be modified so that they apply your specific environment e.g. changing the event variable names interpreted by {{ic|acpi_listen}}.<br />
<br />
To lock the screen with {{ic|xscreensaver}} when closing the laptop lid:<br />
<br />
button/lid)<br />
case $3 in<br />
close)<br />
# The lock command need to be run as the user who owns the xscreensaver process and not as root.<br />
# See: man xscreensaver-command. $xs will have the value of the user owning the process, if any.<br />
<br />
xs=$(ps -C xscreensaver -o user=)<br />
if test $xs; then su $xs -c "xscreensaver-command -lock"; fi<br />
;;<br />
<br />
To suspend the system and lock the screen using {{ic|slimlock}} when the lid is closed:<br />
<br />
button/lid)<br />
case $3 in<br />
close)<br />
#echo "LID switched!">/dev/tty5<br />
/usr/bin/pm-suspend &<br />
DISPLAY=:0.0 su -c - username /usr/bin/slimlock<br />
;;<br />
<br />
To set the laptop screen brightness when plugged in power or not (the numbers might need to be adjusted, see {{ic|/sys/class/backlight/acpi_video0/max_brightness}}):<br />
<br />
ac_adapter)<br />
case "$2" in<br />
AC*|AD*)<br />
case "$4" in<br />
00000000)<br />
echo -n 50 > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
00000001)<br />
echo -n 100 > /sys/class/backlight/acpi_video0/brightness<br />
;;<br />
esac<br />
<br />
=== Enabling volume control ===<br />
<br />
Find out the acpi identity of the volume buttons (see above) and susbtitute it for the acpi events in the files below. We create a script to control the volume (assuming an [[ALSA]] sound card):<br />
<br />
{{hc|/etc/acpi/handlers/vol|<nowiki><br />
#!/bin/sh<br />
step=5<br />
<br />
case $1 in<br />
-) amixer set Master $step-;;<br />
+) amixer set Master $step+;;<br />
esac<br />
</nowiki>}}<br />
<br />
and connect these to new acpi events:<br />
<br />
{{hc|/etc/acpi/events/vol_d|<nowiki><br />
event=button/volumedown<br />
action=/etc/acpi/handlers/vol -<br />
</nowiki>}}<br />
{{hc|/etc/acpi/events/vol_u|<nowiki><br />
event=button/volumeup<br />
action=/etc/acpi/handlers/vol +<br />
</nowiki>}}<br />
<br />
as well as another event to toggle the mute setting:<br />
<br />
{{hc|/etc/acpi/events/mute|<nowiki><br />
event=button/mute<br />
action=/usr/bin/amixer set Master toggle<br />
</nowiki>}}<br />
<br />
=== Enabling backlight control ===<br />
<br />
Similar to volume control, acpid also enables you to control screen backlight. To achieve this you write some handler, like this:<br />
<br />
{{hc|/etc/acpi/handlers/bl|<nowiki><br />
#!/bin/sh<br />
bl_dev=/sys/class/backlight/acpi_video0<br />
step=1<br />
<br />
case $1 in<br />
-) echo $((`cat $bl_dev/brightness` - $step)) >$bl_dev/brightness;;<br />
+) echo $((`cat $bl_dev/brightness` + $step)) >$bl_dev/brightness;;<br />
esac<br />
</nowiki>}}<br />
<br />
and again, connect keys to ACPI events:<br />
<br />
{{hc|/etc/acpi/events/bl_d|<nowiki><br />
event=video/brightnessdown<br />
action=/etc/acpi/handlers/bl -<br />
</nowiki>}}<br />
{{hc|/etc/acpi/events/bl_u|<nowiki><br />
event=video/brightnessup<br />
action=/etc/acpi/handlers/bl +<br />
</nowiki>}}<br />
<br />
=== Enabling Wi-fi toggle ===<br />
<br />
You can also create a simple wireless-power switch by pressing the WLAN button. Example of event:<br />
<br />
{{hc|/etc/acpi/events/wlan|<nowiki><br />
event=button/wlan<br />
action=/etc/acpi/handlers/wlan<br />
</nowiki>}}<br />
<br />
and its' handler:<br />
<br />
{{hc|/etc/acpi/handlers/wlan|<nowiki><br />
#!/bin/sh<br />
rf=/sys/class/rfkill/rfkill0<br />
<br />
case `cat $rf/state` in<br />
0) echo 1 >$rf/state;;<br />
1) echo 0 >$rf/state;;<br />
esac<br />
</nowiki>}}<br />
<br />
=== Laptop Monitor Power Off ===<br />
<br />
Adapted from the [http://en.gentoo-wiki.com/wiki/ACPI/Configuration Gentoo Wiki] comes this little gem. Add this to the ''button/lid'' section of {{ic|/etc/acpi/handler.sh}}. This will turn off the LCD back-light when the lid is closed, and restart when the lid is opened.<br />
case $(cat /proc/acpi/button/lid/LID0/state | awk '{print $2}') in<br />
closed) XAUTHORITY=$(ps -C xinit -f --no-header | sed -n 's/.*-auth //; s/ -[^ ].*//; p') xset -display :0 dpms force off ;;<br />
open) XAUTHORITY=$(ps -C xinit -f --no-header | sed -n 's/.*-auth //; s/ -[^ ].*//; p') xset -display :0 dpms force on ;;<br />
esac<br />
<br />
If you would like to increase/decrease brightness or anything dependent on X, you should specify the X display as well as the MIT magic cookie file (via XAUTHORITY). The last is a security credential providing read and write access to the X server, display, and any input devices.<br />
<br />
Here is another script not using XAUTHORITY but sudo:<br />
<br />
case $(cat /proc/acpi/button/lid/LID0/state | awk '{print $2}') in<br />
closed) sudo -u `ps -o ruser= -C xinit` xset -display :0 dpms force off ;;<br />
open) sudo -u `ps -o ruser= -C xinit` xset -display :0 dpms force on ;;<br />
esac<br />
<br />
With certain combinations of [[Xorg]] and stubborn hardware, {{ic|xset dpms force off}} only blanks the display leaving the backlight turned on. This can be fixed using {{Pkg|vbetool}} from the [[Official Repositories|official repositories]]. Change the LCD section to:<br />
case $(cat /proc/acpi/button/lid/LID0/state | awk '{print $2}') in<br />
closed) vbetool dpms off ;;<br />
open) vbetool dpms on ;;<br />
esac<br />
<br />
If the monitor appears to shut off only briefly before being re-powered, very possibly the power management shipped with xscreensaver conflicts with any manual ''dpms'' settings.<br />
<br />
=== Getting user name of the current display ===<br />
You can use the function {{ic|getuser}} to discover the user of the current display:<br />
getuser ()<br />
{<br />
export DISPLAY=`echo $DISPLAY | cut -c -2`<br />
user=`who | grep " $DISPLAY" | awk '{print $1}' | tail -n1`<br />
export XAUTHORITY=/home/$user/.Xauthority<br />
eval $1=$user<br />
}<br />
<br />
This function can be used for example, when you press the power button and want to shutdown [[KDE]] properly:<br />
button/power)<br />
case "$2" in<br />
PBTN)<br />
getuser "$user"<br />
echo $user > /dev/tty5<br />
su $user -c "dcop ksmserver ksmserver logout 0 2 0"<br />
;;<br />
*) logger "ACPI action undefined $2" ;;<br />
esac<br />
;;<br />
<br />
On newer systems using systemd, X11 logins are no longer necessarily displayed in {{ic|who}}, so the {{ic|getuser}} function above does not work. An alternative is to use {{ic|loginctl}} to obtain the required information, e.g. using [https://github.com/rephorm/xuserrun xuserrun].<br />
<br />
=== ACPI hotkey ===<br />
You can either directly edit {{ic|/etc/acpi/handler.sh}}, to react to the ACPI events, or you can point it to another shell script (i.e. {{ic|/etc/acpi/hotkeys.sh}})<br />
<br />
Under the section<br />
case "$1" in<br />
<br />
Add the following lines:<br />
hkey)<br />
case "$4" in<br />
00000b31)<br />
echo "PreviousButton pressed!"<br />
exailectl p<br />
;;<br />
00000b32)<br />
echo "NextButton pressed!"<br />
exailectl n<br />
;;<br />
00000b33)<br />
echo "Play/PauseButton pressed!"<br />
exailectl pp<br />
echo "executed.."<br />
;;<br />
00000b30)<br />
echo "StopButton pressed!"<br />
exailectl s<br />
;;<br />
*)<br />
echo "Hotkey Else: $4"<br />
;;<br />
esac<br />
;;<br />
<br />
The '00000b31' etc. values are the response received from acpi_listen.<br />
<br />
Also, the exailectl script is a brief shell script I created for controlling Exaile music player. As the ACPID is run from root, you will need to use<br />
sudo -u (username) exaile<br />
for example, otherwise it will not detect your user-level program and recreate another.<br />
<br />
==See also==<br />
<br />
* [http://acpid.sourceforge.net/ acpid homepage]<br />
* [http://www.gentoo-wiki.info/ACPI/Configuration RIP Gentoo wiki entry - New Gentoo Wiki Archives]</div>Kwehmu