https://wiki.archlinux.org/api.php?action=feedcontributions&user=Mdimitro&feedformat=atomArchWiki - User contributions [en]2024-03-29T12:08:45ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Mkinitcpio&diff=758676Mkinitcpio2022-12-03T00:40:22Z<p>Mdimitro: /* Common hooks */ Moved 'filesystems' in the table so as to match the ordering of hooks in the default mkinitcpio.conf examples (it was the only exception, for those that were present)</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Initramfs]]<br />
[[Category:Kernel]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[de:Mkinitcpio]]<br />
[[fr:Mkinitcpio]]<br />
[[ja:Mkinitcpio]]<br />
[[pt:Mkinitcpio]]<br />
[[ru:Mkinitcpio]]<br />
[[zh-hans:Mkinitcpio]]<br />
{{Related articles start}}<br />
{{Related|Booster}}<br />
{{Related|Boot debugging}}<br />
{{Related|dracut}}<br />
{{Related|Kernel modules}}<br />
{{Related|mkinitcpio/Minimal initramfs}}<br />
{{Related|systemd}}<br />
{{Related articles end}}<br />
[https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio mkinitcpio] is a Bash script used to create an [[Wikipedia:Initial ramdisk|initial ramdisk]] environment. From the {{man|8|mkinitcpio}} man page:<br />
<br />
:The initial ramdisk is in essence a very small environment (early userspace) which loads various kernel modules and sets up necessary things before handing over control to {{ic|init}}. This makes it possible to have, for example, encrypted root file systems and root file systems on a software RAID array. ''mkinitcpio'' allows for easy extension with custom hooks, has autodetection at runtime, and many other features.<br />
<br />
Traditionally, the kernel was responsible for all hardware detection and initialization tasks early in the [[boot process]] before mounting the root file system and passing control to {{ic|init}}. However, as technology advances, these tasks have become increasingly complex. <br />
<br />
Nowadays, the root file system may be on a wide range of hardware, from SCSI to SATA to USB drives, controlled by a variety of drive controllers from different manufacturers. Additionally, the root file system may be encrypted or compressed; within a software RAID array or a logical volume group. The simple way to handle that complexity is to pass management into userspace: an initial ramdisk. See also: [https://web.archive.org/web/20150430223035/http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ /dev/brain0 » Blog Archive » Early Userspace in Arch Linux].<br />
<br />
''mkinitcpio'' has been developed by the Arch Linux developers and from community contributions. See the [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio public Git repository].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mkinitcpio}} package, which is a dependency of the {{Pkg|linux}} package, so most users will already have it installed.<br />
<br />
Advanced users may wish to install the latest development version of ''mkinitcpio'' from Git with the {{AUR|mkinitcpio-git}} package.<br />
<br />
{{Note|It is '''highly''' recommended that you follow the [https://lists.archlinux.org/mailman3/lists/arch-projects.lists.archlinux.org/ arch-projects mailing list] if you use ''mkinitcpio'' from Git!}}<br />
<br />
== Image creation and activation ==<br />
<br />
=== Automated generation ===<br />
<br />
Every time a kernel is installed or upgraded, a [[pacman hook]] automatically generates a ''.preset'' file saved in {{ic|/etc/mkinitcpio.d/}}. For example {{ic|linux.preset}} for the official stable {{Pkg|linux}} kernel package. A preset is simply a list of information required to create initial ramdisk images, instead of manually specifying the various parameters and the location of the output files.<br />
By default, it contains the instructions to create two images:<br />
<br />
# the ''default'' ramdisk image created following the directives specified in the mkinitcpio [[#Configuration]], and<br />
# the ''fallback'' ramdisk image, same as above except that the ''autodetect'' hook is skipped during creation, thus including a full range of modules which supports most systems.<br />
<br />
After creating the preset, the pacman hook calls the ''mkinitcpio'' script which generates the two images, using the information provided in the preset.<br />
<br />
{{Note|''.preset'' files are used to automatically regenerate the initramfs after a kernel update; be careful when editing them.}}<br />
<br />
=== Manual generation ===<br />
<br />
To run the script manually, refer to the {{man|8|mkinitcpio}} manual page for instructions. In particular, to (re-)generate the preset provided by a kernel package, use the {{ic|-p}}/{{ic|--preset}} option followed by the preset to utilize. For example, for the {{Pkg|linux}} package, use the command:<br />
<br />
# mkinitcpio -p linux<br />
<br />
To (re-)generate all existing presets, use the {{ic|-P}}/{{ic|--allpresets}} switch. This is typically used to regenerate all the initramfs images after a change of the global [[#Configuration]]:<br />
<br />
# mkinitcpio -P<br />
<br />
Users may create any number of initramfs images with a variety of different configurations. The desired image must be specified in the respective [[boot loader]] configuration file.<br />
<br />
=== Customized generation ===<br />
<br />
Users can generate an image using an alternative configuration file. For example, the following will generate an initial ramdisk image according to the directions in {{ic|/etc/mkinitcpio-custom.conf}} and save it as {{ic|/boot/initramfs-custom.img}}.<br />
<br />
# mkinitcpio --config /etc/mkinitcpio-custom.conf --generate /boot/initramfs-custom.img<br />
<br />
If generating an image for a kernel other than the one currently running, add the kernel release version to the command line. The installed kernel releases can be found in {{ic|/usr/lib/modules/}}, the syntax is consistent with the output of the command {{ic|uname -r}} for each kernel.<br />
<br />
# mkinitcpio --generate /boot/initramfs-custom2.img --kernel 5.7.12-arch1-1<br />
<br />
=== Unified kernel images ===<br />
<br />
As of version 31, ''mkinitpcio'' can also create [[unified kernel image]]s.<br />
<br />
== Configuration ==<br />
<br />
The primary configuration file for ''mkinitcpio'' is {{ic|/etc/mkinitcpio.conf}}. Additionally, preset definitions are provided by kernel packages in the {{ic|/etc/mkinitcpio.d}} directory (e.g. {{ic|/etc/mkinitcpio.d/linux.preset}}).<br />
<br />
Users can modify six variables within the configuration file, see {{man|5|mkinitcpio.conf}} for more details:<br />
<br />
; {{ic|MODULES}}: Kernel modules to be loaded before any boot hooks are run. <br />
; {{ic|BINARIES}}: Additional binaries to be included in the initramfs image.<br />
; {{ic|FILES}}: Additional files to be included in the initramfs image.<br />
; {{ic|HOOKS}}: Hooks are scripts that execute in the initial ramdisk.<br />
; {{ic|COMPRESSION}}: Used to compress the initramfs image.<br />
; {{ic|COMPRESSION_OPTIONS}}: Extra arguments to pass to the {{ic|COMPRESSION}} program. Usage of this setting is strongly discouraged. ''mkinitcpio'' will handle special requirements for compressors (e.g. passing {{ic|1=--check=crc32}} to xz), and misusage can easily lead to an unbootable system.<br />
<br />
{{Note|<br />
* Some hooks that may be required for your system like '''lvm2''', '''mdadm_udev''', and '''encrypt''' are '''NOT''' enabled by default. Read the [[#HOOKS]] section carefully for instructions.<br />
* Users with multiple hardware disk controllers that use the same node names but different kernel modules (e.g. two SCSI/SATA or two IDE controllers) should use [[persistent block device naming]] to ensure that the right devices are mounted. Otherwise, the root device location may change between boots, resulting in kernel panics.<br />
}}<br />
<br />
=== MODULES ===<br />
<br />
The {{ic|MODULES}} array is used to specify modules to load before anything else is done.<br />
<br />
Modules suffixed with a {{ic|?}} will not throw errors if they are not found. This might be useful for custom kernels that compile in modules which are listed explicitly in a hook or configuration file.<br />
<br />
{{Note|<br />
* If using '''reiser4''', it ''must'' be added to the {{ic|MODULES}} array.<br />
* When using the '''encrypt''' or '''sd-encrypt''' hook, the keyboard modules and/or filesystems needed to unlock the LUKS device during system boot need to be added to the {{ic|MODULES}} array when the target system differs from the one used to run ''mkinitcpio''. For example, if you use a keyfile on an ext2 file system but no ext2 file system is mounted at the time ''mkinitcpio'' runs, add {{ic|ext2}}. See [[dm-crypt/System configuration#cryptkey]] for more details.<br />
* If using a keyboard through a USB 3 hub and wish to use it to unlock a LUKS device, add {{ic|usbhid xhci_hcd}}.<br />
* If using displays connected to a docking station, you might need to add a module for your graphic card to make initrd output visible (e.g. {{ic|i915}} for most Intel cards).<br />
}}<br />
<br />
=== BINARIES and FILES ===<br />
<br />
These options allow users to add files to the image. Both {{ic|BINARIES}} and {{ic|FILES}} are added before hooks are run, and may be used to override files used or provided by a hook. {{ic|BINARIES}} are auto-located within a standard {{ic|PATH}} and are dependency-parsed, meaning any required libraries will also be added. {{ic|FILES}} are added ''as-is''. For example:<br />
<br />
FILES=(/etc/modprobe.d/modprobe.conf)<br />
<br />
BINARIES=(kexec)<br />
<br />
Note that as both {{ic|BINARIES}} and {{ic|FILES}} are [[Bash]] arrays, multiple entries can be added delimited with spaces.<br />
<br />
=== HOOKS ===<br />
<br />
The {{ic|HOOKS}} array is the most important setting in the file. Hooks are small scripts which describe what will be added to the image. For some hooks, they will also contain a runtime component which provides additional behavior, such as starting a daemon, or assembling a stacked block device. Hooks are referred to by their name, and executed in the order they exist in the {{ic|HOOKS}} array of the configuration file.<br />
<br />
The default {{ic|HOOKS}} setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [[LVM]], [[RAID]], or [[dm-crypt]], see the respective wiki pages for further necessary configuration.<br />
<br />
==== Build hooks ====<br />
<br />
Build hooks are found in {{ic|/usr/lib/initcpio/install/}}, custom build hooks can be placed in {{ic|/etc/initcpio/install/}}. These files are sourced by the bash shell during runtime of ''mkinitcpio'' and should contain two functions: {{ic|build}} and {{ic|help}}. The {{ic|build}} function describes the modules, files, and binaries which will be added to the image. An API, documented by {{man|8|mkinitcpio}}, serves to facilitate the addition of these items. The {{ic|help}} function outputs a description of what the hook accomplishes.<br />
<br />
For a list of all available hooks:<br />
<br />
$ mkinitcpio -L<br />
<br />
Use ''mkinitcpio'''s {{ic|-H}}/{{ic|--hookhelp}} option to output help for a specific hook, for example:<br />
<br />
$ mkinitcpio -H udev<br />
<br />
==== Runtime hooks ====<br />
<br />
Runtime hooks are found in {{ic|/usr/lib/initcpio/hooks/}}, custom runtime hooks can be placed in {{ic|/etc/initcpio/hooks/}}. For any runtime hook, there should always be a build hook of the same name, which calls {{ic|add_runscript}} to add the runtime hook to the image. These files are sourced by the busybox ash shell during early userspace. With the exception of cleanup hooks, they will always be run in the order listed in the {{ic|HOOKS}} setting. Runtime hooks may contain several functions:<br />
<br />
{{ic|run_earlyhook}}: Functions of this name will be run once the API file systems have been mounted and the kernel command line has been parsed. This is generally where additional daemons, such as udev, which are needed for the early boot process are started from.<br />
<br />
{{ic|run_hook}}: Functions of this name are run shortly after the early hooks. This is the most common hook point, and operations such as assembly of stacked block devices should take place here.<br />
<br />
{{ic|run_latehook}}: Functions of this name are run after the root device has been mounted. This should be used, sparingly, for further setup of the root device, or for mounting other file systems, such as {{ic|/usr}}.<br />
<br />
{{ic|run_cleanuphook}}: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the {{ic|HOOKS}} array in the configuration file. These hooks should be used for any last minute cleanup, such as shutting down any daemons started by an early hook.<br />
<br />
{{Note|Runtime hooks are only used by busybox init. '''systemd''' hook triggers a systemd based init, which does not run any runtime hooks but uses systemd units instead.}}<br />
<br />
==== Common hooks ====<br />
<br />
A table of common hooks and how they affect image creation and runtime follows. Note that this table is not complete, as packages can provide custom hooks.<br />
<br />
{{Expansion|Add info about {{ic|hostdata}}, {{ic|memdisk}}, {{ic|sleep}} and {{ic|strip}}, find out if {{ic|dmraid}}, etc. work/are needed for systemd based initramfs.|section=Improvements for the Common hooks table and section about systemd hook}}<br />
<br />
{| class="wikitable"<br />
! busybox init !! systemd init !! [[#Build hooks|Build hook]] !! [[#Runtime hooks|Runtime hook]] (busybox init only)<br />
|-<br />
|colspan="2" {{C|'''base'''}} || Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing, as it provides critical busybox init when not using '''systemd''' hook. <br/>Optional when using the '''systemd''' hook as it only provides a busybox recovery shell. {{Note|The recovery shell is not usable since the root account in the initramfs is [https://github.com/archlinux/svntogit-packages/commit/776743d220cbb56e9abca2cc8bcef3a0ab7c8d0a locked]. See {{Bug|70408}}.}}<br />
| {{-}}<br />
|-<br />
| {{C|'''udev'''}} ||rowspan="3" {{C|'''systemd'''}} || Adds udevd, udevadm, and a small subset of udev rules to your image. || Starts the udev daemon and processes uevents from the kernel; creating device nodes. As it simplifies the boot process by not requiring the user to explicitly specify necessary modules, using it is recommended.<br />
|-<br />
| {{C|'''usr'''}} || Adds support for {{ic|/usr}} on a separate partition. See [[#/usr as a separate partition]] for details. || Mounts the {{ic|/usr}} partition after the real root has been mounted.<br />
|-<br />
|-<br />
| {{C|'''resume'''}} || {{-}} || Tries to resume from the "suspend to disk" state. See [[Hibernation]] for further configuration.<br />
|-<br />
| {{C|'''btrfs'''}} || {{Grey|–}} || Sets the required modules to enable [[Btrfs]] for using multiple devices with Btrfs. You need to have {{Pkg|btrfs-progs}} installed to use this. This hook is not required for using Btrfs on a single device. || Runs {{ic|btrfs device scan}} to assemble a multi-device Btrfs root file system when '''udev''' hook or '''systemd''' hook is not present. The {{Pkg|btrfs-progs}} package is required for this hook.<br />
|-<br />
|colspan="2" {{C|'''autodetect'''}} || Shrinks your initramfs to a smaller size by creating a whitelist of modules from a scan of sysfs. Be sure to verify included modules are correct and none are missing. This hook must be run before other subsystem hooks in order to take advantage of auto-detection. Any hooks placed before 'autodetect' will be installed in full. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''modconf'''}} || Includes modprobe configuration files from {{ic|/etc/modprobe.d/}} and {{ic|/usr/lib/modprobe.d/}}. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''kms'''}} || Adds GPU modules to provide [[Kernel mode setting#Early KMS start|early KMS start]]. Additionally adds modules that are required by privacy screens built into the LCD panel of some laptops.|| {{-}}<br />
|-<br />
|colspan="2" {{C|'''block'''}} || Adds all block device modules, formerly separately provided by the ''fw'', ''mmc'', ''pata'', ''sata'', ''scsi'', ''usb'', and ''virtio'' hooks. || {{-}}<br />
|-<br />
| {{C|'''net'''}} || {{Grey|''not implemented''}} || Adds the necessary modules for a network device. You must have {{Pkg|mkinitcpio-nfs-utils}} installed to use this, see [[#Using net]] for details. || Provides handling for an NFS-based root file system.<br />
|-<br />
| {{C|'''dmraid'''}} || {{Grey|''?''}} || Provides support for fakeRAID root devices. You must have {{Pkg|dmraid}} installed to use this. Note that it is preferred to use [[mdadm]] with the '''mdadm_udev''' hook with fakeRAID if your controller supports it. See [[#Using RAID]] for details. || Locates and assembles fakeRAID block devices using {{ic|dmraid}}.<br />
|-<br />
|colspan="2" {{C|'''mdadm_udev'''}} || Provides support for assembling RAID arrays via udev. You must have {{Pkg|mdadm}} installed to use this. If you use this hook with a FakeRAID array, it is recommended to include {{ic|mdmon}} in {{ic|BINARIES}}. See [[#Using RAID]] for details. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''keyboard'''}} || Adds the necessary modules for keyboard devices. Use this if you have an USB or serial keyboard and need it in early userspace (either for entering encryption passphrases or for use in an interactive shell). As a side effect, modules for some non-keyboard input devices might be added too, but this should not be relied on. Supersedes old ''usbinput'' hook.<br />
<br />
{{Note|For systems that are booted with different hardware configurations (e.g. laptops with external keyboard vs. internal keyboard or [[Wikipedia:Headless computer|headless systems]]), this hook needs to be placed before '''autodetect''' in order to be able to use the keyboard at boot time, for example to unlock an encrypted device when using the {{ic|encrypt}} hook.}}<br />
<br />
| {{-}}<br />
|-<br />
| {{C|'''keymap'''}} ||rowspan="2" {{C|'''sd-vconsole'''}} || Adds the specified [[Linux console/Keyboard configuration#Persistent configuration|keymap(s)]] from {{ic|/etc/vconsole.conf}} to the initramfs. If you use [[dm-crypt/Encrypting an entire system|system encryption]], especially full-disk encryption, make sure you add it before the {{ic|1=encrypt}} hook. || Loads the specified keymap(s) from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''consolefont'''}} || Adds the specified [[Linux console#Persistent configuration|console font]] from {{ic|/etc/vconsole.conf}} to the initramfs. || Loads the specified console font from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''encrypt'''}} || {{C|'''sd-encrypt'''}} || Adds the {{ic|dm_crypt}} kernel module and the {{ic|cryptsetup}} tool to the image. You must have {{Pkg|cryptsetup}} installed to use this. {{Note|Take notice of the remarks for the ''keyboard'' hook above to unlock an encrypted device during boot, and/or the filesystem remarks in [[#MODULES]] when you use a file to unlock.}} || Detects and unlocks an encrypted root partition. See [[#Runtime customization]] for further configuration.<br />
For '''sd-encrypt''' see [[dm-crypt/System configuration#Using systemd-cryptsetup-generator]].<br />
|-<br />
|colspan="2" {{C|'''lvm2'''}} || Adds the device mapper kernel module and the {{ic|lvm}} tool to the image. You must have {{Pkg|lvm2}} installed to use this. This is necessary if you have your root file system on [[LVM]]. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''filesystems'''}} || This includes necessary file system modules into your image. This hook is '''required''' unless you specify your file system modules in {{ic|MODULES}}. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''fsck'''}} || Adds the fsck binary and file system-specific helpers to allow running fsck against your root device (and {{ic|/usr}} if separate) prior to mounting. If added after the '''autodetect''' hook, only the helper specific to your root file system will be added. Usage of this hook is '''strongly''' recommended, and it is required with a separate {{ic|/usr}} partition. It is highly recommended that if you include this hook that you also include any necessary modules to ensure your keyboard will work in early userspace. <br/>The use of this hook requires the {{ic|rw}} parameter to be set on the [[kernel command line]] ([https://bbs.archlinux.org/viewtopic.php?pid=1307895#p1307895 discussion]). See [[fsck#Boot time checking]] for more details. || {{-}}<br />
|-<br />
|}<br />
<br />
=== COMPRESSION ===<br />
<br />
The kernel supports several formats for compression of the initramfs: {{Pkg|gzip}}, {{Pkg|bzip2}}, lzma, {{Pkg|xz}}, {{Pkg|lzo}}, {{Pkg|lz4}} and {{Pkg|zstd}}. mkinitcpio uses zstd compressed images by default, note that the zstd compression runs in multi-threading mode (with the {{ic|-T0}} option which spawns as many threads as detected cores).<br />
<br />
The provided {{ic|mkinitcpio.conf}} has the various {{ic|COMPRESSION}} options commented out. Uncomment one if you wish to switch to another compression method and make sure you have the corresponding compression utility installed. If none is specified, the zstd default method is used. If you wish to create an uncompressed image, specify {{ic|1=COMPRESSION='''cat'''}} in the configuration file or use {{ic|-z cat}} on the command line.<br />
<br />
{{Tip|With a compression ratio typically around 2.5 on the image in its high compression mode ({{ic|-9}}), lz4 achieves the fastest decompression speed at the cost of a slower single-threaded compression. For a slightly better compression, lzo is still fast to decompress. zstd offers a versatile solution, with multi-threaded compression and a wide range of compression levels through its options — see {{man|1|zstd|Operation modifiers}}. xz achieves the smallest size with a reduction factor around 5 in its high compression preset ({{ic|-9}}), at the cost of a much slower decompression speed.}}<br />
<br />
=== COMPRESSION_OPTIONS ===<br />
<br />
These are additional flags passed to the program specified by {{ic|COMPRESSION}}, such as:<br />
<br />
COMPRESSION_OPTIONS=(-9)<br />
<br />
This option can be left empty; ''mkinitcpio'' will ensure that any supported compression method has the necessary flags to produce a working image.<br />
<br />
{{Warning|Misuse of this option may lead to an '''unbootable system''' if the kernel is unable to unpack the resultant archive.}}<br />
<br />
With the default zstd compression, to save space for custom kernels (especially with a [[dual boot]] setup when using the EFI system partition as {{ic|/boot}}), the {{ic|--long}} option is very effective. However, systems with limited RAM may not be able to decompress initramfs using this option. The {{ic|-v}} option may also be desired to see details during the initramfs generation. For example:<br />
<br />
COMPRESSION_OPTIONS=(-v -5 --long)<br />
<br />
== Runtime customization ==<br />
<br />
{{Expansion|Which options work with the {{ic|systemd}} hook and which are {{ic|base}}-only?}}<br />
<br />
Runtime configuration options can be passed to {{ic|init}} and certain hooks via the kernel command line. Kernel command-line parameters are often supplied by the bootloader. The options discussed below can be appended to the kernel command line to alter default behavior. See [[Kernel parameters]] and [[Arch boot process]] for more information.<br />
<br />
=== init from base hook ===<br />
<br />
; {{ic|root}}: This is the most important parameter specified on the kernel command line, as it determines what device will be mounted as your proper root device. ''mkinitcpio'' is flexible enough to allow a wide variety of formats, for example: {{bc|1=<nowiki><br />
root=/dev/sda1 # /dev node<br />
root=LABEL=CorsairF80 # label<br />
root=UUID=ea1c4959-406c-45d0-a144-912f4e86b207 # UUID<br />
root=PARTUUID=14420948-2cea-4de7-b042-40f67c618660 # GPT partition UUID</nowiki><br />
}} {{Note|The following boot parameters alter the default behavior of {{ic|init}} in the initramfs environment. See {{ic|/usr/lib/initcpio/init}} for details. They will not work when {{ic|systemd}} hook is being used since the {{ic|init}} from {{ic|base}} hook is replaced.}}<br />
<br />
; {{ic|break}}: If {{ic|break}} or {{ic|1=break=premount}} is specified, {{ic|init}} pauses the boot process (after loading hooks, but before mounting the root file system) and launches an interactive shell which can be used for troubleshooting purposes. This shell can be launched after the root has been mounted by specifying {{ic|1=break=postmount}}. Normal boot continues after exiting from the shell.<br />
<br />
; {{ic|disablehooks}}: Disable hooks at runtime by adding {{ic|1=disablehooks=hook1[,hook2,...]}}. For example: {{bc|1=disablehooks=resume}}<br />
<br />
; {{ic|earlymodules}}: Alter the order in which modules are loaded by specifying modules to load early via {{ic|1=earlymodules=mod1[,mod2,...]}}. (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)<br />
<br />
See [[Boot debugging]] and {{man|8|mkinitcpio}} for other parameters.<br />
<br />
=== Using RAID ===<br />
<br />
See [[RAID#Configure mkinitcpio]].<br />
<br />
=== Using net ===<br />
<br />
{{Note|NFSv4 is not yet supported {{Bug|28287}}.}}<br />
<br />
'''Required packages'''<br />
<br />
{{ic|net}} requires the {{Pkg|mkinitcpio-nfs-utils}} package.<br />
<br />
'''Kernel parameters''' <br />
<br />
Comprehensive and up-to-date information can be found in the official [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation].<br />
<br />
'''ip='''<br />
<br />
This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It can take up to nine arguments separated by colons: {{ic|1=ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip>}}.<br />
<br />
If this parameter is missing from the kernel command line, all fields are assumed to be empty, and the defaults mentioned in the [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation] apply. In general this means that the kernel tries to configure everything using autoconfiguration.<br />
<br />
The {{ic|<autoconf>}} parameter can appear alone as the value to the {{ic|ip}} parameter (without all the {{ic|:}} characters before). If the value is {{ic|1=ip=off}} or {{ic|1=ip=none}}, no autoconfiguration will take place, otherwise autoconfiguration will take place. The most common way to use this is {{ic|1=ip=dhcp}}.<br />
<br />
For parameters explanation, see the [https://docs.kernel.org/admin-guide/nfs/nfsroot.html kernel documentation].<br />
<br />
Examples:<br />
<br />
ip=127.0.0.1:::::lo:none --> Enable the loopback interface.<br />
ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.<br />
ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.<br />
<br />
{{Note|Make sure to use kernel device names (e.g. {{ic|eth0}}) for the {{ic|<device>}} parameter, the persistent names (e.g. {{ic|enp2s0}}) will not work. See [[Network configuration#Network interfaces]] for details.}}<br />
<br />
'''BOOTIF='''<br />
<br />
If you have multiple network cards, this parameter can include the MAC address of the interface you are booting from. This is often useful as interface numbering may change, or in conjunction with pxelinux IPAPPEND 2 or IPAPPEND 3 option. If not given, {{ic|eth0}} will be used.<br />
<br />
Example:<br />
<br />
BOOTIF=01-A1-B2-C3-D4-E5-F6 # Note the prepended "01-" and capital letters.<br />
<br />
'''nfsroot='''<br />
<br />
If the {{ic|nfsroot}} parameter is NOT given on the command line, the default {{ic|/tftpboot/%s}} will be used.<br />
<br />
nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]<br />
<br />
Run {{ic|mkinitcpio -H net}} for parameter explanation.<br />
<br />
=== Using LVM ===<br />
<br />
If your root device is on [[LVM]], see [[Install Arch Linux on LVM#Adding mkinitcpio hooks]].<br />
<br />
=== Using encrypted root ===<br />
<br />
If using an [[dm-crypt/Encrypting an entire system|encrypted root]] see [[dm-crypt/System configuration#mkinitcpio]] for detailed information on which hooks to include.<br />
<br />
=== /usr as a separate partition ===<br />
<br />
If you keep {{ic|/usr}} as a separate partition, you must adhere to the following requirements:<br />
<br />
* Add the {{ic|fsck}} hook, mark {{ic|/usr}} with a {{ic|passno}} of {{ic|2}} in {{ic|/etc/fstab}} to run the check on the partition at startup. While recommended for everyone, it is mandatory if you want your {{ic|/usr}} partition to be fsck'ed at boot-up. Without this hook, {{ic|/usr}} will never be fsck'd.<br />
* If not using the systemd hook, add the {{ic|usr}} hook. This will mount the {{ic|/usr}} partition after root is mounted.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Extracting the image ===<br />
<br />
If you are curious about what is inside the initramfs image, you can extract it and poke at the files inside of it. <br />
<br />
The initramfs image is an SVR4 CPIO archive, generated via the {{ic|find}} and {{ic|bsdcpio}} commands, optionally compressed with a compression scheme understood by the kernel. For more information on the compression schemes, see [[#COMPRESSION]].<br />
<br />
''mkinitcpio'' includes a utility called {{man|1|lsinitcpio}} which will list and/or extract the contents of initramfs images.<br />
<br />
You can list the files in the image with:<br />
<br />
# lsinitcpio /boot/initramfs-linux.img<br />
<br />
And to extract them all in the current directory:<br />
<br />
# lsinitcpio -x /boot/initramfs-linux.img<br />
<br />
You can also get a more human-friendly listing of the important parts in the image:<br />
<br />
# lsinitcpio -a /boot/initramfs-linux.img<br />
<br />
=== Recompressing a modified extracted image ===<br />
<br />
Invoke the {{ic|build_image}} function of the {{ic|/usr/bin/mkinitcpio}} script with parameters<br />
<br />
build_image ''outfile'' ''compression''<br />
<br />
It can be done by creating a new script with the contents of the {{ic|build_image}} function and running it with the above parameters.<br />
This will compress the contents present in the current directory in a file named {{ic|''outfile''}}.<br />
<br />
{{Warning|It is a good idea to rename the automatically generated {{ic|/boot/initramfs-linux.img}} before you overwrite it, so you can easily undo your changes. Be prepared for making a mistake that prevents your system from booting. If this happens, you will need to boot through the fallback, or a boot CD, to restore your original, run ''mkinitcpio'' to overwrite your changes, or fix them yourself and recompress the image.}}<br />
<br />
=== "/dev must be mounted" when it already is ===<br />
<br />
The test used by ''mkinitcpio'' to determine if {{ic|/dev}} is mounted is to see if {{ic|/dev/fd/}} is there. If everything else looks fine, it can be "created" manually by:<br />
<br />
# ln -s /proc/self/fd /dev/<br />
<br />
(Obviously, {{ic|/proc}} must be mounted as well. ''mkinitcpio'' requires that anyway, and that is the next thing it will check.)<br />
<br />
=== Possibly missing firmware for module XXXX ===<br />
<br />
When initramfs are being rebuilt after a kernel update, you might get warnings:<br />
<br />
==> WARNING: Possibly missing firmware for module: ''module_name''<br />
<br />
If these messages appear when generating a ''default'' initramfs image, then, as the warning says, installing additional firmware may be required. Most common firmware files can be acquired by [[install]]ing the {{Pkg|linux-firmware}} package. For other packages providing firmware see the table below or try searching for the module name in the [[official repositories]] or [[AUR]].<br />
<br />
Otherwise, if the messages only appear when generating the ''fallback'' initramfs image you have the following options:<br />
<br />
* You can safely ignore the warnings, if you know that you do not use the affected hardware.<br />
* If you want to suppress the warnings, you can install the missing firmware. The meta-package {{AUR|mkinitcpio-firmware}} contains most optional firmwares. Alternatively, manually install the needed packages:<br />
:{| class="wikitable"<br />
|-<br />
! Module !! Package<br />
|-<br />
| aic94xx || {{AUR|aic94xx-firmware}}<br />
|-<br />
| bfa || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| bnx2x || {{Pkg|linux-firmware-bnx2x}}<br />
|-<br />
| liquidio || {{Pkg|linux-firmware-liquidio}}<br />
|-<br />
| mlxsw_spectrum || {{Pkg|linux-firmware-mellanox}}<br />
|-<br />
| nfp || {{Pkg|linux-firmware-nfp}}<br />
|-<br />
| qat_4xxx || Firmware is not yet available.<br />
|-<br />
| qed || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| qla1280 || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| qla2xxx || {{Pkg|linux-firmware-qlogic}}<br />
|-<br />
| wd719x || {{AUR|wd719x-firmware}}<br />
|-<br />
| xhci_pci || {{AUR|upd72020x-fw}}<br />
|}<br />
* If you want to get rid of the warnings, but do not want to waste your system space on unneeded firmware packages, you can disable fallback initramfs generation altogether:<br />
*# Change {{ic|1=PRESETS=('default' 'fallback')}} line to {{ic|1=PRESETS=('default')}} in all ''.preset'' files in {{ic|/etc/mkinitcpio.d/}}.<br />
*# Remove fallback initramfs images: {{ic|# rm /boot/*-fallback.img}}.<br />
*# Regenerate your bootloader config (e.g. for [[GRUB]]: {{ic|# grub-mkconfig -o /boot/grub/grub.cfg}}).<br />
:{{Warning|Disabling fallback initramfs generation will deprive you of another option to boot into the system in case a default initramfs fails. Before proceeding, make sure you have a bootable [[USB flash installation medium|installation medium]] for rescue purposes on hand.}}<br />
<br />
=== No PS/2 controller found ===<br />
<br />
On some motherboards (mostly ancient ones, but also a few new ones), the i8042 controller cannot be automatically detected. It is rare, but some people will surely be without keyboard. You can detect this situation in advance. If you have a PS/2 port and get {{ic|i8042: PNP: No PS/2 controller found. Probing ports directly}} message, add '''atkbd''' to the {{ic|MODULES}} array.<br />
<br />
=== Standard rescue procedures ===<br />
<br />
With an improper initial ram-disk a system often is unbootable. So follow a system rescue procedure like below:<br />
<br />
==== Boot succeeds on one machine and fails on another ====<br />
<br />
''mkinitcpio'''s {{ic|autodetect}} hook filters unneeded [[kernel modules]] in the primary initramfs scanning {{ic|/sys}} and the modules loaded at the time it is run. If you transfer your {{ic|/boot}} directory to another machine and the boot sequence fails during early userspace, it may be because the new hardware is not detected due to missing kernel modules. Note that USB 2.0 and 3.0 need different kernel modules. <br />
<br />
To fix, first try choosing the [[#Image creation and activation|fallback]] image from your [[bootloader]], as it is not filtered by {{ic|autodetect}}. Once booted, run ''mkinitcpio'' on the new machine to rebuild the primary image with the correct modules. If the fallback image fails, try booting into an Arch Linux live CD/USB, chroot into the installation, and run ''mkinitcpio'' on the new machine. As a last resort, try [[#MODULES|manually]] adding modules to the initramfs.<br />
<br />
== See also ==<br />
<br />
* Linux Kernel documentation on [https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html#what-is-rootfs initramfs, "What is rootfs?"]<br />
* Linux Kernel documentation on [https://docs.kernel.org/admin-guide/initrd.html initrd]<br />
* Wikipedia article on [[wikipedia:initrd|initrd]]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=XFS&diff=652339XFS2021-02-14T18:26:07Z<p>Mdimitro: /* Big timestamps */ Fixed error in parameter</p>
<hr />
<div>[[Category:File systems]]<br />
[[it:XFS]]<br />
[[ja:XFS]]<br />
[[ru:XFS]]<br />
[[pt:XFS]]<br />
[[zh-hans:XFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related articles end}}<br />
<br />
XFS is a high-performance journaling file system created by Silicon Graphics, Inc. XFS is particularly proficient at parallel IO due to its allocation group based design. This enables extreme scalability of IO threads, filesystem bandwidth, file and filesystem size when spanning multiple storage devices.<br />
<br />
== Preparation ==<br />
<br />
For XFS userspace utilities [[install]] the {{Pkg|xfsprogs}} package. It contains the tools necessary to manage an XFS file system.<br />
<br />
== Creation ==<br />
<br />
To create a new filesystem on ''device'' use:<br />
<br />
# mkfs.xfs ''device''<br />
<br />
<q>In general, the default options are optimal for common use.</q>[https://access.redhat.com/documentation/en_us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating][https://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E]<br />
<br />
Sample output:{{bc|1=<br />
meta-data=/dev/device isize=256 agcount=4, agsize=3277258 blks<br />
= sectsz=512 attr=2<br />
data = bsize=4096 blocks=13109032, imaxpct=25<br />
= sunit=0 swidth=0 blks<br />
naming =version 2 bsize=4096 ascii-ci=0<br />
log =internal log bsize=4096 blocks=6400, version=2<br />
= sectsz=512 sunit=0 blks, lazy-count=1<br />
realtime =none extsz=4096 blocks=0, rtextents=0<br />
}}<br />
<br />
{{Tip|One can optionally assign a label to the filesystem by using the {{ic|-L <label>}} option.}}<br />
<br />
{{Tip|When using ''mkfs.xfs'' on a block device containing an existing file system, add the {{ic|-f}} option to overwrite that file system.[https://access.redhat.com/documentation/en_us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating]. '''''This operation will destroy all data contained in the previous filesystem'''''.}}<br />
<br />
{{Note|<q>After an XFS file system is created, its size cannot be reduced. However, it can still be enlarged using the xfs_growfs command.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating] See [[#Resize]].}}<br />
<br />
=== Checksumming ===<br />
<br />
{{Pkg|xfsprogs}} 3.2.0 has introduced a new on-disk format (v5) that includes a metadata checksum scheme called [https://www.kernel.org/doc/html/latest/filesystems/xfs-self-describing-metadata.html Self-Describing Metadata]. <br />
Based upon CRC32 it provides for example additional protection against metadata corruption during unexpected power losses. Checksum is enabled by default when using {{Pkg|xfsprogs}} 3.2.3 or later. If you need read-write mountable xfs for older kernel, It can be easily disabled using the {{ic|1=-m crc=0}} switch when calling {{man|8|mkfs.xfs}}.<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
{{Note|Disabling metadata CRCs will also have the effect of disabling support for the [[#Free inode btree]], [[#Reverse mapping btree]] and [[#Big timestamps]] features below, as well as "reference count brtees" (see {{man|8|mkfs.xfs|OPTIONS}} for details).}}<br />
<br />
The XFS v5 on-disk format is considered stable for production workloads starting in Linux Kernel 3.15.<br />
<br />
{{Note|Unlike [[Btrfs]] and [[ZFS]], the CRC32 checksum only applies to the metadata and not actual data.}}<br />
<br />
=== Free inode btree ===<br />
<br />
Starting in Linux 3.16, XFS has added a btree that tracks free inodes. It is equivalent to the existing inode allocation btree with the exception that the free inode btree tracks inode chunks with at least one free inode. The purpose is to improve lookups for free inode clusters for inode allocation. It improves performance on aged filesystems i.e. months or years down the track when you have added and removed millions of files to/from the filesystem. Using this feature does not impact overall filesystem reliability level or recovery capabilities.<br />
<br />
This feature relies on the new v5 on-disk format that has been considered stable for production workloads starting Linux Kernel 3.15. It does not change existing on-disk structures, but adds a new one that must remain consistent with the inode allocation btree; for this reason older kernels will only be able to mount read-only filesystems with the free inode btree feature.<br />
<br />
The feature enabled by default when using xfsprogs 3.2.3 or later. If you need a writable filesystem for older kernels, it can be disable with the {{ic|1=finobt=0}} switch when formatting an XFS partition. You will need {{ic|1=crc=0}} together.<br />
# mkfs.xfs -m crc=0,finobt=0 /dev/''target_partition''<br />
or shortly ({{ic|finobt}} depends {{ic|crc}})<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
=== Reverse mapping btree ===<br />
<br />
The reverse mapping btree is at its core <q>a secondary index of storage space usage that effectively provides a redundant copy of primary space usage metadata. This adds some overhead to filesystem operations, but its inclusion in a filesystem makes cross-referencing very fast. It is an essential feature for repairing filesystems online because we can rebuild damaged primary metadata from the secondary copy.</q>[https://blogs.oracle.com/linux/xfs-online-filesystem-checking]<br />
<br />
<q>The feature graduated from EXPERIMENTAL status in Linux 4.16 and is production ready. However, online filesystem checking and repair is (so far) the only use case for this feature, so it will remain opt-in at least until online checking graduates to production readiness.</q><br />
<br />
From {{man|8|mkfs.xfs|OPTIONS}}:<br />
<br />
<q>The reverse mapping btree maps filesystem blocks to the owner of the filesystem block. Most of the mappings will be to an inode number and an offset, though there will also be mappings to filesystem metadata. This secondary metadata can be used to validate the primary metadata or to pinpoint exactly which data has been lost when a disk error occurs.</q><br />
<br />
See also [https://kernelnewbies.org/Linux_4.16#XFS_reverse_mapping_and_reflink_features_are_now_stable] and [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=35a891be96f1f8e1227e6ad3ca827b8a08ce47ea] for more information.<br />
<br />
To try out this feature or future-proof new filesystems, pass the {{ic|1=-m rmapbt=1}} parameter during filesystem creation:<br />
<br />
# mkfs.xfs -m rmapbt=1 ''device''<br />
<br />
=== Big timestamps ===<br />
<br />
Starting in Linux 5.10, XFS supports using refactored <q>timestamp and inode encoding functions to handle timestamps as a 64-bit nanosecond counter and bit shifting to increase the effective size. This now allows XFS to run well past the Year 2038 problem (where storing the time since 1970 in seconds will no longer fit in a signed 32-bit integer and thus wraparound) to now the Year 2486. Making a new XFS file-system with *bigtime* enabled allows a timestamp range from December 1901 to July 2486 rather than December 1901 to January 2038. For preserving backwards compatibility, the big timestamps feature is not currently enabled by default. </q>[https://www.phoronix.com/scan.php?page=news_item&px=XFS-Linux-5.10]<br />
<br />
The feature will also allow quota timer expirations from January 1970 to July 2486 rather than January 1970 to February 2106.<br />
<br />
To try out this feature or future-proof new filesystems, pass the {{ic|1=-m bigtime=1}} parameter during filesystem creation:<br />
<br />
# mkfs.xfs -m bigtime=1 ''device''<br />
<br />
== Performance ==<br />
<br />
From [https://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E XFS FAQ]:<br />
<br />
<q>The default values already used are optimised for best performance in the first place. mkfs.xfs will detect the difference between single disk and MD/DM RAID setups and change the default values it uses to configure the filesystem appropriately.</q><br />
<br />
<q>In most cases, the only thing you need to to consider for {{ic|mkfs.xfs}} is specifying the stripe unit and width for hardware RAID devices.</q> (see [[#Stripe size and width]])<br />
<br />
{{Tip|When using the XFS filesystem on [[RAID]] devices, performance improvements may be possible by using {{ic|largeio}}, {{ic|swalloc}}, increased {{ic|logbsize}} and {{ic|allocsize}} values, etc. The following articles may provide additional details about those flags:<br />
* https://www.beegfs.io/wiki/StorageServerTuning<br />
* https://help.marklogic.com/Knowledgebase/Article/View/505/0/recommended-xfs-settings-for-marklogic-server<br />
}}<br />
<br />
<q>For mount options, the only thing that will change metadata performance considerably are the {{ic|logbsize}} and {{ic|delaylog}} mount options. Increasing {{ic|logbsize}} reduces the number of journal IOs for a given workload, and {{ic|delaylog}} will reduce them even further. The trade off for this increase in metadata performance is that more operations may be "missing" after recovery if the system crashes while actively making modifications.</q><br />
<br />
{{Tip|See {{man|5|xfs}} for details on all available mount options.}}<br />
<br />
<q>As of kernel 3.2.12, the default i/o scheduler, CFQ, will defeat much of the parallelization in XFS.</q><br />
<br />
{{Note|Arch is configured to use no I/O scheduler when a SATA or [[NVMe]] [[SSD]] is detected; this can confirmed by reading the content of {{ic|/sys/block/nvme*n*/queue/scheduler}}.}}<br />
<br />
Therefore for optimal performance, in most cases you can just follow [[#Creation]].<br />
<br />
=== Stripe size and width ===<br />
<br />
If this filesystem will be on a striped RAID you can gain significant speed improvements by specifying the stripe size to the {{man|8|mkfs.xfs}} command.<br />
<br />
XFS can sometimes detect the geometry under software RAID, but in case you reshape it or you are using hardware RAID see [http://xfs.org/index.php/XFS_FAQ#Q:_How_to_calculate_the_correct_sunit.2Cswidth_values_for_optimal_performance how to calculate the correct sunit,swidth values for optimal performance]<br />
<br />
=== Access time ===<br />
<br />
On some filesystems you can increase performance by adding the {{ic|noatime}} mount option to the {{ic|/etc/fstab}} file. For XFS filesystems <q>the default atime behaviour is {{ic|relatime}}, which has almost no overhead compared to noatime but still maintains sane atime values. All Linux filesystems use this as the default now (since around 2.6.30), but XFS has used relatime-like behaviour since 2006, so no-one should really need to ever use noatime on XFS for performance reasons.</q>[https://xfs.org/index.php/XFS_FAQ#Q:_Is_using_noatime_or.2Fand_nodiratime_at_mount_time_giving_any_performance_benefits_in_xfs_.28or_not_using_them_performance_decrease.29.3F]<br />
<br />
See [[Fstab#atime options]] for more on this topic.<br />
<br />
=== Discard ===<br />
<br />
Despite XFS supporting async discard[https://lwn.net/Articles/787272/] since kernel 4.7[https://www.phoronix.com/scan.php?page=news_item&px=Async-Discard-Linux-4.7][https://events.static.linuxfound.org/sites/events/files/slides/discard_0.pdf], {{man|8|xfs}}{{Dead link|2020|12|13}} still recommends <q>that you use the [[fstrim]] application to discard unused blocks rather than the discard mount option because the performance impact of this option is quite severe.</q><br />
<br />
See [[Solid state drive#Periodic TRIM]].<br />
<br />
=== Defragmentation ===<br />
<br />
Although the extent-based nature of XFS and the delayed allocation strategy it uses significantly improves the file system's resistance to fragmentation problems, XFS provides a filesystem defragmentation utility (''xfs_fsr'', short for XFS filesystem reorganizer) that can defragment the files on a mounted and active XFS filesystem. It can be useful to view XFS fragmentation periodically.<br />
<br />
{{man|8|xfs_fsr}} improves the organization of mounted filesystems. The reorganization algorithm operates on one file at a time, compacting or otherwise improving the layout of the file extents (contiguous blocks of file data).<br />
<br />
==== Inspect fragmentation levels ====<br />
<br />
To see how much fragmentation your file system currently has:<br />
# xfs_db -c frag -r /dev/sda3<br />
<br />
==== Perform defragmentation ====<br />
<br />
To begin defragmentation, use the {{man|8|xfs_fsr}} command:<br />
# xfs_fsr /dev/sda3<br />
<br />
=== External XFS Journal ===<br />
<br />
Using an external log (metadata journal) on for instance a [[SSD]] may be useful to improve performance [https://docs.oracle.com/en/operating-systems/oracle-linux/8/fsadmin/xfs-main.html#extjnl-xfs]. See {{man|8|mkfs.xfs}} for details about the {{ic|logdev}} parameter.<br />
<br />
{{Warning|Beware using flash-memory may wear-out the drive. See [[Improving performance#Reduce disk reads/writes]] for SSD wear-out details.}}<br />
<br />
To reserve an external journal with a specified size when you create an XFS file system, specify the {{ic|1=-l logdev=device,size=size}} option to the {{ic|mkfs.xfs}} command. If you omit the {{ic|size}} parameter, a journal size based on the size of the file system is used. To mount the XFS file system so that it uses the external journal, specify the {{ic|1=-o logdev=device}} option to the [[mount]] command.<br />
<br />
=== Sync interval ===<br />
<br />
XFS has it dedicated [[sysctl]] variable for setting "[[Improving performance#Writeback interval and buffer size|writeback interval]]". Arch has a default value of 3000, larger value is possible to set, just keep in mind that too large may result data loss in some cases:<br />
<br />
{{hc|/etc/sysctl.d/20-xfs-sync-interval.conf|2=<br />
fs.xfs.xfssyncd_centisecs = 10000<br />
}}<br />
<br />
== Administration ==<br />
<br />
=== Resize ===<br />
<br />
{{Note|Currently, it is [https://xfs.org/index.php/Shrinking_Support not possible] to shrink XFS.}}<br />
<br />
XFS can be resized online, after the partition has been altered. Just run {{ic|xfs_growfs}} with the mount point as first parameter to grow the XFS filesystem to the maximal size possible.<br />
<br />
# xfs_growfs ''/path/to/mnt/point''<br />
<br />
=== Online Metadata Checking (scrub) ===<br />
<br />
{{Warning|This program is '''experimental''', which means that its behavior and interface could change at any time. See {{man|8|xfs_scrub}}.}}<br />
<br />
{{ic|xfs_scrub}} asks the kernel to scrub all metadata objects in the XFS filesystem. Metadata records are scanned for obviously bad values and then cross-referenced against other metadata. The goal is to establish a reasonable confidence about the consistency of the overall filesystem by examining the consistency of individual metadata records against the other metadata in the filesystem. Damaged metadata can be rebuilt from other metadata if there exists redundant data structures which are intact.<br />
<br />
[[Enable]]/[[start]] {{ic|xfs_scrub_all.timer}} to periodic check online metadata for all XFS filesystems.<br />
<br />
{{Note|One may want to [[edit]] {{ic|xfs_scrub_all.timer}}: the timer runs every Sunday at 3:10am and will be [[Systemd/Timers#Realtime_timer|triggered immediately]] if it missed the last start time, i.e. due to the system being powered off.}}<br />
<br />
=== Repair ===<br />
<br />
{{Note|<q>Unlike other Linux file systems, ''xfs_repair'' does not run at boot time, even when an XFS file system was not cleanly unmounted. In the event of an unclean unmount, ''xfs_repair'' simply replays the log at mount time, ensuring a consistent file system.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/xfsrepair]}}<br />
<br />
From [https://docs.oracle.com/en/operating-systems/oracle-linux/6/adminsg/ol_repair_xfs.html Checking and Repairing an XFS File System]:<br />
<br />
<q>If you cannot mount an XFS file system, you can use the '''xfs_repair -n''' command to check its consistency. Usually, you would only run this command on the device file of an unmounted file system that you believe has a problem. The '''xfs_repair -n''' command displays output to indicate changes that would be made to the file system in the case where it would need to complete a repair operation, but will not modify the file system directly.</q><br />
<br />
<q>If you can mount the file system and you do not have a suitable backup, you can use '''xfsdump''' to attempt to back up the existing file system data, However, the command might fail if the file system's metadata has become too corrupted.</q><br />
<br />
<q>You can use the '''xfs_repair''' command to attempt to repair an XFS file system specified by its device file. The command replays the journal log to fix any inconsistencies that might have resulted from the file system not being cleanly unmounted. Unless the file system has an inconsistency, it is usually not necessary to use the command, as the journal is replayed every time that you mount an XFS file system.</q><br />
<br />
First [[unmount]] the filesystem, then run the {{man|8|xfs_repair}} tool:<br />
<br />
# xfs_repair ''device''<br />
<br />
<q>If the journal log has become corrupted, you can reset the log by specifying the '''-L''' option '''to xfs_repair'''.</q><br />
<br />
{{Warning|<q>The ''xfs_repair'' utility cannot repair an XFS file system with a dirty log. To clear the log, mount and unmount the XFS file system. If the log is corrupt and cannot be replayed, use the {{ic|-L}} option ("force log zeroing") to clear the log, that is, {{ic|xfs_repair -L /dev/device}}. Be aware that this may result in further corruption or data loss.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/xfsrepair]}}<br />
<br />
{{Warning|<q>Resetting the log can leave the file system in an inconsistent state, resulting in data loss and data corruption. Unless you are experienced in debugging and repairing XFS file systems using '''xfs_db''', it is recommended that you instead recreate the file system and restore its contents from a backup.</q>[https://docs.oracle.com/en/operating-systems/oracle-linux/6/adminsg/ol_repair_xfs.html]}}<br />
<br />
<q>If you cannot mount the file system or you do not have a suitable backup, running '''xfs_repair''' is the only viable option unless you are experienced in using '''xfs_db'''.</q><br />
<br />
<q>'''xfs_db''' provides an internal command set that allows you to debug and repair an XFS file system manually. The commands allow you to perform scans on the file system, and to navigate and display its data structures. If you specify the '''-x''' option to enable expert mode, you can modify the data structures.</q><br />
<br />
# xfs_db [-x] device<br />
<br />
<q>For more information, see the {{man|8|xfs_db}} and {{man|8|xfs_repair}}, and the '''help''' command within '''xfs_db'''.</q><br />
<br />
See also [https://xfs.org/index.php/XFS_FAQ#Q:_Which_factors_influence_the_memory_usage_of_xfs_repair.3F Which factors influence the memory usage of xfs_repair?] and [https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-repair.html XFS Repair].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root file system quota ===<br />
<br />
XFS quota mount options ({{ic|uquota}}, {{ic|gquota}}, {{ic|prjquota}}, etc.) fail during re-mount of the file system. To enable quota for root file system, the mount option must be passed to initramfs as a [[kernel parameter]] {{ic|1=rootflags=}}. Subsequently, it should not be listed among mount options in {{ic|/etc/fstab}} for the root ({{ic|/}}) filesystem.<br />
<br />
{{Note|There are some differences of XFS Quota compared to standard Linux [[Disk quota]], this article http://inai.de/linux/adm_quota may be worth reading.}}<br />
<br />
=== xfs_scrub_all fails if user "nobody" can not access the mountpoint ===<br />
<br />
When running {{ic|xfs_scrub_all}}, it will launch {{ic|xfs_scrub@.service}} for each mounted XFS file system. The service is run as user {{ic|nobody}}, so if {{ic|nobody}} can not navigate to the directory, it will fail with the error:<br />
<br />
xfs_scrub@''mountpoint''.service: Changing to the requested working directory failed: Permission denied<br />
xfs_scrub@''mountpoint''.service: Failed at step CHDIR spawning /usr/bin/xfs_scrub: Permission denied<br />
xfs_scrub@''mountpoint''.service: Main process exited, code=exited, status=200/CHDIR<br />
<br />
To allow the service to run, change the [[permissions]] of the mountpoint so that user {{ic|nobody}} has execute permissions.<br />
<br />
== See also ==<br />
<br />
* [http://xfs.org/index.php/XFS_FAQ XFS FAQ]<br />
* [http://xfs.org/index.php/Improving_Metadata_Performance_By_Reducing_Journal_Overhead Improving Metadata Performance By Reducing Journal Overhead]<br />
* [[wikipedia:XFS|XFS Wikipedia Entry]]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=XFS&diff=652338XFS2021-02-14T18:25:06Z<p>Mdimitro: /* Checksumming */ Corrected in-page links</p>
<hr />
<div>[[Category:File systems]]<br />
[[it:XFS]]<br />
[[ja:XFS]]<br />
[[ru:XFS]]<br />
[[pt:XFS]]<br />
[[zh-hans:XFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related articles end}}<br />
<br />
XFS is a high-performance journaling file system created by Silicon Graphics, Inc. XFS is particularly proficient at parallel IO due to its allocation group based design. This enables extreme scalability of IO threads, filesystem bandwidth, file and filesystem size when spanning multiple storage devices.<br />
<br />
== Preparation ==<br />
<br />
For XFS userspace utilities [[install]] the {{Pkg|xfsprogs}} package. It contains the tools necessary to manage an XFS file system.<br />
<br />
== Creation ==<br />
<br />
To create a new filesystem on ''device'' use:<br />
<br />
# mkfs.xfs ''device''<br />
<br />
<q>In general, the default options are optimal for common use.</q>[https://access.redhat.com/documentation/en_us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating][https://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E]<br />
<br />
Sample output:{{bc|1=<br />
meta-data=/dev/device isize=256 agcount=4, agsize=3277258 blks<br />
= sectsz=512 attr=2<br />
data = bsize=4096 blocks=13109032, imaxpct=25<br />
= sunit=0 swidth=0 blks<br />
naming =version 2 bsize=4096 ascii-ci=0<br />
log =internal log bsize=4096 blocks=6400, version=2<br />
= sectsz=512 sunit=0 blks, lazy-count=1<br />
realtime =none extsz=4096 blocks=0, rtextents=0<br />
}}<br />
<br />
{{Tip|One can optionally assign a label to the filesystem by using the {{ic|-L <label>}} option.}}<br />
<br />
{{Tip|When using ''mkfs.xfs'' on a block device containing an existing file system, add the {{ic|-f}} option to overwrite that file system.[https://access.redhat.com/documentation/en_us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating]. '''''This operation will destroy all data contained in the previous filesystem'''''.}}<br />
<br />
{{Note|<q>After an XFS file system is created, its size cannot be reduced. However, it can still be enlarged using the xfs_growfs command.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating] See [[#Resize]].}}<br />
<br />
=== Checksumming ===<br />
<br />
{{Pkg|xfsprogs}} 3.2.0 has introduced a new on-disk format (v5) that includes a metadata checksum scheme called [https://www.kernel.org/doc/html/latest/filesystems/xfs-self-describing-metadata.html Self-Describing Metadata]. <br />
Based upon CRC32 it provides for example additional protection against metadata corruption during unexpected power losses. Checksum is enabled by default when using {{Pkg|xfsprogs}} 3.2.3 or later. If you need read-write mountable xfs for older kernel, It can be easily disabled using the {{ic|1=-m crc=0}} switch when calling {{man|8|mkfs.xfs}}.<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
{{Note|Disabling metadata CRCs will also have the effect of disabling support for the [[#Free inode btree]], [[#Reverse mapping btree]] and [[#Big timestamps]] features below, as well as "reference count brtees" (see {{man|8|mkfs.xfs|OPTIONS}} for details).}}<br />
<br />
The XFS v5 on-disk format is considered stable for production workloads starting in Linux Kernel 3.15.<br />
<br />
{{Note|Unlike [[Btrfs]] and [[ZFS]], the CRC32 checksum only applies to the metadata and not actual data.}}<br />
<br />
=== Free inode btree ===<br />
<br />
Starting in Linux 3.16, XFS has added a btree that tracks free inodes. It is equivalent to the existing inode allocation btree with the exception that the free inode btree tracks inode chunks with at least one free inode. The purpose is to improve lookups for free inode clusters for inode allocation. It improves performance on aged filesystems i.e. months or years down the track when you have added and removed millions of files to/from the filesystem. Using this feature does not impact overall filesystem reliability level or recovery capabilities.<br />
<br />
This feature relies on the new v5 on-disk format that has been considered stable for production workloads starting Linux Kernel 3.15. It does not change existing on-disk structures, but adds a new one that must remain consistent with the inode allocation btree; for this reason older kernels will only be able to mount read-only filesystems with the free inode btree feature.<br />
<br />
The feature enabled by default when using xfsprogs 3.2.3 or later. If you need a writable filesystem for older kernels, it can be disable with the {{ic|1=finobt=0}} switch when formatting an XFS partition. You will need {{ic|1=crc=0}} together.<br />
# mkfs.xfs -m crc=0,finobt=0 /dev/''target_partition''<br />
or shortly ({{ic|finobt}} depends {{ic|crc}})<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
=== Reverse mapping btree ===<br />
<br />
The reverse mapping btree is at its core <q>a secondary index of storage space usage that effectively provides a redundant copy of primary space usage metadata. This adds some overhead to filesystem operations, but its inclusion in a filesystem makes cross-referencing very fast. It is an essential feature for repairing filesystems online because we can rebuild damaged primary metadata from the secondary copy.</q>[https://blogs.oracle.com/linux/xfs-online-filesystem-checking]<br />
<br />
<q>The feature graduated from EXPERIMENTAL status in Linux 4.16 and is production ready. However, online filesystem checking and repair is (so far) the only use case for this feature, so it will remain opt-in at least until online checking graduates to production readiness.</q><br />
<br />
From {{man|8|mkfs.xfs|OPTIONS}}:<br />
<br />
<q>The reverse mapping btree maps filesystem blocks to the owner of the filesystem block. Most of the mappings will be to an inode number and an offset, though there will also be mappings to filesystem metadata. This secondary metadata can be used to validate the primary metadata or to pinpoint exactly which data has been lost when a disk error occurs.</q><br />
<br />
See also [https://kernelnewbies.org/Linux_4.16#XFS_reverse_mapping_and_reflink_features_are_now_stable] and [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=35a891be96f1f8e1227e6ad3ca827b8a08ce47ea] for more information.<br />
<br />
To try out this feature or future-proof new filesystems, pass the {{ic|1=-m rmapbt=1}} parameter during filesystem creation:<br />
<br />
# mkfs.xfs -m rmapbt=1 ''device''<br />
<br />
=== Big timestamps ===<br />
<br />
Starting in Linux 5.10, XFS supports using refactored <q>timestamp and inode encoding functions to handle timestamps as a 64-bit nanosecond counter and bit shifting to increase the effective size. This now allows XFS to run well past the Year 2038 problem (where storing the time since 1970 in seconds will no longer fit in a signed 32-bit integer and thus wraparound) to now the Year 2486. Making a new XFS file-system with *bigtime* enabled allows a timestamp range from December 1901 to July 2486 rather than December 1901 to January 2038. For preserving backwards compatibility, the big timestamps feature is not currently enabled by default. </q>[https://www.phoronix.com/scan.php?page=news_item&px=XFS-Linux-5.10]<br />
<br />
The feature will also allow quota timer expirations from January 1970 to July 2486 rather than January 1970 to February 2106.<br />
<br />
To try out this feature or future-proof new filesystems, pass the {{ic|1=-m rbigtime=1}} parameter during filesystem creation:<br />
<br />
# mkfs.xfs -m bigtime=1 ''device''<br />
<br />
== Performance ==<br />
<br />
From [https://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E XFS FAQ]:<br />
<br />
<q>The default values already used are optimised for best performance in the first place. mkfs.xfs will detect the difference between single disk and MD/DM RAID setups and change the default values it uses to configure the filesystem appropriately.</q><br />
<br />
<q>In most cases, the only thing you need to to consider for {{ic|mkfs.xfs}} is specifying the stripe unit and width for hardware RAID devices.</q> (see [[#Stripe size and width]])<br />
<br />
{{Tip|When using the XFS filesystem on [[RAID]] devices, performance improvements may be possible by using {{ic|largeio}}, {{ic|swalloc}}, increased {{ic|logbsize}} and {{ic|allocsize}} values, etc. The following articles may provide additional details about those flags:<br />
* https://www.beegfs.io/wiki/StorageServerTuning<br />
* https://help.marklogic.com/Knowledgebase/Article/View/505/0/recommended-xfs-settings-for-marklogic-server<br />
}}<br />
<br />
<q>For mount options, the only thing that will change metadata performance considerably are the {{ic|logbsize}} and {{ic|delaylog}} mount options. Increasing {{ic|logbsize}} reduces the number of journal IOs for a given workload, and {{ic|delaylog}} will reduce them even further. The trade off for this increase in metadata performance is that more operations may be "missing" after recovery if the system crashes while actively making modifications.</q><br />
<br />
{{Tip|See {{man|5|xfs}} for details on all available mount options.}}<br />
<br />
<q>As of kernel 3.2.12, the default i/o scheduler, CFQ, will defeat much of the parallelization in XFS.</q><br />
<br />
{{Note|Arch is configured to use no I/O scheduler when a SATA or [[NVMe]] [[SSD]] is detected; this can confirmed by reading the content of {{ic|/sys/block/nvme*n*/queue/scheduler}}.}}<br />
<br />
Therefore for optimal performance, in most cases you can just follow [[#Creation]].<br />
<br />
=== Stripe size and width ===<br />
<br />
If this filesystem will be on a striped RAID you can gain significant speed improvements by specifying the stripe size to the {{man|8|mkfs.xfs}} command.<br />
<br />
XFS can sometimes detect the geometry under software RAID, but in case you reshape it or you are using hardware RAID see [http://xfs.org/index.php/XFS_FAQ#Q:_How_to_calculate_the_correct_sunit.2Cswidth_values_for_optimal_performance how to calculate the correct sunit,swidth values for optimal performance]<br />
<br />
=== Access time ===<br />
<br />
On some filesystems you can increase performance by adding the {{ic|noatime}} mount option to the {{ic|/etc/fstab}} file. For XFS filesystems <q>the default atime behaviour is {{ic|relatime}}, which has almost no overhead compared to noatime but still maintains sane atime values. All Linux filesystems use this as the default now (since around 2.6.30), but XFS has used relatime-like behaviour since 2006, so no-one should really need to ever use noatime on XFS for performance reasons.</q>[https://xfs.org/index.php/XFS_FAQ#Q:_Is_using_noatime_or.2Fand_nodiratime_at_mount_time_giving_any_performance_benefits_in_xfs_.28or_not_using_them_performance_decrease.29.3F]<br />
<br />
See [[Fstab#atime options]] for more on this topic.<br />
<br />
=== Discard ===<br />
<br />
Despite XFS supporting async discard[https://lwn.net/Articles/787272/] since kernel 4.7[https://www.phoronix.com/scan.php?page=news_item&px=Async-Discard-Linux-4.7][https://events.static.linuxfound.org/sites/events/files/slides/discard_0.pdf], {{man|8|xfs}}{{Dead link|2020|12|13}} still recommends <q>that you use the [[fstrim]] application to discard unused blocks rather than the discard mount option because the performance impact of this option is quite severe.</q><br />
<br />
See [[Solid state drive#Periodic TRIM]].<br />
<br />
=== Defragmentation ===<br />
<br />
Although the extent-based nature of XFS and the delayed allocation strategy it uses significantly improves the file system's resistance to fragmentation problems, XFS provides a filesystem defragmentation utility (''xfs_fsr'', short for XFS filesystem reorganizer) that can defragment the files on a mounted and active XFS filesystem. It can be useful to view XFS fragmentation periodically.<br />
<br />
{{man|8|xfs_fsr}} improves the organization of mounted filesystems. The reorganization algorithm operates on one file at a time, compacting or otherwise improving the layout of the file extents (contiguous blocks of file data).<br />
<br />
==== Inspect fragmentation levels ====<br />
<br />
To see how much fragmentation your file system currently has:<br />
# xfs_db -c frag -r /dev/sda3<br />
<br />
==== Perform defragmentation ====<br />
<br />
To begin defragmentation, use the {{man|8|xfs_fsr}} command:<br />
# xfs_fsr /dev/sda3<br />
<br />
=== External XFS Journal ===<br />
<br />
Using an external log (metadata journal) on for instance a [[SSD]] may be useful to improve performance [https://docs.oracle.com/en/operating-systems/oracle-linux/8/fsadmin/xfs-main.html#extjnl-xfs]. See {{man|8|mkfs.xfs}} for details about the {{ic|logdev}} parameter.<br />
<br />
{{Warning|Beware using flash-memory may wear-out the drive. See [[Improving performance#Reduce disk reads/writes]] for SSD wear-out details.}}<br />
<br />
To reserve an external journal with a specified size when you create an XFS file system, specify the {{ic|1=-l logdev=device,size=size}} option to the {{ic|mkfs.xfs}} command. If you omit the {{ic|size}} parameter, a journal size based on the size of the file system is used. To mount the XFS file system so that it uses the external journal, specify the {{ic|1=-o logdev=device}} option to the [[mount]] command.<br />
<br />
=== Sync interval ===<br />
<br />
XFS has it dedicated [[sysctl]] variable for setting "[[Improving performance#Writeback interval and buffer size|writeback interval]]". Arch has a default value of 3000, larger value is possible to set, just keep in mind that too large may result data loss in some cases:<br />
<br />
{{hc|/etc/sysctl.d/20-xfs-sync-interval.conf|2=<br />
fs.xfs.xfssyncd_centisecs = 10000<br />
}}<br />
<br />
== Administration ==<br />
<br />
=== Resize ===<br />
<br />
{{Note|Currently, it is [https://xfs.org/index.php/Shrinking_Support not possible] to shrink XFS.}}<br />
<br />
XFS can be resized online, after the partition has been altered. Just run {{ic|xfs_growfs}} with the mount point as first parameter to grow the XFS filesystem to the maximal size possible.<br />
<br />
# xfs_growfs ''/path/to/mnt/point''<br />
<br />
=== Online Metadata Checking (scrub) ===<br />
<br />
{{Warning|This program is '''experimental''', which means that its behavior and interface could change at any time. See {{man|8|xfs_scrub}}.}}<br />
<br />
{{ic|xfs_scrub}} asks the kernel to scrub all metadata objects in the XFS filesystem. Metadata records are scanned for obviously bad values and then cross-referenced against other metadata. The goal is to establish a reasonable confidence about the consistency of the overall filesystem by examining the consistency of individual metadata records against the other metadata in the filesystem. Damaged metadata can be rebuilt from other metadata if there exists redundant data structures which are intact.<br />
<br />
[[Enable]]/[[start]] {{ic|xfs_scrub_all.timer}} to periodic check online metadata for all XFS filesystems.<br />
<br />
{{Note|One may want to [[edit]] {{ic|xfs_scrub_all.timer}}: the timer runs every Sunday at 3:10am and will be [[Systemd/Timers#Realtime_timer|triggered immediately]] if it missed the last start time, i.e. due to the system being powered off.}}<br />
<br />
=== Repair ===<br />
<br />
{{Note|<q>Unlike other Linux file systems, ''xfs_repair'' does not run at boot time, even when an XFS file system was not cleanly unmounted. In the event of an unclean unmount, ''xfs_repair'' simply replays the log at mount time, ensuring a consistent file system.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/xfsrepair]}}<br />
<br />
From [https://docs.oracle.com/en/operating-systems/oracle-linux/6/adminsg/ol_repair_xfs.html Checking and Repairing an XFS File System]:<br />
<br />
<q>If you cannot mount an XFS file system, you can use the '''xfs_repair -n''' command to check its consistency. Usually, you would only run this command on the device file of an unmounted file system that you believe has a problem. The '''xfs_repair -n''' command displays output to indicate changes that would be made to the file system in the case where it would need to complete a repair operation, but will not modify the file system directly.</q><br />
<br />
<q>If you can mount the file system and you do not have a suitable backup, you can use '''xfsdump''' to attempt to back up the existing file system data, However, the command might fail if the file system's metadata has become too corrupted.</q><br />
<br />
<q>You can use the '''xfs_repair''' command to attempt to repair an XFS file system specified by its device file. The command replays the journal log to fix any inconsistencies that might have resulted from the file system not being cleanly unmounted. Unless the file system has an inconsistency, it is usually not necessary to use the command, as the journal is replayed every time that you mount an XFS file system.</q><br />
<br />
First [[unmount]] the filesystem, then run the {{man|8|xfs_repair}} tool:<br />
<br />
# xfs_repair ''device''<br />
<br />
<q>If the journal log has become corrupted, you can reset the log by specifying the '''-L''' option '''to xfs_repair'''.</q><br />
<br />
{{Warning|<q>The ''xfs_repair'' utility cannot repair an XFS file system with a dirty log. To clear the log, mount and unmount the XFS file system. If the log is corrupt and cannot be replayed, use the {{ic|-L}} option ("force log zeroing") to clear the log, that is, {{ic|xfs_repair -L /dev/device}}. Be aware that this may result in further corruption or data loss.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/xfsrepair]}}<br />
<br />
{{Warning|<q>Resetting the log can leave the file system in an inconsistent state, resulting in data loss and data corruption. Unless you are experienced in debugging and repairing XFS file systems using '''xfs_db''', it is recommended that you instead recreate the file system and restore its contents from a backup.</q>[https://docs.oracle.com/en/operating-systems/oracle-linux/6/adminsg/ol_repair_xfs.html]}}<br />
<br />
<q>If you cannot mount the file system or you do not have a suitable backup, running '''xfs_repair''' is the only viable option unless you are experienced in using '''xfs_db'''.</q><br />
<br />
<q>'''xfs_db''' provides an internal command set that allows you to debug and repair an XFS file system manually. The commands allow you to perform scans on the file system, and to navigate and display its data structures. If you specify the '''-x''' option to enable expert mode, you can modify the data structures.</q><br />
<br />
# xfs_db [-x] device<br />
<br />
<q>For more information, see the {{man|8|xfs_db}} and {{man|8|xfs_repair}}, and the '''help''' command within '''xfs_db'''.</q><br />
<br />
See also [https://xfs.org/index.php/XFS_FAQ#Q:_Which_factors_influence_the_memory_usage_of_xfs_repair.3F Which factors influence the memory usage of xfs_repair?] and [https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-repair.html XFS Repair].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root file system quota ===<br />
<br />
XFS quota mount options ({{ic|uquota}}, {{ic|gquota}}, {{ic|prjquota}}, etc.) fail during re-mount of the file system. To enable quota for root file system, the mount option must be passed to initramfs as a [[kernel parameter]] {{ic|1=rootflags=}}. Subsequently, it should not be listed among mount options in {{ic|/etc/fstab}} for the root ({{ic|/}}) filesystem.<br />
<br />
{{Note|There are some differences of XFS Quota compared to standard Linux [[Disk quota]], this article http://inai.de/linux/adm_quota may be worth reading.}}<br />
<br />
=== xfs_scrub_all fails if user "nobody" can not access the mountpoint ===<br />
<br />
When running {{ic|xfs_scrub_all}}, it will launch {{ic|xfs_scrub@.service}} for each mounted XFS file system. The service is run as user {{ic|nobody}}, so if {{ic|nobody}} can not navigate to the directory, it will fail with the error:<br />
<br />
xfs_scrub@''mountpoint''.service: Changing to the requested working directory failed: Permission denied<br />
xfs_scrub@''mountpoint''.service: Failed at step CHDIR spawning /usr/bin/xfs_scrub: Permission denied<br />
xfs_scrub@''mountpoint''.service: Main process exited, code=exited, status=200/CHDIR<br />
<br />
To allow the service to run, change the [[permissions]] of the mountpoint so that user {{ic|nobody}} has execute permissions.<br />
<br />
== See also ==<br />
<br />
* [http://xfs.org/index.php/XFS_FAQ XFS FAQ]<br />
* [http://xfs.org/index.php/Improving_Metadata_Performance_By_Reducing_Journal_Overhead Improving Metadata Performance By Reducing Journal Overhead]<br />
* [[wikipedia:XFS|XFS Wikipedia Entry]]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=XFS&diff=652336XFS2021-02-14T18:22:51Z<p>Mdimitro: /* Creation */ Added "Big timestamps" section, note about 'crc=0' disabling support for various options, grammar corrections</p>
<hr />
<div>[[Category:File systems]]<br />
[[it:XFS]]<br />
[[ja:XFS]]<br />
[[ru:XFS]]<br />
[[pt:XFS]]<br />
[[zh-hans:XFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related articles end}}<br />
<br />
XFS is a high-performance journaling file system created by Silicon Graphics, Inc. XFS is particularly proficient at parallel IO due to its allocation group based design. This enables extreme scalability of IO threads, filesystem bandwidth, file and filesystem size when spanning multiple storage devices.<br />
<br />
== Preparation ==<br />
<br />
For XFS userspace utilities [[install]] the {{Pkg|xfsprogs}} package. It contains the tools necessary to manage an XFS file system.<br />
<br />
== Creation ==<br />
<br />
To create a new filesystem on ''device'' use:<br />
<br />
# mkfs.xfs ''device''<br />
<br />
<q>In general, the default options are optimal for common use.</q>[https://access.redhat.com/documentation/en_us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating][https://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E]<br />
<br />
Sample output:{{bc|1=<br />
meta-data=/dev/device isize=256 agcount=4, agsize=3277258 blks<br />
= sectsz=512 attr=2<br />
data = bsize=4096 blocks=13109032, imaxpct=25<br />
= sunit=0 swidth=0 blks<br />
naming =version 2 bsize=4096 ascii-ci=0<br />
log =internal log bsize=4096 blocks=6400, version=2<br />
= sectsz=512 sunit=0 blks, lazy-count=1<br />
realtime =none extsz=4096 blocks=0, rtextents=0<br />
}}<br />
<br />
{{Tip|One can optionally assign a label to the filesystem by using the {{ic|-L <label>}} option.}}<br />
<br />
{{Tip|When using ''mkfs.xfs'' on a block device containing an existing file system, add the {{ic|-f}} option to overwrite that file system.[https://access.redhat.com/documentation/en_us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating]. '''''This operation will destroy all data contained in the previous filesystem'''''.}}<br />
<br />
{{Note|<q>After an XFS file system is created, its size cannot be reduced. However, it can still be enlarged using the xfs_growfs command.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-xfs#xfscreating] See [[#Resize]].}}<br />
<br />
=== Checksumming ===<br />
<br />
{{Pkg|xfsprogs}} 3.2.0 has introduced a new on-disk format (v5) that includes a metadata checksum scheme called [https://www.kernel.org/doc/html/latest/filesystems/xfs-self-describing-metadata.html Self-Describing Metadata]. <br />
Based upon CRC32 it provides for example additional protection against metadata corruption during unexpected power losses. Checksum is enabled by default when using {{Pkg|xfsprogs}} 3.2.3 or later. If you need read-write mountable xfs for older kernel, It can be easily disabled using the {{ic|1=-m crc=0}} switch when calling {{man|8|mkfs.xfs}}.<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
{{Note|Disabling metadata CRCs will also have the effect of disabling support for the [[#free inode btree]], [[#reverse mapping btree]] and [[#big timestamps]] features below, as well as "reference count brtees" (see {{man|8|mkfs.xfs|OPTIONS}} for details).}}<br />
<br />
The XFS v5 on-disk format is considered stable for production workloads starting in Linux Kernel 3.15.<br />
<br />
{{Note|Unlike [[Btrfs]] and [[ZFS]], the CRC32 checksum only applies to the metadata and not actual data.}}<br />
<br />
=== Free inode btree ===<br />
<br />
Starting in Linux 3.16, XFS has added a btree that tracks free inodes. It is equivalent to the existing inode allocation btree with the exception that the free inode btree tracks inode chunks with at least one free inode. The purpose is to improve lookups for free inode clusters for inode allocation. It improves performance on aged filesystems i.e. months or years down the track when you have added and removed millions of files to/from the filesystem. Using this feature does not impact overall filesystem reliability level or recovery capabilities.<br />
<br />
This feature relies on the new v5 on-disk format that has been considered stable for production workloads starting Linux Kernel 3.15. It does not change existing on-disk structures, but adds a new one that must remain consistent with the inode allocation btree; for this reason older kernels will only be able to mount read-only filesystems with the free inode btree feature.<br />
<br />
The feature enabled by default when using xfsprogs 3.2.3 or later. If you need a writable filesystem for older kernels, it can be disable with the {{ic|1=finobt=0}} switch when formatting an XFS partition. You will need {{ic|1=crc=0}} together.<br />
# mkfs.xfs -m crc=0,finobt=0 /dev/''target_partition''<br />
or shortly ({{ic|finobt}} depends {{ic|crc}})<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
=== Reverse mapping btree ===<br />
<br />
The reverse mapping btree is at its core <q>a secondary index of storage space usage that effectively provides a redundant copy of primary space usage metadata. This adds some overhead to filesystem operations, but its inclusion in a filesystem makes cross-referencing very fast. It is an essential feature for repairing filesystems online because we can rebuild damaged primary metadata from the secondary copy.</q>[https://blogs.oracle.com/linux/xfs-online-filesystem-checking]<br />
<br />
<q>The feature graduated from EXPERIMENTAL status in Linux 4.16 and is production ready. However, online filesystem checking and repair is (so far) the only use case for this feature, so it will remain opt-in at least until online checking graduates to production readiness.</q><br />
<br />
From {{man|8|mkfs.xfs|OPTIONS}}:<br />
<br />
<q>The reverse mapping btree maps filesystem blocks to the owner of the filesystem block. Most of the mappings will be to an inode number and an offset, though there will also be mappings to filesystem metadata. This secondary metadata can be used to validate the primary metadata or to pinpoint exactly which data has been lost when a disk error occurs.</q><br />
<br />
See also [https://kernelnewbies.org/Linux_4.16#XFS_reverse_mapping_and_reflink_features_are_now_stable] and [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=35a891be96f1f8e1227e6ad3ca827b8a08ce47ea] for more information.<br />
<br />
To try out this feature or future-proof new filesystems, pass the {{ic|1=-m rmapbt=1}} parameter during filesystem creation:<br />
<br />
# mkfs.xfs -m rmapbt=1 ''device''<br />
<br />
=== Big timestamps ===<br />
<br />
Starting in Linux 5.10, XFS supports using refactored <q>timestamp and inode encoding functions to handle timestamps as a 64-bit nanosecond counter and bit shifting to increase the effective size. This now allows XFS to run well past the Year 2038 problem (where storing the time since 1970 in seconds will no longer fit in a signed 32-bit integer and thus wraparound) to now the Year 2486. Making a new XFS file-system with *bigtime* enabled allows a timestamp range from December 1901 to July 2486 rather than December 1901 to January 2038. For preserving backwards compatibility, the big timestamps feature is not currently enabled by default. </q>[https://www.phoronix.com/scan.php?page=news_item&px=XFS-Linux-5.10]<br />
<br />
The feature will also allow quota timer expirations from January 1970 to July 2486 rather than January 1970 to February 2106.<br />
<br />
To try out this feature or future-proof new filesystems, pass the {{ic|1=-m rbigtime=1}} parameter during filesystem creation:<br />
<br />
# mkfs.xfs -m bigtime=1 ''device''<br />
<br />
== Performance ==<br />
<br />
From [https://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E XFS FAQ]:<br />
<br />
<q>The default values already used are optimised for best performance in the first place. mkfs.xfs will detect the difference between single disk and MD/DM RAID setups and change the default values it uses to configure the filesystem appropriately.</q><br />
<br />
<q>In most cases, the only thing you need to to consider for {{ic|mkfs.xfs}} is specifying the stripe unit and width for hardware RAID devices.</q> (see [[#Stripe size and width]])<br />
<br />
{{Tip|When using the XFS filesystem on [[RAID]] devices, performance improvements may be possible by using {{ic|largeio}}, {{ic|swalloc}}, increased {{ic|logbsize}} and {{ic|allocsize}} values, etc. The following articles may provide additional details about those flags:<br />
* https://www.beegfs.io/wiki/StorageServerTuning<br />
* https://help.marklogic.com/Knowledgebase/Article/View/505/0/recommended-xfs-settings-for-marklogic-server<br />
}}<br />
<br />
<q>For mount options, the only thing that will change metadata performance considerably are the {{ic|logbsize}} and {{ic|delaylog}} mount options. Increasing {{ic|logbsize}} reduces the number of journal IOs for a given workload, and {{ic|delaylog}} will reduce them even further. The trade off for this increase in metadata performance is that more operations may be "missing" after recovery if the system crashes while actively making modifications.</q><br />
<br />
{{Tip|See {{man|5|xfs}} for details on all available mount options.}}<br />
<br />
<q>As of kernel 3.2.12, the default i/o scheduler, CFQ, will defeat much of the parallelization in XFS.</q><br />
<br />
{{Note|Arch is configured to use no I/O scheduler when a SATA or [[NVMe]] [[SSD]] is detected; this can confirmed by reading the content of {{ic|/sys/block/nvme*n*/queue/scheduler}}.}}<br />
<br />
Therefore for optimal performance, in most cases you can just follow [[#Creation]].<br />
<br />
=== Stripe size and width ===<br />
<br />
If this filesystem will be on a striped RAID you can gain significant speed improvements by specifying the stripe size to the {{man|8|mkfs.xfs}} command.<br />
<br />
XFS can sometimes detect the geometry under software RAID, but in case you reshape it or you are using hardware RAID see [http://xfs.org/index.php/XFS_FAQ#Q:_How_to_calculate_the_correct_sunit.2Cswidth_values_for_optimal_performance how to calculate the correct sunit,swidth values for optimal performance]<br />
<br />
=== Access time ===<br />
<br />
On some filesystems you can increase performance by adding the {{ic|noatime}} mount option to the {{ic|/etc/fstab}} file. For XFS filesystems <q>the default atime behaviour is {{ic|relatime}}, which has almost no overhead compared to noatime but still maintains sane atime values. All Linux filesystems use this as the default now (since around 2.6.30), but XFS has used relatime-like behaviour since 2006, so no-one should really need to ever use noatime on XFS for performance reasons.</q>[https://xfs.org/index.php/XFS_FAQ#Q:_Is_using_noatime_or.2Fand_nodiratime_at_mount_time_giving_any_performance_benefits_in_xfs_.28or_not_using_them_performance_decrease.29.3F]<br />
<br />
See [[Fstab#atime options]] for more on this topic.<br />
<br />
=== Discard ===<br />
<br />
Despite XFS supporting async discard[https://lwn.net/Articles/787272/] since kernel 4.7[https://www.phoronix.com/scan.php?page=news_item&px=Async-Discard-Linux-4.7][https://events.static.linuxfound.org/sites/events/files/slides/discard_0.pdf], {{man|8|xfs}}{{Dead link|2020|12|13}} still recommends <q>that you use the [[fstrim]] application to discard unused blocks rather than the discard mount option because the performance impact of this option is quite severe.</q><br />
<br />
See [[Solid state drive#Periodic TRIM]].<br />
<br />
=== Defragmentation ===<br />
<br />
Although the extent-based nature of XFS and the delayed allocation strategy it uses significantly improves the file system's resistance to fragmentation problems, XFS provides a filesystem defragmentation utility (''xfs_fsr'', short for XFS filesystem reorganizer) that can defragment the files on a mounted and active XFS filesystem. It can be useful to view XFS fragmentation periodically.<br />
<br />
{{man|8|xfs_fsr}} improves the organization of mounted filesystems. The reorganization algorithm operates on one file at a time, compacting or otherwise improving the layout of the file extents (contiguous blocks of file data).<br />
<br />
==== Inspect fragmentation levels ====<br />
<br />
To see how much fragmentation your file system currently has:<br />
# xfs_db -c frag -r /dev/sda3<br />
<br />
==== Perform defragmentation ====<br />
<br />
To begin defragmentation, use the {{man|8|xfs_fsr}} command:<br />
# xfs_fsr /dev/sda3<br />
<br />
=== External XFS Journal ===<br />
<br />
Using an external log (metadata journal) on for instance a [[SSD]] may be useful to improve performance [https://docs.oracle.com/en/operating-systems/oracle-linux/8/fsadmin/xfs-main.html#extjnl-xfs]. See {{man|8|mkfs.xfs}} for details about the {{ic|logdev}} parameter.<br />
<br />
{{Warning|Beware using flash-memory may wear-out the drive. See [[Improving performance#Reduce disk reads/writes]] for SSD wear-out details.}}<br />
<br />
To reserve an external journal with a specified size when you create an XFS file system, specify the {{ic|1=-l logdev=device,size=size}} option to the {{ic|mkfs.xfs}} command. If you omit the {{ic|size}} parameter, a journal size based on the size of the file system is used. To mount the XFS file system so that it uses the external journal, specify the {{ic|1=-o logdev=device}} option to the [[mount]] command.<br />
<br />
=== Sync interval ===<br />
<br />
XFS has it dedicated [[sysctl]] variable for setting "[[Improving performance#Writeback interval and buffer size|writeback interval]]". Arch has a default value of 3000, larger value is possible to set, just keep in mind that too large may result data loss in some cases:<br />
<br />
{{hc|/etc/sysctl.d/20-xfs-sync-interval.conf|2=<br />
fs.xfs.xfssyncd_centisecs = 10000<br />
}}<br />
<br />
== Administration ==<br />
<br />
=== Resize ===<br />
<br />
{{Note|Currently, it is [https://xfs.org/index.php/Shrinking_Support not possible] to shrink XFS.}}<br />
<br />
XFS can be resized online, after the partition has been altered. Just run {{ic|xfs_growfs}} with the mount point as first parameter to grow the XFS filesystem to the maximal size possible.<br />
<br />
# xfs_growfs ''/path/to/mnt/point''<br />
<br />
=== Online Metadata Checking (scrub) ===<br />
<br />
{{Warning|This program is '''experimental''', which means that its behavior and interface could change at any time. See {{man|8|xfs_scrub}}.}}<br />
<br />
{{ic|xfs_scrub}} asks the kernel to scrub all metadata objects in the XFS filesystem. Metadata records are scanned for obviously bad values and then cross-referenced against other metadata. The goal is to establish a reasonable confidence about the consistency of the overall filesystem by examining the consistency of individual metadata records against the other metadata in the filesystem. Damaged metadata can be rebuilt from other metadata if there exists redundant data structures which are intact.<br />
<br />
[[Enable]]/[[start]] {{ic|xfs_scrub_all.timer}} to periodic check online metadata for all XFS filesystems.<br />
<br />
{{Note|One may want to [[edit]] {{ic|xfs_scrub_all.timer}}: the timer runs every Sunday at 3:10am and will be [[Systemd/Timers#Realtime_timer|triggered immediately]] if it missed the last start time, i.e. due to the system being powered off.}}<br />
<br />
=== Repair ===<br />
<br />
{{Note|<q>Unlike other Linux file systems, ''xfs_repair'' does not run at boot time, even when an XFS file system was not cleanly unmounted. In the event of an unclean unmount, ''xfs_repair'' simply replays the log at mount time, ensuring a consistent file system.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/xfsrepair]}}<br />
<br />
From [https://docs.oracle.com/en/operating-systems/oracle-linux/6/adminsg/ol_repair_xfs.html Checking and Repairing an XFS File System]:<br />
<br />
<q>If you cannot mount an XFS file system, you can use the '''xfs_repair -n''' command to check its consistency. Usually, you would only run this command on the device file of an unmounted file system that you believe has a problem. The '''xfs_repair -n''' command displays output to indicate changes that would be made to the file system in the case where it would need to complete a repair operation, but will not modify the file system directly.</q><br />
<br />
<q>If you can mount the file system and you do not have a suitable backup, you can use '''xfsdump''' to attempt to back up the existing file system data, However, the command might fail if the file system's metadata has become too corrupted.</q><br />
<br />
<q>You can use the '''xfs_repair''' command to attempt to repair an XFS file system specified by its device file. The command replays the journal log to fix any inconsistencies that might have resulted from the file system not being cleanly unmounted. Unless the file system has an inconsistency, it is usually not necessary to use the command, as the journal is replayed every time that you mount an XFS file system.</q><br />
<br />
First [[unmount]] the filesystem, then run the {{man|8|xfs_repair}} tool:<br />
<br />
# xfs_repair ''device''<br />
<br />
<q>If the journal log has become corrupted, you can reset the log by specifying the '''-L''' option '''to xfs_repair'''.</q><br />
<br />
{{Warning|<q>The ''xfs_repair'' utility cannot repair an XFS file system with a dirty log. To clear the log, mount and unmount the XFS file system. If the log is corrupt and cannot be replayed, use the {{ic|-L}} option ("force log zeroing") to clear the log, that is, {{ic|xfs_repair -L /dev/device}}. Be aware that this may result in further corruption or data loss.</q>[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/xfsrepair]}}<br />
<br />
{{Warning|<q>Resetting the log can leave the file system in an inconsistent state, resulting in data loss and data corruption. Unless you are experienced in debugging and repairing XFS file systems using '''xfs_db''', it is recommended that you instead recreate the file system and restore its contents from a backup.</q>[https://docs.oracle.com/en/operating-systems/oracle-linux/6/adminsg/ol_repair_xfs.html]}}<br />
<br />
<q>If you cannot mount the file system or you do not have a suitable backup, running '''xfs_repair''' is the only viable option unless you are experienced in using '''xfs_db'''.</q><br />
<br />
<q>'''xfs_db''' provides an internal command set that allows you to debug and repair an XFS file system manually. The commands allow you to perform scans on the file system, and to navigate and display its data structures. If you specify the '''-x''' option to enable expert mode, you can modify the data structures.</q><br />
<br />
# xfs_db [-x] device<br />
<br />
<q>For more information, see the {{man|8|xfs_db}} and {{man|8|xfs_repair}}, and the '''help''' command within '''xfs_db'''.</q><br />
<br />
See also [https://xfs.org/index.php/XFS_FAQ#Q:_Which_factors_influence_the_memory_usage_of_xfs_repair.3F Which factors influence the memory usage of xfs_repair?] and [https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-repair.html XFS Repair].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root file system quota ===<br />
<br />
XFS quota mount options ({{ic|uquota}}, {{ic|gquota}}, {{ic|prjquota}}, etc.) fail during re-mount of the file system. To enable quota for root file system, the mount option must be passed to initramfs as a [[kernel parameter]] {{ic|1=rootflags=}}. Subsequently, it should not be listed among mount options in {{ic|/etc/fstab}} for the root ({{ic|/}}) filesystem.<br />
<br />
{{Note|There are some differences of XFS Quota compared to standard Linux [[Disk quota]], this article http://inai.de/linux/adm_quota may be worth reading.}}<br />
<br />
=== xfs_scrub_all fails if user "nobody" can not access the mountpoint ===<br />
<br />
When running {{ic|xfs_scrub_all}}, it will launch {{ic|xfs_scrub@.service}} for each mounted XFS file system. The service is run as user {{ic|nobody}}, so if {{ic|nobody}} can not navigate to the directory, it will fail with the error:<br />
<br />
xfs_scrub@''mountpoint''.service: Changing to the requested working directory failed: Permission denied<br />
xfs_scrub@''mountpoint''.service: Failed at step CHDIR spawning /usr/bin/xfs_scrub: Permission denied<br />
xfs_scrub@''mountpoint''.service: Main process exited, code=exited, status=200/CHDIR<br />
<br />
To allow the service to run, change the [[permissions]] of the mountpoint so that user {{ic|nobody}} has execute permissions.<br />
<br />
== See also ==<br />
<br />
* [http://xfs.org/index.php/XFS_FAQ XFS FAQ]<br />
* [http://xfs.org/index.php/Improving_Metadata_Performance_By_Reducing_Journal_Overhead Improving Metadata Performance By Reducing Journal Overhead]<br />
* [[wikipedia:XFS|XFS Wikipedia Entry]]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=EFI_system_partition&diff=650379EFI system partition2021-01-31T19:00:19Z<p>Mdimitro: /* Typical mount points */ Prefer in-wiki documentation when it's sufficient</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:EFI system partition]]<br />
[[fr:ESP]]<br />
[[ja:EFI システムパーティション]]<br />
[[pt:EFI system partition]]<br />
[[ru:EFI system partition]]<br />
[[zh-hans:EFI system partition]]<br />
{{Related articles start}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|Boot loader}}<br />
{{Related articles end}}<br />
The [[Wikipedia:EFI system partition|EFI system partition]] (also called ESP) is an OS independent partition that acts as the storage place for the EFI bootloaders, applications and drivers to be launched by the UEFI firmware. It is mandatory for UEFI boot. <br />
<br />
{{Move|Unified Extensible Firmware Interface#UEFI drivers|Drivers for non-FAT file systems are out of scope of this article.}}<br />
<br />
The UEFI specification mandates support for the 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 file systems; for example, the firmware in Apple [[Mac]]s supports the HFS+ file system.<br />
<br />
== Check for an existing partition ==<br />
<br />
If you are installing Arch Linux on an UEFI-capable computer with an installed operating system, like [[Dual boot with Windows|Windows]] 10 for example, it is very likely that you already have an EFI system partition.<br />
<br />
To find out the disk partition scheme and the system partition, use [[fdisk]] as root on the disk you want to boot from:<br />
<br />
# fdisk -l /dev/sd''x''<br />
<br />
The command returns:<br />
<br />
* The disk's partition table: it indicates {{ic|Disklabel type: gpt}} if the partition table is [[GPT]] or {{ic|Disklabel type: dos}} if it is [[MBR]].<br />
* The list of partitions on the disk: Look for the EFI system partition in the list, it is usually at least 100 MiB in size and has the type {{ic|EFI System}} or {{ic|EFI (FAT-12/16/32)}}. To confirm this is the ESP, [[mount]] it and check whether it contains a directory named {{ic|EFI}}, if it does this is definitely the ESP.<br />
<br />
{{Tip|To find out whether it is a FAT12, FAT16 or FAT32 file system, follow [[FAT#Detecting FAT type]].}}<br />
<br />
{{Warning|When dual-booting, avoid reformatting the ESP, as it may contain files required to boot other operating systems.}}<br />
<br />
If you found an existing EFI system partition, simply proceed to [[#Mount the partition]]. If you did not find one, you will need to create it, proceed to [[#Create the partition]].<br />
<br />
== Create the partition ==<br />
<br />
The following two sections show how to create an EFI system partition (ESP).<br />
<br />
{{Warning|The EFI system partition must be a physical partition in the main partition table of the disk, not under LVM or software RAID etc.}}<br />
<br />
{{Note|It is recommended to use [[GPT]] since some firmwares might not support UEFI/MBR booting due to it not being supported by [[Dual boot with Windows|Windows Setup]]. See also [[Partitioning#Choosing between GPT and MBR]] for the advantages of GPT in general.}}<br />
<br />
To provide adequate space for storing boot loaders and other files required for booting, and to prevent interoperability issues with other operating systems[https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/configure-uefigpt-based-hard-drive-partitions#diskpartitionrules][https://superuser.com/questions/1310927/what-is-the-absolute-minimum-size-a-uefi-partition-can-be/1310938] the partition should be at least 260 MiB. For early and/or buggy UEFI implementations the size of at least 512 MiB might be needed.[https://www.rodsbooks.com/efi-bootloaders/principles.html]<br />
<br />
=== GPT partitioned disks ===<br />
<br />
EFI system partition on a [[GUID Partition Table]] is identified by the [[Wikipedia:GUID Partition Table#Partition type GUIDs|partition type GUID]] {{ic|C12A7328-F81F-11D2-BA4B-00A0C93EC93B}}.<br />
<br />
'''Choose one''' of the following methods to create an ESP for a GPT partitioned disk:<br />
<br />
* [[fdisk]]: Create a partition with partition type {{ic|EFI System}}.<br />
* [[gdisk]]: Create a partition with partition type {{ic|EF00}}.<br />
* [[GNU Parted]]: Create a partition with {{ic|fat32}} as the file system type and set the {{ic|esp}} flag on it.<br />
<br />
Proceed to [[#Format the partition]] section below.<br />
<br />
=== MBR partitioned disks ===<br />
<br />
EFI system partition on a [[Master Boot Record]] partition table is identified by the [[Wikipedia:Partition type|partition type ID]] {{ic|EF}}.<br />
<br />
'''Choose one''' of the following methods to create an ESP for a MBR partitioned disk:<br />
<br />
* [[fdisk]]: Create a primary partition with partition type {{ic|EFI (FAT-12/16/32)}}.<br />
* [[GNU Parted]]: Create a primary partition with {{ic|fat32}} as the file system type and set the {{ic|esp}} flag on it.<br />
<br />
Proceed to [[#Format the partition]] section below.<br />
<br />
== Format the partition ==<br />
<br />
The UEFI specification mandates support for the FAT12, FAT16, and FAT32 file systems[https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf#G17.1019485]. To prevent potential issues with other operating systems and also since the UEFI specification only mandates supporting FAT16 and FAT12 on removable media[https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf#G17.1345080], it is recommended to use FAT32.<br />
<br />
After creating the partition, [[format]] it as [[FAT32]]. To use the {{ic|mkfs.fat}} utility, [[install]] {{Pkg|dosfstools}}.<br />
<br />
# mkfs.fat -F32 /dev/sd''xY''<br />
<br />
If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}; otherwise the partition may be unreadable by UEFI. See {{man|8|mkfs.fat}} for supported cluster sizes.<br />
<br />
== Mount the partition ==<br />
<br />
The kernels, initramfs files, and, in most cases, the processor's [[microcode]], need to be accessible by the [[boot loader]] or UEFI itself to successfully boot the system. Thus if you want to keep the setup simple, your boot loader choice limits the available mount points for EFI system partition.<br />
<br />
=== Typical mount points ===<br />
<br />
The simplest scenarios for mounting EFI system partition are:<br />
<br />
* [[mount]] ESP to {{ic|/efi}} and use a [[boot loader]] which is capable of accessing the kernel(s) and initramfs image(s) that are stored elsewhere (typically [[Partitioning#/boot|/boot]]). See [[Arch boot process#Boot loader]] for more information on boot loader requirements and capabilities.<br />
* [[mount]] ESP to {{ic|/boot}}. This is the preferred method when directly booting an [[EFISTUB]] kernel from UEFI or booting it via a boot manager like [[systemd-boot]].<br />
* [[mount]] ESP to {{ic|/efi}} and additionally mount an "Extended Boot Loader Partition" (XBOOTLDR) to {{ic|/boot}}. This can be useful when a previously created ESP is too small to hold multiple boot loaders and/or kernels but the ESP cannot be easily resized (such as when installing Linux after Windows to [[dual boot with Windows|dual boot]]). This method is supported by at least [[systemd-boot#Installation using XBOOTLDR|systemd-boot]].<br />
<br />
{{Tip|<br />
* {{ic|/efi}} is a replacement[https://github.com/systemd/systemd/pull/3757#issuecomment-234290236] for the previously popular (and possibly still used by other Linux distributions) ESP mountpoint {{ic|/boot/efi}}.<br />
* The {{ic|/efi}} directory is not available by default, you will need to first create it with {{man|1|mkdir}} before mounting the ESP to it.<br />
}}<br />
<br />
=== Alternative mount points ===<br />
<br />
If you do not use one of the simple methods from [[#Typical mount points]], you will need to copy your boot files to ESP (referred to hereafter as {{ic|''esp''}}).<br />
<br />
# mkdir -p ''esp''/EFI/arch<br />
# cp -a /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
# cp -a /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
# cp -a /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
<br />
{{Note|You may also need to copy the [[Microcode]] to the boot-entry location.}}<br />
<br />
Furthermore, you will need to keep the files on the ESP up-to-date with later kernel updates. Failure to do so could result in an unbootable system. The following sections discuss several mechanisms for automating it.<br />
<br />
{{Note|If ESP is not mounted to {{ic|/boot}}, make sure to not rely on the [[fstab#Automount with systemd|systemd automount mechanism]] (including that of {{man|8|systemd-gpt-auto-generator}}). Always have it mounted manually prior to any system or kernel update, otherwise you may not be able to mount it after the update, locking you in the currently running kernel with no ability to update the copy of kernel on ESP.<br />
<br />
Alternatively [[Kernel module#Automatic module loading with systemd|preload the required kernel modules on boot]], e.g.:<br />
<br />
{{hc|/etc/modules-load.d/vfat.conf|<br />
vfat<br />
nls_cp437<br />
nls_iso8859-1<br />
}}<br />
<br />
}}<br />
<br />
==== Using bind mount ====<br />
<br />
Instead of mounting the ESP itself to {{ic|/boot}}, you can mount a directory of the ESP to {{ic|/boot}} using a bind [[mount]] (see {{man|8|mount}}). This allows [[pacman]] to update the kernel directly while keeping the ESP organized to your liking.<br />
<br />
{{Note|1=This requires a [[FAT#Kernel configuration|kernel]] and [[bootloader]] compatible with FAT32. This is not an issue for a regular Arch install, but could be problematic for other distributions (namely those that require symlinks in {{ic|/boot/}}). See the forum post [https://bbs.archlinux.org/viewtopic.php?pid=1331867#p1331867].}}<br />
<br />
Just like in [[#Alternative mount points]], copy all boot files to a directory on your ESP, but mount the ESP '''outside''' {{ic|/boot}}. Then bind mount the directory:<br />
<br />
# mount --bind ''esp''/EFI/arch /boot<br />
<br />
After verifying success, edit your [[Fstab]] to make the changes persistent:<br />
<br />
{{hc|/etc/fstab|<br />
''esp''/EFI/arch /boot none defaults,bind 0 0<br />
}}<br />
<br />
==== Using systemd ====<br />
<br />
[[Systemd]] features event triggered tasks. In this particular case, the ability to detect a change in path is used to sync the EFISTUB kernel and initramfs files when they are updated in {{ic|/boot/}}. The file watched for changes is {{ic|initramfs-linux-fallback.img}} since this is the last file built by mkinitcpio, to make sure all files have been built before starting the copy. The ''systemd'' path and service files to be created are:<br />
<br />
{{hc|/etc/systemd/system/efistub-update.path|2=<br />
[Unit]<br />
Description=Copy EFISTUB Kernel to EFI system partition<br />
<br />
[Path]<br />
PathChanged=/boot/initramfs-linux-fallback.img<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
WantedBy=system-update.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/efistub-update.service|2=<br />
[Unit]<br />
Description=Copy EFISTUB Kernel to EFI system partition<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/cp -af /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
ExecStart=/usr/bin/cp -af /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
ExecStart=/usr/bin/cp -af /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
}}<br />
<br />
Then [[enable]] and [[start]] {{ic|efistub-update.path}}.<br />
<br />
{{Tip|For [[Secure Boot]] with your own keys, you can set up the service to also sign the image using {{Pkg|sbsigntools}}:<br />
<br />
{{bc|1=ExecStart=/usr/bin/sbsign --key ''/path/to/db.key'' --cert ''/path/to/db.crt'' --output ''esp''/EFI/arch/vmlinuz-linux /boot/vmlinuz-linux}}<br />
<br />
}}<br />
<br />
==== Using filesystem events ====<br />
<br />
[[Autostarting#On filesystem events|Filesystem events]] can be used to run a script syncing the EFISTUB Kernel after kernel updates. An example with [[incron]] follows.<br />
<br />
{{hc|/usr/local/bin/efistub-update|<br />
#!/bin/sh<br />
cp -af /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
cp -af /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
cp -af /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
}}<br />
<br />
{{Note|The first parameter {{ic|/boot/initramfs-linux-fallback.img}} is the file to watch. The second parameter {{ic|IN_CLOSE_WRITE}} is the action to watch for. The third parameter {{ic|/usr/local/bin/efistub-update}} is the script to execute.}}<br />
<br />
{{hc|/etc/incron.d/efistub-update.conf|<br />
/boot/initramfs-linux-fallback.img IN_CLOSE_WRITE /usr/local/bin/efistub-update<br />
}}<br />
<br />
In order to use this method, [[enable]] the {{ic|incrond.service}}.<br />
<br />
==== Using mkinitcpio hook ====<br />
<br />
Mkinitcpio can generate a hook that does not need a system level daemon to function. It spawns a background process which waits for the generation of {{ic|vmlinuz}}, {{ic|initramfs-linux.img}}, and {{ic|initramfs-linux-fallback.img}} before copying the files.<br />
<br />
Add {{ic|efistub-update}} to the list of hooks in {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
{{hc|/etc/initcpio/install/efistub-update|<nowiki><br />
#!/usr/bin/env bash<br />
build() {<br />
/usr/local/bin/efistub-copy $$ &<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook waits for mkinitcpio to finish and copies the finished ramdisk and kernel to the ESP<br />
HELPEOF<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|/usr/local/bin/efistub-copy|<br />
#!/usr/bin/env bash<br />
<br />
<nowiki>if [[ $1 -gt 0 ]]</nowiki><br />
then<br />
while [ -e /proc/$1 ]<br />
do<br />
sleep .5<br />
done<br />
fi<br />
<br />
rsync -a /boot/ ''esp''/<br />
<br />
echo "Synced /boot with ESP"<br />
}}<br />
<br />
==== Using mkinitcpio preset ====<br />
<br />
As the presets in {{ic|/etc/mkinitcpio.d/}} support shell scripting, the kernel and initramfs can be copied by just editing the presets.<br />
<br />
===== Replacing the above mkinitcpio hook =====<br />
<br />
Edit the file {{ic|/etc/mkinitcpio.d/linux.preset}}:<br />
<br />
{{hc|/etc/mkinitcpio.d/linux.preset|<nowiki><br />
# mkinitcpio preset file for the 'linux' package<br />
<br />
# Directory to copy the kernel, the initramfs...<br />
ESP_DIR="''esp''/EFI/arch"<br />
<br />
ALL_config="/etc/mkinitcpio.conf"<br />
ALL_kver="${ESP_DIR}/vmlinuz-linux"<br />
cp -af /boot/vmlinuz-linux "${ESP_DIR}/"<br />
[[ -e /boot/intel-ucode.img ]] && cp -af /boot/intel-ucode.img "${ESP_DIR}/"<br />
[[ -e /boot/amd-ucode.img ]] && cp -af /boot/amd-ucode.img "${ESP_DIR}/"<br />
<br />
PRESETS=('default' 'fallback')<br />
<br />
#default_config="/etc/mkinitcpio.conf"<br />
default_image="${ESP_DIR}/initramfs-linux.img"<br />
default_options=""<br />
<br />
#fallback_config="/etc/mkinitcpio.conf"<br />
fallback_image="${ESP_DIR}/initramfs-linux-fallback.img"<br />
fallback_options="-S autodetect"<br />
</nowiki>}}<br />
To test that, just run:<br />
<br />
# rm /boot/initramfs-linux-fallback.img<br />
# rm /boot/initramfs-linux.img<br />
# mkinitcpio -p linux<br />
<br />
===== Another example =====<br />
<br />
{{hc|/etc/mkinitcpio.d/linux.preset|2=<br />
ESP_DIR="''esp''/EFI/arch"<br />
cp -f "/boot/vmlinuz-linux$suffix" "$ESP_DIR/"<br />
ALL_config="/etc/mkinitcpio.conf"<br />
ALL_kver="$ESP_DIR/vmlinuz-linux$suffix"<br />
PRESETS=('default')<br />
default_config="/etc/mkinitcpio.conf"<br />
default_image="$ESP_DIR/initramfs-linux$suffix.img"<br />
}}<br />
<br />
{{hc|/etc/mkinitcpio.d/linux-zen.preset|2=<br />
suffix='-zen'<br />
source /etc/mkinitcpio.d/linux.preset<br />
}}<br />
<br />
==== Using pacman hook ====<br />
<br />
A last option relies on the [[pacman hooks]] that are run at the end of the transaction.<br />
<br />
The first file is a hook that monitors the relevant files, and it is run if they were modified in the former transaction.<br />
<br />
{{hc|/etc/pacman.d/hooks/999-kernel-efi-copy.hook|<nowiki><br />
[Trigger]<br />
Type = Path<br />
Operation = Install<br />
Operation = Upgrade<br />
Target = usr/lib/modules/*/vmlinuz<br />
Target = usr/lib/initcpio/*<br />
Target = boot/*-ucode.img<br />
<br />
[Action]<br />
Description = Copying linux and initramfs to EFI directory...<br />
When = PostTransaction<br />
Exec = /usr/local/bin/kernel-efi-copy.sh<br />
</nowiki>}}<br />
<br />
The second file is the script itself. Create the file and make it [[executable]]:<br />
<br />
{{hc|/usr/local/bin/kernel-efi-copy.sh|<nowiki><br />
#!/usr/bin/env bash<br />
#<br />
# Copy kernel and initramfs images to EFI directory<br />
#<br />
<br />
ESP_DIR="</nowiki>''esp''<nowiki>/EFI/arch"<br />
<br />
for file in /boot/vmlinuz*<br />
do<br />
cp -af "$file" "$ESP_DIR/$(basename "$file").efi"<br />
[[ $? -ne 0 ]] && exit 1<br />
done<br />
<br />
for file in /boot/initramfs*<br />
do<br />
cp -af "$file" "$ESP_DIR/"<br />
[[ $? -ne 0 ]] && exit 1<br />
done<br />
<br />
[[ -e /boot/intel-ucode.img ]] && cp -af /boot/intel-ucode.img "$ESP_DIR/"<br />
[[ -e /boot/amd-ucode.img ]] && cp -af /boot/amd-ucode.img "$ESP_DIR/"<br />
<br />
exit 0<br />
</nowiki>}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== ESP on software RAID1 ===<br />
<br />
It is possible to make the ESP part of a RAID1 array, but doing so brings the risk of data corruption, and further considerations need to be taken when creating the ESP. See [https://bbs.archlinux.org/viewtopic.php?pid=1398710#p1398710] and [https://bbs.archlinux.org/viewtopic.php?pid=1390741#p1390741] for details and [https://outflux.net/blog/archives/2018/04/19/uefi-booting-and-raid1/ UEFI booting and RAID1] for an in-depth guide with a solution.<br />
<br />
The key part is to use {{ic|--metadata 1.0}} in order to keep the RAID metadata at the end of the partition, otherwise the firmware will not be able to access it:<br />
<br />
# mdadm --create --verbose --level=1 '''--metadata=1.0''' --raid-devices=2 /dev/md/ESP /dev/sda''X'' /dev/sdb''Y''<br />
<br />
=== Firmware does not see the EFI directory ===<br />
<br />
If you give the file system a volume name (with the {{ic|-n}} option), be sure to name it something other than "EFI". That can trigger a bug in some firmwares (due to the volume name matching the EFI directory name) that will cause the firmware to act like the EFI directory does not exist.<br />
<br />
== See also ==<br />
<br />
* [https://blog.uncooperative.org/blog/2014/02/06/the-efi-system-partition/ The EFI system partition and the default boot behavior]<br />
* [https://ramsdenj.com/2016/04/15/multi-boot-linux-with-one-boot-partition.html Multi Boot Linux With One Boot Partition | John Ramsden]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=EFI_system_partition&diff=650377EFI system partition2021-01-31T18:57:43Z<p>Mdimitro: /* Typical mount points */ Introduce the idea of the Extended Boot Loader Partition, more could possibly be added to the following sections to help simplify set-ups</p>
<hr />
<div>[[Category:Boot process]]<br />
[[es:EFI system partition]]<br />
[[fr:ESP]]<br />
[[ja:EFI システムパーティション]]<br />
[[pt:EFI system partition]]<br />
[[ru:EFI system partition]]<br />
[[zh-hans:EFI system partition]]<br />
{{Related articles start}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related|Boot loader}}<br />
{{Related articles end}}<br />
The [[Wikipedia:EFI system partition|EFI system partition]] (also called ESP) is an OS independent partition that acts as the storage place for the EFI bootloaders, applications and drivers to be launched by the UEFI firmware. It is mandatory for UEFI boot. <br />
<br />
{{Move|Unified Extensible Firmware Interface#UEFI drivers|Drivers for non-FAT file systems are out of scope of this article.}}<br />
<br />
The UEFI specification mandates support for the 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 file systems; for example, the firmware in Apple [[Mac]]s supports the HFS+ file system.<br />
<br />
== Check for an existing partition ==<br />
<br />
If you are installing Arch Linux on an UEFI-capable computer with an installed operating system, like [[Dual boot with Windows|Windows]] 10 for example, it is very likely that you already have an EFI system partition.<br />
<br />
To find out the disk partition scheme and the system partition, use [[fdisk]] as root on the disk you want to boot from:<br />
<br />
# fdisk -l /dev/sd''x''<br />
<br />
The command returns:<br />
<br />
* The disk's partition table: it indicates {{ic|Disklabel type: gpt}} if the partition table is [[GPT]] or {{ic|Disklabel type: dos}} if it is [[MBR]].<br />
* The list of partitions on the disk: Look for the EFI system partition in the list, it is usually at least 100 MiB in size and has the type {{ic|EFI System}} or {{ic|EFI (FAT-12/16/32)}}. To confirm this is the ESP, [[mount]] it and check whether it contains a directory named {{ic|EFI}}, if it does this is definitely the ESP.<br />
<br />
{{Tip|To find out whether it is a FAT12, FAT16 or FAT32 file system, follow [[FAT#Detecting FAT type]].}}<br />
<br />
{{Warning|When dual-booting, avoid reformatting the ESP, as it may contain files required to boot other operating systems.}}<br />
<br />
If you found an existing EFI system partition, simply proceed to [[#Mount the partition]]. If you did not find one, you will need to create it, proceed to [[#Create the partition]].<br />
<br />
== Create the partition ==<br />
<br />
The following two sections show how to create an EFI system partition (ESP).<br />
<br />
{{Warning|The EFI system partition must be a physical partition in the main partition table of the disk, not under LVM or software RAID etc.}}<br />
<br />
{{Note|It is recommended to use [[GPT]] since some firmwares might not support UEFI/MBR booting due to it not being supported by [[Dual boot with Windows|Windows Setup]]. See also [[Partitioning#Choosing between GPT and MBR]] for the advantages of GPT in general.}}<br />
<br />
To provide adequate space for storing boot loaders and other files required for booting, and to prevent interoperability issues with other operating systems[https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/configure-uefigpt-based-hard-drive-partitions#diskpartitionrules][https://superuser.com/questions/1310927/what-is-the-absolute-minimum-size-a-uefi-partition-can-be/1310938] the partition should be at least 260 MiB. For early and/or buggy UEFI implementations the size of at least 512 MiB might be needed.[https://www.rodsbooks.com/efi-bootloaders/principles.html]<br />
<br />
=== GPT partitioned disks ===<br />
<br />
EFI system partition on a [[GUID Partition Table]] is identified by the [[Wikipedia:GUID Partition Table#Partition type GUIDs|partition type GUID]] {{ic|C12A7328-F81F-11D2-BA4B-00A0C93EC93B}}.<br />
<br />
'''Choose one''' of the following methods to create an ESP for a GPT partitioned disk:<br />
<br />
* [[fdisk]]: Create a partition with partition type {{ic|EFI System}}.<br />
* [[gdisk]]: Create a partition with partition type {{ic|EF00}}.<br />
* [[GNU Parted]]: Create a partition with {{ic|fat32}} as the file system type and set the {{ic|esp}} flag on it.<br />
<br />
Proceed to [[#Format the partition]] section below.<br />
<br />
=== MBR partitioned disks ===<br />
<br />
EFI system partition on a [[Master Boot Record]] partition table is identified by the [[Wikipedia:Partition type|partition type ID]] {{ic|EF}}.<br />
<br />
'''Choose one''' of the following methods to create an ESP for a MBR partitioned disk:<br />
<br />
* [[fdisk]]: Create a primary partition with partition type {{ic|EFI (FAT-12/16/32)}}.<br />
* [[GNU Parted]]: Create a primary partition with {{ic|fat32}} as the file system type and set the {{ic|esp}} flag on it.<br />
<br />
Proceed to [[#Format the partition]] section below.<br />
<br />
== Format the partition ==<br />
<br />
The UEFI specification mandates support for the FAT12, FAT16, and FAT32 file systems[https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf#G17.1019485]. To prevent potential issues with other operating systems and also since the UEFI specification only mandates supporting FAT16 and FAT12 on removable media[https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf#G17.1345080], it is recommended to use FAT32.<br />
<br />
After creating the partition, [[format]] it as [[FAT32]]. To use the {{ic|mkfs.fat}} utility, [[install]] {{Pkg|dosfstools}}.<br />
<br />
# mkfs.fat -F32 /dev/sd''xY''<br />
<br />
If you get the message {{ic|WARNING: Not enough clusters for a 32 bit FAT!}}, reduce cluster size with {{ic|mkfs.fat -s2 -F32 ...}} or {{ic|-s1}}; otherwise the partition may be unreadable by UEFI. See {{man|8|mkfs.fat}} for supported cluster sizes.<br />
<br />
== Mount the partition ==<br />
<br />
The kernels, initramfs files, and, in most cases, the processor's [[microcode]], need to be accessible by the [[boot loader]] or UEFI itself to successfully boot the system. Thus if you want to keep the setup simple, your boot loader choice limits the available mount points for EFI system partition.<br />
<br />
=== Typical mount points ===<br />
<br />
The simplest scenarios for mounting EFI system partition are:<br />
<br />
* [[mount]] ESP to {{ic|/efi}} and use a [[boot loader]] which is capable of accessing the kernel(s) and initramfs image(s) that are stored elsewhere (typically [[Partitioning#/boot|/boot]]). See [[Arch boot process#Boot loader]] for more information on boot loader requirements and capabilities.<br />
* [[mount]] ESP to {{ic|/boot}}. This is the preferred method when directly booting an [[EFISTUB]] kernel from UEFI or booting it via a boot manager like [[systemd-boot]].<br />
* [[mount]] ESP to {{ic|/efi}} and additionally mount an "Extended Boot Loader Partition" (XBOOTLDR) to {{ic|/boot}}. This can be useful when a previously created ESP is too small to hold multiple boot loaders and/or kernels but the ESP cannot be easily resized (such as when installing Linux after Windows to [[dual boot with Windows|dual boot]]). This method is supported by at least [[systemd-boot]]; see [https://systemd.io/BOOT_LOADER_SPECIFICATION/] for details of implementation.<br />
<br />
{{Tip|<br />
* {{ic|/efi}} is a replacement[https://github.com/systemd/systemd/pull/3757#issuecomment-234290236] for the previously popular (and possibly still used by other Linux distributions) ESP mountpoint {{ic|/boot/efi}}.<br />
* The {{ic|/efi}} directory is not available by default, you will need to first create it with {{man|1|mkdir}} before mounting the ESP to it.<br />
}}<br />
<br />
=== Alternative mount points ===<br />
<br />
If you do not use one of the simple methods from [[#Typical mount points]], you will need to copy your boot files to ESP (referred to hereafter as {{ic|''esp''}}).<br />
<br />
# mkdir -p ''esp''/EFI/arch<br />
# cp -a /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
# cp -a /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
# cp -a /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
<br />
{{Note|You may also need to copy the [[Microcode]] to the boot-entry location.}}<br />
<br />
Furthermore, you will need to keep the files on the ESP up-to-date with later kernel updates. Failure to do so could result in an unbootable system. The following sections discuss several mechanisms for automating it.<br />
<br />
{{Note|If ESP is not mounted to {{ic|/boot}}, make sure to not rely on the [[fstab#Automount with systemd|systemd automount mechanism]] (including that of {{man|8|systemd-gpt-auto-generator}}). Always have it mounted manually prior to any system or kernel update, otherwise you may not be able to mount it after the update, locking you in the currently running kernel with no ability to update the copy of kernel on ESP.<br />
<br />
Alternatively [[Kernel module#Automatic module loading with systemd|preload the required kernel modules on boot]], e.g.:<br />
<br />
{{hc|/etc/modules-load.d/vfat.conf|<br />
vfat<br />
nls_cp437<br />
nls_iso8859-1<br />
}}<br />
<br />
}}<br />
<br />
==== Using bind mount ====<br />
<br />
Instead of mounting the ESP itself to {{ic|/boot}}, you can mount a directory of the ESP to {{ic|/boot}} using a bind [[mount]] (see {{man|8|mount}}). This allows [[pacman]] to update the kernel directly while keeping the ESP organized to your liking.<br />
<br />
{{Note|1=This requires a [[FAT#Kernel configuration|kernel]] and [[bootloader]] compatible with FAT32. This is not an issue for a regular Arch install, but could be problematic for other distributions (namely those that require symlinks in {{ic|/boot/}}). See the forum post [https://bbs.archlinux.org/viewtopic.php?pid=1331867#p1331867].}}<br />
<br />
Just like in [[#Alternative mount points]], copy all boot files to a directory on your ESP, but mount the ESP '''outside''' {{ic|/boot}}. Then bind mount the directory:<br />
<br />
# mount --bind ''esp''/EFI/arch /boot<br />
<br />
After verifying success, edit your [[Fstab]] to make the changes persistent:<br />
<br />
{{hc|/etc/fstab|<br />
''esp''/EFI/arch /boot none defaults,bind 0 0<br />
}}<br />
<br />
==== Using systemd ====<br />
<br />
[[Systemd]] features event triggered tasks. In this particular case, the ability to detect a change in path is used to sync the EFISTUB kernel and initramfs files when they are updated in {{ic|/boot/}}. The file watched for changes is {{ic|initramfs-linux-fallback.img}} since this is the last file built by mkinitcpio, to make sure all files have been built before starting the copy. The ''systemd'' path and service files to be created are:<br />
<br />
{{hc|/etc/systemd/system/efistub-update.path|2=<br />
[Unit]<br />
Description=Copy EFISTUB Kernel to EFI system partition<br />
<br />
[Path]<br />
PathChanged=/boot/initramfs-linux-fallback.img<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
WantedBy=system-update.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/efistub-update.service|2=<br />
[Unit]<br />
Description=Copy EFISTUB Kernel to EFI system partition<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/cp -af /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
ExecStart=/usr/bin/cp -af /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
ExecStart=/usr/bin/cp -af /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
}}<br />
<br />
Then [[enable]] and [[start]] {{ic|efistub-update.path}}.<br />
<br />
{{Tip|For [[Secure Boot]] with your own keys, you can set up the service to also sign the image using {{Pkg|sbsigntools}}:<br />
<br />
{{bc|1=ExecStart=/usr/bin/sbsign --key ''/path/to/db.key'' --cert ''/path/to/db.crt'' --output ''esp''/EFI/arch/vmlinuz-linux /boot/vmlinuz-linux}}<br />
<br />
}}<br />
<br />
==== Using filesystem events ====<br />
<br />
[[Autostarting#On filesystem events|Filesystem events]] can be used to run a script syncing the EFISTUB Kernel after kernel updates. An example with [[incron]] follows.<br />
<br />
{{hc|/usr/local/bin/efistub-update|<br />
#!/bin/sh<br />
cp -af /boot/vmlinuz-linux ''esp''/EFI/arch/<br />
cp -af /boot/initramfs-linux.img ''esp''/EFI/arch/<br />
cp -af /boot/initramfs-linux-fallback.img ''esp''/EFI/arch/<br />
}}<br />
<br />
{{Note|The first parameter {{ic|/boot/initramfs-linux-fallback.img}} is the file to watch. The second parameter {{ic|IN_CLOSE_WRITE}} is the action to watch for. The third parameter {{ic|/usr/local/bin/efistub-update}} is the script to execute.}}<br />
<br />
{{hc|/etc/incron.d/efistub-update.conf|<br />
/boot/initramfs-linux-fallback.img IN_CLOSE_WRITE /usr/local/bin/efistub-update<br />
}}<br />
<br />
In order to use this method, [[enable]] the {{ic|incrond.service}}.<br />
<br />
==== Using mkinitcpio hook ====<br />
<br />
Mkinitcpio can generate a hook that does not need a system level daemon to function. It spawns a background process which waits for the generation of {{ic|vmlinuz}}, {{ic|initramfs-linux.img}}, and {{ic|initramfs-linux-fallback.img}} before copying the files.<br />
<br />
Add {{ic|efistub-update}} to the list of hooks in {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
{{hc|/etc/initcpio/install/efistub-update|<nowiki><br />
#!/usr/bin/env bash<br />
build() {<br />
/usr/local/bin/efistub-copy $$ &<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook waits for mkinitcpio to finish and copies the finished ramdisk and kernel to the ESP<br />
HELPEOF<br />
}<br />
</nowiki>}}<br />
<br />
{{hc|/usr/local/bin/efistub-copy|<br />
#!/usr/bin/env bash<br />
<br />
<nowiki>if [[ $1 -gt 0 ]]</nowiki><br />
then<br />
while [ -e /proc/$1 ]<br />
do<br />
sleep .5<br />
done<br />
fi<br />
<br />
rsync -a /boot/ ''esp''/<br />
<br />
echo "Synced /boot with ESP"<br />
}}<br />
<br />
==== Using mkinitcpio preset ====<br />
<br />
As the presets in {{ic|/etc/mkinitcpio.d/}} support shell scripting, the kernel and initramfs can be copied by just editing the presets.<br />
<br />
===== Replacing the above mkinitcpio hook =====<br />
<br />
Edit the file {{ic|/etc/mkinitcpio.d/linux.preset}}:<br />
<br />
{{hc|/etc/mkinitcpio.d/linux.preset|<nowiki><br />
# mkinitcpio preset file for the 'linux' package<br />
<br />
# Directory to copy the kernel, the initramfs...<br />
ESP_DIR="''esp''/EFI/arch"<br />
<br />
ALL_config="/etc/mkinitcpio.conf"<br />
ALL_kver="${ESP_DIR}/vmlinuz-linux"<br />
cp -af /boot/vmlinuz-linux "${ESP_DIR}/"<br />
[[ -e /boot/intel-ucode.img ]] && cp -af /boot/intel-ucode.img "${ESP_DIR}/"<br />
[[ -e /boot/amd-ucode.img ]] && cp -af /boot/amd-ucode.img "${ESP_DIR}/"<br />
<br />
PRESETS=('default' 'fallback')<br />
<br />
#default_config="/etc/mkinitcpio.conf"<br />
default_image="${ESP_DIR}/initramfs-linux.img"<br />
default_options=""<br />
<br />
#fallback_config="/etc/mkinitcpio.conf"<br />
fallback_image="${ESP_DIR}/initramfs-linux-fallback.img"<br />
fallback_options="-S autodetect"<br />
</nowiki>}}<br />
To test that, just run:<br />
<br />
# rm /boot/initramfs-linux-fallback.img<br />
# rm /boot/initramfs-linux.img<br />
# mkinitcpio -p linux<br />
<br />
===== Another example =====<br />
<br />
{{hc|/etc/mkinitcpio.d/linux.preset|2=<br />
ESP_DIR="''esp''/EFI/arch"<br />
cp -f "/boot/vmlinuz-linux$suffix" "$ESP_DIR/"<br />
ALL_config="/etc/mkinitcpio.conf"<br />
ALL_kver="$ESP_DIR/vmlinuz-linux$suffix"<br />
PRESETS=('default')<br />
default_config="/etc/mkinitcpio.conf"<br />
default_image="$ESP_DIR/initramfs-linux$suffix.img"<br />
}}<br />
<br />
{{hc|/etc/mkinitcpio.d/linux-zen.preset|2=<br />
suffix='-zen'<br />
source /etc/mkinitcpio.d/linux.preset<br />
}}<br />
<br />
==== Using pacman hook ====<br />
<br />
A last option relies on the [[pacman hooks]] that are run at the end of the transaction.<br />
<br />
The first file is a hook that monitors the relevant files, and it is run if they were modified in the former transaction.<br />
<br />
{{hc|/etc/pacman.d/hooks/999-kernel-efi-copy.hook|<nowiki><br />
[Trigger]<br />
Type = Path<br />
Operation = Install<br />
Operation = Upgrade<br />
Target = usr/lib/modules/*/vmlinuz<br />
Target = usr/lib/initcpio/*<br />
Target = boot/*-ucode.img<br />
<br />
[Action]<br />
Description = Copying linux and initramfs to EFI directory...<br />
When = PostTransaction<br />
Exec = /usr/local/bin/kernel-efi-copy.sh<br />
</nowiki>}}<br />
<br />
The second file is the script itself. Create the file and make it [[executable]]:<br />
<br />
{{hc|/usr/local/bin/kernel-efi-copy.sh|<nowiki><br />
#!/usr/bin/env bash<br />
#<br />
# Copy kernel and initramfs images to EFI directory<br />
#<br />
<br />
ESP_DIR="</nowiki>''esp''<nowiki>/EFI/arch"<br />
<br />
for file in /boot/vmlinuz*<br />
do<br />
cp -af "$file" "$ESP_DIR/$(basename "$file").efi"<br />
[[ $? -ne 0 ]] && exit 1<br />
done<br />
<br />
for file in /boot/initramfs*<br />
do<br />
cp -af "$file" "$ESP_DIR/"<br />
[[ $? -ne 0 ]] && exit 1<br />
done<br />
<br />
[[ -e /boot/intel-ucode.img ]] && cp -af /boot/intel-ucode.img "$ESP_DIR/"<br />
[[ -e /boot/amd-ucode.img ]] && cp -af /boot/amd-ucode.img "$ESP_DIR/"<br />
<br />
exit 0<br />
</nowiki>}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== ESP on software RAID1 ===<br />
<br />
It is possible to make the ESP part of a RAID1 array, but doing so brings the risk of data corruption, and further considerations need to be taken when creating the ESP. See [https://bbs.archlinux.org/viewtopic.php?pid=1398710#p1398710] and [https://bbs.archlinux.org/viewtopic.php?pid=1390741#p1390741] for details and [https://outflux.net/blog/archives/2018/04/19/uefi-booting-and-raid1/ UEFI booting and RAID1] for an in-depth guide with a solution.<br />
<br />
The key part is to use {{ic|--metadata 1.0}} in order to keep the RAID metadata at the end of the partition, otherwise the firmware will not be able to access it:<br />
<br />
# mdadm --create --verbose --level=1 '''--metadata=1.0''' --raid-devices=2 /dev/md/ESP /dev/sda''X'' /dev/sdb''Y''<br />
<br />
=== Firmware does not see the EFI directory ===<br />
<br />
If you give the file system a volume name (with the {{ic|-n}} option), be sure to name it something other than "EFI". That can trigger a bug in some firmwares (due to the volume name matching the EFI directory name) that will cause the firmware to act like the EFI directory does not exist.<br />
<br />
== See also ==<br />
<br />
* [https://blog.uncooperative.org/blog/2014/02/06/the-efi-system-partition/ The EFI system partition and the default boot behavior]<br />
* [https://ramsdenj.com/2016/04/15/multi-boot-linux-with-one-boot-partition.html Multi Boot Linux With One Boot Partition | John Ramsden]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=Fcitx&diff=646355Fcitx2020-12-22T18:05:31Z<p>Mdimitro: /* Set environment variables for IM modules */ General cleanup, added note for XDM users (~/.xsession)</p>
<hr />
<div>[[Category:Input methods]]<br />
[[de:Fcitx]]<br />
[[ja:Fcitx]]<br />
[[zh-hans:Fcitx]]<br />
{{Related articles start}}<br />
{{Related|IBus}}<br />
{{Related|Fcitx5}}<br />
{{Related|SCIM}}<br />
{{Related|uim}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Fcitx|Fcitx]] is a lightweight [[input method]] framework aimed at providing environment independent language support for Linux. It supports a lot of different languages and also provides many useful non-CJK features.<br />
<br />
==Installation==<br />
[[Install]] the {{Pkg|fcitx}} package.<br />
<br />
=== Input method engines ===<br />
<br />
Fcitx provides built-in input methods for Chinese [[wikipedia:Pinyin|Pinyin]] and table-based input (for example [[wikipedia:Wubi method|Wubi]]).<br />
<br />
Depending on the language you wish to type, other input method engines are available:<br />
<br />
==== Chinese ====<br />
<br />
* {{AUR|fcitx-baidupinyin}}, fcitx wrapper for Baidu Pinyin IM engine.<br />
* {{Pkg|fcitx-chewing}} is a popular Zhuyin input engine for Traditional Chinese based on {{Pkg|libchewing}}.<br />
* {{Pkg|fcitx-cloudpinyin}} uses internet sources to provide input candidates. The selected cloud result will be added to local dictionary. It support all fcitx pinyin input method except {{Pkg|fcitx-rime}}.<br />
* {{Pkg|fcitx-googlepinyin}}, Googlepinyin wrapper for fcitx.<br />
* {{Pkg|fcitx-libpinyin}}, based on {{Pkg|libpinyin}}. It has a better algorithm than {{Pkg|fcitx-sunpinyin}}.<br />
* {{Pkg|fcitx-rime}}, based on schemas from the [[Rime IME]] project.<br />
* {{AUR|fcitx-sogoupinyin}}, [http://pinyin.sogou.com/linux/ Sogou input method] supporting Jianpin, fuzzy sound, cloud input, English input, and mixed skin.<br />
* {{Pkg|fcitx-sunpinyin}}, based on {{Pkg|sunpinyin}}. It strikes a good balance between speed and accuracy.<br />
<br />
==== Japanese ====<br />
<br />
* {{Pkg|fcitx-anthy}}, a popular Japanese input engine. However, it is not actively developed anymore.<br />
* {{Pkg|fcitx-mozc}}, based on [[Mozc]], the Open Source Edition of Google Japanese Input.<br />
* {{Pkg|fcitx-kkc}}, a Japanese Kana Kanji input engine, based on {{Pkg|libkkc}}.<br />
* {{Pkg|fcitx-skk}}, a Japanese Kana Kanji input engine, based on {{Pkg|libskk}}.<br />
<br />
==== Other languages ====<br />
<br />
* {{Pkg|fcitx-hangul}}, for typing Korean hangul, based on {{Pkg|libhangul}}.<br />
* {{Pkg|fcitx-m17n}}, for other languages provided by [http://www.nongnu.org/m17n/ M17n].<br />
* {{Pkg|fcitx-sayura}}, for typing Sinhalese.<br />
* {{Pkg|fcitx-unikey}}, for typing Vietnamese characters.<br />
<br />
=== Input method module ===<br />
<br />
To obtain a better experience in Qt programs, install the {{AUR|fcitx-qt4}} and {{Pkg|fcitx-qt5}} input method modules as your need, or the {{Grp|fcitx-im}} group to install {{Pkg|fcitx}} and {{Pkg|fcitx-qt5}}. Without those modules, the input method may work on most applications but you may experience input method hang up, preview window screen location error or no preview error. <br />
<br />
Applications below do not use GTK/Qt input module: <br />
<br />
* Applications use Tk, motif or xlib<br />
* Emacs, Opera, OpenOffice, LibreOffice, Skype, Wine, Java, Xterm, urxvt, WPS<br />
<br />
=== Others ===<br />
<br />
* {{Pkg|fcitx-ui-light}}, light UI for fcitx.<br />
* {{Pkg|fcitx-table-extra}} adds [[wikipedia:Cangjie_input_method|Cangjie]], [[wikipedia:Zhengma_method|Zhengma]], [[wikipedia:Boshiamy_method|Boshiamy]] support.<br />
* {{Pkg|fcitx-table-other}}, tables for Latex, Emoji and others. <br />
* [[#GUI configuration tools]]<br />
<br />
Others packages (including git version) are also available in the [[AUR]]. All components of fcitx will requires fcitx to restart after install.<br />
<br />
== Usage ==<br />
{{Note|You need to have [[Fonts#Chinese, Japanese, Korean, Vietnamese|Chinese, Japanese, Korean or Vietnamese font]] installed to be able to enter the corresponding characters.}}<br />
<br />
=== Desktop Environment Autostart ===<br />
If you are using any XDG compatible desktop environment such as [[KDE]], [[GNOME]], [[Xfce]], [[LXDE]], after you re-login, the autostart should work out of box. If not run the ''fcitx'' executable. To see if fcitx is working correctly, open an application and press {{ic|Ctrl+Space}} (the default shortcut for switching the input method) to invoke fcitx and input some words.<br />
<br />
If fcitx failed to start with your desktop automatically or if you want to change the parameters to start fcitx, configure [[Autostarting#On_Xorg_startup|autostart]] or edit the {{ic|fcitx-autostart.desktop}} file in your {{ic|~/.config/autostart/}} directory (copy it from {{ic|/etc/xdg/autostart/}} if it does not exist yet).<br />
<br />
When other input methods with xim support are also running, fcitx may fail to start due to an xim error. Ensure that no other input methods are running before you start fcitx.<br />
<br />
Also please set the following environment variables to prefer IM modules for GTK/Qt applications.<br />
<br />
=== Set environment variables for IM modules ===<br />
<br />
[[Define]] the environment variables to register the input method modules.<br />
Without these variables, applications may fallback to XIM protocol, except for qt5 applications which do not have XIM support and require an IM module in place.<br />
<br />
As a general recommendation, define the following environment variables in {{ic|~/.pam_environment}}.<br />
This file will be read by the [[PAM|pam_env]] module for all logins, including both X11 and Wayland sessions.<br />
See {{man|8|pam_env}} and {{man|5|pam_env.conf}} for details of its syntax and usage.<br />
<br />
{{hc|~/.pam_environment|<nowiki><br />
GTK_IM_MODULE DEFAULT=fcitx<br />
QT_IM_MODULE DEFAULT=fcitx<br />
XMODIFIERS DEFAULT=\@im=fcitx</nowiki><br />
}}<br />
<br />
In case you do not want to define the above variables in {{ic|~/.pam_environment}} for all your login sessions, please consider adding them to one of the start files for your X11 session.<br />
Most [[Display manager]] such as [[GDM]] and [[SDDM]] will source {{ic|~/.xprofile}} for X11 sessions (but not for Wayland sessions).<br />
The syntax of {{ic|~/.xprofile}} may depend on the specific [[Display manager]] and your login shell, consider the following example and modify it to suit your shell syntax:<br />
<br />
{{hc|~/.xprofile|<nowiki><br />
export GTK_IM_MODULE=fcitx<br />
export QT_IM_MODULE=fcitx<br />
export XMODIFIERS=@im=fcitx</nowiki><br />
}}<br />
<br />
For [[SLiM]] or [[startx]] users, they do NOT source {{ic|~/.xprofile}}, but instead run {{ic|~/.xinitrc}} to start your X11 session. Add the export lines to your {{ic|~/.xinitrc}} before the {{ic|exec YOUR_WM}} line:<br />
<br />
{{hc|~/.xinitrc|<nowiki><br />
export GTK_IM_MODULE=fcitx<br />
export QT_IM_MODULE=fcitx<br />
export XMODIFIERS=@im=fcitx<br />
...<br />
exec YOUR_WM</nowiki><br />
}}<br />
<br />
[[XDM]] sources neither {{ic|~/.xprofile}} nor {{ic|~/.xinitrc}}, but rather by default will source {{ic|~/.xsession}}. The syntax is much the same as for {{ic|~/.xinitrc}}, except the final line should just be {{ic|YOUR_WM}} instead of {{ic|exec YOUR_WM}}.<br />
<br />
Re-login or reboot to make these environment changes effective.<br />
<br />
If ''fcitx'' process does not start automatically, you might need to add {{ic|fcitx &}} in your {{ic|~/.xinitrc}}.<br />
If {{ic|fcitx &}} does not start, type {{ic|sleep 2}} after it<br />
<br />
{{Note|<br />
* Avoid {{ic|.bashrc}} for this, see [[GregsWiki:DotFiles]].<br />
* If all Qt apps have problem with fcitx, run ''qtconfig'' (''qtconfig-qt4''), and go to the third tab, make sure ''fcitx'' is in the ''Default Input Method'' combo-box.<br />
}}<br />
<br />
=== XIM ===<br />
<br />
Optionally, you can use the [[Wikipedia:X Input Method|X Input Method]] (XIM) in your GTK and/or Qt programs without installing the above modules in which case you need to change the corresponding lines above as following:<br />
<br />
GTK_IM_MODULE DEFAULT=xim<br />
QT_IM_MODULE DEFAULT=xim<br />
<br />
If you change it in {{ic|~/.xprofile}} or {{ic|~/.xinitrc}}, add {{ic|export}}.<br />
<br />
{{Warning| Using XIM can sometimes cause problems including not being able to input, no cursor following, word selection window issue, application freeze on input method restart. For these XIM related problems, Fcitx cannot provide any fix or support. This is the same with any other input method framework, so please use the GTK and Qt input method modules instead of xim whenever possible}}<br />
<br />
{{Note|Gtk2 uses {{ic|/usr/lib/gtk-2.0/2.10.0/immodules.cache}} as immodule cache file since 2.24.20. If you have set {{ic|GTM_IM_MODULE_FILE}} environment variable or do not use install script of official packages to update the cache, please change/clear the environment variable and use {{ic|/usr/bin/gtk-query-immodules-2.0 --update-cache}} to update immodule cache.}}<br />
<br />
{{Note| Qt5 applications no longer support XIM protocol as Qt4 did, and rely on IM modules entirely for communicating with fcitx.}}<br />
<br />
==Configuration==<br />
<br />
=== GUI configuration tools ===<br />
<br />
fcitx provides a [[KDE]] configuration module ({{Pkg|kcm-fcitx}}) and a GTK3 configuration tool ({{Pkg|fcitx-configtool}}).<br />
<br />
Run ''fcitx-config-gtk3'' after {{Pkg|fcitx-configtool}} is installed. Unset ''Only Show Current Language'' if you want to enable an input method for a different language.<br />
<br />
Stop fcitx manually before changing configuration, or the change may be lost. <br />
<br />
In order to enable spell checking, press {{ic|Ctrl+Alt+h}} when fcitx is on an input method provided by fcitx-keyboard.<br />
<br />
=== Input methods configuration ===<br />
<br />
You can add/remove input methods in the GUI tools. Note that the search is case sensitive.<br />
<br />
The first set input method is the inactive state, while all the rest will be active states. You generally want the inactive state to be one of the ''Keyboard'' options (e.g. "Keyboard - English (US)"). These options just input based on the keyboard layout in the name.<br />
<br />
Under ''Global Config'', the ''Trigger Input Method'' shortcut will only switch between the inactive and last used active state. The ''Scroll between Input Methods'' will by default only scroll between different active states, but can also be set to include the inactive state in the advanced settings. Furthermore, the ''Scroll between Input Methods'' shortcut has to be pressed in order, e.g. {{ic|ALT_SHIFT}} will only activate if {{ic|alt}} is pressed before {{ic|shift}}.<br />
<br />
Configuration settings for IME's can be found by by setting the keyboard to the desired IME and right-clicking the tray icon.<br />
<br />
=== Change default UI ===<br />
<br />
Fcitx support kimpanel protocol to provide better desktop integration.<br />
<br />
* Gnome-Shell: You can install kimpanel from extensions.gnome.org or {{AUR|gnome-shell-extension-kimpanel-git}}, which provides a similar user experience as ibus-gjs.<br />
* KDE: {{Pkg|kimtoy}} could use skin from Sogou and fcitx.<br />
<br />
=== Extend pinyin dictionary ===<br />
<br />
Pinyin dictionary is located at {{ic|~/.config/fcitx/pinyin}}. File {{ic|pybase.mb}} is for single characters and file {{ic|pyphrase.mb}} defines pinyin phrases. To extend them, put your file into {{ic|/usr/share/fcitx/pinyin}} and restart fcitx.<br />
<br />
=== Skins ===<br />
<br />
You can download skins and extract them to one of the following directories, you can create the directory if it does not exist:<br />
<br />
/usr/share/fcitx/skin #Global settings<br />
~/.config/fcitx/skin #User settings<br />
<br />
=== Cloud Pinyin configuration ===<br />
After installing the {{Pkg|fcitx-cloudpinyin}} input method, restart fcitx. If you could not find it in configuration GUI, enable advanced settings. The cloud query result will be added to current input method dictionary automatically. <br />
<br />
If your network prevents you from accessing Google, change Cloud Pinyin source to Baidu.<br />
<br />
The query result from cloud will list as secondary candidate by default and it is configurable. If the result already exists, only one item is shown. <br />
<br />
{{Note|Set query result as first candidate is not recommend because the dictionary order will be changed if query returns an empty result}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Shortcut keys ===<br />
<br />
Some commonly used default shortcut keys:<br />
<br />
* Ctrl + Space - activates the input method<br />
* Left Shift - temporarily switches to English<br />
* Ctrl + Shift - switch between input methods<br />
* -/= - page forward/backward<br />
* Shift + Space - Full-width, half-width switching<br />
<br />
{{Note|You can modify these shortcut keys in the global configuration of the configuration interface.}}<br />
<br />
=== Vim ===<br />
<br />
If you often use Fcitx under Vim, you can install the {{AUR|vim-fcitx}} plugin, or add the following code to {{ic|~/.vimrc}}. When exiting insert mode, Fcitx is automatically closed, otherwise the reverse:<br />
<br />
"##### auto fcitx ###########<br />
let g:input_toggle = 1<br />
function! Fcitx2en()<br />
let s:input_status = system("fcitx-remote")<br />
if s:input_status == 2<br />
let g:input_toggle = 1<br />
let l:a = system("fcitx-remote -c")<br />
endif<br />
endfunction<br />
<br />
function! Fcitx2zh()<br />
let s:input_status = system("fcitx-remote")<br />
if s:input_status != 2 && g:input_toggle == 1<br />
let l:a = system("fcitx-remote -o")<br />
let g:input_toggle = 0<br />
endif<br />
endfunction<br />
<br />
set ttimeoutlen=150<br />
"Exit insert mode<br />
autocmd InsertLeave * call Fcitx2en()<br />
"Enter insert mode<br />
autocmd InsertEnter * call Fcitx2zh()<br />
"##### auto fcitx end ######<br />
<br />
{{Note|Due to calling external programs, this will significantly slow down the mapping that will repeatedly enter and exit insert mode. It is recommended to rewrite the relevant mapping, and use Vim with Python support in conjunction with fcitx.vim to improve efficiency.}}<br />
<br />
=== Clipboard ===<br />
<br />
[https://www.csslayer.info/wordpress/fcitx-dev/fcitx-clipboard/ Fcitx comes with a clipboard], the shortcut key is {{ic|Ctrl + ;}}, a small function to save the world.<br />
<br />
=== Special symbols ===<br />
<br />
Create {{ic|~/.config/fcitx/data/pySym.mb}}, the content of the file is as follows:<br />
<br />
#The first line with "#" is a comment<br />
#Format: coding symbol<br />
#Code can only be lowercase letters, after pinyin analysis, the longest is 10 (such as py is 2, pinyin is also 2)<br />
#Mathematics symbols<br />
sxfh +<br />
sxfh -<br />
sxfh <<br />
sxfh =<br />
sxfh ><br />
sxfh ±<br />
sxfh ×<br />
sxfh ÷<br />
sxfh ∈<br />
sxfh ∏<br />
sxfh ∑<br />
sxfh ∕<br />
sxfh √<br />
sxfh ∝<br />
<br />
Enter a code directly to match the corresponding special symbol.<br />
<br />
{{Note|The encoding can only be expressed with twenty-six lowercase letters; starting with v is invalid.}}<br />
<br />
===Clipboard Access===<br />
You can use fcitx to input text in you clipboard (as well as a short clipboard history and primary selection). The default trigger key is {{ic|Ctrl-;}}. You can change the trigger key as well as other options in the Clipboard addon configure page.<br />
<br />
{{Note|This is NOT a clipboard manager, it does not hold the selection or change its content as what a clipboard manager is supposed to do. It can only be used to input from the clipboard.}}<br />
<br />
{{Warning| Some clients do not support multi-line input, so you may see the multi-line clipboard content pasted as a single line using fcitx-clipboard. This is either a bug or feature of the program being used and it is not something fcitx is able to help with.}}<br />
<br />
===fcitx-remote===<br />
''fcitx-remote'' is a commandline tool that can be used to control the fcitx state. It is installed with the {{Pkg|fcitx}} package.<br />
<br />
One option worth elaborating upon here is {{ic|fcitx-remote -s ''imname''}}, which switches to the input method identified by {{ic|''imname''}}. The correct {{ic|''imname''}} for an in use input method can be found by executing ''fcitx-diagnose'', and looking under the "## Input Methods:" section.<br />
<br />
=== Input special character ===<br />
<br />
See [[Fcitx5#Input special character]], this content also applies to Fcitx.<br />
<br />
==Troubleshooting==<br />
<br />
=== Disable or change ''Extra key for trigger input method'' [sic] ===<br />
This setting is under the ''Global Config'' tab and defaults to ''SHIFT Both'', meaning that pressing ''either'' shift key will immediately change input methods. Although it should only apply when a shift key is pressed individually, it tends to randomly interrupt typing capital letters, selecting text with the keyboard, etc. while using standard keyboard input.<br />
<br />
In addition, this setting may revert to default without warning at any time. To ensure fcitx's config cannot be modified, you must make fcitx's config file immutable: {{ic|chattr +i ~/.config/fcitx/config}} (as the root user).<br />
<br />
=== Diagnose the problem ===<br />
If you have problems using fcitx, eg. Ctrl+Space fail to work in all applications, then the first thing you should try is to diagnose using {{ic|fcitx-diagnose}}.<br />
The output of {{ic|fcitx-diagnose}} should contain the clue to most common problems.<br />
Providing the output of it will also help when you consult other people(eg. in IRC or forums).<br />
<br />
=== Emacs ===<br />
If your {{ic|LC_CTYPE}} is English, you may not be able to use input method in emacs due to an old emacs bug. You can set your {{ic|LC_CTYPE}} to something else such as {{ic|zh_CN.UTF-8}} before emacs starts to get rid of this problem. <br />
<br />
Note that the corresponding [[locale]] should be [[Locale#Generating locales|generated]] on your your system.<br />
<br />
The default fontset will use `-*-*-*-r-normal--14-*-*-*-*-*-*-*' as basefont (in {{ic|src/xfns.c}}), if you do not have one matched (like terminus or 75dpi things, you can look the output of `xlsfonts'), XIM can not be activated. According to [https://fcitx-im.org/wiki/FAQ#Emacs FAQ] and [[Fonts#Bitmap|Fonts]], it's likely that {{AUR|xorg-fonts-misc-otb}} is the one that should be installed since {{Pkg|xorg-fonts-misc}} no longer provides the required fontset.<br />
<br />
==== Emacs Daemon ====<br />
<br />
If you are using [[Emacs#As_a_daemon|emacs daemon/client mode]], {{ic|LC_CTYPE}} should be set when starting the daemon. For example, by running emacs daemon with {{ic|1=LC_CTYPE=zh_CN.UTF-8 emacs --daemon}}.<br />
<br />
If starting emacs daemon from [[systemd]], [[Systemd#Editing provided_units|set]] {{ic|1=Environment="LC_CTYPE=zh_CN.UTF-8" "XMODIFIERS=@im=fcitx"}} in the unit file.<br />
<br />
({{ic|XMODIFIERS}} may need to be set explicitly here as systemd does not load {{ic|.xprofile}}. Check the {{ic|initial-environment}} variable in emacs to verify both variables are set correctly.)<br />
<br />
=== Ctrl+Space fail to work in GTK programs ===<br />
<br />
This problem sometimes happens especially when the locale is set as English. Please make sure your {{ic|GTK_IM_MODULE}} is set correctly.<br />
<br />
See also [http://fcitx-im.org/wiki/FAQ#When_use_Ctrl_.2B_Space.2C_Fcitx_cannot_be_triggered_on FAQ]<br />
<br />
If you have set the {{ic|*_IM_MODULE}} environment variables to fcitx but cannot activate fcitx, please check if you have installed the corresponding input method modules.<br />
<br />
Some programs can only use xim, if you are using these programs, please make sure your {{ic|XMODIFIERS}} is set properly and be aware of the problems you may have. These programs include all programs that are not using GTK or Qt (e.g. programs that use tk, motif, or xlib directly), emacs, opera, openoffice, libreoffice, skype.<br />
<br />
If you cannot enable fcitx in ''gnome-terminal'' under Gnome and the above way does not work, try:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"<br />
<br />
=== Buildin Chinese Pinyin Default NOT ACTIVE ===<br />
<br />
If your locale is {{ic|en_US.UTF-8}}, fcitx did NOT enable the buildin Chinese Pinyin input method by default. There is only {{ic|fcitx-keyboard-us}} input method enabled. You can get a notice by {{ic|fcitx-diagnose}} command like this:<br />
<br />
## Input Methods:<br />
1. Found 1 enabled input methods:<br />
fcitx-keyboard-us<br />
2. Default input methods:<br />
**You only have one input method enabled, please add a keyboard input method as the first one and your main input method as the second one.**<br />
<br />
Then you should add {{ic|Pinyin}} or {{ic|Shuangpin}} input method to actived input methods by the GUI configure tool.<br />
<br />
=== fcitx and KDE ===<br />
<br />
For some reasons, [[KDE]] does not handle keyboard layouts properly. For example, if you switch from US (English) to LT (Lithuanian), all numbers on the keyboard should produce Lithuanian letters, but they still produce numbers as the output. This can be fixed by these steps:<br />
<br />
# Turn off ''fcitx'' if it is running in the background.<br />
# Disable stuff related to KDE:<br />
## At ''System settings > Input devices > Layouts (tab)'' make sure that ''Configure layouts'' is unchecked.<br />
## At ''System settings > Input devices > Advanced (tab)'' make sure that ''Configure keyboard options'' is unchecked.<br />
# Start ''fcitx'' to start it. You can close the terminal - ''fcitx'' will still be running in the background.<br />
# Set up your needed layouts (right click on the system tray icon, then ''Configure'').<br />
# Right click on the system tray icon, then ''Exit''<br />
<br />
At this point you should have working layouts, native KDE layouts switch icon should appear and you can switch them by mouse scroll or click on it.<br />
<br />
=== Input method switched to English unintentionally ===<br />
<br />
For instance, in XMind, when the user presses {{ic|Enter}} to create a node, input method is always switched to English, and has to be switched back to Chinese manually.<br />
<br />
To fix this issue, open the ''fcitx'' GUI configuration tool (provided by {{Pkg|fcitx-configtool}}), switch to tab ''Global Config'', in dropdown menu ''Share State Among Window'', select ''PerProgram'' or ''All''.<br />
<br />
=== xmodmap settings being overwritten ===<br />
<br />
fcitx controls keyboard layout, so your [[xmodmap]] settings will be overwritten.<br />
Since 4.2.7, Fcitx will try to load {{ic|~/.Xmodmap}} if it exists.<br />
<br />
For more details on how you can save your xmodmap changes see [http://fcitx-im.org/wiki/FAQ#xmodmap_settings_being_overwritten FAQ]<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.com/fcitx/fcitx Fcitx GitLab]<br />
* [http://fcitx-im.org/ Fcitx Wiki]</div>Mdimitrohttps://wiki.archlinux.org/index.php?title=Mercurial&diff=583645Mercurial2019-09-22T17:46:07Z<p>Mdimitro: /* Installation */ Added mention of the dev (-hg) version in the AUR</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[ja:Mercurial]]<br />
[https://www.mercurial-scm.org/ Mercurial] (commonly referred to as '''hg''') is a distributed version control system written in Python and is similar in many ways to [[Git]], [http://bazaar.canonical.com/ Bazaar] and [[Darcs]].<br />
<br />
== Installation ==<br />
[[Install]] {{Pkg|mercurial}}, available in the [[Official repositories]]. For the development version, install {{AUR|mercurial-hg}}.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://www.mercurial-scm.org/wiki/OtherTools#Graphical_user_interfaces Mercurial graphical user interfaces].<br />
<br />
* {{App|EasyMercurial|Simple user interface for the Mercurial distributed version control system.|https://easyhg.org/|{{AUR|easyhg}}}}<br />
* {{App|hgk|Tcl/Tk based tool to browse the history of a repository in a graphical way.|https://www.mercurial-scm.org/wiki/HgkExtension|{{Pkg|mercurial}} + {{Pkg|tk}}}}<br />
* {{App|hgtui|Textual user interface frontend for DSCM mercurial.|https://bitbucket.org/hgtui/hgtui|{{AUR|hgtui-hg}}}}<br />
* {{App|hgview|Qt4 and text based Mercurial log navigator.|https://www.logilab.org/project/hgview/|{{AUR|hgview}}}}<br />
* {{App|[[Wikipedia:TortoiseHg|TortoiseHg]]|Set of graphical tools and a Nautilus extension for the Mercurial distributed revision control system.|https://tortoisehg.bitbucket.io/|{{AUR|tortoisehg}}}}<br />
<br />
== Configuration ==<br />
At the minimum you should configure your username or mercurial will most likely give you an error when trying to commit. Do this by editing {{ic|~/.hgrc}} and adding the following:<br />
<br />
{{hc|~/.hgrc|2=[ui]<br />
username = John Smith <johnsmith@domain.tld>}}<br />
<br />
To use the graphical browser '''hgk''' aka. '''hg view''', add the following to {{ic|~/.hgrc}} (see [https://bbs.archlinux.org/viewtopic.php?id=31999 forum thread]):<br />
<br />
{{hc|~/.hgrc|2=[extensions]<br />
hgk=}}<br />
<br />
You will need to install {{Pkg|tk}} before running '''hg view''' to avoid the rather cryptic error message:<br />
<br />
/usr/bin/env: wish: No such file or directory<br />
<br />
To remove Mercurial warnings of unverified certificate fingerprints, add the following to {{ic|~/.hgrc}} (see [http://mercurial.selenic.com/wiki/CACertificates Mercurial wiki]):<br />
<br />
{{hc|~/.hgrc|2=[web]<br />
cacerts = /etc/ssl/certs/ca-certificates.crt}}<br />
<br />
If you are going to be working with large repositories, you may want to enable the ''progress'' extension by adding it to your {{ic|~/.hgrc}} file:<br />
<br />
{{hc|~/.hgrc|2=[extensions]<br />
progress =}}<br />
<br />
This will show progress bars on longer operations after 3 seconds. If you would like the progress bar to show sooner, you can append the following to your configuration file:<br />
<br />
{{hc|~/.hgrc|2=[progress]<br />
delay = 1.5}}<br />
<br />
== Usage ==<br />
All mercurial commands are initiated with the ''hg'' prefix. To see a list of some of the common commands, run<br />
$ hg help<br />
<br />
You can either work with a pre-existing repository (collection of code or files), or create your own to share.<br />
<br />
To work with a pre-existing repository, you must clone it to a directory of your choice:<br />
<br />
$ mkdir mercurial<br />
$ cd mercurial<br />
$ hg clone http://hg.serpentine.com/tutorial/<br />
<br />
To create you own, change to the directory you wish to share and initiate a mercurial project<br />
<br />
$ cd myfiles<br />
$ hg init myfiles<br />
<br />
=== Dotfiles Repo ===<br />
<br />
{{Merge|Dotfiles|Uses git, but the idea is the same.}}<br />
<br />
If you intend on creating a repo of all your {{ic|~/.}} files, you simply initiate the project in your home folder:<br />
<br />
$ hg init<br />
<br />
It is then just a case of adding the specific files you wish to track:<br />
<br />
$ hg add |file1 file2 file3<br />
<br />
You can then create a {{ic|~/.hgignore}} to ensure that only the files you wish to include in the repository are tracked by mercurial.<br />
{{Tip|If you include: syntax: glob at the top of the {{ic|.hgignore}} file, you can easily exclude groups of files from your repository.}}<br />
<br />
== See also ==<br />
<br />
* [http://hgbook.red-bean.com/read/ Mercurial: The Definitive Guide]<br />
* [http://hginit.com/ hginit.com] - a tutorial by Joel Spolsky<br />
* [http://mercurial.aragost.com/kick-start/en/ Mercurial Kick-Start] one more tutorial by Aragost.<br />
* [http://bitbucket.org Bitbucket] - free and commercial hosting of Mercurial repositories (all Mercurial repositories [https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket will be removed] on 2020-06-01)</div>Mdimitro