https://wiki.archlinux.org/api.php?action=feedcontributions&user=Ketsui&feedformat=atomArchWiki - User contributions [en]2024-03-29T07:03:30ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Microcode&diff=698409Microcode2021-10-06T08:47:39Z<p>Ketsui: /* Early loading */ Use kernel.org link</p>
<hr />
<div>[[Category:CPU]]<br />
[[Category:Security]]<br />
[[de:Microcode]]<br />
[[es:Microcode]]<br />
[[ja:マイクロコード]]<br />
[[ru:Microcode]]<br />
[[zh-hans:Microcode]]<br />
Processor manufacturers release stability and security updates to the processor [[Wikipedia:Microcode|microcode]]. These updates provide bug fixes that can be critical to the stability of your system. Without them, you may experience spurious crashes or unexpected system halts that can be difficult to track down.<br />
<br />
All users with an AMD or Intel CPU should install the microcode updates to ensure system stability.<br />
<br />
Microcode updates are usually shipped with the motherboard's firmware and applied during firmware initialization. Since OEMs might not release firmware updates in a timely fashion and old systems do not get new firmware updates at all, the ability to apply CPU microcode updates during boot was added to the Linux kernel. [https://www.kernel.org/doc/html/latest/x86/microcode.html The Linux microcode loader] supports three loading methods:<br />
<br />
# '''Early loading''' updates the microcode very early during boot, before the initramfs stage, so it is the preferred method. This is mandatory for CPUs with severe hardware bugs, like the Intel Haswell and Broadwell processor families.<br />
# '''Late loading''' updates the microcode after booting which could be too late since the CPU might have already tried to use a bugged instruction set. Even if already using early loading, late loading can still be used to apply a newer microcode update without needing to reboot.<br />
# '''Built-in microcode''' can be compiled into the kernel that is then applied by the early loader.<br />
<br />
== Early loading ==<br />
{{Tip|If the initramfs generator you use already prepends the microcode cpio into the initramfs[https://www.kernel.org/doc/html/latest/x86/microcode.html#early-load-microcode] then none of these configuration is necessary. ({{Pkg|dracut}} for example already does this by default[https://man.archlinux.org/man/dracut.conf.5.en#DESCRIPTION])}}<br />
=== Installation ===<br />
<br />
Depending on the processor, [[install]] the following package:<br />
* {{Pkg|amd-ucode}} for AMD processors,<br />
* {{Pkg|intel-ucode}} for Intel processors.<br />
<br />
Microcode must be loaded by the [[boot loader]]. Because of the wide variability in users' early-boot configuration, microcode updates may not be triggered automatically by Arch's default configuration. Many AUR kernels have followed the path of the official Arch [[kernels]] in this regard.<br />
<br />
These updates must be enabled by adding {{ic|/boot/amd-ucode.img}} or {{ic|/boot/intel-ucode.img}} as the '''first initrd in the bootloader config file'''. This is before the normal initrd file. See below for instructions for common bootloaders.<br />
<br />
In the following sections replace {{ic|''cpu_manufacturer''}} with your CPU manufacturer, i.e. {{ic|amd}} or {{ic|intel}}.<br />
<br />
{{Tip|For [[Install Arch Linux on a removable medium|Arch Linux on a removable drive]], which could be run on any of these processors, install both packages and add both microcode files as {{ic|initrd}} to the boot loader configuration. Their order does not matter as long as they both are specified before the initramfs image.}}<br />
<br />
=== Configuration ===<br />
<br />
==== Enabling early microcode loading in custom kernels ====<br />
<br />
In order for early loading to work in custom kernels, "CPU microcode loading support" needs to be compiled into the kernel, '''not''' compiled as a module. This will enable the "Early load microcode" prompt which should be set to {{ic|Y}}.<br />
<br />
CONFIG_BLK_DEV_INITRD=Y<br />
CONFIG_MICROCODE=y<br />
CONFIG_MICROCODE_INTEL=Y<br />
CONFIG_MICROCODE_AMD=y<br />
<br />
==== GRUB ====<br />
<br />
''grub-mkconfig'' will automatically detect the microcode update and configure [[GRUB]] appropriately. After installing the microcode package, regenerate the GRUB config to activate loading the microcode update by running:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|''grub-mkconfig'' does not add the microcode images to the fallback initramfs boot entry. See {{Bug|60999}}.}}<br />
<br />
Alternatively, users that manage their GRUB config file manually can add {{ic|/boot/''cpu_manufacturer''-ucode.img}} (or {{ic|/''cpu_manufacturer''-ucode.img}} if {{ic|/boot}} is a separate partition) as follows:<br />
<br />
{{hc|/boot/grub/grub.cfg|<br />
...<br />
echo 'Loading initial ramdisk'<br />
initrd '''/boot/''cpu_manufacturer''-ucode.img''' /boot/initramfs-linux.img<br />
...<br />
}}<br />
<br />
Repeat it for each menu entry.<br />
<br />
==== systemd-boot ====<br />
<br />
Use the {{ic|initrd}} option to load the microcode, before the initial ramdisk, as follows:<br />
<br />
{{hc|/boot/loader/entries/''entry''.conf|<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
'''initrd /''cpu_manufacturer''-ucode.img'''<br />
initrd /initramfs-linux.img<br />
...<br />
}}<br />
<br />
The latest microcode {{ic|''cpu_manufacturer''-ucode.img}} must be available at boot time in your [[EFI system partition]] (ESP). The ESP must be mounted as {{ic|/boot}} in order to have the microcode updated every time {{Pkg|amd-ucode}} or {{Pkg|intel-ucode}} is updated. Otherwise, copy {{ic|/boot/''cpu_manufacturer''-ucode.img}} to your ESP at every update of the microcode package.<br />
<br />
===== Unified kernel images =====<br />
<br />
For [[systemd-boot#Preparing a unified kernel image|unified kernel images]], first generate the initrd to integrate by creating a new one as follows: <br />
<br />
$ cat /boot/''cpu_manufacturer''-ucode.img /boot/initramfs-linux.img > my_new_initrd.img<br />
$ objcopy ... --add-section .initrd=my_new_initrd .img<br />
<br />
==== EFISTUB ====<br />
<br />
Append two {{ic|1=initrd=}} options:<br />
<br />
'''initrd=\''cpu_manufacturer''-ucode.img''' initrd=\initramfs-linux.img<br />
<br />
==== rEFInd ====<br />
<br />
Edit boot options in {{ic|/boot/refind_linux.conf}} and add {{ic|1=initrd=boot\''cpu_manufacturer''-ucode.img}} (or {{ic|1=initrd=''cpu_manufacturer''-ucode.img}} if {{ic|/boot}} is a separate partition) as the first initramfs. For example:<br />
<br />
"Boot using default options" "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap '''initrd=boot\''cpu_manufacturer''-ucode.img''' initrd=boot\initramfs-%v.img"<br />
<br />
{{Tip|Users who previously did not specify an {{ic|initrd}} kernel parameter will need to follow the steps described in [[rEFInd#Configuration]] to enable passing of multiple {{ic|initrd}} parameters.}}<br />
<br />
Users employing [[rEFInd#Manual boot stanzas|manual stanzas]] in {{ic|''esp''/EFI/refind/refind.conf}} to define the kernels should simply add {{ic|1=initrd=boot\''cpu_manufacturer''-ucode.img}} (or {{ic|1=initrd=''cpu_manufacturer''-ucode.img}} if {{ic|/boot}} is a separate partition) as required to the options line, and not in the main part of the stanza. E.g.:<br />
<br />
options "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap '''initrd=boot\''cpu_manufacturer''-ucode.img'''"<br />
<br />
==== Syslinux ====<br />
<br />
{{Note|There must be no spaces between the {{ic|''cpu_manufacturer''-ucode.img}} and {{ic|initramfs-linux.img}} initrd files. The {{ic|INITRD}} line must be exactly as illustrated below.}}<br />
<br />
Multiple initrd's can be separated by commas in {{ic|/boot/syslinux/syslinux.cfg}}:<br />
<br />
LABEL arch<br />
MENU LABEL Arch Linux<br />
LINUX ../vmlinuz-linux<br />
INITRD '''../''cpu_manufacturer''-ucode.img''',../initramfs-linux.img<br />
...<br />
<br />
==== LILO ====<br />
<br />
[[LILO]] and potentially other old bootloaders do not support multiple initrd images. In that case, {{ic|''cpu_manufacturer''-ucode.img}} and {{ic|initramfs-linux.img}} will have to be merged into one image.<br />
<br />
{{Warning|The merged image must be recreated after each kernel update!}}<br />
<br />
{{Note|The order is important. The original image {{ic|initramfs-linux.img}} must be placed '''after''' {{ic|''cpu_manufacturer''-ucode.img}} in the resulting image.}}<br />
<br />
To merge both images into one image named {{ic|initramfs-merged.img}}, the following command can be used:<br />
<br />
# cat /boot/''cpu_manufacturer''-ucode.img /boot/initramfs-linux.img > /boot/initramfs-merged.img<br />
<br />
Now, edit {{ic|/etc/lilo.conf}} to load the new image.<br />
<br />
...<br />
initrd=/boot/initramfs-merged.img<br />
...<br />
<br />
And run {{ic|lilo}} as root:<br />
<br />
# lilo<br />
<br />
== Late loading ==<br />
<br />
Late loading of microcode updates happens after the system has booted. It uses files in {{ic|/usr/lib/firmware/amd-ucode/}} and {{ic|/usr/lib/firmware/intel-ucode/}}.<br />
<br />
For AMD processors the microcode update files are provided by {{Pkg|linux-firmware}}.<br />
<br />
For Intel processors no package provides the microcode update files ({{Bug|59841}}). To use late loading you need to manually extract {{ic|intel-ucode/}} from [https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/releases Intel's provided archive].<br />
<br />
=== Enabling late microcode updates ===<br />
<br />
Unlike early loading, late loading of microcode updates on Arch Linux are enabled by default using {{ic|/usr/lib/tmpfiles.d/linux-firmware.conf}}. After boot the file gets parsed by {{man|8|systemd-tmpfiles-setup.service}} and CPU microcode gets updated.<br />
<br />
To manually reload the microcode, e.g. after updating the microcode files in {{ic|/usr/lib/firmware/amd-ucode/}} or {{ic|/usr/lib/firmware/intel-ucode/}}, run:<br />
<br />
# echo 1 > /sys/devices/system/cpu/microcode/reload<br />
<br />
This allows to apply newer microcode updates without rebooting the system. For {{Pkg|linux-firmware}} you can automate it with a [[pacman hook]], e.g.:<br />
<br />
{{hc|/etc/pacman.d/hooks/microcode_reload.hook|2=<br />
[Trigger]<br />
Operation = Upgrade<br />
Type = Path<br />
Target = usr/lib/firmware/amd-ucode/*<br />
<br />
[Action]<br />
Description = Applying CPU microcode updates...<br />
When = PostTransaction<br />
Depends = sh<br />
Exec = /bin/sh -c 'echo 1 > /sys/devices/system/cpu/microcode/reload'<br />
}}<br />
<br />
=== Disabling late microcode updates ===<br />
<br />
For AMD systems the CPU microcode will get updated even if {{Pkg|amd-ucode}} is not installed since the files in {{ic|/usr/lib/firmware/amd-ucode/}} are provided by the {{Pkg|linux-firmware}} package ({{Bug|59840}}).<br />
<br />
For [[virtual machine]]s and [[Wikipedia:Container (virtualization)|containers]] ({{Bug|46591}}) it is not possible to update the CPU microcode, so you may want to disable microcode updates. To do so, you must override the [[tmpfile]] {{ic|/usr/lib/tmpfiles.d/linux-firmware.conf}} that is provided by {{Pkg|linux-firmware}}. It can be done by creating a file with the same filename in {{ic|/etc/tmpfiles.d/}}:<br />
<br />
# ln -s /dev/null /etc/tmpfiles.d/linux-firmware.conf<br />
<br />
== Verifying that microcode got updated on boot ==<br />
<br />
Check the kernel messages with ''journalctl'' to see if the microcode has been updated:<br />
<br />
# journalctl -k --grep=microcode<br />
<br />
On Intel systems one should see something similar to the following on every boot, indicating that microcode is updated very early on:<br />
<br />
microcode: microcode updated early to revision 0xde, date = 2020-05-18<br />
microcode: sig=0x806ec, pf=0x80, revision=0xde<br />
microcode: Microcode Update Driver: v2.2.<br />
<br />
{{Note|The date displayed does not correspond to the version of the {{Pkg|intel-ucode}} package installed. It does show the last time Intel updated the microcode that corresponds to the specific hardware being updated.}}<br />
<br />
It is entirely possible, particularly with newer hardware, that there is no microcode update for the CPU. In that case, the output may look like this:<br />
<br />
microcode: sig=0x806ec, pf=0x80, revision=0xde<br />
microcode: Microcode Update Driver: v2.2.<br />
<br />
On AMD systems using early loading the output would look something like this:<br />
<br />
microcode: microcode updated early to new patch_level=0x0700010f<br />
microcode: CPU0: patch_level=0x0700010f<br />
microcode: CPU1: patch_level=0x0700010f<br />
microcode: CPU2: patch_level=0x0700010f<br />
microcode: CPU3: patch_level=0x0700010f<br />
microcode: Microcode Update Driver: v2.2.<br />
<br />
On AMD systems using late loading the output will show the version of the old microcode before reloading the microcode and the new one once it is reloaded. It would look something like this:<br />
<br />
microcode: CPU0: patch_level=0x0700010b<br />
microcode: CPU1: patch_level=0x0700010b<br />
microcode: CPU2: patch_level=0x0700010b<br />
microcode: CPU3: patch_level=0x0700010b<br />
microcode: Microcode Update Driver: v2.2.<br />
microcode: CPU2: new patch_level=0x0700010f<br />
microcode: CPU0: new patch_level=0x0700010f<br />
microcode: CPU1: new patch_level=0x0700010f<br />
microcode: CPU3: new patch_level=0x0700010f<br />
x86/CPU: CPU features have changed after loading microcode, but might not take effect.<br />
<br />
== Which CPUs accept microcode updates ==<br />
<br />
Users may consult either Intel or AMD at the following links to see if a particular model is supported:<br />
<br />
* [http://www.amd64.org/microcode.html AMD's Operating System Research Center]{{Dead link|2019|07|01}}.<br />
* [https://downloadcenter.intel.com/SearchResult.aspx?lang=eng&keyword=processor%20microcode%20data%20file Intel's download center].<br />
<br />
=== Detecting available microcode update ===<br />
<br />
It is possible to find out if the {{ic|intel-ucode.img}} contains a microcode image for the running CPU with {{Pkg|iucode-tool}}.<br />
<br />
# [[Install]] {{Pkg|intel-ucode}} (changing initrd is not required for detection)<br />
# [[Install]] {{Pkg|iucode-tool}}<br />
# Load the {{ic|cpuid}} kernel module: {{bc|# modprobe cpuid}}<br />
# Extract microcode image and search it for your cpuid:<br/>{{bc|# bsdtar -Oxf /boot/intel-ucode.img {{!}} iucode_tool -tb -lS -}}<br />
# If an update is available, it should show up below ''selected microcodes''<br />
# The microcode might already be in your vendor bios and not show up loading in ''dmesg''. Compare to the current microcode running {{ic|grep microcode /proc/cpuinfo}}<br />
<br />
== See also ==<br />
<br />
* [https://flossexperiences.wordpress.com/2013/11/17/updating-microcodes/ Updating microcodes – Experiences in the community]<br />
* [http://inertiawar.com/microcode/ Notes on Intel Microcode updates – Ben Hawkes]<br />
* [https://www.kernel.org/doc/html/latest/x86/microcode.html Kernel microcode loader – kernel documentation]<br />
* [https://www.anandtech.com/show/8376/intel-disables-tsx-instructions-erratum-found-in-haswell-haswelleep-broadwelly Erratum found in Haswell/Broadwell – AnandTech]<br />
* [https://gitlab.com/iucode-tool/iucode-tool iucode-tool GitLab project]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Microcode&diff=698407Microcode2021-10-06T08:31:57Z<p>Ketsui: /* Early loading */ None of these boot loader configuration is needed if the initramfs generator you use already combines the microcode cpio with the initramfs the kernel uses to find the root, as described in https://github.com/torvalds/linux/blob/master/Documentation/x86/microcode.rst#early-load-microcode</p>
<hr />
<div>[[Category:CPU]]<br />
[[Category:Security]]<br />
[[de:Microcode]]<br />
[[es:Microcode]]<br />
[[ja:マイクロコード]]<br />
[[ru:Microcode]]<br />
[[zh-hans:Microcode]]<br />
Processor manufacturers release stability and security updates to the processor [[Wikipedia:Microcode|microcode]]. These updates provide bug fixes that can be critical to the stability of your system. Without them, you may experience spurious crashes or unexpected system halts that can be difficult to track down.<br />
<br />
All users with an AMD or Intel CPU should install the microcode updates to ensure system stability.<br />
<br />
Microcode updates are usually shipped with the motherboard's firmware and applied during firmware initialization. Since OEMs might not release firmware updates in a timely fashion and old systems do not get new firmware updates at all, the ability to apply CPU microcode updates during boot was added to the Linux kernel. [https://www.kernel.org/doc/html/latest/x86/microcode.html The Linux microcode loader] supports three loading methods:<br />
<br />
# '''Early loading''' updates the microcode very early during boot, before the initramfs stage, so it is the preferred method. This is mandatory for CPUs with severe hardware bugs, like the Intel Haswell and Broadwell processor families.<br />
# '''Late loading''' updates the microcode after booting which could be too late since the CPU might have already tried to use a bugged instruction set. Even if already using early loading, late loading can still be used to apply a newer microcode update without needing to reboot.<br />
# '''Built-in microcode''' can be compiled into the kernel that is then applied by the early loader.<br />
<br />
== Early loading ==<br />
{{Tip|If the initramfs generator you use already prepends the microcode cpio into the initramfs[https://github.com/torvalds/linux/blob/master/Documentation/x86/microcode.rst#early-load-microcode] then none of these configuration is necessary. ({{Pkg|dracut}} for example already does this by default[https://man.archlinux.org/man/dracut.conf.5.en#DESCRIPTION])}}<br />
=== Installation ===<br />
<br />
Depending on the processor, [[install]] the following package:<br />
* {{Pkg|amd-ucode}} for AMD processors,<br />
* {{Pkg|intel-ucode}} for Intel processors.<br />
<br />
Microcode must be loaded by the [[boot loader]]. Because of the wide variability in users' early-boot configuration, microcode updates may not be triggered automatically by Arch's default configuration. Many AUR kernels have followed the path of the official Arch [[kernels]] in this regard.<br />
<br />
These updates must be enabled by adding {{ic|/boot/amd-ucode.img}} or {{ic|/boot/intel-ucode.img}} as the '''first initrd in the bootloader config file'''. This is before the normal initrd file. See below for instructions for common bootloaders.<br />
<br />
In the following sections replace {{ic|''cpu_manufacturer''}} with your CPU manufacturer, i.e. {{ic|amd}} or {{ic|intel}}.<br />
<br />
{{Tip|For [[Install Arch Linux on a removable medium|Arch Linux on a removable drive]], which could be run on any of these processors, install both packages and add both microcode files as {{ic|initrd}} to the boot loader configuration. Their order does not matter as long as they both are specified before the initramfs image.}}<br />
<br />
=== Configuration ===<br />
<br />
==== Enabling early microcode loading in custom kernels ====<br />
<br />
In order for early loading to work in custom kernels, "CPU microcode loading support" needs to be compiled into the kernel, '''not''' compiled as a module. This will enable the "Early load microcode" prompt which should be set to {{ic|Y}}.<br />
<br />
CONFIG_BLK_DEV_INITRD=Y<br />
CONFIG_MICROCODE=y<br />
CONFIG_MICROCODE_INTEL=Y<br />
CONFIG_MICROCODE_AMD=y<br />
<br />
==== GRUB ====<br />
<br />
''grub-mkconfig'' will automatically detect the microcode update and configure [[GRUB]] appropriately. After installing the microcode package, regenerate the GRUB config to activate loading the microcode update by running:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|''grub-mkconfig'' does not add the microcode images to the fallback initramfs boot entry. See {{Bug|60999}}.}}<br />
<br />
Alternatively, users that manage their GRUB config file manually can add {{ic|/boot/''cpu_manufacturer''-ucode.img}} (or {{ic|/''cpu_manufacturer''-ucode.img}} if {{ic|/boot}} is a separate partition) as follows:<br />
<br />
{{hc|/boot/grub/grub.cfg|<br />
...<br />
echo 'Loading initial ramdisk'<br />
initrd '''/boot/''cpu_manufacturer''-ucode.img''' /boot/initramfs-linux.img<br />
...<br />
}}<br />
<br />
Repeat it for each menu entry.<br />
<br />
==== systemd-boot ====<br />
<br />
Use the {{ic|initrd}} option to load the microcode, before the initial ramdisk, as follows:<br />
<br />
{{hc|/boot/loader/entries/''entry''.conf|<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
'''initrd /''cpu_manufacturer''-ucode.img'''<br />
initrd /initramfs-linux.img<br />
...<br />
}}<br />
<br />
The latest microcode {{ic|''cpu_manufacturer''-ucode.img}} must be available at boot time in your [[EFI system partition]] (ESP). The ESP must be mounted as {{ic|/boot}} in order to have the microcode updated every time {{Pkg|amd-ucode}} or {{Pkg|intel-ucode}} is updated. Otherwise, copy {{ic|/boot/''cpu_manufacturer''-ucode.img}} to your ESP at every update of the microcode package.<br />
<br />
===== Unified kernel images =====<br />
<br />
For [[systemd-boot#Preparing a unified kernel image|unified kernel images]], first generate the initrd to integrate by creating a new one as follows: <br />
<br />
$ cat /boot/''cpu_manufacturer''-ucode.img /boot/initramfs-linux.img > my_new_initrd.img<br />
$ objcopy ... --add-section .initrd=my_new_initrd .img<br />
<br />
==== EFISTUB ====<br />
<br />
Append two {{ic|1=initrd=}} options:<br />
<br />
'''initrd=\''cpu_manufacturer''-ucode.img''' initrd=\initramfs-linux.img<br />
<br />
==== rEFInd ====<br />
<br />
Edit boot options in {{ic|/boot/refind_linux.conf}} and add {{ic|1=initrd=boot\''cpu_manufacturer''-ucode.img}} (or {{ic|1=initrd=''cpu_manufacturer''-ucode.img}} if {{ic|/boot}} is a separate partition) as the first initramfs. For example:<br />
<br />
"Boot using default options" "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap '''initrd=boot\''cpu_manufacturer''-ucode.img''' initrd=boot\initramfs-%v.img"<br />
<br />
{{Tip|Users who previously did not specify an {{ic|initrd}} kernel parameter will need to follow the steps described in [[rEFInd#Configuration]] to enable passing of multiple {{ic|initrd}} parameters.}}<br />
<br />
Users employing [[rEFInd#Manual boot stanzas|manual stanzas]] in {{ic|''esp''/EFI/refind/refind.conf}} to define the kernels should simply add {{ic|1=initrd=boot\''cpu_manufacturer''-ucode.img}} (or {{ic|1=initrd=''cpu_manufacturer''-ucode.img}} if {{ic|/boot}} is a separate partition) as required to the options line, and not in the main part of the stanza. E.g.:<br />
<br />
options "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap '''initrd=boot\''cpu_manufacturer''-ucode.img'''"<br />
<br />
==== Syslinux ====<br />
<br />
{{Note|There must be no spaces between the {{ic|''cpu_manufacturer''-ucode.img}} and {{ic|initramfs-linux.img}} initrd files. The {{ic|INITRD}} line must be exactly as illustrated below.}}<br />
<br />
Multiple initrd's can be separated by commas in {{ic|/boot/syslinux/syslinux.cfg}}:<br />
<br />
LABEL arch<br />
MENU LABEL Arch Linux<br />
LINUX ../vmlinuz-linux<br />
INITRD '''../''cpu_manufacturer''-ucode.img''',../initramfs-linux.img<br />
...<br />
<br />
==== LILO ====<br />
<br />
[[LILO]] and potentially other old bootloaders do not support multiple initrd images. In that case, {{ic|''cpu_manufacturer''-ucode.img}} and {{ic|initramfs-linux.img}} will have to be merged into one image.<br />
<br />
{{Warning|The merged image must be recreated after each kernel update!}}<br />
<br />
{{Note|The order is important. The original image {{ic|initramfs-linux.img}} must be placed '''after''' {{ic|''cpu_manufacturer''-ucode.img}} in the resulting image.}}<br />
<br />
To merge both images into one image named {{ic|initramfs-merged.img}}, the following command can be used:<br />
<br />
# cat /boot/''cpu_manufacturer''-ucode.img /boot/initramfs-linux.img > /boot/initramfs-merged.img<br />
<br />
Now, edit {{ic|/etc/lilo.conf}} to load the new image.<br />
<br />
...<br />
initrd=/boot/initramfs-merged.img<br />
...<br />
<br />
And run {{ic|lilo}} as root:<br />
<br />
# lilo<br />
<br />
== Late loading ==<br />
<br />
Late loading of microcode updates happens after the system has booted. It uses files in {{ic|/usr/lib/firmware/amd-ucode/}} and {{ic|/usr/lib/firmware/intel-ucode/}}.<br />
<br />
For AMD processors the microcode update files are provided by {{Pkg|linux-firmware}}.<br />
<br />
For Intel processors no package provides the microcode update files ({{Bug|59841}}). To use late loading you need to manually extract {{ic|intel-ucode/}} from [https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/releases Intel's provided archive].<br />
<br />
=== Enabling late microcode updates ===<br />
<br />
Unlike early loading, late loading of microcode updates on Arch Linux are enabled by default using {{ic|/usr/lib/tmpfiles.d/linux-firmware.conf}}. After boot the file gets parsed by {{man|8|systemd-tmpfiles-setup.service}} and CPU microcode gets updated.<br />
<br />
To manually reload the microcode, e.g. after updating the microcode files in {{ic|/usr/lib/firmware/amd-ucode/}} or {{ic|/usr/lib/firmware/intel-ucode/}}, run:<br />
<br />
# echo 1 > /sys/devices/system/cpu/microcode/reload<br />
<br />
This allows to apply newer microcode updates without rebooting the system. For {{Pkg|linux-firmware}} you can automate it with a [[pacman hook]], e.g.:<br />
<br />
{{hc|/etc/pacman.d/hooks/microcode_reload.hook|2=<br />
[Trigger]<br />
Operation = Upgrade<br />
Type = Path<br />
Target = usr/lib/firmware/amd-ucode/*<br />
<br />
[Action]<br />
Description = Applying CPU microcode updates...<br />
When = PostTransaction<br />
Depends = sh<br />
Exec = /bin/sh -c 'echo 1 > /sys/devices/system/cpu/microcode/reload'<br />
}}<br />
<br />
=== Disabling late microcode updates ===<br />
<br />
For AMD systems the CPU microcode will get updated even if {{Pkg|amd-ucode}} is not installed since the files in {{ic|/usr/lib/firmware/amd-ucode/}} are provided by the {{Pkg|linux-firmware}} package ({{Bug|59840}}).<br />
<br />
For [[virtual machine]]s and [[Wikipedia:Container (virtualization)|containers]] ({{Bug|46591}}) it is not possible to update the CPU microcode, so you may want to disable microcode updates. To do so, you must override the [[tmpfile]] {{ic|/usr/lib/tmpfiles.d/linux-firmware.conf}} that is provided by {{Pkg|linux-firmware}}. It can be done by creating a file with the same filename in {{ic|/etc/tmpfiles.d/}}:<br />
<br />
# ln -s /dev/null /etc/tmpfiles.d/linux-firmware.conf<br />
<br />
== Verifying that microcode got updated on boot ==<br />
<br />
Check the kernel messages with ''journalctl'' to see if the microcode has been updated:<br />
<br />
# journalctl -k --grep=microcode<br />
<br />
On Intel systems one should see something similar to the following on every boot, indicating that microcode is updated very early on:<br />
<br />
microcode: microcode updated early to revision 0xde, date = 2020-05-18<br />
microcode: sig=0x806ec, pf=0x80, revision=0xde<br />
microcode: Microcode Update Driver: v2.2.<br />
<br />
{{Note|The date displayed does not correspond to the version of the {{Pkg|intel-ucode}} package installed. It does show the last time Intel updated the microcode that corresponds to the specific hardware being updated.}}<br />
<br />
It is entirely possible, particularly with newer hardware, that there is no microcode update for the CPU. In that case, the output may look like this:<br />
<br />
microcode: sig=0x806ec, pf=0x80, revision=0xde<br />
microcode: Microcode Update Driver: v2.2.<br />
<br />
On AMD systems using early loading the output would look something like this:<br />
<br />
microcode: microcode updated early to new patch_level=0x0700010f<br />
microcode: CPU0: patch_level=0x0700010f<br />
microcode: CPU1: patch_level=0x0700010f<br />
microcode: CPU2: patch_level=0x0700010f<br />
microcode: CPU3: patch_level=0x0700010f<br />
microcode: Microcode Update Driver: v2.2.<br />
<br />
On AMD systems using late loading the output will show the version of the old microcode before reloading the microcode and the new one once it is reloaded. It would look something like this:<br />
<br />
microcode: CPU0: patch_level=0x0700010b<br />
microcode: CPU1: patch_level=0x0700010b<br />
microcode: CPU2: patch_level=0x0700010b<br />
microcode: CPU3: patch_level=0x0700010b<br />
microcode: Microcode Update Driver: v2.2.<br />
microcode: CPU2: new patch_level=0x0700010f<br />
microcode: CPU0: new patch_level=0x0700010f<br />
microcode: CPU1: new patch_level=0x0700010f<br />
microcode: CPU3: new patch_level=0x0700010f<br />
x86/CPU: CPU features have changed after loading microcode, but might not take effect.<br />
<br />
== Which CPUs accept microcode updates ==<br />
<br />
Users may consult either Intel or AMD at the following links to see if a particular model is supported:<br />
<br />
* [http://www.amd64.org/microcode.html AMD's Operating System Research Center]{{Dead link|2019|07|01}}.<br />
* [https://downloadcenter.intel.com/SearchResult.aspx?lang=eng&keyword=processor%20microcode%20data%20file Intel's download center].<br />
<br />
=== Detecting available microcode update ===<br />
<br />
It is possible to find out if the {{ic|intel-ucode.img}} contains a microcode image for the running CPU with {{Pkg|iucode-tool}}.<br />
<br />
# [[Install]] {{Pkg|intel-ucode}} (changing initrd is not required for detection)<br />
# [[Install]] {{Pkg|iucode-tool}}<br />
# Load the {{ic|cpuid}} kernel module: {{bc|# modprobe cpuid}}<br />
# Extract microcode image and search it for your cpuid:<br/>{{bc|# bsdtar -Oxf /boot/intel-ucode.img {{!}} iucode_tool -tb -lS -}}<br />
# If an update is available, it should show up below ''selected microcodes''<br />
# The microcode might already be in your vendor bios and not show up loading in ''dmesg''. Compare to the current microcode running {{ic|grep microcode /proc/cpuinfo}}<br />
<br />
== See also ==<br />
<br />
* [https://flossexperiences.wordpress.com/2013/11/17/updating-microcodes/ Updating microcodes – Experiences in the community]<br />
* [http://inertiawar.com/microcode/ Notes on Intel Microcode updates – Ben Hawkes]<br />
* [https://www.kernel.org/doc/html/latest/x86/microcode.html Kernel microcode loader – kernel documentation]<br />
* [https://www.anandtech.com/show/8376/intel-disables-tsx-instructions-erratum-found-in-haswell-haswelleep-broadwelly Erratum found in Haswell/Broadwell – AnandTech]<br />
* [https://gitlab.com/iucode-tool/iucode-tool iucode-tool GitLab project]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Dm-crypt/Specialties&diff=645865Dm-crypt/Specialties2020-12-18T10:30:38Z<p>Ketsui: /* Discard/TRIM support for solid state drives (SSD) */ refresh expects names in /dev/mapper</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[es:Dm-crypt (Español)/Specialties]]<br />
[[ja:Dm-crypt/特記事項]]<br />
[[pl:Dm-crypt (Polski)/Specialties]]<br />
[[pt:Dm-crypt (Português)/Specialties]]<br />
== Securing the unencrypted boot partition ==<br />
<br />
The {{ic|/boot}} partition and the [[Master Boot Record]] are the two areas of the disk that are not encrypted, even in an [[dm-crypt/Encrypting an entire system|encrypted root]] configuration. They cannot usually be encrypted because the [[boot loader]] and BIOS (respectively) are unable to unlock a dm-crypt container in order to continue the boot process. An exception is [[GRUB]], which gained a feature to unlock a LUKS encrypted {{ic|/boot}} - see [[dm-crypt/Encrypting an entire system#Encrypted boot partition (GRUB)]]. <br />
<br />
This section describes steps that can be taken to make the boot process more secure. <br />
<br />
{{Warning|Note that securing the {{ic|/boot}} partition and MBR can mitigate numerous attacks that occur during the boot process, but systems configured this way may still be vulnerable to BIOS/UEFI/firmware tampering, hardware keyloggers, cold boot attacks, and many other threats that are beyond the scope of this article. For an overview of system-trust issues and how these relate to full-disk encryption, refer to [http://www.youtube.com/watch?v&#61;pKeiKYA03eE].}}<br />
<br />
=== Booting from a removable device ===<br />
<br />
{{Warning|systemd version 230 cryptsetup generator emits {{ic|RequiresMountsFor}} for crypto keyfile. Therefore, when the filesystem that holds this file is unmounted, it also stops cryptsetup service. This behavior is incorrect because the filesystem and cryptokey is required only once, when the crypto container is initially setup. See [https://github.com/systemd/systemd/issues/3816 systemd issue 3816].}}<br />
<br />
Using a separate device to boot a system is a fairly straightforward procedure, and offers a significant security improvement against some kinds of attacks. Two vulnerable parts of a system employing an [[Dm-crypt/Encrypting_an_entire_system|encrypted root filesystem]] are<br />
<br />
* the [[Master Boot Record]], and<br />
* the {{ic|/boot}} partition.<br />
<br />
These must be stored unencrypted in order for the system to boot. In order to protect these from tampering, it is advisable to store them on a removable medium, such as a USB drive, and boot from that drive instead of the hard disk. As long as you keep the drive with you at all times, you can be certain that those components have not been tampered with, making authentication far more secure when unlocking your system.<br />
<br />
It is assumed that you already have your system configured with a dedicated partition mounted at {{ic|/boot}}. If you do not, please follow the steps in [[dm-crypt/System configuration#Boot loader]], substituting your hard disk for a removable drive.<br />
<br />
{{Note|You must make sure your system supports booting from the chosen medium, be it a USB drive, an external hard drive, an SD card, or anything else.}}<br />
<br />
Prepare the removable drive ({{ic|/dev/sdx}}).<br />
<br />
# gdisk /dev/sdx #format if necessary. Alternatively, cgdisk, fdisk, cfdisk, gparted...<br />
# mkfs.ext2 /dev/sdx1<br />
# mount /dev/sdx1 /mnt<br />
<br />
Copy your existing {{ic|/boot}} contents to the new one.<br />
<br />
# cp -ai /boot/* /mnt/<br />
<br />
Mount the new partition. Do not forget to update your [[fstab]] file accordingly.<br />
<br />
# umount /boot<br />
# umount /mnt<br />
# mount /dev/sdx1 /boot<br />
# genfstab -p -U / > /etc/fstab<br />
<br />
Update [[GRUB]]. {{ic|grub-mkconfig}} should detect the new partition UUID automatically, but custom menu entries may need to be updated manually.<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
# grub-install /dev/sdx #install to the removable device, not the hard disk.<br />
<br />
Reboot and test the new configuration. Remember to set your device boot order accordingly in your BIOS or [[UEFI]]. If the system fails to boot, you should still be able to boot from the hard drive in order to correct the problem.<br />
<br />
=== chkboot ===<br />
<br />
{{Warning|chkboot makes a {{ic|/boot}} partition '''tamper-evident''', not '''tamper-proof'''. By the time the chkboot script is run, you have already typed your password into a potentially compromised boot loader, kernel, or initrd. If your system fails the chkboot integrity test, no assumptions can be made about the security of your data.}}<br />
<br />
Referring to an article from the ct-magazine (Issue 3/12, page 146, 01.16.2012, [http://www.heise.de/ct/inhalt/2012/03/6/]) the following script checks files under {{ic|/boot}} for changes of SHA-1 hash, inode, and occupied blocks on the hard drive. It also checks the [[Master Boot Record]]. The script cannot prevent certain type of attacks, but a lot are made harder. No configuration of the script itself is stored in unencrypted {{ic|/boot}}. With a locked/powered-off encrypted system, this makes it harder for some attackers because it is not apparent that an automatic checksum comparison of the partition is done upon boot. However, an attacker who anticipates these precautions can manipulate the firmware to run their own code on top of your kernel and intercept file system access, e.g. to {{ic|boot}}, and present the untampered files. Generally, no security measures below the level of the firmware are able to guarantee trust and tamper evidence.<br />
<br />
The script with installation instructions is [ftp://ftp.heise.de/pub/ct/listings/1203-146.zip available] (Author: Juergen Schmidt, ju at heisec.de; License: GPLv2). There is also package {{AUR|chkboot}} to [[install]].<br />
<br />
After installation add a service file (the package includes one based on the following) and [[enable]] it: <br />
<br />
[Unit]<br />
Description=Check that boot is what we want<br />
Requires=basic.target<br />
After=basic.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/local/bin/chkboot.sh<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
There is a small caveat for systemd. At the time of writing, the original {{ic|chkboot.sh}} script provided contains an empty space at the beginning of {{ic|<u> </u>#!/bin/bash}} which has to be removed for the service to start successfully.<br />
<br />
As {{ic|/usr/local/bin/chkboot_user.sh}} needs to be executed right after login, you need to add it to the [[autostart]] (e.g. under KDE -> ''System Settings -> Startup and Shutdown -> Autostart''; GNOME 3: ''gnome-session-properties''). <br />
<br />
With Arch Linux, changes to {{ic|/boot}} are pretty frequent, for example by new kernels rolling-in. Therefore it may be helpful to use the scripts with every full system update. One way to do so: <br />
<br />
#!/bin/bash<br />
#<br />
# Note: Insert your <user> and execute it with sudo for pacman & chkboot to work automagically<br />
#<br />
echo "Pacman update [1] Quickcheck before updating" & <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user> <br />
/usr/local/bin/chkboot.sh<br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user> <br />
echo "Pacman update [2] Syncing repos for pacman" <br />
pacman -Syu<br />
/usr/local/bin/chkboot.sh<br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user><br />
echo "Pacman update [3] All done, let us roll on ..."<br />
<br />
=== mkinitcpio-chkcryptoboot ===<br />
<br />
{{Warning|This hook does '''not''' encrypt [[GRUB]]'s core (MBR) code or EFI stub, nor does it protect against situations where an attacker is able to modify the behaviour of the bootloader to compromise the kernel and/or initramfs at run-time.}}<br />
<br />
{{aur|mkinitcpio-chkcryptoboot}} is a [[mkinitcpio]] hook that performs integrity checks during early-userspace and advises the user not to enter their root partition password if the system appears to have been compromised. Security is achieved through an [[dm-crypt/Encrypting an entire system#Encrypted boot partition (GRUB)|encrypted boot partition]], which is unlocked using [[GRUB#Encrypted /boot|GRUB]]'s {{ic|cryptodisk.mod}} module, and a root filesystem partition, which is encrypted with a password different from the former. This way, the [[initramfs]] and [[kernel]] are secured against offline tampering, and the root partition can remain secure even if the {{ic|/boot}} partition password is entered on a compromised machine (provided that the chkcryptoboot hook detects the compromise, and is not itself compromised at run-time). <br />
<br />
This hook requires {{Pkg|grub}} release >=2.00 to function, and a dedicated, LUKS encrypted {{ic|/boot}} partition with its own password in order to be secure.<br />
<br />
==== Installation ====<br />
<br />
[[Install]] {{aur|mkinitcpio-chkcryptoboot}} and edit {{ic|/etc/default/chkcryptoboot.conf}}. If you want the ability of detecting if your boot partition was bypassed, edit the {{ic|CMDLINE_NAME}} and {{ic|CMDLINE_VALUE}} variables, with values known only to you. You can follow the advice of using two hashes as is suggested right after the installation. Also, be sure to make the appropriate changes to the [[kernel command line]] in {{ic|/etc/default/grub}}. Edit the {{ic|1=HOOKS=}} line in {{ic|/etc/mkinitcpio.conf}}, and insert the {{ic|chkcryptoboot}} hook '''before''' {{ic|encrypt}}. When finished, [[regenerate the initramfs]].<br />
<br />
==== Technical Overview ====<br />
<br />
{{aur|mkinitcpio-chkcryptoboot}} consists of an install hook and a run-time hook for mkinitcpio. The install hook runs every time the initramfs is rebuilt, and hashes the GRUB [[EFI]] stub ({{ic|$esp/EFI/grub_uefi/grubx64.efi}}) (in the case of [[UEFI]] systems) or the first 446 bytes of the disk on which GRUB is installed (in the case of BIOS systems), and stores that hash inside the initramfs located inside the encrypted {{ic|/boot}} partition. When the system is booted, GRUB prompts for the {{ic|/boot}} password, then the run-time hook performs the same hashing operation and compares the resulting hashes before prompting for the root partition password. If they do not match, the hook will print an error like this:<br />
<br />
CHKCRYPTOBOOT ALERT!<br />
CHANGES HAVE BEEN DETECTED IN YOUR BOOT LOADER EFISTUB!<br />
YOU ARE STRONGLY ADVISED NOT TO ENTER YOUR ROOT CONTAINER PASSWORD!<br />
Please type uppercase yes to continue:<br />
<br />
In addition to hashing the boot loader, the hook also checks the parameters of the running kernel against those configured in {{ic|/etc/default/chkcryptoboot.conf}}. This is checked both at run-time and after the boot process is done. This allows the hook to detect if GRUB's configuration was not bypassed at run-time and afterwards to detect if the entire {{ic|/boot}} partition was not bypassed.<br />
<br />
For BIOS systems the hook creates a hash of GRUB's first stage bootloader (installed to the first 446 bytes of the bootdevice) to compare at the later boot processes. The main second-stage GRUB bootloader {{ic|core.img}} is not checked.<br />
<br />
=== AIDE ===<br />
<br />
Alternatively to above scripts, a hash check can be set up with [[AIDE]] which can be customized via a very flexible configuration file. <br />
<br />
=== STARK ===<br />
<br />
While one of these methods should serve the purpose for most users, they do not address all security problems associated with the unencrypted {{ic|/boot}}. One approach which endeavours to provide a fully authenticated boot chain was published with POTTS as an academic thesis to implement the [https://www1.informatik.uni-erlangen.de/stark STARK] authentication framework. <br />
<br />
The POTTS proof-of-concept uses Arch Linux as a base distribution and implements a system boot chain with:<br />
<br />
* POTTS - a boot menu for a one-time authentication message prompt <br />
* TrustedGrub - a [[GRUB Legacy]] implementation which authenticates the kernel and initramfs against [[Trusted Platform Module|TPM chip]] PCR registers <br />
* TRESOR - a kernel patch which implements AES but keeps the master-key not in RAM but in CPU registers during runtime. <br />
<br />
As part of the thesis [https://13.tc/p/potts/manual.html installation] instructions based on Arch Linux (ISO as of 2013-01) have been published. If you want to try it, be aware these tools are not in standard repositories and the solution will be time consuming to maintain.<br />
<br />
== Using GPG, LUKS, or OpenSSL Encrypted Keyfiles ==<br />
<br />
The following forum posts give instructions to use two factor authentication, gpg or openssl encrypted keyfiles, instead of a plaintext keyfile described earlier in this wiki article [https://bbs.archlinux.org/viewtopic.php?id=120243 System Encryption using LUKS with GPG encrypted keys]:<br />
<br />
* GnuPG: [https://bbs.archlinux.org/viewtopic.php?pid=943338#p943338 Post regarding GPG encrypted keys] This post has the generic instructions.<br />
* OpenSSL: [https://bbs.archlinux.org/viewtopic.php?pid=947805#p947805 Post regarding OpenSSL encrypted keys] This post only has the {{ic|ssldec}} hooks.<br />
* OpenSSL: [https://bbs.archlinux.org/viewtopic.php?id=155393 Post regarding OpenSSL salted bf-cbc encrypted keys] This post has the {{ic|bfkf}} initcpio hooks, install, and encrypted keyfile generator scripts.<br />
* LUKS: [https://bbs.archlinux.org/viewtopic.php?pid=1502651#p1502651 Post regarding LUKS encrypted keys] with a {{ic|lukskey}} initcpio hook. Or [[#Encrypted /boot and a detached LUKS header on USB]] below with a custom encrypt hook for initcpio.<br />
<br />
Note that:<br />
<br />
* You can follow the above instructions with only two primary partitions, one boot partition (required because of encryption) and one primary LVM partition. Within the LVM partition you can have as many partitions as you need, but most importantly it should contain at least root, swap, and home logical volume partitions. This has the added benefit of having only one keyfile for all your partitions, and having the ability to hibernate your computer (suspend to disk) where the swap partition is encrypted. If you decide to do so your hooks in {{ic|/etc/mkinitcpio.conf}} should look like this:{{bc|1=HOOKS=( ... usb usbinput (etwo or ssldec) encrypt (if using openssl) lvm2 resume ... )}} and you should add {{bc|1=resume=/dev/<VolumeGroupName>/<LVNameOfSwap>}} to your [[kernel parameters]].<br />
* If you need to temporarily store the unencrypted keyfile somewhere, do not store them on an unencrypted disk. Even better make sure to store them to RAM such as {{ic|/dev/shm}}.<br />
* If you want to use a GPG encrypted keyfile, you need to use a statically compiled GnuPG version 1.4 or you could edit the hooks and use this AUR package {{AUR|gnupg1}}<br />
* It is possible that an update to OpenSSL could break the custom {{ic|ssldec}} mentioned in the second forum post.<br />
<br />
== Remote unlocking of the root (or other) partition ==<br />
<br />
If you want to be able to reboot a fully LUKS-encrypted system remotely, or start it with a [[Wake-on-LAN]] service, you will need a way to enter a passphrase for the root partition/volume at startup. This can be achieved by running a [[mkinitcpio]] hook that configures a network interface. Some packages listed below contribute various [[Mkinitcpio#Build hooks|mkinitcpio build hooks]] to ease with the configuration.<br />
<br />
{{Note|<br />
* Keep in mind to use kernel device names for the network interface (e.g. {{ic|eth0}}) and not [[udev|udev's]] ones (e.g. {{ic|enp1s0}}), as those will not work.<br />
* By default, Predictable Network Interface Names are activated and '''change''' the kernel device name during late boot. Use dmesg and look what your Network kernel module does to find the original name (e.g. {{ic|eth0}})<br />
* It could be necessary to add the module for your [[Network configuration/Ethernet#Device driver|ethernet]] or [[Network configuration/Wireless#Device driver|wireless]] network card to the [[Mkinitcpio#MODULES|MODULES]] array.<br />
}}<br />
<br />
=== Remote unlocking (hooks: systemd, systemd-tool) ===<br />
<br />
The package {{Pkg|mkinitcpio-systemd-tool}} provides a {{Pkg|systemd}}-centric mkinitcpio hook named ''systemd-tool'' with the following set of features for systemd in initramfs:<br />
<br />
{| class="wikitable"<br />
|- style="vertical-align:top;"<br />
| width=50% style="padding:10px;" |<br />
Core features provided by the hook:<br />
* unified systemd + mkinitcpio configuration<br />
* automatic provisioning of binary and config resources<br />
* on-demand invocation of mkinitcpio scripts and in-line functions <br />
| width=50% style="padding:10px;" |<br />
Features provided by the included service units:<br />
* initrd debugging<br />
* early network setup<br />
* interactive user shell<br />
* remote ssh access in initrd<br />
* cryptsetup + custom password agent <br />
|}<br />
<br />
The {{Pkg|mkinitcpio-systemd-tool}} package requires the [[mkinitcpio#Common hooks|systemd hook]]. For more information be sure to read the project's [https://github.com/random-archer/mkinitcpio-systemd-tool/blob/master/README.md README] as well as the provided default [https://github.com/random-archer/mkinitcpio-systemd-tool systemd service unit files] to get you started.<br />
<br />
The recommended hooks are: {{ic|base autodetect modconf block filesystems keyboard fsck systemd systemd-tool}}.<br />
<br />
=== Remote unlocking (hooks: netconf, dropbear, tinyssh, ppp) ===<br />
<br />
Another package combination providing remote logins to the initcpio is {{Pkg|mkinitcpio-netconf}} and/or {{AUR|mkinitcpio-ppp}} (for remote unlocking using a [[Wikipedia:Point-to-Point Protocol|PPP]] connection over the internet) along with an [[SSH]] server. You have the option of using either {{Pkg|mkinitcpio-dropbear}} or {{Pkg|mkinitcpio-tinyssh}}. Those hooks do not install any shell, so you also need to [[install]] the {{Pkg|mkinitcpio-utils}} package. The instructions below can be used in any combination of the packages above. When there are different paths, it will be noted.<br />
<br />
# If you do not have an SSH key pair yet, [[SSH keys#Generating_an_SSH_key_pair|generate one]] on the client system (the one which will be used to unlock the remote machine). {{Note|{{ic|tinyssh}} only supports [[SSH_keys#Ed25519|Ed25519]] and [[SSH_keys#ECDSA|ECDSA]] key types. If you chose to use {{Pkg|mkinitcpio-tinyssh}}, you need to create/use one of these.}} {{Note|{{ic|mkinitcpio-dropbear}} in version 0.0.3-5 is not compatible with the current dropbear implementation that removed dss. See [https://github.com/grazzolini/mkinitcpio-dropbear/issues/8 Github] for details and a fix.}}<br />
# Insert your SSH public key (i.e. the one you usually put onto hosts so that you can ssh in without a password, or the one you just created and which ends with ''.pub'') into the remote machine's {{ic|/etc/dropbear/root_key}} or {{ic|/etc/tinyssh/root_key}} file. {{Tip|This method can later be used to add other SSH public keys as needed; In the case of simply copying the content of the remote's {{ic|~/.ssh/authorized_keys}}, be sure to verify that it only contains keys you intend to be using to unlock the remote machine. When adding additional keys, regenerate your initrd as well using {{ic|mkinitcpio}}. See also [[OpenSSH#Protection]].}}<br />
# Add all three {{ic|<netconf and/or ppp> <dropbear or tinyssh> encryptssh}} [[Mkinitcpio#HOOKS|hooks]] before {{ic|filesystems}} within the "HOOKS" array in {{ic|/etc/mkinitcpio.conf}} (the {{ic|encryptssh}} replaces the {{ic|encrypt}} hook). Then [[regenerate the initramfs]]. {{Note|The {{ic|net}} hook provided by {{Pkg|mkinitcpio-nfs-utils}} is '''not''' needed.}}{{Note|If you experience the error {{ic|libgcc_s.so.1 must be installed for pthread_cancel to work}} when trying to decrypt, you need to add {{ic|/usr/lib/libgcc_s.so.1}} to the "[[Mkinitcpio#BINARIES_and_FILES|BINARIES]]" array.}}<br />
# Configure the required {{ic|1=cryptdevice=}} [[Dm-crypt/System_configuration#Boot_loader|parameter]] and add the {{ic|1=ip=}} [[Kernel_parameters|kernel command parameter]] to your bootloader configuration with the appropriate arguments. For example, if the DHCP server does not attribute a static IP to your remote system, making it difficult to access via SSH across reboots, you can explicitly state the IP you want to be using:{{bc|1=ip=192.168.1.1:::::eth0:none}}Alternatively, you can also specify the subnet mask and gateway required by the network:{{bc|1=ip=192.168.1.1::192.168.1.254:255.255.255.0::eth0:none}}{{Note|As of version 0.0.4 of {{Pkg|mkinitcpio-netconf}}, you can nest multiple {{ic|1=ip=}} parameters in order to configure multiple interfaces. You cannot mix it with {{ic|1=ip=dhcp}} ({{ic|1=ip=:::::eth0:dhcp}}) alone. An interface needs to be specified.}}{{bc|1=ip=ip=192.168.1.1:::::eth0:none:ip=172.16.1.1:::::eth1:none}}For a detailed description have a look at the [[Mkinitcpio#Using net|according mkinitcpio section]]. When finished, update the configuration of your [[bootloader]].<br />
# Finally, restart the remote system and try to [[OpenSSH#Client usage|ssh to it]], '''explicitly stating the "root" username''' (even if the root account is disabled on the machine, this root user is used only in the initrd for the purpose of unlocking the remote system). If you are using the {{Pkg|mkinitcpio-dropbear}} package and you also have the {{Pkg|openssh}} package installed, then you most probably will not get any warnings before logging in, because it convert and use the same host keys openssh uses (except Ed25519 keys, as dropbear does not support them). In case you are using {{Pkg|mkinitcpio-tinyssh}}, you have the option of installing {{Pkg|tinyssh-convert}} or {{AUR|tinyssh-convert-git}} so you can use the same keys as your {{Pkg|openssh}} installation (currently only Ed25519 keys). In either case, you should have run [[OpenSSH#Daemon_management|the ssh daemon]] at least once, using the provided systemd units, so the keys can be generated first. After rebooting the machine, you should be prompted for the passphrase to unlock the root device. The system will complete its boot process and you can then ssh to it [[OpenSSH#Client usage|as you normally would]] (with the remote user of your choice).<br />
<br />
=== Remote unlock via wifi ===<br />
<br />
The net hook is normally used with an ethernet connection. In case you want to setup a computer with wireless only, and unlock it via wifi, you can use a predefined hook or create a custom hook to connect to a wifi network before the net hook is run.<br />
<br />
==== Predefined hook ====<br />
You can install a predefined hook based on the one in this wiki:<br />
# Install {{AUR|mkinitcpio-wifi}}.<br />
# Configure your wifi connection by creating a wpa_supplicant configuration with your network properties: {{bc|wpa_passphrase "ESSID" "passphrase" > /etc/wpa_supplicant/initcpio.conf}}<br />
# Add the {{ic|wifi}} hook before {{ic|netconf}} in your {{ic|/etc/mkinitcpio.conf}}. Your wifi-related modules should be autodetected, if not: add them to the {{ic|MODULES}} section.<br />
# Add {{ic|1=ip=:::::wlan0:dhcp}} to the [[kernel parameters]].<br />
# [[Regenerate the initramfs]].<br />
# Update the configuration of your [[boot loader]].<br />
<br />
==== Build your own ====<br />
Below example shows a setup using a usb wifi adapter, connecting to a wifi network protected with WPA2-PSK. In case you use for example WEP or another boot loader, you might need to change some things.<br />
<br />
# Modify {{ic|/etc/mkinitcpio.conf}}:<br />
#* Add the needed kernel module for your specific wifi adatper.<br />
#* Include the {{ic|wpa_passphrase}} and {{ic|wpa_supplicant}} binaries.<br />
#* Add a hook {{ic|wifi}} (or a name of your choice, this is the custom hook that will be created) before the {{ic|net}} hook.{{bc|1=MODULES=(''module'')<br>BINARIES=(wpa_passphrase wpa_supplicant)<br>HOOKS=(base udev autodetect ... '''wifi''' net ... dropbear encryptssh ...)}}<br />
# Create the {{ic|wifi}} hook in {{ic|/etc/initcpio/hooks/wifi}}:{{bc|run_hook ()<br>{<br>&#09;# sleep a couple of seconds so wlan0 is setup by kernel<br>&#09;sleep 5<br><br>&#09;# set wlan0 to up<br>&#09;ip link set wlan0 up<br><br>&#09;# assocciate with wifi network<br>&#09;# 1. save temp config file<br>&#09;wpa_passphrase "''network ESSID''" "''pass phrase''" > /tmp/wifi<br><br>&#09;# 2. assocciate<br>&#09;wpa_supplicant -B -D nl80211,wext -i wlan0 -c /tmp/wifi<br><br>&#09;# sleep a couple of seconds so that wpa_supplicant finishes connecting<br>&#09;sleep 5<br><br>&#09;# wlan0 should now be connected and ready to be assigned an ip by the net hook<br>}<br><br>run_cleanuphook ()<br>{<br>&#09;# kill wpa_supplicant running in the background<br>&#09;killall wpa_supplicant<br><br>&#09;# set wlan0 link down<br>&#09;ip link set wlan0 down<br><br>&#09;# wlan0 should now be fully disconnected from the wifi network<br>}|}}<br />
# Create the hook installation file in {{ic|/etc/initcpio/install/wifi}}:{{bc|build ()<br>{<br>&#09;add_runscript<br>}<br>help ()<br>{<br>cat<<HELPEOF<br>&#09;Enables wifi on boot, for dropbear ssh unlocking of disk.<br>HELPEOF<br>}|}}<br />
# Add {{ic|1=ip=:::::wlan0:dhcp}} to the [[kernel parameters]]. Remove {{ic|1=ip=:::::eth0:dhcp}} so it does not conflict.<br />
# Optionally create an additional boot entry with kernel parameter {{ic|1=ip=:::::eth0:dhcp}}.<br />
# [[Regenerate the initramfs]].<br />
# Update the configuration of your [[boot loader]].<br />
<br />
Remember to setup [[wifi]], so you are able to login once the system is fully booted. In case you are unable to connect to the wifi network, try increasing the sleep times a bit.<br />
<br />
== Discard/TRIM support for solid state drives (SSD) ==<br />
<br />
[[Solid state drive]] users should be aware that, by default, TRIM commands are not enabled by the device-mapper, i.e. block-devices are mounted without the {{ic|discard}} option unless you override the default. <br />
<br />
The device-mapper maintainers have made it clear that TRIM support will never be enabled by default on dm-crypt devices because of the potential security implications.[http://www.saout.de/pipermail/dm-crypt/2011-September/002019.html][http://www.saout.de/pipermail/dm-crypt/2012-April/002420.html] Minimal data leakage in the form of freed block information, perhaps sufficient to determine the filesystem in use, may occur on devices with TRIM enabled. An illustration and discussion of the issues arising from activating TRIM is available in the [http://asalor.blogspot.de/2011/08/trim-dm-crypt-problems.html blog] of a ''cryptsetup'' developer. If you are worried about such factors, keep also in mind that threats may add up: for example, if your device is still encrypted with the previous (cryptsetup <1.6.0) default cipher {{ic|--cipher aes-cbc-essiv}}, more information leakage may occur from trimmed sector observation than with the current [[dm-crypt/Device encryption#Encryption options for LUKS mode|default]]. <br />
<br />
The following cases can be distinguished:<br />
<br />
* The device is encrypted with default dm-crypt LUKS mode:<br />
** By default the LUKS header is stored at the beginning of the device and using TRIM is useful to protect header modifications. If for example a compromised LUKS password is revoked, without TRIM the old header will in general still be available for reading until overwritten by another operation; if the drive is stolen in the meanwhile, the attackers could in theory find a way to locate the old header and use it to decrypt the content with the compromised password. See [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects cryptsetup FAQ, section 5.19 What about SSDs, Flash and Hybrid Drives?] and [https://www.reddit.com/r/archlinux/comments/2f370s/full_disk_encryption_on_an_ssd/ck5p5c5 Full disk encryption on an ssd]. <br />
** TRIM can be left disabled if the security issues stated at the top of this section are considered a worse threat than the above bullet.<br />
: See also [[Securely wipe disk#Flash memory]].<br />
* The device is encrypted with dm-crypt plain mode, or the LUKS header is stored [[#Encrypted system using a detached LUKS header|separately]]:<br />
** If plausible deniability is required, TRIM should '''never''' be used because of the considerations at the top of this section, or the use of encryption will be given away.<br />
** If plausible deniability is not required, TRIM can be used for its performance gains, provided that the security dangers described at the top of this section are not of concern.<br />
<br />
{{Warning|Before enabling TRIM on a drive, make sure the device fully supports TRIM commands, or data loss can occur. See [[Solid State Drives#TRIM]].}}<br />
<br />
In {{Pkg|linux}} 3.1 and up, support for dm-crypt TRIM pass-through can be toggled upon device creation or mount with dmsetup. Support for this option also exists in {{Pkg|cryptsetup}} version 1.4.0 and up. To add support during boot, you will need to add {{ic|:allow-discards}} to the {{ic|cryptdevice}} option. The TRIM option may look like this:<br />
<br />
cryptdevice=/dev/sdaX:root:allow-discards<br />
<br />
For the main {{ic|cryptdevice}} configuration options before the {{ic|:allow-discards}} see [[Dm-crypt/System configuration]].<br />
<br />
If you are using a systemd based initrd, you must pass:<br />
<br />
rd.luks.options=discard<br />
<br />
{{Note|The {{ic|1=rd.luks.options=discard}} kernel option does not have any effect on devices included in the initramfs image's {{ic|/etc/crypttab}} file ({{ic|/etc/crypttab.initramfs}} on real root). You must specify option {{ic|discard}} in {{ic|/etc/crypttab.initramfs}}.}}<br />
<br />
Besides the kernel option, it is also required to periodically run {{ic|fstrim}} or mount the filesystem (e.g. {{ic|/dev/mapper/root}} in this example) with the {{ic|discard}} option in {{ic|/etc/fstab}}. For details, please refer to the [[TRIM]] page.<br />
<br />
For LUKS devices unlocked via {{ic|/etc/crypttab}} use option {{ic|discard}}, e.g.:<br />
<br />
{{hc|/etc/crypttab|<br />
2=luks-123abcdef-etc UUID=123abcdef-etc none discard}}<br />
<br />
When manually unlocking devices on the console use {{ic|--allow-discards}}.<br />
<br />
With LUKS2 you can set {{ic|allow-discards}} as a default flag for a device by opening it once with the option {{ic|--persistent}}:<br />
<br />
# cryptsetup --allow-discards --persistent open /dev/sdaX root<br />
<br />
When the device is already opened, the {{ic|open}} action will raise an error. You can use the {{ic|refresh}} option in these cases, e.g.:<br />
<br />
# cryptsetup --allow-discards --persistent refresh root<br />
<br />
You can confirm the flag is persistently set in the LUKS2 header by looking at the {{ic|cryptsetup luksDump}} output:<br />
<br />
{{hc|# cryptsetup luksDump /dev/sdaX {{!}} grep Flags|<br />
Flags: allow-discards<br />
}}<br />
<br />
In any case, you can verify whether the device actually was opened with discards by inspecting the {{ic|dmsetup table}} output:<br />
<br />
{{hc|# dmsetup table|<br />
luks-123abcdef-etc: 0 1234567 crypt aes-xts-plain64 000etc000 0 8:2 4096 1 allow_discards<br />
}}<br />
<br />
== The encrypt hook and multiple disks ==<br />
<br />
{{Tip|{{ic|sd-encrypt}} hook supports unlocking multiple devices. They can be specified on the kernel command line or in {{ic|/etc/crypttab.initramfs}}. See [[dm-crypt/System configuration#Using sd-encrypt hook]].}}<br />
<br />
The {{ic|encrypt}} hook only allows for a '''single''' {{ic|1=cryptdevice=}} entry ({{Bug|23182}}). In system setups with multiple drives this may be limiting, because ''dm-crypt'' has no feature to exceed the physical device. For example, take "LVM on LUKS": The entire LVM exists inside a LUKS mapper. This is perfectly fine for a single-drive system, since there is only one device to decrypt. But what happens when you want to increase the size of the LVM? You cannot, at least not without modifying the {{ic|encrypt}} hook.<br />
<br />
The following sections briefly show alternatives to overcome the limitation. The first deals with how to expand a [[Dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|LUKS on LVM]] setup to a new disk. The second with modifying the {{ic|encrypt}} hook to unlock multiple disks in LUKS setups without LVM.<br />
<br />
=== Expanding LVM on multiple disks ===<br />
<br />
The management of multiple disks is a basic [[LVM]] feature and a major reason for its partitioning flexibility. It can also be used with ''dm-crypt'', but only if LVM is employed as the first mapper. In such a [[dm-crypt/Encrypting an entire system#LUKS_on_LVM|LUKS on LVM]] setup the encrypted devices are created inside the logical volumes (with a separate passphrase/key per volume). The following covers the steps to expand that setup to another disk. <br />
<br />
{{Warning|Back up! While resizing filesystems may be standard, keep in mind that operations '''may''' go wrong and the following might not apply to a particular setup. Generally, extending a filesystem to free disk space is less problematic than shrinking one. This in particular applies when stacked mappers are used, as it is the case in the following example.}}<br />
<br />
==== Adding a new drive ====<br />
<br />
First, it may be desired to prepare a new disk according to [[dm-crypt/Drive preparation]]. <br />
Second, it is partitioned as a LVM, e.g. all space is allocated to {{ic|/dev/sdY1}} with partition type {{ic|8E00}} (Linux LVM). <br />
Third, the new disk/partition is attached to the existing LVM volume group, e.g.:<br />
<br />
# pvcreate /dev/sdY1<br />
# vgextend MyStorage /dev/sdY1<br />
<br />
==== Extending the logical volume ====<br />
<br />
For the next step, the final allocation of the new diskspace, the logical volume to be extended has to be unmounted. It can be performed for the {{ic|cryptdevice}} root partition, but in this case the procedure has to be performed from an Arch Install ISO. <br />
<br />
In this example, it is assumed that the logical volume for {{ic|/home}} (lv-name {{ic|homevol}}) is going to be expanded with the fresh disk space: <br />
<br />
# umount /home<br />
# fsck /dev/mapper/home<br />
# cryptsetup luksClose /dev/mapper/home<br />
# lvextend -l +100%FREE MyStorage/homevol<br />
<br />
Now the logical volume is extended and the LUKS container comes next: <br />
<br />
# cryptsetup open /dev/MyStorage/homevol home<br />
# umount /home # as a safety, in case it was automatically remounted<br />
# cryptsetup --verbose resize home<br />
<br />
Finally, the filesystem itself is resized: <br />
<br />
# e2fsck -f /dev/mapper/home<br />
# resize2fs /dev/mapper/home<br />
<br />
Done! If it went to plan, {{ic|/home}} can be remounted and now includes the span to the new disk:<br />
<br />
# mount /dev/mapper/home /home<br />
<br />
Note that the {{ic|cryptsetup resize}} action does not affect encryption keys, and these have not changed.<br />
<br />
=== Modifying the encrypt hook for multiple partitions ===<br />
<br />
==== Root filesystem spanning multiple partitions ====<br />
<br />
It is possible to modify the encrypt hook to allow multiple hard drive decrypt root ({{ic|/}}) at boot. One way:<br />
<br />
# cp /usr/lib/initcpio/install/encrypt /etc/initcpio/install/encrypt2<br />
# cp /usr/lib/initcpio/hooks/encrypt /etc/initcpio/hooks/encrypt2<br />
# sed -i "s/cryptdevice/cryptdevice2/" /etc/initcpio/hooks/encrypt2<br />
# sed -i "s/cryptkey/cryptkey2/" /etc/initcpio/hooks/encrypt2<br />
<br />
Add {{ic|1=cryptdevice2=}} to your boot options (and {{ic|1=cryptkey2=}} if needed), and add the {{ic|encrypt2}} hook to your [[mkinitcpio.conf]] before rebuilding it. See [[dm-crypt/System configuration]].<br />
<br />
==== Multiple non-root partitions ====<br />
<br />
Maybe you have a requirement for using the {{ic|encrypt}} hook on a non-root partition. Arch does not support this out of the box, however, you can easily change the cryptdev and cryptname values in {{ic|/lib/initcpio/hooks/encrypt}} (the first one to your {{ic|/dev/sd*}} partition, the second to the name you want to attribute). That should be enough.<br />
<br />
The big advantage is you can have everything automated, while setting up {{ic|/etc/crypttab}} with an external key file (i.e. the keyfile is not on any internal hard drive partition) can be a pain - you need to make sure the USB/FireWire/... device gets mounted before the encrypted partition, which means you have to change the order of {{ic|/etc/fstab}} (at least).<br />
<br />
Of course, if the {{pkg|cryptsetup}} package gets upgraded, you will have to change this script again. Unlike {{ic|/etc/crypttab}}, only one partition is supported, but with some further hacking one should be able to have multiple partitions unlocked.<br />
<br />
{{Accuracy|Why not use the supported Grub2 right away? See also [[mkinitcpio#Using RAID]]}} <br />
<br />
If you want to do this on a software RAID partition, there is one more thing you need to do. Just setting the {{ic|/dev/mdX}} device in {{ic|/lib/initcpio/hooks/encrypt}} is not enough; the {{ic|encrypt}} hook will fail to find the key for some reason, and not prompt for a passphrase either. It looks like the RAID devices are not brought up until after the {{ic|encrypt}} hook is run. You can solve this by putting the RAID array in {{ic|/boot/grub/menu.lst}}, like <br />
<br />
kernel /boot/vmlinuz-linux md=1,/dev/hda5,/dev/hdb5<br />
<br />
If you set up your root partition as a RAID, you will notice the similarities with that setup. [[GRUB]] can handle multiple array definitions just fine:<br />
<br />
kernel /boot/vmlinuz-linux root=/dev/md0 ro md=0,/dev/sda1,/dev/sdb1 md=1,/dev/sda5,/dev/sdb5,/dev/sdc5<br />
<br />
== Encrypted system using a detached LUKS header ==<br />
<br />
This example follows the same setup as in [[dm-crypt/Encrypting an entire system#Plain dm-crypt]], which should be read first before following this guide.<br />
<br />
By using a detached header the encrypted blockdevice itself only carries encrypted data, which gives [[Wikipedia:Deniable encryption|deniable encryption]] as long as the existence of a header is unknown to the attackers. It is similar to using [[dm-crypt/Encrypting an entire system#Plain_dm-crypt|plain dm-crypt]], but with the LUKS advantages such as multiple passphrases for the masterkey and key derivation. Further, using a detached header offers a form of two factor authentication with an easier setup than [[#Using GPG, LUKS, or OpenSSL Encrypted Keyfiles|using GPG or OpenSSL encrypted keyfiles]], while still having a built-in password prompt for multiple retries. See [[Data-at-rest encryption#Cryptographic metadata]] for more information.<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for LUKS mode]] for encryption options before performing the first step to setup the encrypted system partition and creating a header file to use with {{ic|cryptsetup}}:<br />
<br />
# dd if=/dev/zero of=header.img bs=16M count=1<br />
# cryptsetup luksFormat /dev/sdX --offset 32768 --header header.img<br />
<br />
{{Tip|The {{ic|--offset}} option allows specifying the start of encrypted data on a device. By reserving a space at the beginning of device you have the option of later [[dm-crypt/Device encryption#Restore using cryptsetup|reattaching the LUKS header]]. The value is specified in 512-byte sectors, see {{man|8|cryptsetup}} for more details.}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open --header header.img /dev/sdX enc<br />
<br />
Now follow the [[dm-crypt/Encrypting an entire system#Preparing the non-boot partitions|LVM on LUKS setup]] to your requirements. The same applies for [[dm-crypt/Encrypting an entire system#Preparing the boot partition 4|preparing the boot partition]] on the removable device (because if not, there is no point in having a separate header file for unlocking the encrypted disk).<br />
Next move the {{ic|header.img}} onto it:<br />
<br />
# mv header.img /mnt/boot<br />
<br />
Follow the installation procedure up to the mkinitcpio step (you should now be {{ic|arch-chroot}}ed inside the encrypted system). <br />
<br />
{{Tip|1=You will notice that since the system partition only has "random" data, it does not have a partition table and by that an {{ic|UUID}} or a {{ic|LABEL}}. But you can still have a consistent mapping using the [[Persistent block device naming#by-id and by-path]]. E.g. using disk id from {{ic|/dev/disk/by-id/}}.}}<br />
<br />
There are two options for initramfs to support a detached LUKS header.<br />
<br />
=== Using systemd hook ===<br />
<br />
{{Expansion|Since systemd 247 the LUKS header does not need to be embedded in the initramfs, the volume on which the file is placed and its path can now be specified from the kernel command line.}}<br />
<br />
{{man|8|systemd-cryptsetup-generator}} does not support a detached LUKS header specified in the kernel command line (see [https://github.com/systemd/systemd/pull/16444 systemd pull request 16444]), so a {{ic|/etc/crypttab.initramfs}} must be used instead.<br />
<br />
First create {{ic|/etc/crypttab.initramfs}} and add the encrypted device to it. The syntax is defined in {{man|5|crypttab}}<br />
<br />
{{hc|/etc/crypttab.initramfs|2=<br />
enc /dev/disk/by-id/''your-disk_id'' none header=/boot/header.img<br />
}}<br />
<br />
Modify {{ic|/etc/mkinitcpio.conf}} [[Mkinitcpio#Common_hooks|to use systemd]] and add the header to {{ic|FILES}}.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
FILES=('''/boot/header.img''')<br />
...<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
...<br />
}}<br />
<br />
[[Regenerate the initramfs]] and you are done.<br />
<br />
{{Note|No cryptsetup parameters need to be passed to the kernel command line, since {{ic|/etc/crypttab.initramfs}} will be added as {{ic|/etc/crypttab}} in the initramfs. If you wish to specify them in the kernel command line see [[dm-crypt/System configuration#Using sd-encrypt hook]] for the supported options.}}<br />
<br />
=== Modifying encrypt hook ===<br />
<br />
This method shows how to modify the {{ic|encrypt}} hook in order to use a detached LUKS header. <br />
Now the {{ic|encrypt}} hook has to be modified to let {{ic|cryptsetup}} use the separate header ({{Bug|42851}}; base source and idea for these changes [https://bbs.archlinux.org/viewtopic.php?pid=1076346#p1076346 published on the BBS]). Make a copy so it is not overwritten on a [[mkinitcpio]] update:<br />
<br />
# cp /usr/lib/initcpio/hooks/encrypt /etc/initcpio/hooks/encrypt2<br />
# cp /usr/lib/initcpio/install/encrypt /etc/initcpio/install/encrypt2<br />
<br />
{{hc|/etc/initcpio/hooks/encrypt2 (around line 52)|output=<br />
warn_deprecated() {<br />
echo "The syntax 'root=${root}' where '${root}' is an encrypted volume is deprecated"<br />
echo "Use 'cryptdevice=${root}:root root=/dev/mapper/root' instead."<br />
}<br />
<br />
'''local headerFlag=false'''<br />
for cryptopt in ${cryptoptions//,/ }; do<br />
case ${cryptopt} in<br />
allow-discards)<br />
cryptargs="${cryptargs} --allow-discards"<br />
;; <br />
<b>header)<br />
cryptargs="${cryptargs} --header /boot/header.img"<br />
headerFlag=true<br />
;;</b><br />
*) <br />
echo "Encryption option '${cryptopt}' not known, ignoring." >&2 <br />
;; <br />
esac<br />
done<br />
<br />
if resolved=$(resolve_device "${cryptdev}" ${rootdelay}); then<br />
if '''$headerFlag &#124;&#124; '''cryptsetup isLuks ${resolved} >/dev/null 2>&1; then<br />
[ ${DEPRECATED_CRYPT} -eq 1 ] && warn_deprecated<br />
dopassphrase=1<br />
}}<br />
<br />
Now edit the [[mkinitcpio.conf]] to add the {{ic|encrypt2}} and {{ic|lvm2}} hooks, the {{ic|header.img}} to {{ic|FILES}} and the {{ic|loop}} to {{ic|MODULES}}, apart from other configuration the system requires:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
MODULES=('''loop''')<br />
...<br />
FILES=('''/boot/header.img''')<br />
...<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt2''' '''lvm2''' filesystems fsck)<br />
...<br />
}}<br />
<br />
This is required so the LUKS header is available on boot allowing the decryption of the system, exempting us from a more complicated setup to mount another separate USB device in order to access the header. After this set up [[Mkinitcpio#Image_creation_and_activation|the initramfs]] is created.<br />
<br />
Next the [[dm-crypt/Encrypting an entire system#Configuring the boot loader 4|boot loader is configured]] to specify the {{ic|1=cryptdevice=}} also passing the new {{ic|header}} option for this setup: <br />
<br />
cryptdevice=/dev/disk/by-id/''your-disk_id'':enc:header<br />
<br />
To finish, following [[dm-crypt/Encrypting an entire system#Post-installation]] is particularly useful with a {{ic|/boot}} partition on an USB storage medium.<br />
<br />
== Encrypted /boot and a detached LUKS header on USB ==<br />
<br />
{{Out of date|1=This scenario was based on [https://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&oldid=562642#Encrypted_boot_partition_(GRUB)], whose structure was then changed with [https://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=next&oldid=562642].|section=Encrypted /boot and a detached LUKS header on USB}}<br />
<br />
Rather than embedding the {{ic|header.img}} and keyfile into the [[initramfs]] image, this setup will make your system depend entirely on the usb key rather than just the image to boot, and on the encrypted keyfile inside of the encrypted boot partition. Since the header and keyfile are not included in the [[initramfs]] image and the custom encrypt hook is specifically for the usb's [[Persistent_block_device_naming#by-id_and_by-path|by-id]], you will literally need the usb key to boot.<br />
<br />
For the usb drive, since you are encrypting the drive and the keyfile inside, it is preferred to cascade the ciphers as to not use the same one twice. Whether a [[Wikipedia:Meet-in-the-middle_attack|meet-in-the-middle]] attack would actually be feasible is debatable. You can do twofish-serpent or serpent-twofish.<br />
<br />
=== Preparing the disk devices ===<br />
<br />
{{ic|sdb}} will be assumed to be the USB drive, {{ic|sda}} will be assumed to be the main hard drive.<br />
<br />
Prepare the devices according to [[dm-crypt/Drive preparation]].<br />
<br />
==== Preparing the USB key ====<br />
<br />
Use [[gdisk]] to partition the disk according to the layout [[Dm-crypt/Encrypting_an_entire_system#Preparing_the_disk_5|shown here]], with the exception that it should only include the first two partitions. So as follows:<br />
<br />
{{hc|# gdisk /dev/sdb|<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 1050623 512.0 MiB EF00 EFI System<br />
2 1050624 1460223 200.0 MiB 8300 Linux filesystem<br />
}}<br />
<br />
Before running {{ic|cryptsetup}}, look at the [[Dm-crypt/Device_encryption#Encryption_options_for_LUKS_mode|Encryption options for LUKS mode]] and [[Disk_encryption#Ciphers_and_modes_of_operation|Ciphers and modes of operation]] first to select your desired settings.<br />
<br />
[[Dm-crypt/Encrypting_an_entire_system#Preparing_the_boot_partition_5|Prepare the boot partition]]{{Broken section link}} but do not {{ic|mount}} any partition yet and [[EFI system partition#Format the partition|Format the EFI system partition]].<br />
<br />
# mount /dev/mapper/cryptboot /mnt<br />
# dd if=/dev/urandom of=/mnt/key.img bs=''filesize'' count=1<br />
# cryptsetup luksFormat /mnt/key.img<br />
# cryptsetup open /mnt/key.img lukskey<br />
<br />
''filesize'' is in bytes but can be followed by a suffix such as {{ic|M}}. Having too small of a file will get you a nasty {{ic|Requested offset is beyond real size of device /dev/loop0}} error. As a rough reference, creating a 4M file will encrypt it successfully. You should make the file larger than the space needed since the encrypted loop device will be a little smaller than the file's size.<br />
<br />
With a big file, you can use {{ic|1=--keyfile-offset=''offset''}} and {{ic|1=--keyfile-size=''size''}} to navigate to the correct position. [https://wiki.gentoo.org/wiki/Custom_Initramfs#Encrypted_keyfile]<br />
<br />
Now you should have {{ic|lukskey}} opened in a loop device (underneath {{ic|/dev/loop1}}), mapped as {{ic|/dev/mapper/lukskey}}.<br />
<br />
==== The main drive ====<br />
<br />
# truncate -s 16M /mnt/header.img<br />
# cryptsetup --key-file=/dev/mapper/lukskey --keyfile-offset=''offset'' --keyfile-size=''size'' luksFormat /dev/sda --offset 32768 --header /mnt/header.img<br />
<br />
Pick an ''offset'' and ''size'' in bytes (8192 bytes is the maximum keyfile size for {{ic|cryptsetup}}).<br />
<br />
# cryptsetup open --header /mnt/header.img --key-file=/dev/mapper/lukskey --keyfile-offset=''offset'' --keyfile-size=''size'' /dev/sda enc <br />
# cryptsetup close lukskey<br />
# umount /mnt<br />
<br />
Follow [[Dm-crypt/Encrypting_an_entire_system#Preparing_the_logical_volumes|Preparing the logical volumes]] to set up LVM on LUKS.<br />
<br />
See [[Partitioning#Discrete partitions]] for recommendations on the size of your partitions.<br />
<br />
Once your root partition is mounted, {{ic|mount}} your encrypted boot partition as {{ic|/mnt/boot}} and your EFI system partition as {{ic|/mnt/efi}}.<br />
<br />
=== Installation procedure and custom encrypt hook ===<br />
<br />
Follow the [[installation guide]] up to the {{ic|mkinitcpio}} step but do not do it yet, and skip the partitioning, formatting, and mounting steps as they have already been done.<br />
<br />
In order to get the encrypted setup to work, you need to build your own hook, which is thankfully easy to do and here is the code you need. You will have to follow [[Persistent block device naming#by-id and by-path]] to figure out your own {{ic|by-id}} values for the usb and main hard drive (they are linked -> to {{ic|sda}} or {{ic|sdb}}).<br />
<br />
You should be using the {{ic|by-id}} instead of just {{ic|sda}} or {{ic|sdb}} because {{ic|sdX}} can change and this ensures it is the correct device.<br />
<br />
You can name {{ic|customencrypthook}} anything you want, and custom build hooks can be placed in the {{ic|hooks}} and {{ic|install}} folders of {{ic|/etc/initcpio}}. Keep a backup of both files ({{ic|cp}} them over to the {{ic|/home}} partition or your user's {{ic|/home}} directory after you make one). {{ic|/usr/bin/ash}} is not a typo.<br />
<br />
{{hc|/etc/initcpio/hooks/customencrypthook|output=<nowiki><br />
#!/usr/bin/ash<br />
<br />
run_hook() {<br />
modprobe -a -q dm-crypt >/dev/null 2>&1<br />
modprobe loop<br />
[ "${quiet}" = "y" ] && CSQUIET=">/dev/null"<br />
<br />
while [ ! -L '/dev/disk/by-id/</nowiki>''usbdrive''<nowiki>-part2' ]; do<br />
echo 'Waiting for USB'<br />
sleep 1<br />
done<br />
<br />
cryptsetup open /dev/disk/by-id/</nowiki>''usbdrive''<nowiki>-part2 cryptboot<br />
mkdir -p /mnt<br />
mount /dev/mapper/cryptboot /mnt<br />
cryptsetup open /mnt/key.img lukskey<br />
cryptsetup --header /mnt/header.img --key-file=/dev/mapper/lukskey --keyfile-offset=''offset'' --keyfile-size=''size'' open /dev/disk/by-id/</nowiki>''harddrive''<nowiki> enc<br />
cryptsetup close lukskey<br />
umount /mnt<br />
}<br />
</nowiki>}}<br />
<br />
{{ic|''usbdrive''}} is your USB drive {{ic|by-id}}, and {{ic|''harddrive''}} is your main hard drive {{ic|by-id}}.<br />
<br />
{{Tip|You could also close {{ic|cryptboot}} using {{ic|cryptsetup close}}, but having it open makes it easier to mount for system updates using [[Pacman]] and regenerating the initramfs with [[mkinitcpio]]. The {{ic|/boot}} partition must be mounted for updates that affect the [[kernel]] or [[Initramfs]], and the initramfs will be automatically regenerated after these updates.}}<br />
<br />
# cp /usr/lib/initcpio/install/encrypt /etc/initcpio/install/customencrypthook<br />
<br />
Now edit the copied file and remove the {{ic|help()}} section as it is not necessary.<br />
<br />
{{hc|/etc/mkinitcpio.conf (edit this only do not replace it, these are just excerpts of the necessary parts)|output=<br />
MODULES=(loop)<br />
...<br />
HOOKS=(base udev autodetect modconf block customencrypthook lvm2 filesystems keyboard fsck)<br />
}}<br />
<br />
The {{ic|1=files=()}} and {{ic|1=binaries=()}} arrays are empty, and you should not have to replace {{ic|1=HOOKS=(...)}} array entirely just edit in {{ic|customencrypthook lvm2}} after {{ic|block}} and before {{ic|filesystems}}, and make sure {{ic|systemd}}, {{ic|sd-lvm2}}, and {{ic|encrypt}} are removed.<br />
<br />
==== Boot Loader ====<br />
<br />
Finish the [[Installation_guide#Initramfs|Installation Guide]] from the {{ic|mkinitcpio}} step. To boot you would need either [[GRUB]] or [[efibootmgr]]. Note you can use [[GRUB]] to support the encrypted disks by [[Dm-crypt/Encrypting_an_entire_system#Configuring_the_boot_loader_6|Configuring the boot loader]]{{Broken section link}} but editing the {{ic|GRUB_CMDLINE_LINUX}} is not necessary for this set up.<br />
<br />
Or use Direct UEFI Secure boot by generating keys with {{AUR|cryptboot}} then signing the initramfs and kernel and creating a bootable ''.efi'' file for your EFI system partition with {{AUR|sbupdate-git}}. Before using cryptboot or sbupdate note this excerpt from [[Secure Boot#Using your own keys]]:<br />
<br />
{{Tip|Note that {{AUR|cryptboot}} requires the encrypted boot partition to be specified in {{ic|/etc/crypttab}} before it runs, and if you are using it in combination with {{AUR|sbupdate-git}}, sbupdate expects the {{ic|/boot/efikeys/db.*}} files created by cryptboot to be capitalized like {{ic|DB.*}} unless otherwise configured in {{ic|/etc/default/sbupdate}}. Users who do not use systemd to handle encryption may not have anything in their {{ic|/etc/crypttab}} file and would need to create an entry.<br />
}}<br />
<br />
# efibootmgr -c -d /dev/''device'' -p ''partition_number'' -L "Arch Linux Signed" -l "EFI\Arch\linux-signed.efi"<br />
<br />
See {{man|8|efibootmgr}} for an explanation of the options.<br />
<br />
Make sure the boot order puts {{ic|Arch Linux Signed}} first. If not change it with {{ic|efibootmgr -o XXXX,YYYY,ZZZZ}}.<br />
<br />
=== Changing the LUKS keyfile ===<br />
<br />
{{Merge|dm-crypt/Device encryption#Keyfiles|Changing the keyfile is not a required action in this setup.}}<br />
<br />
# cryptsetup --header /boot/header.img --key-file=/dev/mapper/lukskey --keyfile-offset=''offset'' --keyfile-size=''size'' luksChangeKey /dev/mapper/enc /dev/mapper/lukskey2 --new-keyfile-size=''newsize'' --new-keyfile-offset=''newoffset''<br />
<br />
Afterwards, {{ic|cryptsetup close lukskey}} and [[shred]] or [[Securely_wipe_disk#dd|dd]] the old keyfile with random data before deleting it, then make sure that the new keyfile is renamed to the same name of the old one: {{ic|key.img}} or other name.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Android_Debug_Bridge&diff=524511Android Debug Bridge2018-06-03T05:06:27Z<p>Ketsui: /* Troubleshooting */ Slapping sudo in front of a command is not troubleshooting.</p>
<hr />
<div>[[Category:Android]]<br />
The [https://developer.android.com/studio/command-line/adb Android Debug Bridge] (ADB) is a command-line tool that can be used to install, uninstall and debug apps, transfer files and access the device's shell.<br />
<br />
== Installation ==<br />
<br />
ADB is part of the Platform-Tools [[Android#SDK packages|SDK package]] and the {{Pkg|android-tools}} package.<br />
<br />
== Usage ==<br />
<br />
=== Connect device ===<br />
<br />
{{Tip|<br />
* For some devices, you may have to enable MTP on the device, before ADB will work. Some other devices require enable PTP mode to work.<br />
* Many devices' [[udev]] rules are included in {{Pkg|libmtp}}, so if you have this installed, the following steps may not be necessary.<br />
* Make sure your USB cable is capable of both charge and data. Many USB cables bundled with mobile devices do not include the USB data pin.<br />
}}<br />
<br />
To connect to a real device or phone via ADB under Arch, you must:<br />
<br />
# You might want to install {{Pkg|android-udev}} if you wish to connect the device to the proper {{ic|/dev/}} entries.<br />
# plug in your android device via USB.<br />
# Enable USB Debugging on your phone or device:<br />
#* Jelly Bean (4.2) and newer: Go to ''Settings > About Phone'' tap ''Build Number'' 7 times until you get a popup that you have become a developer. Then go to ''Settings > Developer > USB debugging'' and enable it. The device will ask to allow the computer with its fingerprint to connect. allowing it permanent will copy {{ic|$HOME/.android/adbkey.pub}} onto the devices {{ic|/data/misc/adb/adb_keys}} folder.<br />
#* Older versions: This is usually done from ''Settings > Applications > Development > USB debugging''. Reboot the phone after checking this option to make sure USB debugging is enabled.<br />
<br />
If [[#Detect the device|ADB recognizes your device]] ({{ic|adb devices}} shows it as {{ic|"device" and not as "unauthorized"}}, or it is visible and accessible in IDE), you are done. Otherwise see instructions below.<br />
<br />
=== Figure out device IDs ===<br />
<br />
Each Android device has a USB vendor/product ID. An example for HTC Evo is:<br />
<br />
vendor id: 0bb4<br />
product id: 0c8d<br />
<br />
Plug in your device and execute:<br />
<br />
$ lsusb<br />
<br />
It should come up something like this:<br />
<br />
Bus 002 Device 006: ID 0bb4:0c8d High Tech Computer Corp.<br />
<br />
=== Adding udev Rules ===<br />
<br />
Use the rules from {{Pkg|android-udev}} (or {{Aur|android-udev-git}}), install them manually from [https://source.android.com/source/initializing#configuring-usb-access Android developer], or use the following template for your [[udev rules]], just replace {{ic|[VENDOR ID]}} and {{ic|[PRODUCT ID]}} with yours. Copy these rules into {{ic|/etc/udev/rules.d/51-android.rules}}:<br />
<br />
{{hc|/etc/udev/rules.d/51-android.rules|2=<nowiki><br />
SUBSYSTEM=="usb", ATTR{idVendor}=="[VENDOR ID]", MODE="0660", GROUP="adbusers"<br />
SUBSYSTEM=="usb",ATTR{idVendor}=="[VENDOR ID]",ATTR{idProduct}=="[PRODUCT ID]",SYMLINK+="android_adb"<br />
SUBSYSTEM=="usb",ATTR{idVendor}=="[VENDOR ID]",ATTR{idProduct}=="[PRODUCT ID]",SYMLINK+="android_fastboot"<br />
</nowiki>}}<br />
<br />
Then, to reload your new udev rules, execute:<br />
<br />
# udevadm control --reload-rules<br />
<br />
Make sure you are member of {{ic|adbusers}} [[group]] to access {{ic|adb}} devices.<br />
<br />
=== Configuring adb ===<br />
<br />
Instead of using udev rules, you may create/edit {{ic|~/.android/adb_usb.ini}} which contains a list of vendor IDs.<br />
<br />
{{hc|~/.android/adb_usb.ini|<br />
0x27e8<br />
}}<br />
<br />
=== Detect the device ===<br />
<br />
After you have setup the udev rules, unplug your device and replug it.<br />
<br />
After running:<br />
<br />
$ adb devices<br />
<br />
you should see something like:<br />
<br />
List of devices attached <br />
HT07VHL00676 device<br />
<br />
=== Transferring files ===<br />
<br />
You can now use adb to transfer files between the device and your computer. To transfer files to the device, use<br />
<br />
$ adb push ''<what-to-copy>'' ''<where-to-place>''<br />
<br />
To transfer files from the device, use<br />
<br />
$ adb pull ''<what-to-pull>'' ''<where-to-place>''<br />
<br />
Also see [[#Tools building on ADB]].<br />
<br />
== Tools building on ADB ==<br />
<br />
* {{aur|adbfs-rootless-git}} - a [[FUSE]] filesystem over ADB<br />
* [https://github.com/google/adb-sync adb-sync] (available as {{AUR|adb-sync-git}}) – a tool to synchronize files between a PC and an Android device using the ADB protocol.<br />
* [http://xsavikx.github.io/AndroidScreencast AndroidScreencast] (available as {{aur|androidscreencast-bin}}) – view and control your Android device from a PC (via ADB).<br />
<br />
== Troubleshooting ==<br />
<br />
* If you are getting an empty list (your device is not there), it may be because you have not enabled USB debugging on your device. You can do that by going to ''Settings > Applications > Development'' and enabling USB debugging. On Android 4.2 (Jelly Bean) the Development menu is hidden; to enable it go to ''Settings > About phone'' and tap Build number 7 times.<br />
<br />
* On Moto E, the device could have a different vendor/product ID in the sideload and fastboot modes; if you get the "no permission" error, verify the device's ID with {{ic|lsusb}}.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=522825RetroArch2018-05-24T01:07:32Z<p>Ketsui: /* Installation */ removed retroarch-autoconfig-udev</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install the {{Pkg|retroarch-assets-xmb}} package to allow the default menu driver (XMB) to work properly.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enabling the ''Online Updater'' ===<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.<br />
<br />
=== Enabling ''SaveRAM Autosave Interval'' ===<br />
<br />
By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|autosave_interval}} to ''n''.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
autosave_interval = "600"<br />
}}<br />
<br />
With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.<br />
<br />
{{Warning|Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [https://github.com/libretro/RetroArch/issues/4901#issuecomment-300888019]}}<br />
<br />
=== Reset settings to their default value ===<br />
<br />
To reset a setting or keybind to its default value through the GUI, highlight it and press {{ic|Start}}. To remove a button from a keybind, highlight the keybind and press {{ic|Y}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
=== Save data is lost whenever RetroArch crashes ===<br />
<br />
See [[#Enabling SaveRAM Autosave Interval]].<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Talk:Arch_User_Repository&diff=521273Talk:Arch User Repository2018-05-15T13:42:29Z<p>Ketsui: /* Redirect users to Makepkg#Improving_compile_times instead of linking just ccache? */ removed</p>
<hr />
<div>== What is the correct AUR forum section? ==<br />
<br />
[[Arch_User_Repository#Submitting_packages]] says it's [https://bbs.archlinux.org/viewforum.php?id=4], but we also have [https://bbs.archlinux.org/viewforum.php?id=38]. One of them should be added to [[Arch_User_Repository#I_have_a_PKGBUILD_I_would_like_to_submit.3B_can_someone_check_it_to_see_if_there_are_any_errors.3F]]. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 12:30, 7 August 2015 (UTC)<br />
<br />
== AUR link ==<br />
<br />
The link to this page from the [https://aur.archlinux.org/ AUR homepage] is outdated.<br />
<br />
[https://wiki.archlinux.org/index.php/Arch_User_Repository#AUR_4 "Submitting packages"] located above the SSH keys directs to an AUR4 link, which has since become just AUR. I'm not knowledgeable of the methods to correct this.<br />
<br />
-- [[User:Ctag|Ctag]] ([[User talk:Ctag|talk]]) 00:05, 23 September 2015 (UTC)<br />
<br />
:You can submit a bug report for the [https://bugs.archlinux.org/index.php?project=2&do=index&switch=1 AUR web interface] project in the tracker. Or even provide a patch: sources are at [https://projects.archlinux.org/aurweb.git/]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:22, 23 September 2015 (UTC)<br />
<br />
== gitignore ==<br />
<br />
Adding {{ic|*}} to {{ic|.gitignore}} is an ugly workaround for something (in case of dotfiles, programs not respecting standards and e.g. storing cache and config files together). There isn't much to be excluded here - the only unpredictable part is the source tarballs and VCS directories, which can be easily put away by configuring {{ic|SRCDEST}} in {{ic|makepkg.conf}}. We can still recommend to add the source files explicitly.<br />
<br />
The recommendation will affect everybody using the given package, not only the user managing his personal config files, so I think an explicit blacklist is better than the {{ic|*}} wildcard here.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:58, 6 March 2016 (UTC)<br />
:I agree, as per my original recommendation. The simple thing to do is {{ic|git add .}}; some packages ''do have'' an annoying variety of files. Better to explicitly exclude download directories other known cruft in .gitignore. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 12:15, 6 March 2016 (UTC)<br />
<br />
::So the concern is you'd miss to whitelist some "annoying variety" of files, which you wouldn't with {{ic|git add .}}? You might as well argue that you'd miss to blacklist a file you wouldn't want to upload to the AUR... <br />
::Either way, I'd agree configuring SRCDEST is the better (and universal) solution here. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:05, 6 March 2016 (UTC)<br />
:::<strike>Good point, the whole reason for posting a guide indeed is to show users how to deal with AUR4 in the way Archlinux administration expects, this seems to be the more reliable solution[</strike><br />
::::Then I remembered what SRCDEST actually does and realized it wouldn't sufficiently resolve the issue (the source directory is not the only cruft to be avoided). [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 03:55, 13 March 2016 (UTC)<br />
<br />
:::::I have SRCDEST, PKGDEST, LOGDEST, and BUILDDEST set. Suffice to say there's no cruft in my .git dirs. It's not much a bother either, since the values are commented in makepkg.conf. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 12:35, 13 March 2016 (UTC)<br />
<br />
::::::What about the symlinks to the built packages and signatures? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:04, 13 March 2016 (UTC)<br />
<br />
:::::::Assuming only makepkg crates symlinks in the clone directory (correct me if I'm wrong), you can do something like {{ic|find -maxdepth 2 -type l -delete}} in the directory above, in my case a dedicated "AURDEST".<br />
:::::::Perhaps too specific for the general case, but the special type helps anyway. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 13:43, 13 March 2016 (UTC)<br />
<br />
::::::::That's cleanup, not prevention. Anyway, the point of {{ic|.gitignore}} is not to move the "cruft" away, but to keep the repo directory clean ''in git terms'', i.e. git should not report files created by makepkg as untracked. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:48, 14 March 2016 (UTC)<br />
<br />
:::::::::In that case, I refer to my comment below on just mentioning {{ic|.gitignore}}, but not recommending a specific method. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:47, 14 March 2016 (UTC)<br />
<br />
::::Recommending either way is problematic since this is more a question of git usage style rather than AUR usage. The maintainer should set up the .gitignore in an intuitive way ''depending'' on their git workflow and how the package is organized. If I had to recommend anything, it would be either: don't {{ic|git add .}} (because it's lazy and can easily backfire), or always check {{ic|git status}} before you commit to make sure you know what's staged (and we already recommend checking your commits before pushing). But again, those are more general git recommendations than anything AUR-specific. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 21:58, 9 March 2016 (UTC)<br />
<br />
:::::Using gitignore is useful not only for the comfort of the maintainer, but also of users building and installing the package. For example if {{ic|pkg/}}, {{ic|src/}} etc. are not gitignored, tools such as [https://github.com/kynikos/repocheck repocheck] will not work correctly. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:05, 9 March 2016 (UTC)<br />
<br />
::::::I still don't see how that is AUR-specific information. It is certainly good practice to have a gitignore for any git repo with files you don't want to track, but it is by no means necessary nor is it a practice specific to AUR repos. Adding git tricks to this article that are just general best practices is a slippery slope to creating a duplicate git tutorial like Quequotion did. I would much rather direct users to https://git-scm.com/doc and emphasize the importance of learning git properly before contributing AUR packages. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 17:58, 10 March 2016 (UTC)<br />
<br />
:::::::We know certain things could be .gitignored for every package, such as {{ic|src/}}, {{ic|pkg/}}, and {{ic|*.pkg.tar.xz}}; but we cannot know what files a packager may be using otherwise. I think having packagers create an explicit blacklist is the smallest and easiest of the available options. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 03:55, 13 March 2016 (UTC)<br />
<br />
::::::::Stuff makepkg creates can be moved automatically, as indicated above. The rest is an edge case, and the best way to handle it is subject to debate. If anything, just mention .gitignore, but not a specific approach to using it. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 12:35, 13 March 2016 (UTC)<br />
<br />
:::::::::I've changed my mind, and my perspective on this issue. I realized too late, after uploading several ridiculously large .gitignore files to AUR, that it's a huge waste of space (actually, you don't ''have to'' send .gitignore to AUR at all--but subsequent clones of your package will then not have a .gitignore). Putting an asterisk in it and using {{ic|git add -f}} is a better idea for the AUR's bandwidth and storage space. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 17:55, 17 July 2017 (UTC)<br />
<br />
== AUR search takes '%' literally ==<br />
<br />
[[Arch User Repository#Searching]] is marked by [[template:Accuracy]], though I couldn't see the discussion here. Did I missed something? There are some comments at [https://bbs.archlinux.org/viewtopic.php?id=226931 this forum thread]. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 14:21, 5 June 2017 (UTC)<br />
: I haven’t started the discussion, because I assume that the first person that has something to say should do that. Since all I had to say was stated in the {{ic|reason}}, I was not re-stating the problem here. Also I can’t fix that myself, because I have no idea how exactly AUR search works internally now and if this is just a bug or the current ''official'' status is that strings are taken literally. Therefore only marking it with [[Template:Accuracy]]. --[[User:Mpan|Mpan]] ([[User talk:Mpan|talk]]) 15:56, 5 June 2017 (UTC)<br />
<br />
== Markdown Syntax ==<br />
<br />
Should there be a Markdown syntax section? [https://lists.archlinux.org/pipermail/aur-general/2017-December/033697.html][https://git.archlinux.org/aurweb.git/log/?id=v4.6.0] All those seem to work: [https://aur.archlinux.org/packages/chromium-snapshot-bin/#comment-589706 link] —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 16:24, 5 December 2017 (UTC)<br />
<br />
:Oh wow, yes please. I had no idea that this was possible. And it's still unclear to me what syntax it uses. —[[User:Ostiensis|Ostiensis]] ([[User talk:Ostiensis|talk]]) 20:52, 5 December 2017 (UTC)<br />
<br />
::Well, there's a preliminary section: [[Arch_User_Repository#Comment_syntax]]. --'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 22:28, 13 December 2017 (UTC)<br />
<br />
:::[https://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=502556&oldid=502552] Well, I don't know how to do that, since they only implemented a small part of it? --'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 22:35, 13 December 2017 (UTC)<br />
<br />
::::[https://git.archlinux.org/aurweb.git/commit/?id=9aa4203c7efd5ef1015eb32eca5e0764a5afe183 Here] they use the [https://python-markdown.github.io/ Python-Markdown] library, which "is almost completely compliant with the reference implementation, though there are a few very minor [https://python-markdown.github.io/#differences differences]." -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:50, 13 December 2017 (UTC)<br />
<br />
:Thanks for that. FWIW I've never seen that multiline code syntax before, so I wonder if it *is* some strange home-brew markdown. —[[User:Ostiensis|Ostiensis]] ([[User talk:Ostiensis|talk]]) 22:37, 13 December 2017 (UTC)<br />
<br />
== FAQ - outdated package ==<br />
<br />
Do you understand what the comment means "When we are talking about a package which is flagged out of date for more than 3 months and is in general not updated for a long time, please add this in your orphan request. " ?<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 15:49, 13 January 2018 (UTC)<br />
<br />
:When people request a package to be orphaned because the current maintainer does not respond to out-of-date notifications, it should be clarified in the request to speed up the resolution. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:05, 13 January 2018 (UTC)<br />
<br />
::Yes indeed and what about the 2 weeks vs the 3 months difference in the comments? This is what I don't get, if this is more than 3 months we should say in the comments "it has been 4 months" but if it has been let say 2 months we should not mention it? The rule is not clear and I am wondering if it is more urgent to find an adopter for a package that has not been updated for 2 years or for 3 weeks. In the latter case it does seem more urgent, rather the opposite then. [[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 18:57, 13 January 2018 (UTC)<br />
<br />
:::I think that the 2 weeks are for the maintainers to react to the request, even if it is not due to out-of-date package. Anyway, the FAQ entries are not strict, I doubt that the 3 months are obligatory. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 13 January 2018 (UTC)<br />
::::I have rephrased providing some more details in line with the AUR request template. The 3 months does not seems to be anything official, the 2 weeks neither but sounds reasonable. Feel free to amend or revert. [[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 19:41, 13 January 2018 (UTC)<br />
<br />
== Add unsupported label in first paragraph ==<br />
<br />
Due to some people not getting the memo that AUR is not supported and packages should be inspected carefully, and there is no assumption of quality, this should be stated in the first paragraph to avoid confusion and butthurt. Especially for those unfamiliar with Arch Linux<br />
{{Unsigned|22:49, 30 March 2018|GI Jack}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=521272Arch User Repository2018-05-15T13:39:32Z<p>Ketsui: /* How can I speed up repeated build processes? */ Link to Makepkg#Improving_compile_times instead of just ccache.</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Package development]]<br />
[[Category:Package management]]<br />
[[ar:Arch User Repository]]<br />
[[cs:Arch User Repository]]<br />
[[da:Arch User Repository]]<br />
[[de:Arch User Repository]]<br />
[[el:Arch User Repository]]<br />
[[es:Arch User Repository]]<br />
[[fi:AUR]]<br />
[[fr:AUR]]<br />
[[it:Arch User Repository]]<br />
[[ja:Arch User Repository]]<br />
[[nl:Arch User Repository]]<br />
[[pl:Arch User Repository]]<br />
[[pt:Arch User Repository]]<br />
[[ro:AUR]]<br />
[[ru:Arch User Repository]]<br />
[[sr:Arch User Repository]]<br />
[[zh-hans:Arch User Repository]]<br />
[[zh-hant:Arch User Repository]]<br />
{{Related articles start}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|AurJson}}<br />
{{Related|AUR Trusted User Guidelines}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related|Creating packages}}<br />
{{Related|AUR helpers}}<br />
{{Related articles end}}<br />
<br />
The Arch User Repository (AUR) is a community-driven repository for Arch users. It contains package descriptions ([[PKGBUILD]]s) that allow you to compile a package from source with [[makepkg]] and then install it via [[pacman#Additional commands|pacman]]. The AUR was created to organize and share new packages from the community and to help expedite popular packages' inclusion into the [[community]] repository. This document explains how users can access and utilize the AUR.<br />
<br />
A good number of new packages that enter the official repositories start in the AUR. In the AUR, users are able to contribute their own package builds (PKGBUILD and related files). The AUR community has the ability to vote for or against packages in the AUR. If a package becomes popular enough &mdash; provided it has a compatible license and good packaging technique &mdash; it may be entered into the ''community'' repository (directly accessible by [[pacman]] or [[abs]]).<br />
<br />
== Getting started ==<br />
<br />
Users can search and download PKGBUILDs from the [https://aur.archlinux.org AUR Web Interface]. These PKGBUILDs can be built into installable packages using [[makepkg]], then installed using pacman.<br />
<br />
* Ensure the {{Grp|base-devel}} package group is installed ({{ic|pacman -S --needed base-devel}}).<br />
* Glance over the [[#FAQ]] for answers to the most common questions.<br />
* You may wish to adjust {{ic|/etc/makepkg.conf}} to optimize for your processor prior to building packages from the AUR. A significant improvement in compile times can be realized on systems with multi-core processors by adjusting the MAKEFLAGS variable. Users can also enable hardware-specific optimizations in GCC via the CFLAGS variable. See [[makepkg]] for more information.<br />
<br />
It is also possible to interact with the AUR through SSH: type {{ic|ssh aur@aur.archlinux.org help}} for a list of available commands.<br />
<br />
== History ==<br />
<br />
In the beginning, there was {{ic|<nowiki>ftp://ftp.archlinux.org/incoming</nowiki>}}, and people contributed by simply uploading the PKGBUILD, the needed supplementary files, and the built package itself to the server. The package and associated files remained there until a [[Package Maintainer]] saw the program and adopted it.<br />
<br />
Then the Trusted User Repositories were born. Certain individuals in the community were allowed to host their own repositories for anyone to use. The AUR expanded on this basis, with the aim of making it both more flexible and more usable. In fact, the AUR maintainers are still referred to as TUs (Trusted Users).<br />
<br />
Between 2015-06-08 and 2015-08-08 the AUR transitioned from version 3.5.1 to 4.0.0, introducing the use of Git repositories for publishing the PKGBUILDs.<br />
Existing packages were dropped unless manually migrated to the new infrastructure by their maintainers.<br />
<br />
=== Git repositories for AUR3 packages ===<br />
<br />
The [https://github.com/aur-archive AUR Archive] on GitHub has a repository for every package that was in AUR 3 at the time of the migration.<br />
Alternatively, there is the [https://github.com/felixonmars/aur3-mirror/ aur3-mirror] repository which provides the same.<br />
<br />
== Installing packages ==<br />
Installing packages from the AUR is a relatively simple process. Essentially:<br />
<br />
# Acquire the build files, including the [[PKGBUILD]] and possibly other required files, like [[systemd]] units and patches (often not the actual code).<br />
# Verify that the [[PKGBUILD]] and accompanying files are not malicious or untrustworthy.<br />
# Run {{ic|makepkg -si}} in the directory where the files are saved. This will download the code, resolve the dependencies with [[pacman]], compile it, package it, and install the package.<br />
<br />
{{Note|The AUR is unsupported, so any packages you install are ''your responsibility'' to update, not pacman's. If packages in the official repositories are updated, you will need to rebuild any AUR packages that depend on those libraries.}}<br />
=== Prerequisites ===<br />
<br />
First ensure that the necessary tools are installed by [[install]]ing the {{grp|base-devel}} group which includes {{pkg|make}} and other tools needed for compiling from source.<br />
<br />
{{Note|Packages in the AUR assume that the {{grp|base-devel}} group is installed, i.e. they do not list the group's members as dependencies explicitly.}}<br />
<br />
Next choose an appropriate build directory. A build directory is simply a directory where the package will be made or "built" and can be any directory. The examples in the following sections will use {{ic|~/builds}} as the build directory.<br />
<br />
=== Acquire build files ===<br />
<br />
Locate the package in the AUR. This is done using the search feature (text field at the top of the [https://aur.archlinux.org/ AUR home page]). Clicking the application's name in the search list brings up an information page on the package. Read through the description to confirm that this is the desired package, note when the package was last updated, and read any comments.<br />
<br />
There are several methods for acquiring the build files:<br />
<br />
* Clone the [[git]] repository that is labeled as the "Git Clone URL" in the "Package Details":<br />
<br />
$ git clone <nowiki>https://aur.archlinux.org/</nowiki>''package_name''.git<br />
<br />
:An advantage of this method is that you can easily get updates to the package via {{ic|git pull}}.<br />
* Download the build files with your web browser by clicking the "Download snapshot" link under "Package Actions" on the right hand side. This will download a compressed file, which must be extracted (preferably in a directory set aside for AUR builds)<br />
<br />
$ tar -xvf ''package_name''.tar.gz<br />
* Similarly, you can download a tarball from the terminal (and extract it):<br />
<br />
$ curl -L -O <nowiki>https://aur.archlinux.org/cgit/aur.git/snapshot/</nowiki>''package_name''.tar.gz<br />
<br />
=== Build and install the package ===<br />
<br />
Change directories to the directory containing the package's [[PKGBUILD]].<br />
<br />
{{Warning|'''Carefully check all files.''' Carefully check the {{ic|PKGBUILD}} and any ''.install'' file for malicious commands. {{ic|PKGBUILD}}s are [[bash]] scripts containing functions to be executed by ''makepkg'': these functions can contain ''any'' valid commands or Bash syntax, so it is totally possible for a {{ic|PKGBUILD}} to contain dangerous commands through malice or ignorance on the part of the author. Since ''makepkg'' uses ''fakeroot'' (and should never be run as root), there is some level of protection but you should never count on it. If in doubt, do not build the package and seek advice on the forums or mailing list.}}<br />
<br />
$ cd ''package_name''<br />
$ less PKGBUILD<br />
$ less ''package_name''.install<br />
<br />
Make the package. After manually confirming the integrity of the files, run [[makepkg]] as a normal user:<br />
<br />
$ makepkg -si<br />
<br />
* {{ic|-s}}/{{ic|--syncdeps}} automatically resolves and installs any dependencies with [[pacman]] before building. If the package depends on other AUR packages, you will need to manually install them first.<br />
* {{ic|-i}}/{{ic|--install}} installs the package if it is built successfully. Alternatively the built package can be installed with {{ic|pacman -U ''package''.pkg.tar.xz}}.<br />
<br />
Other useful flags are<br />
<br />
* {{ic|-r}}/{{ic|--rmdeps}} removes build-time dependencies after the build, as they are no longer needed. However these dependencies may need to be reinstalled the next time the package is updated.<br />
* {{ic|-c}}/{{ic|--clean}} cleans up temporary build files after the build, as they are no longer needed. These files are usually needed only when debugging the build process.<br />
<br />
{{Note|The above example is only a brief summary of the build process. It is '''highly''' recommended to read the [[makepkg]] and [[ABS]] articles for more details.}}<br />
<br />
== Feedback ==<br />
<br />
The [https://aur.archlinux.org AUR Web Interface] has a comments facility that allows users to provide suggestions and feedback on improvements to the PKGBUILD contributor. Avoid pasting patches or PKGBUILDs into the comments section: they quickly become obsolete and just end up needlessly taking up lots of space. Instead email those files to the maintainer, or even use a [[pastebin]].<br />
<br />
One of the easiest activities for '''all''' Arch users is to browse the AUR and '''vote''' for their favourite packages using the online interface. All packages are eligible for adoption by a TU for inclusion in the [[community]] repository, and the vote count is one of the considerations in that process; it is in everyone's interest to vote!<br />
<br />
== Sharing and maintaining packages ==<br />
<br />
{{Note|1=Please see [https://wiki.archlinux.org/index.php?title=Talk:Arch_User_Repository&oldid=484964#Scope_of_the_AUR4_section Talk:Arch User Repository#Scope of the AUR4 section] before making changes to this section.}}<br />
<br />
Users can '''share''' PKGBUILDs using the Arch User Repository. It does not contain any binary packages but allows users to upload PKGBUILDs that can be downloaded by others. These PKGBUILDs are completely unofficial and have not been thoroughly vetted, so they should be used at your own risk.<br />
<br />
=== Submitting packages ===<br />
<br />
{{Warning|Before attempting to submit a package you are expected to familiarize yourself with [[Arch packaging standards]] and all the articles under "Related articles". '''Verify carefully''' that what you are uploading is correct. Packages that violate the rules may be '''deleted''' without warning.}}<br />
<br />
If you are unsure in any way about the package or the build/submission process even after reading this section twice, submit the PKGBUILD to the [https://mailman.archlinux.org/mailman/listinfo/aur-general AUR mailing list], the [https://bbs.archlinux.org/viewforum.php?id=4 AUR forum] on the Arch forums, or ask on our [[IRC channel]] for public review before adding it to the AUR.<br />
<br />
==== Rules of submission ====<br />
<br />
When submitting a package to the AUR, observe the following rules:<br />
<br />
* The submitted PKGBUILDs must not build applications '''already in any''' of the '''official''' binary '''repositories''' under any circumstances. Check the [https://www.archlinux.org/packages/ official package database] for the package. If any version of it exists, '''do not''' submit the package. If the official package is out-of-date, flag it as such. If the official package is broken or is lacking a feature, then please file a [https://bugs.archlinux.org/ bug report].<br />
:'''Exception''' to this strict rule may only be packages having '''extra features''' enabled and/or '''patches''' in comparison to the official ones. In such an occasion the {{ic|pkgname}} should be different to express that difference. For example, a package for GNU screen containing the sidebar patch could be named {{ic|screen-sidebar}}. Additionally the {{ic|1=provides=('screen')}} array should be used in order to avoid conflicts with the official package.<br />
<br />
* '''Check the AUR''' if the package '''already exists'''. If it is currently maintained, changes can be submitted in a comment for the maintainer's attention. If it is unmaintained or the maintainer is unresponsive, the package can be adopted and updated as required. Do not create duplicate packages.<br />
<br />
* Make sure the package you want to upload is '''useful'''. Will anyone else want to use this package? Is it extremely specialized? If more than a few people would find this package useful, it is appropriate for submission.<br />
<br />
:The AUR and official repositories are intended for packages which install generally software and software-related content, including one or more of the following: executable(s); config file(s); online or offline documentation for specific software or the Arch Linux distribution as a whole; media intended to be used directly by software.<br />
<br />
* Do not use {{ic|replaces}} in an AUR PKGBUILD unless the package is to be renamed, for example when ''Ethereal'' became ''Wireshark''. If the package is an '''alternate version of an already existing package''', use {{ic|conflicts}} (and {{ic|provides}} if that package is required by others). The main difference is: after syncing (-Sy) pacman immediately wants to replace an installed, 'offending' package upon encountering a package with the matching {{ic|replaces}} anywhere in its repositories; {{ic|conflicts}}, on the other hand, is only evaluated when actually installing the package, which is usually the desired behavior because it is less invasive.<br />
<br />
* Submitting '''binaries''' should be '''avoided''' if the sources are available. The AUR should not contain the binary tarball created by makepkg, nor should it contain the filelist.<br />
<br />
* Please add a '''comment line''' to the top of the {{ic|PKGBUILD}} file which contains information about the current '''maintainers''' and previous '''contributors''', respecting the following format. Remember to disguise your email to protect against spam. Additional or unneeded lines are facultative.<br />
:If you are assuming the role of maintainer for an existing PKGBUILD, add your name to the top like this<br />
:{{bc|<nowiki><br />
# Maintainer: Your Name <address at domain dot tld><br />
</nowiki>}}<br />
:If there were previous maintainers, put them as contributors. The same applies for the original submitter if this is not you. If you are a co-maintainer, add the names of the other current maintainers as well.<br />
:{{bc|<nowiki><br />
# Maintainer: Your name <address at domain dot tld><br />
# Maintainer: Other maintainer's name <address at domain dot tld><br />
# Contributor: Previous maintainer's name <address at domain dot tld><br />
# Contributor: Original submitter's name <address at domain dot tld><br />
</nowiki>}}<br />
<br />
==== Authentication ====<br />
<br />
For write access to the AUR, you need to have an [[SSH keys|SSH key pair]]. The content of the public key needs to be copied to your profile in ''My Account'', and the corresponding private key configured for the {{ic|aur.archlinux.org}} host. For example:<br />
<br />
{{hc|~/.ssh/config|<br />
Host aur.archlinux.org<br />
IdentityFile ~/.ssh/aur<br />
User aur}}<br />
<br />
You should [[SSH_keys#Generating_an_SSH_key_pair|create a new key pair]] rather than use an existing one, so that you can selectively revoke the keys should something happen:<br />
<br />
$ ssh-keygen -f ~/.ssh/aur<br />
<br />
{{Tip|You can add multiple public keys to your profile by separating them with a newline in the input field.}}<br />
<br />
==== Creating a new package ====<br />
<br />
In order to create a new, empty, local Git repository for a package, simply {{ic|git clone}} the remote repository with the corresponding name. If the package does not exist on AUR yet, you will see the following warning:<br />
<br />
{{hc|$ git clone <nowiki>ssh://</nowiki>aur@aur.archlinux.org/''package_name''.git|<br />
Cloning into &apos;''package_name''&apos;...<br />
warning: You appear to have cloned an empty repository.<br />
Checking connectivity... done.}}<br />
<br />
{{Note|When a package on the AUR is deleted, the git repository is not deleted so it is possible for a deleted package's repository to not be empty when cloned if someone is creating a package with the same name.}}<br />
<br />
If you have already created a git repository, you can simply create a remote for the AUR git repository and then fetch it:<br />
<br />
$ git remote add ''remote_name'' <nowiki>ssh://</nowiki>aur@aur.archlinux.org/''package_name''.git<br />
$ git fetch ''remote_name''<br />
<br />
where {{ic|''remote_name''}} is the name of the remote to create (''e.g.,'' "origin"). See [[Git#Using remotes]] for more information.<br />
<br />
The new package will appear on AUR after you ''push'' the first commit. You can now add the source files to the local copy of the Git repository. See [[#Uploading packages]].<br />
<br />
{{Warning|Your AUR commits will be authored according to your git user name and email address and it is very difficult to change commits after you push them (see {{Bug|45425}}). If you want to push to AUR under a different name/email, you can change them for this package via {{ic|git config user.name [...]}} and {{ic|git config user.email [...]}}. Review your commits before pushing them!}}<br />
<br />
==== Uploading packages ====<br />
<br />
The procedure for uploading packages to the AUR is the same for new packages and package updates. You need at least [[PKGBUILD]] and [[.SRCINFO]] in the top-level directory to ''push'' your package to AUR.<br />
<br />
{{Note|You need to regenerate the {{ic|.SRCINFO}} every time you change {{ic|PKGBUILD}} metadata, such as [[PKGBUILD#pkgver|pkgver()]] updates. Otherwise the AUR will not show the updated version numbers.}}<br />
<br />
To upload, add the {{ic|PKGBUILD}}, {{ic|.SRCINFO}}, and any helper files (like ''.install'' files or local source files like ''.patch'') to the ''staging area'' with {{ic|git add}}, commit them to your local tree with a commit message with {{ic|git commit}}, and finally publish the changes to the AUR with {{ic|git push}}.<br />
<br />
For example:<br />
<br />
$ makepkg --printsrcinfo > .SRCINFO<br />
$ git add PKGBUILD .SRCINFO<br />
$ git commit -m "''useful commit message''"<br />
$ git push<br />
<br />
{{Tip|<br />
* If you initially forgot to commit the {{ic|.SRCINFO}} and added it in a later commit, the AUR will still reject your pushes because the {{ic|.SRCINFO}} must exist for ''every'' commit. To solve this problem you can use [https://git-scm.com/docs/git-rebase git rebase] with the {{ic|--root}} option or [https://git-scm.com/docs/git-filter-branch git filter-branch] with the {{ic|--tree-filter}} option.<br />
* To prevent untracked files from commits and to keep the working directory as clean as possible, exclude all files with {{ic|.gitignore}} and force-add files instead. See [[dotfiles#Using gitignore]].<br />
}}<br />
<br />
=== Maintaining packages ===<br />
<br />
* Check for feedback and comments from other users and try to incorporate any improvements they suggest; consider it a learning process!<br />
* Please do not leave a comment containing the version number every time you update the package. This keeps the comment section usable for valuable content mentioned above. [[AUR helpers]] are suited better to check for updates.<br />
* Please do not just submit and forget about packages! It is the maintainer's job to maintain the package by checking for updates and improving the PKGBUILD.<br />
* If you do not want to continue to maintain the package for some reason, {{ic|disown}} the package using the AUR web interface and/or post a message to the AUR Mailing List. If all maintainers of an AUR package disown it, it will become an [https://aur.archlinux.org/packages/?O=0&SeB=nd&K=&outdated=&SB=n&SO=a&PP=50&do_Orphans=Orphans "orphaned"] package.<br />
<br />
=== Other requests ===<br />
<br />
Orphan, deletion and merge requests can be created by clicking on the "Submit Request" link under "Package Actions" on the right hand side. This automatically sends a notification email to the current package maintainer and to the [https://mailman.archlinux.org/mailman/listinfo/aur-requests aur-requests mailing list] for discussion. [[Trusted Users]] will then either accept or reject the request. <br />
* Orphan requests will be granted after two weeks if the current maintainer did not react.<br />
* Merge requests are to delete the package base and transfer its votes and comments to another package base. The name of the package base to merge into is required. Note this has nothing to do with 'git merge' or GitLab's merge requests. <br />
* Deletion requests require the following information:<br />
** A short note explaining the reason for deletion. Note that a package's comments does not sufficiently point out the reasons why a package is up for deletion. Because as soon as a TU takes action, the only place where such information can be obtained is the aur-requests mailing list.<br />
** Supporting details, like when a package is provided by another package, if you are the maintainer yourself, it is renamed and the original owner agreed, etc.<br />
** Deletion requests can be rejected, in which case if you are the maintainer of the package you will likely be advised to disown the package to allow adoption by another packager.<br />
<br />
== Web interface translation ==<br />
<br />
See [https://projects.archlinux.org/aurweb.git/tree/doc/i18n.txt i18n.txt] in the AUR source tree for information about creating and maintaining translation of the AUR web interface.<br />
<br />
== Comment syntax ==<br />
<br />
The [https://python-markdown.github.io/ Python-Markdown] syntax is supported in comments.<br />
It provides basic [[Wikipedia:Markdown|Markdown]] syntax to format comments. Note this implementation has some occasional [https://python-markdown.github.io/#differences differences] with the official [https://daringfireball.net/projects/markdown/syntax syntax rules]. Commit hashes to the Git repository of the package and references to Flyspray tickets are converted to links automatically. Long comments are collapsed and can be expanded on demand.<br />
<br />
== FAQ ==<br />
<br />
=== What is the AUR? ===<br />
<br />
The AUR (Arch User Repository) is a place where the Arch Linux community can upload [[PKGBUILD]]s of applications, libraries, etc., and share them with the entire community. Fellow users can then vote for their favorites to be moved into the [[community]] repository to be shared with Arch Linux users in binary form.<br />
<br />
=== What kind of packages are permitted on the AUR? ===<br />
<br />
The packages on the AUR are merely "build scripts", i.e. recipes to build binaries for pacman. For most cases, everything is permitted, subject to the abovementioned [[#Rules of submission|usefulness and scope guidelines]], as long as you are in compliance with the licensing terms of the content. For other cases, where it is mentioned that "you may not link" to downloads, i.e. contents that are not redistributable, you may only use the file name itself as the source. This means and requires that users already have the restricted source in the build directory prior to building the package. When in doubt, ask.<br />
<br />
=== How can I vote for packages in the AUR? ===<br />
<br />
Sign up on the [https://aur.archlinux.org/ AUR website] to get a "Vote for this package" option while browsing packages. After signing up it is also possible to vote from the commandline with {{AUR|aurvote}}, {{AUR|aurvote-git}} or {{AUR|aur-auto-vote-git}}.<br />
<br />
Alternatively, if you have set up [[#Authentication|ssh authentication]] as above, you can directly vote from the command line using your ssh key. This means that you won't need to save or type in your AUR password.<br />
<br />
ssh aur@aur.archlinux.org vote <PACKAGE_NAME><br />
<br />
=== What is a Trusted User / TU? ===<br />
<br />
A [[AUR Trusted User Guidelines|Trusted User]], in short TU, is a person who is chosen to oversee AUR and the [[community]] repository. They are the ones who maintain popular PKGBUILDs in ''community'', and overall keep the AUR running.<br />
<br />
=== What is the difference between the Arch User Repository and the community repository? ===<br />
<br />
The Arch User Repository is where all PKGBUILDs that users submit are stored, and must be built manually with [[makepkg]]. When PKGBUILDs receive enough community interest and the support of a TU, they are moved into the [[community]] repository (maintained by the TUs), where the binary packages can be installed with [[pacman]].<br />
<br />
=== Foo in the AUR is outdated; what should I do? ===<br />
<br />
First, you should flag the package ''out-of-date'' indicating details on why the package is outdated, preferably including links to the release announcement or the new release tarball.<br />
You should also try to reach out to the maintainer directly by email. If there is no response from the maintainer after ''two weeks'', you can file an ''orphan'' request. This means you ask a [[Trusted User]] to disown the package base. This is to be done only if the package requires maintainer action, that he/she is not responding and you already tried to contact him/her previously.<br />
<br />
In the meantime, you can try updating the package yourself by editing the PKGBUILD locally. Sometimes, updates do not require changes to the build or package process, in which case simply updating the {{ic|pkgver}} or {{ic|source}} array is sufficient.<br />
<br />
{{Note|[[VCS package guidelines|VCS packages]] are not considered out of date when the pkgver changes, do not flag them as the maintainer will merely unflag the package and ignore you. AUR maintainers should not commit mere pkgver bumps.}}<br />
<br />
=== Foo in the AUR does not compile when I run makepkg; what should I do? ===<br />
<br />
You are probably missing something trivial.<br />
<br />
# [[Pacman#Upgrading_packages|Upgrade the system]] before compiling anything with {{ic|makepkg}} as the problem may be that your system is not up-to-date.<br />
# Ensure you have both {{Grp|base}} and {{Grp|base-devel}} groups installed.<br />
# Try using the {{ic|-s}} option with {{ic|makepkg}} to check and install all the dependencies needed before starting the build process.<br />
<br />
Be sure to first read the PKGBUILD and the comments on the AUR page of the package in question.<br />
The reason might not be trivial after all. Custom CFLAGS, LDFLAGS and MAKEFLAGS can cause failures. It is also possible that the PKGBUILD is broken for everyone. If you cannot figure it out on your own, just report it to the maintainer e.g. by posting the errors you are getting in the comments on the AUR page.<br />
<br />
=== How do I create a PKGBUILD? ===<br />
<br />
The best resource is the wiki page about [[creating packages]]. Remember to look in AUR before creating the PKGBUILD as to not duplicate efforts.<br />
<br />
=== I have a PKGBUILD I would like to submit; can someone check it to see if there are any errors? ===<br />
<br />
If you would like to have your PKGBUILD reviewed, post it on the [https://mailman.archlinux.org/mailman/listinfo/aur-general aur-general mailing list] to get feedback from the TUs and fellow AUR members. You could also get help from the [[IRC channel]], #archlinux-aur on irc.freenode.net. You can also use [[namcap]] to check your PKGBUILD and the resulting package for errors.<br />
<br />
=== How to get a PKGBUILD into the community repository? ===<br />
<br />
Usually, at least 10 votes are required for something to move into [[community]]. However, if a TU wants to support a package, it will often be found in the repository.<br />
<br />
Reaching the required minimum of votes is not the only requirement, there has to be a TU willing to maintain the package. TUs are not required to move a package into the ''community'' repository even if it has thousands of votes.<br />
<br />
Usually when a very popular package stays in the AUR it is because:<br />
<br />
* Arch Linux already has another version of a package in the repositories<br />
* The package is AUR-centric (e.g. an [[AUR helper]])<br />
* Its license prohibits redistribution<br />
<br />
See also [[DeveloperWiki:Community repo candidates]] and [[AUR Trusted User Guidelines#Rules for Packages Entering the .5Bcommunity.5D Repo|Rules for Packages Entering the community Repo]].<br />
<br />
=== How can I speed up repeated build processes? ===<br />
<br />
See [[Makepkg#Improving_compile_times]].<br />
<br />
=== What is the difference between foo and foo-git packages? ===<br />
<br />
Many AUR packages are presented in regular ("stable") and development versions ("unstable"). A development package usually has a suffix such as {{ic|-cvs}}, {{ic|-svn}}, {{ic|-git}}, {{ic|-hg}}, {{ic|-bzr}} or {{ic|-darcs}}. While development packages are not intended for regular use, they may offer new features or bugfixes. Because these packages download the latest available source when you execute {{ic|makepkg}}, a package version to track possible updates is not directly available for these. Likewise, these packages cannot perform an authenticity checksum, instead it is relied on the maintainer(s) of the Git repository. <br />
<br />
See also [[System maintenance#Use proven software packages]].<br />
<br />
=== Why has foo disappeared from the AUR? ===<br />
<br />
It is possible the package has been adopted by a TU and is now in the [[community]] repository.<br />
<br />
Packages may be deleted if they did not fulfill the [[#Rules of submission]]. See the [https://lists.archlinux.org/pipermail/aur-requests/ aur-requests archives] for the reason for deletion.<br />
<br />
If the package used to exist in AUR3, it might not have been [https://lists.archlinux.org/pipermail/aur-general/2015-August/031322.html migrated to AUR4]. See the [[#Git repositories for AUR3 packages]] where these are preserved.<br />
<br />
=== How do I find out if any of my installed packages disappeared from AUR? ===<br />
<br />
The simplest way is to check the HTTP status of the package's AUR page:<br />
<br />
$ comm -23 <(pacman -Qqm | sort) <(curl https://aur.archlinux.org/packages.gz | gzip -cd | sort)<br />
<br />
If you use an [[AUR helper]], you can shorten this script by replacing the curl command with whatever command queries the AUR for a package.<br />
<br />
=== How can I obtain a list of all AUR packages? ===<br />
<br />
* https://aur.archlinux.org/packages.gz<br />
* Use <code>aurpkglist</code> from {{aur|python3-aur}}<br />
<br />
== See also ==<br />
* [https://aur.archlinux.org AUR Web Interface]<br />
* [https://lists.archlinux.org/listinfo/aur-general AUR Mailing List]<br />
* [[DeveloperWiki:AUR Cleanup Day]]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521269Mpv2018-05-15T13:02:49Z<p>Ketsui: /* Hardware decoding */ the opengl vo was renamed to gpu</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|gpu}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of ''mpv'''s Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, ''mpv'' can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when ''mpv'' is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
''mpv'' may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line (the -v flag increases verbosity). If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv -v video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv -v --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521268Mpv2018-05-15T12:50:52Z<p>Ketsui: /* General debugging */ Add verbose flag</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of ''mpv'''s Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, ''mpv'' can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when ''mpv'' is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
''mpv'' may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line (the -v flag increases verbosity). If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv -v video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv -v --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521267Mpv2018-05-15T12:47:27Z<p>Ketsui: /* GNOME Blank screen (Wayland) */ Help:Style/Formatting_and_punctuation#Executable.2Fapplication_names</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of ''mpv'''s Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, ''mpv'' can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when ''mpv'' is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
''mpv'' may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line. If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521266Mpv2018-05-15T12:46:57Z<p>Ketsui: /* Use mpv with a compositor */ Help:Style/Formatting_and_punctuation#Executable.2Fapplication_names</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of ''mpv'''s Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, ''mpv'' can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when ''mpv'' is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line. If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521265Mpv2018-05-15T12:46:30Z<p>Ketsui: /* Twitch.tv streaming over mpv */ Help:Style/Formatting_and_punctuation#Executable.2Fapplication_names</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of ''mpv'''s Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, ''mpv'' can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when mpv is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line. If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521264Mpv2018-05-15T12:45:59Z<p>Ketsui: /* Improving mpv as a music player with Lua scripts */ Help:Style/Formatting_and_punctuation#Executable.2Fapplication_names</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of ''mpv'''s Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, mpv can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when mpv is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line. If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521263Mpv2018-05-15T12:44:06Z<p>Ketsui: /* Restoring old OSC */ Help:Style/Formatting_and_punctuation#Executable.2Fapplication_names</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, ''mpv'' has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the ''mpv'' configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of mpv's Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, mpv can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when mpv is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line. If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Mpv&diff=521262Mpv2018-05-15T12:42:17Z<p>Ketsui: /* In GNOME Wayland */ Help:Style/Formatting_and_punctuation#Executable.2Fapplication_names</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Multimedia players]]<br />
[[ja:Mpv]]<br />
[[ru:Mpv]]<br />
[[zh-hans:Mpv]]<br />
{{Related articles start}}<br />
{{Related|MPlayer}}<br />
{{Related articles end}}<br />
<br />
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and the now unmaintained ''mplayer2''. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.<br />
<br />
=== Front ends ===<br />
<br />
mpv comes with a minimal GUI called On Screen Controller ''(OSC)'', that appears when moving the mouse. There are also other front ends available:<br />
<br />
* {{App|Baka MPlayer|Free and open source, cross-platform, ''mpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}}}<br />
* {{App|Deepin Movie|Movie player for Deepin desktop based on ''mpv''.|https://github.com/linuxdeepin/deepin-movie-reborn|{{Pkg|deepin-movie}}}}<br />
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{Pkg|gnome-mpv}}}}<br />
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt}}}}<br />
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}<br />
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv}}}}<br />
<br />
== Configuration ==<br />
<br />
''mpv'' comes with good all-around defaults that should work well on computers with weaker/older video cards. However, if you have a computer with a more modern video card then mpv allows you to do a great deal of configuration to achieve better video quality (limited only by the power of your video card). To do this one only needs to create a few configuration files (they do not exist by default).<br />
<br />
{{Note| Configuration files are read system-wide from {{ic|/etc/mpv}} and per-user from {{ic|~/.config/mpv}} (unless the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is set), where per-user settings override system-wide settings, all of which are overridden by the command line. User specific configuration is suggested since it may require some trial and error.}}<br />
<br />
First create the {{ic|~/.config/mpv}} directory if it does not already exist.<br />
$ mkdir ~/.config/mpv<br />
<br />
To help you get you started ''mpv'' provides a couple empty sample configuration files with a lot of options commented out, they are located at {{ic|/usr/share/doc/mpv/}}. <br />
* {{ic|mpv.conf}} will contain the majority of ''mpv'''s settings.<br />
* {{ic|input.conf}} will just contain key bindings.<br />
<br />
Read through both of them to get an idea of how they work and what options are available. You may copy them to your config folder to use as a starting point if you like:<br />
$ cp /usr/share/doc/mpv/mpv.conf ~/.config/mpv/mpv.conf<br />
$ cp /usr/share/doc/mpv/input.conf ~/.config/mpv/input.conf<br />
<br />
=== General settings - mpv.conf ===<br />
<br />
==== High quality configurations ====<br />
<br />
This loads high quality OpenGL options. Most users can run these without any problems, but they are not enabled by default to avoid causing problems for the few users who cannot run them.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
}}<br />
<br />
The {{ic|gpu-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
}}<br />
<br />
These last three options are a little more complicated. The first option makes it so that if audio and video go out of sync then instead of dropping video frames it will resample the audio (a slight change in audio pitch is often less noticeable than dropped frames). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Display-synchronization Display Synchronization]. The remaining two essentially make motion appear smoother on your display by changing the way that frames are shown so that the source framerate jives better with your display's refresh rate (not to be confused with SVP's technique which actually converts video to 60fps). The mpv wiki has an in depth article on it titled [https://github.com/mpv-player/mpv/wiki/Interpolation Interpolation] though it is also commonly known as ''smoothmotion''.<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=gpu-hq<br />
scale=ewa_lanczossharp<br />
cscale=ewa_lanczossharp<br />
video-sync=display-resample<br />
interpolation<br />
tscale=oversample<br />
}}<br />
<br />
Beyond this there is still a lot you can do but things become more complicated, require more powerful video cards, and are in constant development. As a brief overview, it is possible to load special shaders that perform exotic scaling and sharpening techniques including some that actually use deep neural networks trained on images (for both real world and animated content). To learn more about this take a look around the [https://github.com/mpv-player/mpv/wiki mpv wiki], particularly the [https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders user shader's section].<br />
<br />
There are also plenty of other options you may find desirable as well. It is worthwhile taking a look at {{man|1|mpv}}. It's also helpful to run ''mpv'' from the command line to check for error messages about the config.<br />
<br />
==== Profiles ====<br />
<br />
In {{ic|mpv.conf}} it is possible to create ''profiles'' which are essentially just "groups of options" with which you can:<br />
* Quickly switch between different configurations without having to rewrite the file.<br />
* Create special profiles for special content.<br />
* ''nest'' profiles so that you can make more complicated ''profiles'' out of simpler ones.<br />
<br />
Creating a profile is easy. The area at the top of {{ic|mpv.conf}} is called the top level, any options you write there will kick into effect once ''mpv'' is started. However, once you define a profile by writing its name in brackets then every option you write below it (until you define a new profile) is considered part of that profile. Here is an example {{ic|mpv.conf}}:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=<br />
profile=myprofile2 #Top level area, load myprofile2<br />
ontop=yes #Always on top<br />
<br />
[myprofile1] #A simple profile, top level area ends here<br />
profile-desc="a profile" #Optional description for profile<br />
fs=yes #Start in full screen<br />
<br />
[myprofile2] #Another simple profile<br />
profile=gpu-hq #A built in profile that comes with mpv<br />
log-file=~~/log #Sets a location for writing a log file, ~~/ translates to ~/.config/mpv<br />
}}<br />
<br />
There are only two lines within the top level area and there are two separate profiles defined below it. When ''mpv'' starts it sees the first line, loads the options in {{ic|myprofile2}} (which means it loads the options in {{ic|gpu-hq}} and {{ic|1=log-file=~~/log}}) finally it loads {{ic|1=ontop=yes}} and finishes starting up. Note, {{ic|myprofile1}} is never loaded because it's never called in the top level area.<br />
<br />
Alternatively one could call mpv from the command line with<br />
$ mpv --profile=myprofile1 video.mkv<br />
and it would ignore all options except the ones in {{ic|myprofile1}}.<br />
<br />
=== Key bindings - input.conf ===<br />
<br />
Key bindings are actually fairly straightforward given the examples in {{ic|/usr/share/doc/mpv/input.conf}} and the relevant section in the [https://mpv.io/manual/master/#command-interface manual].<br />
<br />
Here is an {{ic|input.conf}} file that attempts to reproduce [https://github.com/dragons4life/MPC-HC-config-for-MPV/blob/master/input.conf MPC-HC keybindings] in mpv.<br />
<br />
Here are some more fun examples:<br />
<br />
Alt+RIGHT add video-rotate 90<br />
Alt+LEFT add video-rotate -90<br />
Alt+- add video-zoom -0.25<br />
Alt+= add video-zoom 0.25<br />
Alt+j add video-pan-x -0.05<br />
Alt+l add video-pan-x 0.05<br />
Alt+i add video-pan-y 0.05<br />
Alt+k add video-pan-y -0.05<br />
Alt+BS set video-zoom 0; set video-pan-x 0; set video-pan-y 0<br />
<br />
=== Additional configuration files ===<br />
<br />
In addition there are a few more configuration files one can create:<br />
* {{ic|~/.config/mpv/lua-settings/osc.conf}} manages the [https://mpv.io/manual/master/#on-screen-controller On Screen Controller]<br />
* If you are using any Lua scripts then you can create a corresponding conf file for each one here: {{ic|~/.config/mpv/lua-settings/''scriptname''.conf}} <br />
* [https://mpv.io/manual/master/#files lots more]<br />
<br />
== Scripts ==<br />
<br />
''mpv'' has a [https://github.com/mpv-player/mpv/wiki/User-Scripts large variety of scripts] that extend the functionality of the player. To this end, it has internal bindings for both Lua and JavaScript (added recently).<br />
<br />
Scripts are typically installed by putting them in the {{ic|~/.config/mpv/scripts/}} directory (you may have to create it first). After that they will be automatically loaded when mpv starts (this behavior can be altered with other mpv options). Some scripts come with their own installation and configuration instructions, so make sure to have a look. In addition some scripts are old, broken, and unmaintained.<br />
<br />
=== JavaScript ===<br />
<br />
Since JavaScript support is still fairly new, there is currently very little in the way of scripts, but [https://mpv.io/manual/master/#javascript documentation exists] for anyone interested in making their own.<br />
<br />
JavaScript support isn't available in the {{Pkg|mpv}} build, but it's supported by some AUR packages e.g. {{AUR|mpv-full}} and {{AUR|mpv-full-git}}.<br />
<br />
=== Lua ===<br />
<br />
There are a lot of interesting Lua scripts for mpv. If you would like to make your own, the relevant documentation may be found [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst here].<br />
<br />
==== mpv-stats ====<br />
<br />
[https://github.com/Argon-/mpv-stats/ mpv-stats] (or simply ''stats'') is a Lua script that outputs a lot of live statistics showing how well mpv is currently doing. It is very useful for making sure that your hardware can keep up with your configuration and for comparing different configurations. Since version [https://github.com/mpv-player/mpv/releases/tag/v0.28.0 v0.28.0], the script is built into {{Pkg|mpv}} and can be toggled on or off with the {{ic|i}} or {{ic|I}} keys (by default).<br />
<br />
==== mpv-webm ====<br />
<br />
[https://github.com/ElegantMonkey/mpv-webm mpv-webm] (or simply ''webm'') is a very easy to use Lua script that allows one to create WebM files while watching videos. It includes several features and does not have any extra dependencies (relies entirely on mpv).<br />
<br />
=== C ===<br />
<br />
==== mpv-mpris ====<br />
<br />
The C plugin [https://github.com/hoyon/mpv-mpris mpv-mpris] allows other applications to integrate with mpv via the MPRIS protocol. For example, with mpv-mpris installed, {{pkg|kdeconnect}} can automatically pause video playback in mpv when a phone call arrives.<br />
<br />
Install {{AUR|mpv-mpris}} and follow the post-installation instructions displayed by Pacman.<br />
<br />
== Vapoursynth ==<br />
<br />
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.<br />
<br />
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package (or {{AUR|vapoursynth-git}}) and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.<br />
<br />
This is easier to do by first installing Vapoursynth and then installing (or re-installing if it's already installed) {{AUR|mpv-git}}. The configure script for {{AUR|mpv-git}} will auto-detect Vapoursynth (as long as it has already been installed) and it will automatically compile mpv with support for Vapoursynth without having to manually change any configure options or anything (this makes it very easy to update mpv as well).<br />
<br />
=== SVP 4 Linux (SmoothVideoProject) ===<br />
<br />
[https://www.svp-team.com/wiki/Main_Page SmoothVideoProject SVP] is a program that's primarily known for converting video to 60fps. It's free [as in beer] and full featured for 64bit Linux (costs money for Windows and OS X and is incompatible with 32bit Linux).<br />
<br />
It has three main features and each one can be disabled/enabled as one chooses (you are not forced to use motion interpolation).<br />
# [https://www.svp-team.com/wiki/Manual:FRC Motion interpolation] ([https://www.youtube.com/watch?v=Wjb6CSe4708 youtube video]) - An algorithm that converts video to 60fps. This creates the somewhat controversial "soap opera effect" that some people love and others hate. Unfortunately the algorithm is not perfect and it also introduces more than its share of weird artifacts. The algorithm can be tuned (via a slider) for either performance or quality. It also has some artifact reduction settings that interpolate actual frames with the generated frames reducing the noticeability of the artifacts. The framerate detection can be set to automatic or manual (manual seems to resolve performance issues for some users).<br />
# [https://www.svp-team.com/wiki/Manual:Outer_lighting Black bar lighting] ([https://www.youtube.com/watch?v=yTzTpW3kTBE youtube video]) - If the image has an aspect ratio that produces black bars on your display then SVP will illuminate the black bars with "lights" generated by the content on the screen. It has some amount of customization but the defaults are pretty close to optimal.<br />
# [https://www.svp-team.com/wiki/Manual:SVPlight LED ambient lighting control] ([https://www.youtube.com/watch?v=UUM2n-8kIJ8 youtube video]) - Has the ability to control LED ambient lighting attached to your television.<br />
<br />
Once you have mpv compiled with Vapoursynth support it's fairly easy to get SVP working with mpv. Simply install {{AUR|svp}}, open the SVP program to let it assess your system performance (you may want to close other programs first so that it gets an accurate reading), and finally add the following mpv profile to your mpv.conf (taken from [https://www.svp-team.com/wiki/SVP:mpv here]):<br />
{{hc|1=mpv.conf|2=<br />
[svp]<br />
input-ipc-server=/tmp/mpvsocket # Receives input from SVP<br />
hr-seek-framedrop=no # Fixes audio desync<br />
resume-playback=no # Not compatible with SVP<br />
<br />
# Can fix stuttering in some cases, in other cases probably causes it. Try it if you experience stuttering.<br />
#opengl-early-flush=yes <br />
}}<br />
Then, in order to use SVP you must have the SVP program running in the background before opening the file using mpv with that profile. Either do:<br />
$ mpv --profile=svp video.mkv<br />
or set {{ic|1=profile=svp}} in the top-level portion of the mpv [[#Profiles|config]].<br />
<br />
If you want to use hardware decoding then you must use a copy-back decoder since normal decoders are not compatible with Vapoursynth (choose a {{ic|hwdec}} option that ends in {{ic|-copy}}). For instance:<br />
hwdec=auto-copy<br />
hwdec-codecs=all<br />
Either way, hardware decoding is discouraged by mpv devs and is not likely to make a significant difference in performance.<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Hardware decoding ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
{{Warning|Hardware decoding is known to sometimes cause problems and as such it is considered "[https://github.com/mpv-player/mpv/commit/dbef5b737e2f994f02923c8214cba368b663a655 usually a bad idea unless absolutely needed]" by the developers. For that reason and because it typically offers very similar performance to software decoding it is disabled by default. Moreover, depending on the video card, drivers installed, and file being decoded hardware decoding may perform differently or may not even be used at all leading to inconsistent behavior that can be difficult to debug.}}<br />
<br />
{{Note|The main difference between hardware decoding and software decoding is that in software decoding the file will be decompressed and then moved onto the video card whereas with hardware decoding it will be moved to the video card first and then decompressed. In either case, video ''playback'' will still be hardware accelerated via the video card.}}<br />
<br />
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking in the {{man|1|mpv}} manual. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file. If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.<br />
<br />
The default video output driver, {{ic|opengl}}, is the preferred video output driver and all others are offered only for compatibility purposes. If one encounters problems they may choose to use either {{ic|1=vo=vdpau}} (if using {{ic|1=hwdec=vdpau}}) or {{ic|1=vo=vaapi}} (if using {{ic|1=hwdec=vaapi}}) instead. This can affect the framedrop code used and cause other small differences.<br />
<br />
Even with hardware decoding enabled, it will only be used for [https://mpv.io/manual/stable/#options-hwdec-codecs some codecs] by default. In order to use hardware decoding with all codecs set {{ic|1=hwdec-codecs=all}}. It is also possible to specify an exact list of codecs for which you want hardware decoding to be used (provided it has been enabled) by setting {{ic|1=--hwdec-codecs=h264,mpeg2video}}.<br />
<br />
==== In GNOME Wayland ====<br />
<br />
Because GNOME in Wayland mode also runs an Xorg server, video acceleration will fail with {{ic|1=[vaapi] libva: va_getDriverName() failed with unknown libva error,driver_name=(null)}}.<br />
<br />
To make ''mpv'' use the Wayland compositor, add the mpv option {{ic|1=opengl-backend=wayland}}[https://github.com/01org/intel-vaapi-driver/issues/203#issuecomment-311299852]. Note however that this will prevent the display of window decorations (titlebar and border).<br />
<br />
=== Save position on quit ===<br />
<br />
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting <br />
{{ic|quit_watch_later}} in the key bindings configuration file.<br />
<br />
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.<br />
<br />
=== Volume is too low ===<br />
<br />
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=150}}, which then allows you to increase your volume up to 150%, which is more than twice as loud. Increasing your volume too high will result in clipping artefacts. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.<br />
<br />
=== Play a DVD ===<br />
To start the main stream of a video DVD, use the command:<br />
$ mpv dvd://<br />
<br />
=== Quickly cycle between aspect ratios ===<br />
<br />
You can cycle between aspect ratios using {{ic|Shift+a}}.<br />
<br />
=== Ignoring aspect ratio ===<br />
<br />
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.<br />
<br />
=== Draw to the root window ===<br />
<br />
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.<br />
<br />
=== Always show GUI ===<br />
<br />
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.<br />
<br />
=== Hide GUI for video files ===<br />
<br />
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.<br />
<br />
=== Restoring old OSC ===<br />
<br />
Since version 0.21.0, mpv has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the mpv configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].<br />
<br />
=== Use as a browser plugin ===<br />
<br />
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.<br />
<br />
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.<br />
<br />
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.<br />
<br />
=== Improving mpv as a music player with Lua scripts ===<br />
<br />
The development of mpv's Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]<br />
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]<br />
of the [https://github.com/mpv-player/mpv mpv repository].<br />
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the<br />
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,<br />
which shows how Lua scripts can be used to improve mpv as a music player.<br />
<br />
=== Twitch.tv streaming over mpv ===<br />
<br />
If {{Pkg|youtube-dl}} is installed, mpv can directly open a Twitch livestream.<br />
<br />
Alternatively, see [[Streamlink#Twitch]].<br />
<br />
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc<br />
<br />
=== youtube-dl and choosing formats ===<br />
<br />
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.<br />
<br />
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.<br />
<br />
ytdl-format=bestvideo[height<=?1080]+bestaudio/best<br />
<br />
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:<br />
<br />
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best<br />
<br />
If you prefer best quality open codecs (VP9 and Opus), use:<br />
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"<br />
<br />
=== youtube-dl audio with search ===<br />
<br />
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:<br />
<br />
function mm() {<br />
mpv --ytdl-format=bestaudio ytdl://ytsearch:"$@"<br />
}<br />
<br />
=== Use mpv with a compositor ===<br />
<br />
If you are using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when mpv is playing a video, try {{ic|1=x11-bypass-compositor=no}}<br />
<br />
=== Creating a single screenshot ===<br />
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):<br />
<br />
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png<br />
<br />
Screenshots will be saved in /path/to/screenshot.png.<br />
<br />
=== GNOME Blank screen (Wayland) ===<br />
<br />
MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== General debugging ===<br />
<br />
If you are having trouble with ''mpv'''s playback (or if it's flat out failing to run) then the first three things you should do are:<br />
# Run ''mpv'' from the command line. If you are lucky there will be an error message there telling you what is wrong.<br>{{ic|$ mpv video.mkv}}<br />
# Have ''mpv'' output a log file. The log file might be difficult to sift through but if something is broken you might see it there.<br>{{ic|1=$ mpv --log-file=./log video.mkv}}<br />
# Run ''mpv'' without a configuration. If this runs well then the problem is somewhere in your configuration (perhaps your hardware cannot keep up with your settings).<br>{{ic|$ mpv --no-config video.mkv}}<br />
<br />
If ''mpv'' runs but it just does not run well then a fourth thing that might be worth taking a look at is installing the [[#mpv-stats|mpv-stats]] script and using it to see exactly how it's performing.<br />
<br />
=== Fix jerky playback and tearing ===<br />
<br />
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:<br />
<br />
{{hc|1=~/.config/mpv/mpv.conf|2=vo=xv}}<br />
<br />
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.<br />
<br />
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.<br />
<br />
The following [[#Configuration|options]] may be considered to increase the video playback performance:<br />
<br />
{{hc|~/.config/mpv/mpv.conf|2=<br />
vd-lavc-fast<br />
vd-lavc-skiploopfilter=<skipvalue><br />
vd-lavc-skipframe=<skipvalue><br />
vd-lavc-framedrop=<skipvalue><br />
vd-lavc-threads=<threads><br />
}}<br />
<br />
=== Problems with window compositors ===<br />
<br />
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).<br />
<br />
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.<br />
<br />
=== No volume bar, cannot change volume ===<br />
<br />
Spin the mouse wheel over the volume icon.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=VDPAU_(%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9)&diff=512946VDPAU (Русский)2018-03-07T13:32:50Z<p>Ketsui: /* Поддерживаемые форматы */ Update link</p>
<hr />
<div>[[Category:Graphics (Русский)]]<br />
[[Category:X server (Русский)]]<br />
[[Category:Русский]]<br />
[[en:Hardware video acceleration]]<br />
[[zh-hans:Hardware video acceleration]]<br />
{{Related articles start (Русский)}}<br />
{{Related|VA-API (Русский)}}<br />
{{Related|XvMC}}<br />
{{Related articles end}}<br />
{{TranslationStatus (Русский)|VDPAU|12 декабря 2015|411185}}<br />
{{Unmaintained (Русский)}}<br />
<br />
'''[http://http.download.nvidia.com/XFree86/vdpau/doxygen/html/ Video Decode and Presentation API for Unix]''' — открытая библиотека и API для выполнения задач декодирования и постобработки видео на аппаратных ускорителях.<br />
<br />
== Поддерживаемые видеокарты ==<br />
<br />
'''Свободные драйверы:'''<br />
<br />
* [[ATI|AMD]] Radeon 9500 и новее поддерживаются пакетом {{Pkg|mesa-vdpau}}.<br />
* [[Intel graphics|Intel]] GMA 4500 серии и новее поддерживаются пакетом {{Pkg|libvdpau-va-gl}} вместе с {{pkg|libva-intel-driver}}.<br />
* [[Nouveau|NVIDIA]] GeForce 8 серии и новее поддерживаются пакетом {{Pkg|mesa-vdpau}}. Он [http://nouveau.freedesktop.org/wiki/VideoAcceleration/#firmware требует] пакет {{AUR|nouveau-fw}}, который содержит в себе необходимые прошивки для работы, взятые из закрытого драйвера NVIDIA.<br />
<br />
'''Проприетарные драйверы:'''<br />
<br />
* [[AMD Catalyst|AMD]] Radeon HD 4000 серии и новее поддерживаются пакетом {{Pkg|libvdpau-va-gl}}, вместе с пакетом {{AUR|libva-xvba-driver}}{{Broken package link (Русский)|{{aur-mirror (Русский)|libva-xvba-driver}}}}. Он использует драйвер {{AUR|catalyst-utils}} для Radeon HD 5000 серии и новее, и {{AUR|catalyst-total-hd234k}} для Radeon HD 4000 серии.<br />
<br />
* [[NVIDIA]] GeForce 400 серии и новее поддерживаются пакетом {{Pkg|nvidia-utils}}.<br />
** GeForce 8/9 и GeForce 100-300 серии и новее поддерживаются пакетом {{Pkg|nvidia-340xx-utils}}.<br />
<br />
=== Поддерживаемые форматы ===<br />
<br />
{| class="wikitable" style="width: 100%"<br />
!<br />
! colspan="3" | Открытые<br />
! colspan="2" | Проприетарные<br />
|-<br />
!<br />
! AMD<br />
! Intel<br />
! Nvidia<br />
! AMD<br />
! Nvidia<br />
|-<br />
| Декодирование MPEG2<br />
| Radeon 9500 и новее<br />
| <center>— <sup>2</sup></center><br />
| GeForce 8 и новее<br />
| <center>— <sup>2</sup></center><br />
| GeForce 8 и новее<br />
|-<br />
| Декодирование MPEG4<br />
| Radeon HD 6000 и новее<br />
| <center>—</center><br />
| GeForce 200 и новее<br />
| <center>— <sup>2</sup></center><br />
| GeForce 200 и новее<br />
|-<br />
| Декодирование H.264<br />
| Radeon HD 4000 и новее<br />
| GMA 4500<sup>1</sup>, Ironlake Graphics и новее<br />
| GeForce 8 и новее<br />
| Radeon HD 4000 и новее<br />
| GeForce 8 и новее<br />
|-<br />
| H.265 decoding<br />
| <center>—</center><br />
| <center>—</center><br />
| <center>—</center><br />
| <center>—</center><br />
| [http://www.phoronix.com/scan.php?page=news_item&px=VDPAU-H.265-HEVC-Decode upcoming:] GeForce 900<sup>4</sup> и новее<br />
|-<br />
| Декодирование VC1<br />
| Radeon HD 4000 и новее<br />
| <center>— <sup>2</sup></center><br />
| GeForce 8<sup>3</sup> и новее<br />
| <center>— <sup>2</sup></center><br />
| GeForce 8<sup>3</sup> и новее<br />
|}<br />
<br />
* <sup>1</sup> Поддерживается пакетом {{AUR|libva-intel-driver-g45-h264}}. Инструкция и важная информация доступна на странице [[Intel graphics#Hardware accelerated H.264 decoding on GMA 4500]].<br />
* <sup>2</sup> Драйвер VA GL не поддерживает другие аппаратные декодеры помимо H.264 (на состояние 21 июня 2014 года, ветка master, версия 0.3.x).<br />
* <sup>3</sup> [[Wikipedia:Nvidia PureVideo|За исключением]] GeForce 8800 Ultra, 8800 GTX, 8800 GTS (320/640 MB).<br />
* <sup>4</sup> Except GeForce GTX 970 and GTX 980.<br />
<br />
Чтобы проверить, какие возможности поддерживаются вашей видеокартой, воспользуйтесь следующей командой, предоставляемой пакетом {{Pkg|vdpauinfo}}:<br />
<br />
$ vdpauinfo<br />
<br />
=== Настройка ===<br />
<br />
{{Note|Можно не экспортировать переменную {{ic|VDPAU_DRIVER}}, так как большинство (современных) приложений и сред умеют находить библиотеку VDPAU [[#Проверка|автоматически]]{{Broken section link}}}}<br />
<br />
В переменной окружения {{ic|VDPAU_DRIVER}} должен быть указан файл драйвера. Вы можете установить [[Environment variables (Русский)|переменную окружения]] [[Environment variables (Русский)#На системном уровне|глобально]] или [[Environment variables (Русский)#На уровне пользователя|для отдельного пользователя]].<br />
<br />
Корректное название драйвера зависит от вашей конфигурации:<br />
<br />
* Для Intel Graphics или AMD Catalyst: {{ic|va_gl}}.<br />
* Для свободного драйвера AMD/ATI, необходимо выставить название, включающее в себя корректную версию драйвера, которая зависит от вашей видеокарты.<br />
* Для проприетарного драйвера Nvidia: {{ic|nvidia}}<br />
Чтобы определить правильное название драйвера, воспользуйтесь командой<br />
<br />
{{hc|$ grep -i vdpau /var/log/Xorg.0.log|<br />
(II) RADEON(0): [DRI2] VDPAU driver: r300<br />
}}<br />
<br />
В данном примере необходимо установить значение {{ic|1=VDPAU_DRIVER=r300}}.<br />
<br />
==== Гибридная графика ====<br />
<br />
Для конфигураций с гибридной графикой (NVIDIA и AMD), возможно понадобится установить следующую переменную окружения:<br />
<br />
$ export DRI_PRIME=1<br />
<br />
Больше информации доступно на странице [[PRIME]].<br />
<br />
== Поддерживаемое программное обеспечение ==<br />
<br />
* {{App|Adobe Flash Player|смотрите раздел [[Плагины для браузеров#Adobe Flash Player]]||{{Pkg|flashplugin}}}}<br />
* {{App|bomi|аппаратное ускорение можно включить в: ''Preferences > Video > Hardware acceleration''|https://bomi-player.github.io|{{Aur|bomi}} {{Aur|bomi-git}}}}<br />
* {{App|gnome-mplayer|чтобы включить аппаратное ускорение зайдите в ''Edit > Preferences > Player'' и установите параметр {{ic|vdpau}} в положение ''Video Output''||{{Pkg|gnome-mplayer}}}}<br />
* {{App|[[MPlayer (Русский)|MPlayer]] или [http://www.mplayer2.org/ mplayer2]|смотрите раздел [[MPlayer (Русский)#Использование vdpau (только для новых видеокарт nVidia)]]||{{Pkg|mplayer}} {{Aur|mplayer2}}}}<br />
* {{App|[[mpv (Русский)|mpv]]|смотрите раздел [[Mpv (Русский)#Аппаратное декодирование]]||{{Pkg|mpv}}}}<br />
* {{App|[[MPlayer (Русский)#Решение проблем|SMplayer]]|чтобы включить аппаратное ускорение зайдите в ''Options > Preferences > General > Video'' и установите параметр {{ic|vdpau}} в положение ''Output driver''||{{Pkg|smplayer}}}}<br />
* {{App|[[VLC media player]]|смотрите раздел [[VLC media player#Hardware acceleration support]]||{{Pkg|vlc}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=VA-API_(%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9)&diff=512945VA-API (Русский)2018-03-07T13:04:01Z<p>Ketsui: /* Поддерживаемые форматы */ Update link</p>
<hr />
<div>[[Category:Русский]]<br />
[[Category:Graphics (Русский)]]<br />
[[Category:X server (Русский)]]<br />
[[en:Hardware video acceleration]]<br />
[[ja:ハードウェアビデオアクセラレーション]]<br />
[[zh-hans:Hardware video acceleration]]<br />
{{Related articles start (Русский)}}<br />
{{Related|VDPAU (Русский)}}<br />
{{Related|XvMC}}<br />
{{Related articles end}}<br />
{{TranslationStatus (Русский)|VA-API|12 декабря 2015|411159}}<br />
{{Unmaintained (Русский)}}<br />
<br />
'''[http://www.freedesktop.org/wiki/Software/vaapi Video Acceleration API]''' — спецификация и открытая библиотека, созданная с целью предоставить возможность аппаратного кодирования и декодирования видео.<br />
<br />
== Поддерживаемые видеокарты ==<br />
<br />
'''Свободные драйверы:'''<br />
<br />
* [[ATI|AMD]] Radeon 9500 и новее поддерживаются пакетами {{pkg|libva-vdpau-driver}} и {{pkg|mesa}}.<br />
* [[Intel graphics|Intel]] GMA 4500 серии и новее поддерживаются пакетами {{pkg|libva-intel-driver}} и {{pkg|mesa}}.<br />
* [[Nouveau|NVIDIA]] GeForce 8 серии и новее поддерживаются пакетами {{pkg|libva-vdpau-driver}} и {{pkg|mesa}},. Он использует пакет {{AUR|nouveau-fw}}, содержащий в себе необходимые прошивки для работы, взятые из закрытого драйвера NVIDIA.<br />
<br />
'''Проприетарные драйверы:'''<br />
<br />
* [[AMD Catalyst|AMD]] Radeon HD 4000 серии и новее поддерживаются пакетами {{AUR|libva-xvba-driver}}{{Broken package link (Русский)|{{aur-mirror (Русский)|libva-xvba-driver}}}},. Он использует драйвера {{AUR|catalyst-utils}} для Radeon HD 5000 серии и новее, и {{AUR|catalyst-total-hd234k}} для Radeon HD 4000 серии.<br />
* [[NVIDIA]] GeForce 8 серии и новее поддерживаются пакетами {{pkg|libva-vdpau-driver}} и {{pkg|nvidia-utils}}.<br />
<br />
=== Поддерживаемые форматы ===<br />
<br />
{| class="wikitable" style="width: 100%"<br />
!<br />
! colspan="3" | Open source<br />
! colspan="2" | Proprietary<br />
|-<br />
!<br />
! AMD<br />
! Intel<br />
! Nvidia<br />
! AMD<br />
! Nvidia<br />
|-<br />
| Декодирование MPEG2<br />
| AMD Radeon 9500 и новее<br />
| Intel GMA 4500 и новее<br />
| Nvidia GeForce 8 и новее<br />
| AMD Radeon HD 4000 и новее<br />
| Nvidia GeForce 8 и новее<br />
|-<br />
| MPEG4 decoding<br />
| AMD Radeon HD 6000 и новее<br />
| <center>—</center><br />
| Nvidia GeForce 200 и новее<br />
| AMD Radeon HD 6000 и новее<br />
| Nvidia GeForce 200 и новее<br />
|-<br />
| Декодирование H264<br />
| AMD Radeon HD 4000 и новее<br />
| Intel GMA 4500<sup>1</sup>, Ironlake Graphics и новее<br />
| Nvidia GeForce 8 и новее<br />
| AMD Radeon HD 4000 и новее<br />
| Nvidia GeForce 8 и новее<br />
|-<br />
| Декодирование VC1<br />
| AMD Radeon HD 4000 и новее<br />
| Intel Sandy Bridge Graphics и новее<br />
| Nvidia GeForce 8200, 8300, 8400, 9300, 200 и новее<br />
| AMD Radeon HD 4000 и новее<br />
| Nvidia GeForce 8 и новее<br />
|-<br />
| Кодирование в MPEG2<br />
| <center>—</center><br />
| Intel Ivy Bridge Graphics и новее<br />
| <center>—</center><br />
| <center>—</center><br />
| <center>—</center><br />
|-<br />
| Кодирование в H264<br />
| <center>—</center><br />
| Intel Sandy Bridge Graphics и новее<br />
| <center>—</center><br />
| <center>—</center><br />
| <center>—</center><br />
|}<br />
<br />
<sup>1</sup>Поддерживается пакетом {{AUR|libva-intel-driver-g45-h264}}. Инструкция и важная информация доступна на странице [[Intel graphics#Hardware accelerated H.264 decoding on GMA 4500]].<br />
<br />
Чтобы проверить, какие профили (возможности) поддерживаются вашей видеокартой, обратитесь к секции [[#Проверка]]<br />
<br />
=== Настройка ===<br />
{{Note|Можно не экспортировать {{ic|LIBVA_DRIVER}}, так как большинство (современные) приложений и сред умеют находить VAAPI библиотеку [[#Проверка|автоматически]].}}<br />
<br />
{{Pkg|libva-vdpau-driver}} необходимо включить вручную, используя [[Environment variables (Русский)|переменную окружения]] [[Environment variables (Русский)#На системном уровне|глобально]] или [[Environment variables (Русский)#На уровне пользователя|для отдельного пользователя]]:<br />
<br />
export LIBVA_DRIVER_NAME=vdpau<br />
<br />
=== Проверка ===<br />
Проверрьте настройки VAAPI выполнив {{ic|vainfo}}, которое предоставляет пакет {{Pkg|libva}}:<br />
{{hc|$ vainfo|<nowiki><br />
libva info: VA-API version 0.38.0<br />
libva info: va_getDriverName() returns 0<br />
libva info: User requested driver 'vdpau'<br />
libva info: Trying to open /usr/lib/dri/vdpau_drv_video.so<br />
libva info: Found init function __vaDriverInit_0_35<br />
libva info: va_openDriver() returns 0<br />
vainfo: VA-API version: 0.38 (libva 1.6.1)<br />
vainfo: Driver version: Splitted-Desktop Systems VDPAU backend for VA-API - 0.7.4<br />
vainfo: Supported profile and entrypoints<br />
VAProfileMPEG2Simple : VAEntrypointVLD<br />
VAProfileMPEG2Main : VAEntrypointVLD<br />
VAProfileMPEG4Simple : VAEntrypointVLD<br />
VAProfileMPEG4AdvancedSimple : VAEntrypointVLD<br />
VAProfileH264Baseline : VAEntrypointVLD<br />
VAProfileH264Main : VAEntrypointVLD<br />
VAProfileH264High : VAEntrypointVLD<br />
VAProfileVC1Simple : VAEntrypointVLD<br />
VAProfileVC1Main : VAEntrypointVLD<br />
VAProfileVC1Advanced : VAEntrypointVLD</nowiki>}}<br />
Строка ''VAEntrypointVLD'' означает, что ваша видеокарта поддерживает декодирование данного формата, а ''VAEntrypointEncSlice'' — что доступно кодирование в этот формат.<br />
<br />
== Поддерживаемое программное обеспечение ==<br />
<br />
* Плееры, основанные на [[GStreamer]]: VA-API используется автоматически, если найден поддерживаемый формат.<br />
: Больше информации доступно по ссылке: http://docs.gstreamer.com/display/GstSDK/Playback+tutorial+8%3A+Hardware-accelerated+video+decoding.<br />
* VLC: [[VLC media player#Hardware acceleration support]].<br />
* Mpv: [[Mpv (Русский)#Аппаратное декодирование]].<br />
* MPlayer: [[MPlayer#Enabling VA-API]].</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Hardware_video_acceleration&diff=512944Hardware video acceleration2018-03-07T12:45:57Z<p>Ketsui: /* Installing VA-API */ Update link</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[ja:ハードウェアビデオアクセラレーション]]<br />
[[ru:VA-API]]<br />
[[zh-hans:Hardware video acceleration]]<br />
{{Related articles start}}<br />
{{Related|XvMC}}<br />
{{Related articles end}}<br />
Hardware video acceleration makes it possible for the video card to decode/encode video, thus offloading the CPU and saving power.<br />
<br />
There are several ways to achieve this on Linux:<br />
<br />
* '''[http://www.freedesktop.org/wiki/Software/vaapi Video Acceleration API]''' (VA-API) is a specification and open source library to provide both hardware accelerated video encoding and decoding, developed by Intel.<br />
* '''[http://http.download.nvidia.com/XFree86/vdpau/doxygen/html/ Video Decode and Presentation API for Unix]''' (VDPAU) is an open source library and API to offload portions of the video decoding process and video post-processing to the GPU video-hardware, developed by NVIDIA.<br />
* X-Video Motion Compensation ([[XvMC]]) is an extension for the X.Org Server, allowing video programs to offload portions of the video decoding process to the GPU video-hardware.<br />
<br />
== Support ==<br />
<br />
=== Formats ===<br />
<br />
{{Expansion|Fill in capabilities of {{pkg|libva-mesa-driver}} and {{aur|amdgpu-pro-vdpau}}.}}<br />
<br />
{{Note|To choose the correct driver see [[#Installation]].}}<br />
<br />
{| class="wikitable" style="width: 100%; text-align:center;"<br />
|+ VA-API<br />
!<br />
! {{pkg|libva-intel-driver}} [https://github.com/01org/intel-vaapi-driver/blob/master/README]<br />
! {{pkg|libva-mesa-driver}}<br />
! [[AMD Catalyst#Video acceleration|Catalyst XvBA]]<br />
! {{pkg|libva-vdpau-driver}}<br />
(VDPAU adapter)<br />
|-<br />
! colspan=5 | Decoding<br />
|-<br />
! MPEG2<br />
| {{G|GMA 4500 and newer}}<br />
| {{G|Radeon HD 4000 and newer?}}<br />
| {{G|Radeon HD 4000 and newer}}<br />
| rowspan=5 style="background:#d3d3d3;" | See VDPAU.<br />
|-<br />
! MPEG4<br />
| {{R|✗}}<br />
| ?<br />
| {{G|Radeon HD 6000 and newer}}<br />
|-<br />
! H.264<br />
| {{G|GMA 4500<sup>1</sup>, Ironlake Graphics and newer}}<br />
| {{G|Radeon HD 4000 and newer?}}<br />
| {{G|Radeon HD 4000 and newer}}<br />
|-<br />
! HEVC (H.265)<br />
| {{G|Cherryview/Braswell and newer}}<br />
| {{G|Radeon HD 6000 and newer?}}<br />
| {{R|✗}}<br />
|-<br />
! VC1<br />
| {{G|Sandy Bridge Graphics and newer}}<br />
| {{G|Radeon HD 4000 and newer?}}<br />
| {{G|Radeon HD 4000 and newer}}<br />
|-<br />
! VP8<br />
| {{G|Broadwell and newer}}<br />
| ?<br />
| {{R|✗}}<br />
| rowspan=2 style="background:#faa;" | ✗<br />
|-<br />
! VP9<br />
| {{G|Broxton and newer}}<br />
| ?<br />
| {{R|✗}}<br />
|-<br />
! colspan=5 | Encoding<br />
|-<br />
! MPEG2<br />
| {{G|Ivy Bridge Graphics and newer}}<br />
| ?<br />
| rowspan=5 style="background:#faa;" | ✗<br />
| rowspan=5 style="background:#faa;" | ✗<br />
|-<br />
! H.264<br />
| {{G|Sandy Bridge Graphics and newer}}<br />
| {{G|Radeon HD 4000 and newer?}}<br />
|-<br />
! HEVC (H.265)<br />
| {{G|Skylake and newer}}<br />
| ?<br />
|-<br />
! VP8<br />
| {{G|Cherryview/Braswell and newer}}<br />
| ?<br />
|-<br />
! VP9<br />
| {{G|Kaby Lake and newer}}<br />
| ?<br />
|-<br />
|}<br />
<br />
{| class="wikitable" style="width: 100%; text-align:center;"<br />
|+ VDPAU<br />
! <br />
! {{pkg|mesa-vdpau}}<br />
! {{pkg|nvidia-utils}}<br />
! {{aur|amdgpu-pro-vdpau}}<br />
! {{pkg|libvdpau-va-gl}}<br />(VA-API adapter)<br />
|-<br />
|-<br />
! colspan=5 | Decoding<br />
|-<br />
! MPEG2<br />
| {{G|Radeon 9500 and newer, GeForce 8 and newer}}<br />
| {{G|GeForce 8 and newer}}<br />
| rowspan=5 | ?<br />
| rowspan=2 style="background:#faa;" | ✗<sup>2</sup><br />
|-<br />
! MPEG4<br />
| {{G|Radeon HD 6000 and newer, GeForce 200 and newer}}<br />
| {{G|GeForce 200 and newer}}<br />
|-<br />
! H.264<br />
| {{G|Radeon HD 4000 and newer, GeForce 8 and newer}}<br />
| {{G|GeForce 8 and newer}}<br />
| {{Grey|See VA-API.}}<br />
|-<br />
! HEVC (H.265)<br />
| {{G|1=[https://cgit.freedesktop.org/mesa/mesa/commit/src/gallium/state_trackers/vdpau/decode.c?id=5609a6986f3eb3c452d66d373b6081df5c6fb34c yes] (which cards?)}}<br />
| {{G|GeForce 900<sup>4</sup> and newer}}<br />
| rowspan=4 style="background:#faa;" | ✗<sup>2</sup><br />
|-<br />
! VC1<br />
| {{G|Radeon HD 4000 and newer, GeForce 8<sup>3</sup> and newer}}<br />
| {{G|GeForce 8<sup>3</sup> and newer}}<br />
|-<br />
|}<br />
<br />
* <sup>1</sup> Supported by {{aur|libva-intel-driver-g45-h264}} instead.<br />
* <sup>2</sup> As of version 0.3, the VA GL driver does not support any other hardware decoder than H.264.<br />
* <sup>3</sup> [[Wikipedia:Nvidia PureVideo|Except]] GeForce 8800 Ultra, 8800 GTX, 8800 GTS (320/640 MB).<br />
* <sup>4</sup> Except GeForce GTX 970 and GTX 980.<br />
<br />
{| class="wikitable" style="text-align:center;"<br />
|+ Nvidia NVDEC/NVENC ([[NVIDIA]] only)<br />
!<br />
! Decoding (NVDEC)<br />
! Encoding (NVENC)<br />
|-<br />
! MPEG-2<br />
| {{G|✓}}<br />
| {{R|✗}}<br />
|-<br />
! VC-1<br />
| {{G|✓}}<br />
| {{R|✗}}<br />
|-<br />
! H.264<br />
| {{G|✓}}<br />
| {{G|✓}}<br />
|-<br />
! HEVC (H.265)<br />
| {{G|Pascal and newer}}<br />
| {{G|Pascal and newer}}<br />
|-<br />
! VP8<br />
| {{G|Maxwell2 and newer}}<br />
| {{R|✗}}<br />
|-<br />
! VP9<br />
| {{G|Pascal and newer}}<br />
| {{R|✗}}<br />
|-<br />
|}<br />
<br />
The features supported by your GPU may vary. To see what your GPU supports see [[#Verification]].<br />
<br />
Regarding the {{aur|amdgpu-pro-vdpau}} package, see [[AMDGPU#AMDGPU PRO]].<br />
<br />
=== Software ===<br />
<br />
{| class="wikitable" style="width: 100%;"<br />
! <br />
! VA-API<br />
! VDPAU<br />
! NVDEC/NVENC<br />
|-<br />
! [[GStreamer]]<br />
| {{G|✓ (with {{pkg|gstreamer-vaapi}}, see [[GStreamer#Hardware acceleration]])}}<br />
| {{G|✓ (with {{pkg|gst-plugins-bad}}, see [[GStreamer#Hardware acceleration]])}}<br />
| {{G|✓ (with {{pkg|gst-plugins-bad}}, see [[GStreamer#Hardware acceleration]])}}<br />
|-<br />
! [[VLC media player]]<br />
| {{G|✓ (see [[VLC media player#Hardware acceleration support]])}}<br />
| {{G|✓ (see [[VLC media player#Hardware acceleration support]])}}<br />
| {{R|✗}}<br />
|-<br />
! [[mpv]]<br />
| {{G|✓ (see [[mpv#Hardware decoding]])}}<br />
| {{G|✓ (see [[mpv#Hardware decoding]])}}<br />
| {{G|1=[https://www.phoronix.com/scan.php?page=news_item&px=MPV-Player-0.21 ✓]}}<br />
|-<br />
! [[MPlayer]]<br />
| {{G|✓ (with {{aur|mplayer-vaapi}}, see [[MPlayer#Enabling VA-API]])}}<br />
| {{G|✓ (see [[MPlayer#Enabling VDPAU]])}}<br />
| {{R|✗}}<br />
|-<br />
! [[Flash]]<br />
| {{G|✓ (with {{pkg|libvdpau-va-gl}}, see [[Flash#Configuration]])}}<br />
| {{G|✓ (see [[Flash#Configuration]])}}<br />
| {{R|✗}}<br />
|-<br />
! [[Kodi]]<br />
| {{G|✓}}<br />
| {{G|✓}}<br />
| {{G|✓}}<br />
|-<br />
! [[Firefox]]<br />
| colspan=2 style="background:#faa; text-align: center;" | ✗ [https://bugzilla.mozilla.org/show_bug.cgi?id=1210726] [https://bugzilla.mozilla.org/show_bug.cgi?id=1210727] [https://bugzilla.mozilla.org/show_bug.cgi?id=563206]<br />
| {{R|✗}}<br />
|-<br />
! [[Chromium]]<br />
| {{Y|[https://chromium-review.googlesource.com/c/chromium/src/+/532294 WIP] ({{AUR|chromium-vaapi}})}}<br />
| {{R|✗}}<br />
| {{R|✗}}<br />
|-<br />
! [[FFmpeg]]<br />
| {{G|✓}}<br />
| {{G|✓}}<br />
| {{G|1=✓ [https://www.phoronix.com/scan.php?page=news_item&px=FFmpeg-NVDEC-H264-Acceleration (from 3.5)]}}<br />
|}<br />
<br />
== Installation ==<br />
<br />
{{Expansion|The [[AMDGPU]] driver is not mentioned.}}<br />
<br />
The choice varies depending on your video card vendor:<br />
<br />
* For Intel Graphics use VA-API.<br />
* For NVIDIA cards use VDPAU.<br />
* For AMD cards you can use both (with {{Pkg|mesa}}). The difference is really only in the application implementation [https://www.phoronix.com/forums/forum/linux-graphics-x-org-drivers/open-source-amd-linux/887994-vaapi-or-vdpau].<br />
<br />
There are also two specific types of drivers for VA-API and VDPAU:<br />
<br />
* {{pkg|libva-vdpau-driver}}, which uses VDPAU as a backend for VA-API.<br />
* {{pkg|libvdpau-va-gl}}, which uses VA-API as a backend for VDPAU.<br />
<br />
For pre-2007 cards see [[XvMC]].<br />
<br />
{{Tip|It is recommended to install and configure both VA-API and VDPAU to achieve support in different scenarios, e.g. [[Flash]] does not support VA-API but can use the VDPAU VA-API backend.}}<br />
<br />
=== Installing VA-API ===<br />
<br />
'''Open source drivers:'''<br />
<br />
* [[ATI]]/[[AMDGPU]] Radeon 9500 and newer GPUs are supported by either {{pkg|libva-mesa-driver}} with {{pkg|mesa}} or {{pkg|libva-vdpau-driver}} (see [[#Installing VDPAU]]).<br />
* [[Intel]] GMA 4500 series and newer GPUs are supported by {{pkg|libva-intel-driver}} with {{pkg|mesa}}.<br />
** To get better support on GMA 4500 consider using {{aur|libva-intel-driver-g45-h264}} instead, see [[Intel#Hardware accelerated H.264 decoding on GMA 4500]] for instructions and caveats.<br />
* [[Nouveau|NVIDIA]] GeForce 8 series and newer GPUs are supported by {{pkg|libva-vdpau-driver}} (see [[#Installing VDPAU]]).<br />
<br />
'''Proprietary drivers:'''<br />
<br />
* AMD cards depend on the driver:<br />
** [[AMD Catalyst]] uses [[AMD Catalyst#Video acceleration|xvba]].<br />
** [[AMDGPU PRO]] uses {{pkg|libva-vdpau-driver}} + {{AUR|amdgpu-pro-vdpau}} (see [[AMDGPU#AMDGPU PRO]]).<br />
* [[NVIDIA]] GeForce 8 series and newer GPUs are supported by {{pkg|libva-vdpau-driver}} (see [[#Installing VDPAU]]).<br />
<br />
=== Installing VDPAU ===<br />
<br />
'''Open source drivers:'''<br />
<br />
* [[ATI]]/[[AMDGPU]] Radeon 9500 and newer GPUs are supported by {{pkg|mesa-vdpau}}.<br />
* [[Intel]] GMA 4500 series and newer GPUs are supported by {{pkg|libvdpau-va-gl}} (see [[#Installing VA-API]]).<br />
* [[Nouveau|NVIDIA]] GeForce 8 series and newer GPUs are supported by {{pkg|mesa-vdpau}}. It [http://nouveau.freedesktop.org/wiki/VideoAcceleration/#firmware requires] {{AUR|nouveau-fw}}, which contains the required firmware to operate that is presently extracted from the NVIDIA binary driver.<br />
<br />
'''Proprietary drivers:'''<br />
<br />
* AMD cards depend on the driver:<br />
** [[AMD Catalyst]] uses {{pkg|libvdpau-va-gl}} (see [[#Installing VA-API]]).<br />
** [[AMDGPU PRO]] uses {{AUR|amdgpu-pro-vdpau}} (see [[AMDGPU#AMDGPU PRO]]).<br />
* [[NVIDIA]] GeForce 400 series and newer GPUs are supported by {{pkg|nvidia-utils}}.<br />
** GeForce 8/9 and GeForce 100-300 series are supported by {{pkg|nvidia-340xx-utils}}.<br />
<br />
== Verification ==<br />
<br />
Your system may work perfectly out-of-the-box without needing any configuration. Therefore it is a good idea to start with this section to see that it is the case.<br />
<br />
{{Tip|[[mpv#Hardware decoding|mpv]] is great for testing hardware acceleration in practice.}}<br />
<br />
=== Verifying VA-API ===<br />
<br />
Verify the settings for VA-API by running {{ic|vainfo}}, which is provided by {{Pkg|libva-utils}}:<br />
<br />
{{hc|$ vainfo|<nowiki><br />
libva info: VA-API version 0.39.4<br />
libva info: va_getDriverName() returns 0<br />
libva info: Trying to open /usr/lib/dri/i965_drv_video.so<br />
libva info: Found init function __vaDriverInit_0_39<br />
libva info: va_openDriver() returns 0<br />
vainfo: VA-API version: 0.39 (libva 1.7.3)<br />
vainfo: Driver version: Intel i965 driver for Intel(R) Skylake - 1.7.3<br />
vainfo: Supported profile and entrypoints<br />
VAProfileMPEG2Simple : VAEntrypointVLD<br />
VAProfileMPEG2Simple : VAEntrypointEncSlice<br />
VAProfileMPEG2Main : VAEntrypointVLD<br />
VAProfileMPEG2Main : VAEntrypointEncSlice<br />
VAProfileH264ConstrainedBaseline: VAEntrypointVLD<br />
VAProfileH264ConstrainedBaseline: VAEntrypointEncSlice<br />
VAProfileH264ConstrainedBaseline: VAEntrypointEncSliceLP<br />
VAProfileH264Main : VAEntrypointVLD<br />
VAProfileH264Main : VAEntrypointEncSlice<br />
VAProfileH264Main : VAEntrypointEncSliceLP<br />
VAProfileH264High : VAEntrypointVLD<br />
VAProfileH264High : VAEntrypointEncSlice<br />
VAProfileH264High : VAEntrypointEncSliceLP<br />
VAProfileH264MultiviewHigh : VAEntrypointVLD<br />
VAProfileH264MultiviewHigh : VAEntrypointEncSlice<br />
VAProfileH264StereoHigh : VAEntrypointVLD<br />
VAProfileH264StereoHigh : VAEntrypointEncSlice<br />
VAProfileVC1Simple : VAEntrypointVLD<br />
VAProfileVC1Main : VAEntrypointVLD<br />
VAProfileVC1Advanced : VAEntrypointVLD<br />
VAProfileNone : VAEntrypointVideoProc<br />
VAProfileJPEGBaseline : VAEntrypointVLD<br />
VAProfileJPEGBaseline : VAEntrypointEncPicture<br />
VAProfileVP8Version0_3 : VAEntrypointVLD<br />
VAProfileVP8Version0_3 : VAEntrypointEncSlice<br />
VAProfileHEVCMain : VAEntrypointVLD<br />
VAProfileHEVCMain : VAEntrypointEncSlice<br />
</nowiki>}}<br />
<br />
{{ic|VAEntrypointVLD}} means that your card is capable to decode this format, {{ic|VAEntrypointEncSlice}} means that you can encode to this format.<br />
<br />
In this example the {{ic|i965}} driver is used, as you can see in this line:<br />
<br />
libva info: Trying to open /usr/lib/dri/'''i965'''_drv_video.so<br />
<br />
If the following error is displayed when running {{ic|vainfo}}:<br />
<br />
libva info: va_openDriver() returns -1<br />
vaInitialize failed with error code -1 (unknown libva error),exit<br />
<br />
You need to configure the correct driver, see [[#Configuring VA-API]].<br />
<br />
=== Verifying VDPAU ===<br />
<br />
Install {{pkg|vdpauinfo}} to verify if the VDPAU driver is loaded correctly and retrieve a full report of the configuration:<br />
<br />
{{hc|$ vdpauinfo|<br />
display: :0 screen: 0<br />
API version: 1<br />
Information string: G3DVL VDPAU Driver Shared Library version 1.0<br />
<br />
Video surface:<br />
<br />
name width height types<br />
-------------------------------------------<br />
420 16384 16384 NV12 YV12 <br />
422 16384 16384 UYVY YUYV <br />
444 16384 16384 Y8U8V8A8 V8U8Y8A8 <br />
<br />
Decoder capabilities:<br />
<br />
name level macbs width height<br />
----------------------------------------------------<br />
MPEG1 --- not supported ---<br />
MPEG2_SIMPLE 3 9216 2048 1152<br />
MPEG2_MAIN 3 9216 2048 1152<br />
H264_BASELINE 41 9216 2048 1152<br />
H264_MAIN 41 9216 2048 1152<br />
H264_HIGH 41 9216 2048 1152<br />
VC1_SIMPLE 1 9216 2048 1152<br />
VC1_MAIN 2 9216 2048 1152<br />
VC1_ADVANCED 4 9216 2048 1152<br />
<br />
..<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Although the video driver should automatically enable hardware video acceleration support for both VA-API and VDPAU, it may be needed to configure VA-API/VDPAU manually. Only continue to this section if you went through [[#Verification]].<br />
<br />
The default driver names, used if there is no other configuration present, are guess by the system. However, they are often hacked together and may not work. You can see the guessed values by running:<br />
<br />
{{hc|$ grep -iE 'vdpau {{!}} dri driver' ~/.local/share/xorg/Xorg.0.log|<br />
(II) RADEON(0): [DRI2] DRI driver: radeonsi<br />
(II) RADEON(0): [DRI2] VDPAU driver: radeonsi<br />
}}<br />
<br />
In this case {{ic|radeonsi}} is the default for both VA-API and VDPAU.<br />
<br />
{{Note|If you use [[GDM]], run {{ic|journalctl -b {{!}} grep -iE 'vdpau {{!}} dri driver'}} instead.}}<br />
<br />
This does not represent the ''configuration'' however. The values above will not change even if you override them.<br />
<br />
=== Configuring VA-API ===<br />
<br />
You can override the [http://www.freedesktop.org/wiki/Software/vaapi/#driversback-endsthatimplementva-api driver] for VA-API by using the {{ic|LIBVA_DRIVER_NAME}} [[environment variable]]:<br />
<br />
* For Intel Graphics use {{ic|i965}}.<br />
* For NVIDIA use {{ic|vdpau}}.<br />
* For AMD use either {{ic|radeonsi}} or {{ic|vdpau}}.<br />
<br />
{{Note|<br />
* You can find the installed drivers in {{ic|/usr/lib/dri/}}. They are used as {{ic|/usr/lib/dri/'''${LIBVA_DRIVER_NAME}'''_drv_video.so}}.<br />
* Some drivers are installed several times under different names for compatibility reasons. You can see which by running {{ic|sha1sum /usr/lib/dri/*}}.<br />
* Since version 12.0.1 {{Pkg|libva-mesa-driver}} provides {{ic|radeonsi}} instead of {{ic|gallium}}.<br />
}}<br />
<br />
=== Configuring VDPAU ===<br />
<br />
You can override the driver for VDPAU by using the {{ic|VDPAU_DRIVER}} [[environment variable]].<br />
<br />
The correct driver name depends on your setup:<br />
<br />
* For Intel Graphics or AMD Catalyst you [[#Failed to open VDPAU backend|need]] to set it to {{ic|va_gl}}.<br />
* For the open source AMD/ATI driver set it to the proper driver version depending on your GPU, see [[#Verification]].<br />
* For NVIDIA's proprietary version set it to {{ic|nvidia}}.<br />
<br />
{{Note|<br />
* You can find the installed drivers in {{ic|/usr/lib/vdpau/}}. They are used as {{ic|/usr/lib/vdpau/libvdpau_'''${VDPAU_DRIVER}'''.so}}.<br />
* Some drivers are installed several times under different names for compatibility reasons. You can see which by running {{ic|sha1sum /usr/lib/vdpau/*}}.<br />
* For hybrid setups (both NVIDIA and AMD), it may be necessary to [[environment variable|set]] {{ic|1=DRI_PRIME=1}}. For more information see [[PRIME]].<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Failed to open VDPAU backend ===<br />
<br />
This happens when you use {{pkg|libvdpau-va-gl}} without overriding {{ic|VDPAU_DRIVER}}. VDPAU does not know what driver to use in this case for some reason and guesses wrongly. See [[#Configuring VDPAU]].<br />
<br />
However you may want to configure your media player to use VA-API instead, getting far better results. See [[#Software]].<br />
<br />
=== VAAPI init failed ===<br />
<br />
An error along the lines of {{ic|libva: /usr/lib/dri/i965_drv_video.so init failed}} is encountered. This can happen because of improper detection of Wayland. One solution is to unset {{ic|$DISPLAY}} so that mpv, mplayer, VLC, etc. do not assume it is X11. Another mpv-specific solution is to add the parameter {{ic|1=--opengl-backend=wayland}}.</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Intel_graphics&diff=512943Intel graphics2018-03-07T12:20:42Z<p>Ketsui: /* H.264 decoding on GMA 4500 */ Made it clearer that this section is about hardware acceleration</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[cs:Intel graphics]]<br />
[[de:Intel]]<br />
[[es:Intel graphics]]<br />
[[fr:Intel]]<br />
[[hu:Intel graphics]]<br />
[[it:Intel graphics]]<br />
[[ja:Intel Graphics]]<br />
[[pl:Intel graphics]]<br />
[[pt:Intel graphics]]<br />
[[ru:Intel graphics]]<br />
[[zh-hans:Intel graphics]]<br />
[[zh-hant:Intel graphics]]<br />
{{Related articles start}}<br />
{{Related|Intel GMA 3600}}<br />
{{Related|Xorg}}<br />
{{Related|Kernel mode setting}}<br />
{{Related|Xrandr}}<br />
{{Related|Hybrid graphics}}<br />
{{Related|Vulkan}}<br />
{{Related articles end}}<br />
<br />
Since Intel provides and supports open source drivers, Intel graphics are essentially plug-and-play.<br />
<br />
For a comprehensive list of Intel GPU models and corresponding chipsets and CPUs, see [[Wikipedia:Comparison of Intel graphics processing units|this comparison on Wikipedia]].<br />
<br />
{{Note|PowerVR-based graphics ([[Intel GMA 3600|GMA 3600]] series) are not supported by open source drivers.}}<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mesa}} package, which provides the DRI driver for 3D acceleration.<br />
<br />
* For 32-bit application support, also install the {{Pkg|lib32-mesa}} package from the [[multilib]] repository.<br />
* For the DDX driver (which provides 2D acceleration in [[Xorg]]), [[install]] the {{Pkg|xf86-video-intel}} package. (Often not recommended, see note below.)<br />
* For [[Vulkan]] support (''Ivy Bridge'' and newer), install the {{Pkg|vulkan-intel}} package.<br />
<br />
Also see [[Hardware video acceleration]].<br />
<br />
{{Note|1=Some ([http://www.phoronix.com/scan.php?page=news_item&px=Ubuntu-Debian-Abandon-Intel-DDX Debian & Ubuntu], [http://www.phoronix.com/scan.php?page=news_item&px=Fedora-Xorg-Intel-DDX-Switch Fedora], [https://community.kde.org/Plasma/5.9_Errata#Intel_GPUs KDE]) recommend not installing the {{Pkg|xf86-video-intel}} driver, and instead falling back on the modesetting driver for fourth generation and newer GPUs. See [https://www.reddit.com/r/archlinux/comments/4cojj9/it_is_probably_time_to_ditch_xf86videointel/], [http://www.phoronix.com/scan.php?page=article&item=intel-modesetting-2017&num=1], [[Xorg#Installation]], and {{man|4|modesetting}}. However, the modesetting driver can cause problems such as [https://bugs.chromium.org/p/chromium/issues/detail?id=370022 Chromium Issue 370022].}}<br />
<br />
== Loading ==<br />
<br />
The Intel kernel module should load fine automatically on system boot.<br />
<br />
If it does not happen, then:<br />
<br />
* Make sure you do '''not''' have {{ic|nomodeset}} or {{ic|1=vga=}} as a [[kernel parameter]], since Intel requires kernel mode-setting.<br />
* Also, check that you have not disabled Intel by using any modprobe blacklisting within {{ic|/etc/modprobe.d/}} or {{ic|/usr/lib/modprobe.d/}}.<br />
<br />
=== Enable early KMS ===<br />
<br />
[[Kernel mode setting]] (KMS) is supported by Intel chipsets that use the i915 DRM driver and is mandatory and enabled by default.<br />
<br />
Refer to [[Kernel mode setting#Early KMS start]] for instuctions on how to enable KMS as soon as possible at the boot process.<br />
<br />
=== Enable GuC / HuC firmware loading ===<br />
<br />
For Skylake and newer processors, some video features (e.g. CBR rate control on SKL low-power encoding mode) may require the use of an updated GPU firmware, which is currently (as of 4.14) not enabled by default. <br />
<br />
It is necessary to add {{ic|1=i915.enable_guc_loading=1 i915.enable_guc_submission=1}} to the [[kernel parameters]] to enable it. Alternatively, if the initramfs already includes the i915 module (see [[Kernel mode setting#Early KMS start]]), you can set these options through a file in {{ic|/etc/modprobe.d/}}. E.g.:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 enable_guc_loading=1 enable_guc_submission=1<br />
}}<br />
<br />
You can verify that it is enabled by checking ''dmesg'':<br />
<br />
[ 2.142029] [drm] GuC loaded (firmware i915/skl_guc_ver6_1.bin [version 6.1])<br />
<br />
Alternatively, check:<br />
<br />
# cat /sys/kernel/debug/dri/0/i915_huc_load_status<br />
# cat /sys/kernel/debug/dri/0/i915_guc_load_status<br />
<br />
== Xorg configuration ==<br />
<br />
There is no need for any configuration to run [[Xorg]].<br />
<br />
However, to take advantage of some driver options, you will need to create a Xorg configuration file similar to the one below:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
EndSection}}<br />
<br />
Additional options are added by the user on new lines below {{ic|Driver}}.<br />
<br />
{{Note|<br />
*You may need to indicate {{ic|Option "AccelMethod"}} when creating a configuration file, even just to set it to the default method (currently {{ic|"sna"}}); otherwise, X may crash.<br />
*You might need to add more device sections than the one listed above. This will be indicated where necessary.}} <br />
<br />
For the full list of options, see the {{man|4|intel}} man page.<br />
<br />
== Module-based Powersaving Options ==<br />
<br />
The {{ic|i915}} kernel module allows for configuration via [[Kernel modules#Setting module options|module options]]. Some of the module options impact power saving.<br />
<br />
A list of all options along with short descriptions and default values can be generated with the following command:<br />
<br />
$ modinfo -p i915<br />
<br />
To check which options are currently enabled, run<br />
<br />
# systool -m i915 -av<br />
<br />
You will note that many options default to -1, resulting in per-chip powersaving defaults. It is however possible to configure more aggressive powersaving by using [[Kernel modules#Setting module options|module options]].<br />
<br />
{{Warning|1=Diverting from the defaults will mark the kernel as [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=fc9740cebc3ab7c65f3c5f6ce0caf3e4969013ca tainted] from Linux 3.18 onwards. This basically implies using other options than the per-chip defaults is considered experimental and not supported by the developers. }}<br />
<br />
The following set of options should be generally safe to enable:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|<nowiki><br />
options i915 enable_rc6=1 enable_fbc=1 semaphores=1<br />
</nowiki>}}<br />
<br />
=== RC6 sleep modes (enable_rc6) ===<br />
<br />
You can experiment with higher values for {{ic|enable_rc6}}, but your GPU may not support them or the activation of the other options [https://wiki.archlinux.org/index.php?title=Talk:Intel_Graphics&oldid=327547#Kernel_Module_options].<br />
<br />
The available {{ic|enable_rc6}} values are a bitmask with bit values RC6=1, RC6p=2, RC6pp=4[https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/gpu/drm/i915/intel_pm.c#n34] - where "RC6p" and "RC6pp" are lower power states.<br />
<br />
To confirm the current running RC6 level, you can look in sysfs:<br />
<br />
# cat /sys/class/drm/card0/power/rc6_enable<br />
<br />
... if the value read is a lower number than expected, the other RC6 level are probably not supported. Passing {{ic|1=drm.debug=0xe}} will add DRM debugging information to the kernel log - possibly including a line like this:<br />
<br />
[drm:sanitize_rc6_option] Adjusting RC6 mask to 1 (requested 7, valid 1)<br />
<br />
=== Framebuffer compression (enable_fbc) ===<br />
<br />
Framebuffer compression may be unreliable or unavailable on Intel GPU generations before Sandy Bridge (generation 6). This results in messages logged to the system journal similar to this one:<br />
kernel: drm: not enough stolen space for compressed buffer, disabling.<br />
<br />
Enabling frame buffer compression on pre-Sandy Bridge CPUs results in endless error messages:<br />
<br />
$ dmesg |tail <br />
[ 2360.475430] [drm] not enough stolen space for compressed buffer (need 4325376 bytes), disabling<br />
[ 2360.475437] [drm] hint: you may be able to increase stolen memory size in the BIOS to avoid this<br />
<br />
The solution is to disable frame buffer compression which will imperceptibly increase power consumption (around 0.06 W). In order to disable it add {{ic|i915.enable_fbc&#61;0}} to the kernel line parameters. More information on the results of disabled compression can be found [http://kernel.ubuntu.com/~cking/power-benchmarking/background-colour-and-framebuffer-compression/ here].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Tear-free video ===<br />
<br />
The SNA acceleration method causes tearing for some people. To fix this, enable the {{ic|"TearFree"}} option in the driver by adding the following line to your [[#Xorg configuration|configuration file]]:<br />
Option "TearFree" "true"<br />
<br />
See the [https://bugs.freedesktop.org/show_bug.cgi?id=37686 original bug report] for more info.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* This option may not work when {{ic|SwapbuffersWait}} is {{ic|false}}.<br />
* This option may increases memory allocation considerably and reduce performance. [https://bugs.freedesktop.org/show_bug.cgi?id=37686#c123]<br />
* This option is problematic for applications that are very picky about vsync timing, like [[Wikipedia:Super Meat Boy|Super Meat Boy]].<br />
* This option does not work with UXA acceleration method, only with SNA.<br />
}}<br />
<br />
=== Disable Vertical Synchronization (VSYNC) ===<br />
Useful when:<br />
* Chomium/Chrome has lags and slow performance due to GPU and runs smoothly with --disable-gpu switch<br />
* glxgears test does not show desired performance<br />
<br />
The intel-driver uses [http://www.intel.com/support/graphics/sb/CS-004527.htm Triple Buffering] for vertical synchronization, this allows for full performance and avoids tearing. To turn vertical synchronization off (e.g. for benchmarking) use this {{ic|.drirc}} in your home directory:<br />
<br />
{{hc|~/.drirc|<br />
<device screen&#61;"0" driver&#61;"dri2"><br />
<application name&#61;"Default"><br />
<option name&#61;"vblank_mode" value&#61;"0"/><br />
</application><br />
</device>}}<br />
<br />
{{Warning|Do not use {{Pkg|driconf}} to create this file. It is buggy and will set the wrong driver.}}<br />
<br />
=== Setting scaling mode ===<br />
<br />
This can be useful for some full screen applications:<br />
<br />
$ xrandr --output LVDS1 --set PANEL_FITTING ''param''<br />
<br />
where {{ic|''param''}} can be:<br />
<br />
* {{ic|center}}: resolution will be kept exactly as defined, no scaling will be made,<br />
* {{ic|full}}: scale the resolution so it uses the entire screen or<br />
* {{ic|full_aspect}}: scale the resolution to the maximum possible but keep the aspect ratio.<br />
<br />
If it does not work, try:<br />
<br />
$ xrandr --output LVDS1 --set "scaling mode" ''param''<br />
<br />
where {{ic|''param''}} is one of {{ic|"Full"}}, {{ic|"Center"}} or {{ic|"Full aspect"}}.<br />
<br />
{{Note|1=This option currently does not work for external displays (e.g. VGA, DVI, HDMI, DP). [https://bugs.freedesktop.org/show_bug.cgi?id=90989]}}<br />
<br />
=== KMS Issue: console is limited to small area ===<br />
<br />
One of the low-resolution video ports may be enabled on boot which is causing the terminal to utilize a small area of the screen. To fix, explicitly disable the port with an i915 module setting with {{ic|1=video=SVIDEO-1:d}} in the kernel command line parameter in the bootloader. See [[Kernel parameters]] for more info.<br />
<br />
If that does not work, try disabling TV1 or VGA1 instead of SVIDEO-1. Video port names can be listed with [[xrandr]].<br />
<br />
=== Hardware accelerated H.264 decoding on GMA 4500 ===<br />
<br />
The {{Pkg|libva-intel-driver}} package only provides hardware accelerated MPEG-2 decoding for GMA 4500 series GPUs. The H.264 decoding support is maintained in a separated g45-h264 branch, which can be used by installing {{AUR|libva-intel-driver-g45-h264}} package. Note however that this support is experimental and its development has been abandoned. Using the VA-API with this driver on a GMA 4500 series GPU will offload the CPU but may not result in as smooth a playback as non-accelerated playback. Tests using mplayer showed that using vaapi to play back an H.264 encoded 1080p video halved the CPU load (compared to the XV overlay) but resulted in very choppy playback, while 720p worked reasonably well [https://bbs.archlinux.org/viewtopic.php?id=150550]. This is echoed by other experiences [http://www.emmolution.org/?p=192&cpage=1#comment-12292].<br />
Setting the preallocated video ram size higher in bios results in much better hardware decoded playback. Even 1080p h264 works well if this is done.<br />
Smooth playback (1080p/720p) works also with {{AUR|mpv-git}} in combination with {{AUR|ffmpeg-git}} and {{AUR|libva-intel-driver-g45-h264}}. With MPV and the Firefox plugin "Watch with MPV"[https://addons.mozilla.org/de/firefox/addon/watch-with-mpv/] it is possible to watch hardware accelerated YouTube videos.<br />
<br />
=== Setting brightness and gamma ===<br />
<br />
See [[Backlight]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== SNA issues ===<br />
<br />
''SNA'' is the default acceleration method in {{Pkg|xf86-video-intel}}. If you experience issues with ''SNA'' (e.g. pixelated graphics, corrupt text, etc.), try using ''UXA'' instead, which can be done by adding the following line to your [[#Xorg configuration|configuration file]]:<br />
Option "AccelMethod" "uxa"<br />
<br />
See {{man|4|intel}} under {{ic|Option "AccelMethod"}}.<br />
<br />
=== DRI3 issues ===<br />
<br />
''DRI3'' is the default DRI version in {{Pkg|xf86-video-intel}}. On some systems this can cause issues such as [https://bugs.chromium.org/p/chromium/issues/detail?id=370022 this]. To switch back to ''DRI2'' add the following line to your [[#Xorg configuration|configuration file]]:<br />
Option "DRI" "2"<br />
<br />
For the {{ic|modesetting}} driver, this method of disabling DRI3 does not work. Instead, one can set the environment variable {{ic|1=LIBGL_DRI3_DISABLE=1}}.<br />
<br />
=== Font and screen corruption in GTK+ applications (missing glyphs after suspend/resume) ===<br />
<br />
Should you experience missing font glyphs in GTK+ applications, the following workaround might help. [[textedit|Edit]] {{ic|/etc/environment}} to add the following line:<br />
<br />
{{hc|/etc/environment|output=<br />
COGL_ATLAS_DEFAULT_BLIT_MODE=framebuffer<br />
}}<br />
<br />
See also [https://bugs.freedesktop.org/show_bug.cgi?id=88584 FreeDesktop bug 88584].<br />
<br />
=== Blank screen during boot, when "Loading modules" ===<br />
<br />
If using "late start" KMS and the screen goes blank when "Loading modules", it may help to add {{ic|i915}} and {{ic|intel_agp}} to the initramfs. See [[Kernel mode setting#Early KMS start]] section.<br />
<br />
Alternatively, appending the following [[kernel parameter]] seems to work as well:<br />
<br />
video=SVIDEO-1:d<br />
<br />
If you need to output to VGA then try this:<br />
<br />
video=VGA-1:1280x800<br />
<br />
=== X freeze/crash with intel driver ===<br />
<br />
Some issues with X crashing, GPU hanging, or problems with X freezing, can be fixed by disabling the GPU usage with the {{ic|NoAccel}} option - add the following lines to your [[#Xorg configuration|configuration file]]:<br />
Option "NoAccel" "True"<br />
<br />
Alternatively, try to disable the 3D acceleration only with the {{ic|DRI}} option:<br />
Option "DRI" "False"<br />
<br />
If you experience crashes and have<br />
<br />
Option "TearFree" "true"<br />
Option "AccelMethod" "sna"<br />
<br />
in your configuration file, in most cases these can be fixed by adding<br />
<br />
i915.semaphores=1<br />
<br />
to your boot parameters.<br />
<br />
=== Baytrail complete freeze ===<br />
<br />
If you are using kernel > 3.16 on Baytrail architecture and randomly encounter total system freezes, the following kernel option is a workaround until [https://bugzilla.kernel.org/show_bug.cgi?id=109051 this bug] is fixed in the linux kernel.<br />
<br />
intel_idle.max_cstate=1<br />
<br />
This is originally an Intel CPU bug that can be triggered by certain c-state transitions. It can also happen with Linux kernel 3.16 or Windows, though apparently much more rarely.<br />
The kernel option will prevent the freeze by avoiding c-state transitions but will also increase power consumption.<br />
<br />
=== Adding undetected resolutions ===<br />
<br />
This issue is covered on the [[Xrandr#Adding undetected resolutions|Xrandr page]].<br />
<br />
=== Weathered colors (color range problem) ===<br />
<br />
Kernel 3.9 [http://lists.freedesktop.org/archives/dri-devel/2013-January/033576.html contains] a new default "Automatic" mode for the "Broadcast RGB" property in the Intel driver. It is almost equivalent to "Limited 16:235" (instead of the old default "Full") whenever an HDMI/DP output is in a [http://raspberrypi.stackexchange.com/questions/7332/what-is-the-difference-between-cea-and-dmt CEA mode]. If a monitor does not support signal in limited color range, it will cause weathered colors.<br />
<br />
{{Note|Some monitors/TVs support both color range. In that case an option often known as ''Black Level'' may need to be adjusted to make them handle the signal correctly. Some TVs can handle signal in limited range only. Setting Broadcast RGB to "Full" will cause color clipping. You may need to set it to "Limited 16:235" manually to avoid the clipping.}}<br />
<br />
One can force mode e.g. {{ic|xrandr --output <HDMI> --set "Broadcast RGB" "Full"}} (replace {{ic|<HDMI>}} with the appropriate output device, verify by running {{ic|xrandr}}).<br />
<br />
Unfortunately, the Intel driver does not support setting the color range through an {{ic|xorg.conf.d}} configuration file.<br />
<br />
A [https://bugzilla.kernel.org/show_bug.cgi?id=94921 bug report] is filed and a patch can be found in the attachment.<br />
<br />
Also there are other related problems which can be fixed editing GPU registers. More information can be found [http://lists.freedesktop.org/archives/intel-gfx/2012-April/016217.html] and [http://github.com/OpenELEC/OpenELEC.tv/commit/09109e9259eb051f34f771929b6a02635806404c].<br />
<br />
=== Backlight is not adjustable===<br />
<br />
If after resuming from suspend, the hotkeys for changing the screen brightness do not take effect, check your configuration against the [[Backlight]] article.<br />
<br />
If the problem persists, try one of the following [[kernel parameters]]:<br />
<br />
acpi_osi=Linux<br />
acpi_osi="!Windows 2012"<br />
acpi_osi=<br />
<br />
=== Corruption/Unresponsiveness in Chromium and Firefox ===<br />
<br />
If you experience corruption, unresponsiveness, lags or slow performance in Chromium and/or Firefox: <br />
* [[#SNA issues|Set the AccelMethod to "uxa"]]<br />
* [[#Disable Vertical Synchronization (VSYNC)|Disable VSYNC]]<br />
<br />
=== Kernel crashing w/kernels 4.0+ on Broadwell/Core-M chips ===<br />
<br />
A few seconds after X/Wayland loads the machine will freeze and journalctl will log a kernel crash referencing the Intel graphics as below:<br />
<br />
Jun 16 17:54:03 hostname kernel: BUG: unable to handle kernel NULL pointer dereference at (null)<br />
Jun 16 17:54:03 hostname kernel: IP: [< (null)>] (null)<br />
...<br />
Jun 16 17:54:03 hostname kernel: CPU: 0 PID: 733 Comm: gnome-shell Tainted: G U O 4.0.5-1-ARCH #1<br />
...<br />
Jun 16 17:54:03 hostname kernel: Call Trace:<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa055cc27>] ? i915_gem_object_sync+0xe7/0x190 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0579634>] intel_execlists_submission+0x294/0x4c0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa05539fc>] i915_gem_do_execbuffer.isra.12+0xabc/0x1230 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa055d349>] ? i915_gem_object_set_to_cpu_domain+0xa9/0x1f0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ba2ae>] ? __kmalloc+0x2e/0x2a0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0555471>] i915_gem_execbuffer2+0x141/0x2b0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa042fcab>] drm_ioctl+0x1db/0x640 [drm]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0555330>] ? i915_gem_execbuffer+0x450/0x450 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff8122339b>] ? eventfd_ctx_read+0x16b/0x200<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ebc36>] do_vfs_ioctl+0x2c6/0x4d0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811f6452>] ? __fget+0x72/0xb0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ebec1>] SyS_ioctl+0x81/0xa0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff8157a589>] system_call_fastpath+0x12/0x17<br />
Jun 16 17:54:03 hostname kernel: Code: Bad RIP value.<br />
Jun 16 17:54:03 hostname kernel: RIP [< (null)>] (null)<br />
<br />
This can be fixed by disabling execlist support which was changed to default on with kernel 4.0. Add the following [[kernel parameter]]:<br />
i915.enable_execlists=0<br />
<br />
This is known to be broken to at least kernel 4.0.5.<br />
<br />
=== Lag in Windows guests ===<br />
<br />
The video output of a Windows guest in VirtualBox sometimes hangs until the host forces a screen update (e.g. by moving the mouse cursor). Removing the {{ic|1=enable_fbc=1}} option fixes this issue.<br />
<br />
=== Screen flickering ===<br />
<br />
The following power saving features used by intel iGPUs are known to cause flickering in some instances. A temporary solution is to disable one of them using the appropriate [[Kernel_parameters|kernel boot parameter]] option:<br />
<br />
*Rc6 sleep modes (see [[#RC6 sleep modes (enable_rc6)]]), can be disabled with {{ic|1=i915.enable_rc6=0}}.<br />
<br />
*Panel Self Refresh (PSR) {{Bug|49628}} {{Bug|49371}} {{Bug|50605}}. To disable this feature use the option {{ic|1=i915.enable_psr=0}}.<br />
<br />
=== OpenGL 2.1 with i915 driver ===<br />
<br />
The update of {{Pkg|mesa}} from version 13.x to 17 may break support for OpenGL 2.1 on third gen Intel GPUs (GMA3100, see [[wikipedia:List_of_Intel_graphics_processing_units#Third_generation|here]]), as described in this [http://www.phoronix.com/scan.php?page=news_item&px=Mesa-i915-OpenGL-2-Drop article], reverting it back to OpenGL 1.4. However this could be restored manually by setting {{ic|/etc/drirc}} or {{ic|~/.drirc}} options like :<br />
{{hc|/etc/drirc|output=<br />
<driconf><br />
...<br />
<device driver="i915"><br />
<application name="Default"><br />
<option name="'''stub_occlusion_query'''" value="'''true'''" /><br />
<option name="'''fragment_shader'''" value="'''true'''" /><br />
</application><br />
</device><br />
...<br />
</driconf><br />
}}<br />
{{Note|the reason of this step back was Chromium and other apps bad experience. If needed, you might edit the drirc file in a "app-specific" style, see [https://dri.freedesktop.org/wiki/ConfigurationInfrastructure/ here], to disable gl2.1 on executable chromium for instance.}}<br />
<br />
== See also ==<br />
<br />
* https://01.org/linuxgraphics/documentation (includes a list of supported hardware)</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512489Pacman/Tips and tricks2018-03-02T13:15:57Z<p>Ketsui: Undo revision 512485 by Ketsui (talk)</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies. With opion {{ic|-n}}, foreign packages (e.g. from AUR) are ommited from the list.}}<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
In case the list includes foreign packages, such as [[AUR]] packages, remove them first:<br />
<br />
# pacman -S $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512488Pacman/Tips and tricks2018-03-02T13:14:53Z<p>Ketsui: Undo revision 512484 by Ketsui (talk) Never mind</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies. With opion {{ic|-n}}, foreign packages (e.g. from AUR) are ommited from the list.}}<br />
<br />
To create a list of AUR and foreign packages:<br />
<br />
$ pacman -Qqm > aurpkglist.txt<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
In case the list includes foreign packages, such as [[AUR]] packages, remove them first:<br />
<br />
# pacman -S $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512487Pacman/Tips and tricks2018-03-02T13:14:33Z<p>Ketsui: Undo revision 512486 by Ketsui (talk) Never mind</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqen > pkglist.txt<br />
<br />
{{Note|When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies.}}<br />
<br />
To create a list of AUR and foreign packages:<br />
<br />
$ pacman -Qqm > aurpkglist.txt<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512486Pacman/Tips and tricks2018-03-02T13:10:07Z<p>Ketsui: /* List of installed packages */ Added a note</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqen > pkglist.txt<br />
<br />
{{Note|The {{ic|-n}} option ensures that AUR and foreign packages are excluded from the list to avoid 'package not found' error when reinstalling from the list. When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies.}}<br />
<br />
To create a list of AUR and foreign packages:<br />
<br />
$ pacman -Qqm > aurpkglist.txt<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512485Pacman/Tips and tricks2018-03-02T13:02:10Z<p>Ketsui: /* List of installed packages */ Added how to create a list of installed AUR packages</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqen > pkglist.txt<br />
<br />
{{Note|When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies.}}<br />
<br />
To create a list of AUR and foreign packages:<br />
<br />
$ pacman -Qqm > aurpkglist.txt<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512484Pacman/Tips and tricks2018-03-02T12:59:34Z<p>Ketsui: /* List of installed packages */ We can just exclude AUR/foreign packages from the list by passing -n</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqen > pkglist.txt<br />
<br />
{{Note|When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies.}}<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512481Pacman/Tips and tricks2018-03-02T12:50:14Z<p>Ketsui: /* List of installed packages */ Help:Style/Formatting_and_punctuation#File_names_and_paths typo fix and also a minor reword</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|When using option {{ic|-t}}, when reinstalling the list all the non-top-level packages would be set as dependencies. With opion {{ic|-n}}, foreign packages (e.g. from AUR) are ommited from the list.}}<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
In case the list includes foreign packages, such as [[AUR]] packages, remove them first:<br />
<br />
# pacman -S $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=OpenVPN&diff=512375OpenVPN2018-03-01T13:28:24Z<p>Ketsui: /* Update resolv-conf script */ Help:Style/Formatting_and_punctuation#File_names_and_paths</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[de:OpenVPN]]<br />
[[ja:OpenVPN]]<br />
[[ru:OpenVPN]]<br />
[[zh-hans:OpenVPN]]<br />
{{Related articles start}}<br />
{{Related|OpenVPN (client) in Linux containers}}<br />
{{Related|OpenVPN (server) in Linux containers}}<br />
{{Related|Easy-RSA}}<br />
{{Related articles end}}<br />
<br />
This article describes a basic installation and configuration of [http://openvpn.net OpenVPN], suitable for private and small business use. For more detailed information, please see the [https://community.openvpn.net/openvpn/wiki/Openvpn24ManPage OpenVPN 2.4 man page] and the [http://openvpn.net/index.php/open-source/documentation OpenVPN documentation]. OpenVPN is a robust and highly flexible [[Wikipedia:VPN|VPN]] daemon. It supports [[Wikipedia:SSL/TLS|SSL/TLS]] security, [[Wikipedia:Bridging_(networking)|Ethernet bridging]], [[Wikipedia:Transmission_Control_Protocol|TCP]] or [[Wikipedia:User_Datagram_Protocol|UDP]] [[Wikipedia:Tunneling_protocol|tunnel transport]] through [[Wikipedia:Proxy_server|proxies]] or [[Wikipedia:Network address translation|NAT]]. Additionally it has support for dynamic IP addresses and [[Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]], scalability to hundreds or thousands of users, and portability to most major OS platforms.<br />
<br />
OpenVPN is tightly bound to the [http://www.openssl.org OpenSSL] library, and derives much of its crypto capabilities from it. It supports conventional encryption using a [[Wikipedia:Pre-shared_key|pre-shared secret key]] (Static Key mode) or [[Wikipedia:Public_key|public key security]] ([[Wikipedia:SSL/TLS|SSL/TLS]] mode) using client & server certificates. Additionally it supports unencrypted TCP/UDP tunnels.<br />
<br />
OpenVPN is designed to work with the [[Wikipedia:TUN/TAP|TUN/TAP]] virtual networking interface that exists on most platforms. Overall, it aims to offer many of the key features of [[Wikipedia:Ipsec|IPSec]] but with a relatively lightweight footprint. OpenVPN was written by James Yonan and is published under the [[Wikipedia:GNU General Public License|GNU General Public License (GPL)]].<br />
<br />
== Install OpenVPN ==<br />
<br />
[[Install]] the {{Pkg|openvpn}} package, which provides both server and client mode.<br />
<br />
== Kernel configuration ==<br />
<br />
OpenVPN requires TUN/TAP support, which is already configured in the default kernel. Users of custom kernel should make sure to enable the {{ic|tun}} module:<br />
<br />
{{hc|Kernel config file|<br />
Device Drivers<br />
--> Network device support<br />
[M] Universal TUN/TAP device driver support<br />
}}<br />
<br />
Read [[Kernel modules]] for more information.<br />
<br />
== Connect to a VPN provided by a third party ==<br />
<br />
To connect to a VPN service provided by a third party, most of the following can most likely be ignored, especially regarding server setup. Begin with [[#The client config profile]] and skip ahead to [[#Starting OpenVPN]] after that. One should use the provider certificates and instructions, see [[:Category:VPN providers]] for examples that can be adapted to other providers. [[OpenVPN (client) in Linux containers]] also has general applicable instructions, while it goes a step further by isolating an OpenVPN client process into a container.<br />
<br />
{{Note|Most free VPN providers will (often only) offer [[PPTP server|PPTP]], which is drastically easier to setup and configure, but [http://poptop.sourceforge.net/dox/protocol-security.phtml not secure].}}<br />
<br />
== Create a Public Key Infrastructure (PKI) from scratch ==<br />
<br />
When setting up an OpenVPN server, users need to create a [[Wikipedia:Public key infrastructure|Public Key Infrastructure (PKI)]] which is detailed in the [[Easy-RSA]] article. Once the needed certificates, private keys, and associated files are created via following the steps in the separate article, one should have 5 files in {{ic|/etc/openvpn/server}} at this point:<br />
<br />
ca.crt<br />
dh.pem<br />
servername.crt<br />
servername.key<br />
ta.key<br />
<br />
Alternatively, as of OpenVPN 2.4, one can use Easy-RSA to generate certificates and keys using elliptic curves. See the OpenVPN documentation for details.<br />
<br />
== A basic L3 IP routing configuration ==<br />
<br />
{{Note|Unless otherwise explicitly stated, the rest of this article assumes a basic L3 IP routing configuration.}}<br />
<br />
OpenVPN is an extremely versatile piece of software and many configurations are possible, in fact machines can be both servers and clients.<br />
<br />
With the release of v2.4, server configurations are stored in {{ic|/etc/openvpn/server}} and client configurations are stored in {{ic|/etc/openvpn/client}} and each mode has its own respective systemd unit, namely, {{ic|openvpn-client@.service}} and {{ic|openvpn-server@.service}}.<br />
<br />
=== Example configuration ===<br />
<br />
The OpenVPN package comes with a collection of example configuration files for different purposes. The sample server and client configuration files make an ideal starting point for a basic OpenVPN setup with the following features:<br />
<br />
* Uses [[Wikipedia:Public key infrastructure|Public Key Infrastructure (PKI)]] for authentication.<br />
* Creates a VPN using a virtual TUN network interface (OSI L3 IP routing).<br />
* Listens for client connections on UDP port 1194 (OpenVPN's official IANA port number[https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=openvpn]).<br />
* Distributes virtual addresses to connecting clients from the 10.8.0.0/24 subnet.<br />
<br />
For more advanced configurations, please see the {{man|8|openvpn}} man page and the [http://openvpn.net/index.php/open-source/documentation OpenVPN documentation].<br />
<br />
=== The server configuration file ===<br />
<br />
{{Note|Note that if the server is behind a firewall or a NAT translating router, the OpenVPN port must be forwarded on to the server.}}<br />
<br />
Copy the example server configuration file {{ic|/usr/share/openvpn/examples/server.conf}} to {{ic|/etc/openvpn/server/server.conf}}.<br />
<br />
Edit the file making a minimum of the following changes:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
ca ca.crt<br />
cert servername.crt<br />
key servername.key # This file should be kept secret<br />
dh dh.pem<br />
.<br />
tls-crypt ta.key # Replaces ''tls-auth ta.key 0''<br />
.<br />
user nobody<br />
group nobody<br />
}}<br />
<br />
==== Hardening the server ====<br />
<br />
If security is a priority, additional configuration is recommended including: limiting the server to use a strong cipher/auth method and (optionally) limiting the set of enabled TLS ciphers to the newer ciphers.<br />
<br />
Add the following to {{ic|/etc/openvpn/server/server.conf}}:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
cipher AES-256-CBC<br />
auth SHA512<br />
tls-version-min 1.2<br />
tls-cipher TLS-DHE-RSA-WITH-AES-256-GCM-SHA384:TLS-DHE-RSA-WITH-AES-128-GCM-SHA256:TLS-DHE-RSA-WITH-AES-256-CBC-SHA:TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA:TLS-DHE-RSA-WITH-AES-128-CBC-SHA:TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA<br />
.<br />
}}<br />
<br />
{{Note|<br />
*The .ovpn client profile '''must''' contain a matching cipher and auth line to work properly (at least with the iOS and Android client).<br />
*Using {{ic|tls-cipher}} incorrectly may cause difficulty with debugging connections and may not be necessary. See [https://community.openvpn.net/openvpn/wiki/Hardening#Useof--tls-cipher OpenVPN’s community wiki] for more information.}}<br />
<br />
==== Enabling compression ====<br />
<br />
Since OpenVPN v2.4 it is possible to use LZ4 compression over lzo. LZ4 generally offering the best performance with least CPU usage. For backwards compatibility with OpenVPN versions before v2.4, use lzo {{ic|comp-lzo}}. Do '''not''' enable both compression options at the same time.<br />
<br />
To do so, configure {{ic|/etc/openvpn/server/server.conf}} as such:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
compress lz4-v2<br />
push "compress lz4-v2"<br />
.<br />
}}<br />
<br />
On the client set {{ic|--compress lz4}} [https://community.openvpn.net/openvpn/wiki/DeprecatedOptions], although this may be deprecated in the near future.<br />
<br />
==== Deviating from the standard port and/or protocol ====<br />
<br />
Some public/private network admins may not allow OpenVPN connections on its default port and/or protocol. One strategy to circumvent this is to mimic https/SSL traffic which is very likely unobstructed.<br />
<br />
To do so, configure {{ic|/etc/openvpn/server/server.conf}} as such:<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
port 443<br />
proto tcp<br />
.<br />
}}<br />
<br />
{{Note|The .ovpn client profile '''must''' contain a matching port and proto line to work properly!}}<br />
<br />
===== TCP vs UDP =====<br />
<br />
There are subtle differences between TCP and UDP.<br />
<br />
TCP<br />
<br />
* So-called "stateful protocol."<br />
* High reliability due to error correction (i.e. waits for packet acknowledgment).<br />
* Potentially slower than UDP.<br />
<br />
UDP<br />
<br />
* So-called "stateless protocol."<br />
* Less reliable than TCP as no error correction is in use.<br />
* Potentially faster than TCP.<br />
<br />
{{Note|It is generally a bad idea to use TCP for VPN unless your connection to the server is very stable. High reliability sounds great in theory but any disruption (packet drop, lag spikes, etc...) to the connection will potentially snowball into a [http://sites.inka.de/bigred/devel/tcp-tcp.html TCP Meltdown][http://adsabs.harvard.edu/abs/2005SPIE.6011..138H].}}<br />
<br />
=== The client config profile ===<br />
<br />
Copy the example client configuration file {{ic|/usr/share/openvpn/examples/client.conf}} to {{ic|/etc/openvpn/client/}}.<br />
<br />
Edit the following:<br />
<br />
* The {{ic|remote}} directive to reflect either the server's [[Wikipedia:Fully qualified domain name|Fully Qualified Domain Name]], hostname (as known to the client), or its IP address.<br />
* Uncomment the {{ic|user}} and {{ic|group}} directives to drop privileges.<br />
* The {{ic|ca}}, {{ic|cert}}, and {{ic|key}} parameters to reflect the path and names of the keys and certificates.<br />
* Enable the TLS HMAC handshake protection ({{ic|--tls-crypt}} or {{ic|--tls-auth}}).<br />
<br />
{{hc|/etc/openvpn/client/client.conf|<br />
client<br />
remote elmer.acmecorp.org 1194<br />
.<br />
user nobody<br />
group nobody<br />
ca ca.crt<br />
cert client.crt<br />
key client.key<br />
.<br />
tls-crypt ta.key # Replaces ''tls-auth ta.key 1''<br />
}}<br />
<br />
==== Run as unprivileged user ====<br />
<br />
Using the options {{ic|user nobody}} and {{ic|group nobody}} in the configuration file makes ''OpenVPN'' drop its {{ic|root}} privileges after establishing the connection. The downside is that upon VPN disconnect the daemon is unable to delete its set network routes again. If one wants to limit transmitting traffic without the VPN connection, then lingering routes may be considered beneficial. It can also happen, however, that the OpenVPN server pushes updates to routes at runtime of the tunnel. A client with dropped privileges will be unable to perform the update and exit with an error.<br />
<br />
As it could seem to require manual action to manage the routes, the options {{ic|user nobody}} and {{ic|group nobody}} might seem undesirable. Depending on setup, however, there are different ways to handle these situations: <br />
<br />
* For errors of the unit, a simple way is to [[edit]] it and add a {{ic|1=Restart=on-failure}} to the {{ic|[Service]}} section. Though, this alone will not delete any obsoleted routes, so it may happen that the restarted tunnel is not routed properly. <br />
* The package contains the {{ic|/usr/lib/openvpn/plugins/openvpn-plugin-down-root.so}}, which can be used to let ''openvpn'' fork a process with root privileges with the only task to execute a custom script when receiving a down signal from the main process, which is handling the tunnel with dropped privileges (see also its [https://community.openvpn.net/openvpn/browser/plugin/down-root/README?rev=d02a86d37bed69ee3fb63d08913623a86c88da15 README]).<br />
<br />
The OpenVPN HowTo's linked below go further by creating a dedicated non-privileged user/group, instead of the already existing {{ic|nobody}}. The advantage is that this avoids potential risks when sharing a user among daemons:<br />
* The [https://openvpn.net/index.php/open-source/documentation/howto.html#security OpenVPN HowTo] explains another way how to create an unprivileged user mode and wrapper script to have the routes restored automatically.<br />
* It is possible to let OpenVPN start as a non-privileged user in the first place, without ever running as root, see [https://community.openvpn.net/openvpn/wiki/UnprivilegedUser this OpenVPN wiki] (howto). The howto assumes the presence of System V init, rather than [[Systemd]] and does not cover the handling of {{ic|--up}}/{{ic|--down}} scripts - those should be handled the same way as the ''ip'' command, with additional attention to access rights.<br />
<br />
{{Note|Due to a [https://community.openvpn.net/openvpn/ticket/812 bug] in OpenVPN 2.4.0, the {{ic|persist-tun}} option mentioned in the howtos should '''not''' be used, otherwise new routes/IPs pushed on reconnect will be ignored by the client.}}<br />
<br />
{{Tip|[[#openvpn-unroot]] describes a tool to automate above setup.}}<br />
<br />
=== Converting certificates to encrypted .p12 format ===<br />
<br />
Some software will only read VPN certificates that are stored in a password-encrypted .p12 file. These can be generated with the following command:<br />
{{bc|# openssl pkcs12 -export -inkey keys/bugs.key -in keys/bugs.crt -certfile keys/ca.crt -out keys/bugs.p12}}<br />
<br />
=== Testing the OpenVPN configuration ===<br />
<br />
Run {{ic|# openvpn /etc/openvpn/server/server.conf}} on the server, and {{ic|# openvpn /etc/openvpn/client/client.conf}} on the client. Example output should be similar to the following:<br />
<br />
{{hc|# openvpn /etc/openvpn/server/server.conf|2=<br />
Wed Dec 28 14:41:26 2011 OpenVPN 2.2.1 x86_64-unknown-linux-gnu [SSL] [LZO2] [EPOLL] [eurephia] built on Aug 13 2011<br />
Wed Dec 28 14:41:26 2011 NOTE: OpenVPN 2.1 requires '--script-security 2' or higher to call user-defined scripts or executables<br />
Wed Dec 28 14:41:26 2011 Diffie-Hellman initialized with 2048 bit key<br />
.<br />
.<br />
Wed Dec 28 14:41:54 2011 bugs/95.126.136.73:48904 MULTI: primary virtual IP for bugs/95.126.136.73:48904: 10.8.0.6<br />
Wed Dec 28 14:41:57 2011 bugs/95.126.136.73:48904 PUSH: Received control message: 'PUSH_REQUEST'<br />
Wed Dec 28 14:41:57 2011 bugs/95.126.136.73:48904 SENT CONTROL [bugs]: 'PUSH_REPLY,route 10.8.0.1,topology net30,ping 10,ping-restart 120,ifconfig 10.8.0.6 10.8.0.5' (status=1)<br />
}}<br />
<br />
{{hc|# openvpn /etc/openvpn/client/client.conf|2=<br />
Wed Dec 28 14:41:50 2011 OpenVPN 2.2.1 i686-pc-linux-gnu [SSL] [LZO2] [EPOLL] [eurephia] built on Aug 13 2011<br />
Wed Dec 28 14:41:50 2011 NOTE: OpenVPN 2.1 requires '--script-security 2' or higher to call user-defined scripts or executables<br />
Wed Dec 28 14:41:50 2011 LZO compression initialized<br />
.<br />
.<br />
Wed Dec 28 14:41:57 2011 GID set to nobody<br />
Wed Dec 28 14:41:57 2011 UID set to nobody<br />
Wed Dec 28 14:41:57 2011 Initialization Sequence Completed<br />
}}<br />
<br />
On the server, find the IP address assigned to the tunX device:<br />
<br />
{{hc|# ip addr show|2=<br />
.<br />
.<br />
40: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 100<br />
link/none<br />
inet 10.8.0.1 peer 10.8.0.2/32 scope global tun0<br />
}}<br />
<br />
Here we see that the server end of the tunnel has been given the IP address 10.8.0.1.<br />
<br />
Do the same on the client:<br />
<br />
{{hc|# ip addr show|2=<br />
.<br />
.<br />
37: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 100<br />
link/none<br />
inet 10.8.0.6 peer 10.8.0.5/32 scope global tun0<br />
}}<br />
<br />
And the client side has been given the IP address 10.8.0.6.<br />
<br />
Now try pinging the interfaces.<br />
<br />
On the server:<br />
<br />
{{hc|# ping -c3 10.8.0.6|2=<br />
PING 10.8.0.6 (10.8.0.6) 56(84) bytes of data.<br />
64 bytes from 10.8.0.6: icmp_req=1 ttl=64 time=238 ms<br />
64 bytes from 10.8.0.6: icmp_req=2 ttl=64 time=237 ms<br />
64 bytes from 10.8.0.6: icmp_req=3 ttl=64 time=205 ms<br />
<br />
--- 10.8.0.6 ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2002ms<br />
rtt min/avg/max/mdev = 205.862/227.266/238.788/15.160 ms<br />
}}<br />
<br />
On the client:<br />
<br />
{{hc|# ping -c3 10.8.0.1|2=<br />
PING 10.8.0.1 (10.8.0.1) 56(84) bytes of data.<br />
64 bytes from 10.8.0.1: icmp_req=1 ttl=64 time=158 ms<br />
64 bytes from 10.8.0.1: icmp_req=2 ttl=64 time=158 ms<br />
64 bytes from 10.8.0.1: icmp_req=3 ttl=64 time=157 ms<br />
<br />
--- 10.8.0.1 ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2001ms<br />
rtt min/avg/max/mdev = 157.426/158.278/158.940/0.711 ms<br />
}}<br />
<br />
{{Note|If using a firewall, make sure that IP packets on the TUN device are not blocked.}}<br />
<br />
=== Configure the MTU with Fragment and MSS ===<br />
<br />
If experiencing issues when using (remote) services over OpenVPN (e.g. web browsing, [[DNS]], [[NFS]]), it may be needed to set a MTU value manually.<br />
<br />
The following message may indicate the MTU value should be adjusted:<br />
<br />
read UDPv4 [EMSGSIZE Path-MTU=1407]: Message too long (code=90)<br />
<br />
In order to get the maximum segment size (MSS), the client needs to discover the smallest MTU along the path to the server. In order to do this ping the server and disable fragmentation, then specify the maximum packet size [https://www.sonassi.com/help/troubleshooting/setting-correct-mtu-for-openvpn]:<br />
<br />
# ping -M do -s 1500 -c 1 example.com<br />
<br />
Decrease the 1500 value by 10 each time, until the ping succeeds.<br />
<br />
{{Note|Clients that do not support the 'fragment' directive (e.g. OpenELEC, [https://forums.openvpn.net/topic13201.html#p31156 iOS app]) are not able to connect to a server that uses the {{ic|fragment}} directive. See {{ic|mtu-test}} as alternative solution.}}<br />
<br />
Update the client configuration to use the succeeded MTU value, e.g.:<br />
<br />
{{hc|/etc/openvpn/client/client.conf|<br />
remote example.com 1194<br />
...<br />
tun-mtu 1500<br />
fragment 1300<br />
mssfix # will take its default max parameter from the --fragment max option<br />
}}<br />
<br />
OpenVPN may be instructed to test the MTU every time on client connect. Be patient, since your client may not inform about the test being run and the connection may appear as nonfunctional until finished. The following will add about 3 minutes to OpenVPN start time. It is advisable to configure the fragment size unless a client will be connecting over many different networks and the bottle neck is not on the server side:<br />
<br />
{{hc|/etc/openvpn/client/client.conf|<br />
remote example.com 1194<br />
...<br />
mtu-test<br />
...<br />
}}<br />
<br />
=== IPv6 ===<br />
<br />
==== Connect to the server via IPv6 ====<br />
<br />
In order to enable Dual Stack for OpenVPN, you have to change {{ic|proto udp}} to {{ic|proto udp6}} in both server.conf and client.conf. Afterwards both IPv4 and IPv6 are enabled.<br />
<br />
==== Provide IPv6 inside the tunnel ====<br />
<br />
In order to provide IPv6 inside the tunnel, you need to have a IPv6 prefix routed to your OpenVPN server. Either set up a static route on your gateway (if you have a static block assigned), or use a DHCPv6 client to get a prefix with DHCPv6 Prefix delegation (see [[IPv6#Prefix delegation (DHCPv6-PD)|IPv6 Prefix delegation]] for details). You can also use a unique local address from the address block fc00::/7. Both methods have advantages and disadvantages:<br />
<br />
* Many ISPs only provide dynamically changing IPv6 prefixes. OpenVPN does not support prefix changes, so you need to change your server.conf every time the prefix is changed (Maybe can be automated with a script).<br />
* ULA addresses are not routed to the Internet, and setting up NAT is not as straightforward as with IPv4. So you cannot route the entire traffic over the tunnel. If you only want to connect two sites via IPv6, without the need to connect to the Internet over the tunnel, the ULA addresses may be easier to use.<br />
<br />
After you have received a prefix (a /64 is recommended), append the following to the server.conf:<br />
<br />
server-ipv6 2001:db8:0:123::/64<br />
<br />
This is the IPv6 equivalent to the default 10.8.0.0/24 network of OpenVPN and needs to be taken from the DHCPv6 client. Or use for example fd00:1234::/64.<br />
<br />
If you want to push a route to your home network (192.168.1.0/24 equivalent), also append:<br />
<br />
push "route-ipv6 2001:db8:0:abc::/64"<br />
<br />
OpenVPN does not yet include DHCPv6, so there is no method to e.g. push DNS server over IPv6. This needs to be done with IPv4. The [https://community.openvpn.net/openvpn/wiki/IPv6 OpenVPN Wiki] provides some other configuration options.<br />
<br />
== Starting OpenVPN ==<br />
<br />
=== Manual startup ===<br />
<br />
To troubleshoot a VPN connection, start the client's daemon manually with {{ic|openvpn /etc/openvpn/client/client.conf}} as root. The server can be started the same way using its own configuration file (e.g., {{ic|openvpn /etc/openvpn/server/server.conf}}).<br />
<br />
=== systemd service configuration ===<br />
<br />
To start the OpenVPN server automatically at system boot, [[enable]] {{ic|openvpn-server@''<configuration>''.service}} on the applicable machine. For a client, [[enable]] {{ic|openvpn-client@''<configuration>''.service}} instead. (Leave {{ic|.conf}} out of the {{ic|<configuration>}} string.)<br />
<br />
For example, if the client configuration file is {{ic|/etc/openvpn/client/''client''.conf}}, the service name is {{ic|openvpn-client@''client''.service}}. Or, if the server configuration file is {{ic|/etc/openvpn/server/''server''.conf}}, the service name is {{ic|openvpn-server@''server''.service}}.<br />
<br />
=== Letting NetworkManager start a connection ===<br />
<br />
On a client you might not always need to run a VPN tunnel and/or only want to establish it for a specific NetworkManager connection. This can be done by adding a script to {{ic|/etc/NetworkManager/dispatcher.d/}}. In the following example "Provider" is the name of the NetworkManager connection:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-openvpn|2=<br />
#!/bin/bash<br />
<br />
case "$2" in<br />
up)<br />
if [ "$CONNECTION_ID" == "Provider" ]; then<br />
systemctl start openvpn-client@''<configuration>''<br />
fi<br />
;;<br />
down)<br />
systemctl stop openvpn-client@''<configuration>''<br />
;;<br />
esac}}<br />
<br />
See [[NetworkManager#Network services with NetworkManager dispatcher]] for more details.<br />
<br />
=== Gnome configuration ===<br />
<br />
If you would like to connect a client to an OpenVPN server through Gnome's built-in network configuration do the following. First, install {{pkg|networkmanager-openvpn}}. Then go to the Settings menu and choose Network. Click the plus sign to add a new connection and choose VPN. From there you can choose OpenVPN and manually enter the settings. You can also choose to import [[#The client config profile]], if you have already created one. Yet, be aware NetworkManager does not show error messages for options it does not import. To connect to the VPN simply turn the connection on and check the options are applied as you configured (e.g. via {{ic|journalctl -b -u NetworkManager}}).<br />
<br />
== Routing all client traffic through the server ==<br />
<br />
{{Note|There are potential pitfalls when routing all traffic through a VPN server. Refer to [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect the OpenVPN documentation on this topic] for more information.}}<br />
<br />
By default only traffic directly to and from an OpenVPN server passes through the VPN. To have all traffic, including web traffic, pass through the VPN do the following. First add the following to your server's configuration file (i.e., {{ic|/etc/openvpn/server/server.conf}}) [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect]:<br />
<br />
push "redirect-gateway def1 bypass-dhcp"<br />
push "dhcp-option DNS 8.8.8.8"<br />
<br />
Change {{ic|8.8.8.8}} to your preferred DNS IP address if configured to run on the same box as the server or else leave it at 8.8.8.8 to use google's DNS.<br />
<br />
If you have problems with non responsive DNS after connecting to server, install [[BIND]] as simple DNS forwarder and push the IP address of the OpenVPN server as DNS to clients.<br />
<br />
After setting up the configuration file, one must [[Internet_sharing#Enable_packet_forwarding|enable packet forwarding]] on the server. Additionally, the server's firewall will need to be set up to allow VPN traffic through it, which is described below for both [[ufw]] and [[iptables]].<br />
<br />
To allow clients to be able to reach other (private) subnets behind the server, you may want to use the {{ic|push "route <address pool> <subnet>"}} option:<br />
<br />
push "route 172.10.142.0 255.255.255.0"<br />
push "route 172.20.142.0 255.255.255.0"<br />
<br />
=== Firewall configuration ===<br />
<br />
==== ufw ====<br />
<br />
In order to configure your ufw settings for VPN traffic first add the following to {{ic|/etc/default/ufw}}:<br />
<br />
{{hc|/etc/default/ufw|2=<br />
DEFAULT_FORWARD_POLICY="ACCEPT"<br />
}}<br />
<br />
Now change {{ic|/etc/ufw/before.rules}}, and add the following code after the header and before the "*filter" line. Do not forget to change the IP/subnet mask to match the one in {{ic|/etc/openvpn/server/server.conf}}. The adapter ID in the example is generically called {{ic|eth0}} so edit it for your system accordingly.<br />
<br />
{{hc|/etc/ufw/before.rules|2=<br />
# NAT (Network Address Translation) table rules<br />
*nat<br />
:POSTROUTING ACCEPT [0:0]<br />
<br />
# Allow traffic from clients to eth0<br />
-A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE<br />
<br />
# do not delete the "COMMIT" line or the NAT table rules above will not be processed<br />
COMMIT<br />
}}<br />
<br />
Open OpenVPN port 1194:<br />
<br />
# ufw allow 1194<br />
<br />
Lastly, reload UFW:<br />
<br />
# ufw reload<br />
<br />
==== iptables ====<br />
<br />
In order to allow VPN traffic through your iptables firewall of your server, first create an iptables rule for NAT forwarding [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect] on the server, assuming the interface you want to forward to is named {{ic|eth0}}:<br />
<br />
iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE<br />
<br />
If you have difficulty pinging the server through the VPN, you may need to add explicit rules to open up TUN/TAP interfaces to all traffic. If that is the case, do the following [https://community.openvpn.net/openvpn/wiki/255-qconnection-initiated-with-xxxxq-but-i-cannot-ping-the-server-through-the-vpn]:<br />
<br />
{{Warning|There are security implications for the following rules if you do not trust all clients which connect to the server. Refer to the [https://community.openvpn.net/openvpn/wiki/255-qconnection-initiated-with-xxxxq-but-i-cannot-ping-the-server-through-the-vpn OpenVPN documentation on this topic] for more details.}}<br />
<br />
iptables -A INPUT -i tun+ -j ACCEPT<br />
iptables -A FORWARD -i tun+ -j ACCEPT<br />
iptables -A INPUT -i tap+ -j ACCEPT<br />
iptables -A FORWARD -i tap+ -j ACCEPT<br />
<br />
Additionally be sure to accept connections from the OpenVPN port (default 1194) and through the physical interface.<br />
<br />
When you are satisfied make the changes permanent as shown in [[iptables#Configuration and usage]].<br />
<br />
If you have multiple {{ic|tun}} or {{ic|tap}} interfaces, or more than one VPN configuration, you can "pin" the name of your interface by specifying it in the OpenVPN config file, e.g. {{ic|tun22}} instead of {{ic|tun}}. This is advantageous if you have different firewall rules for different interfaces or OpenVPN configurations.<br />
<br />
=== Prevent leaks if VPN goes down ===<br />
<br />
The idea is simple: prevent all traffic through our default interface (enp3s0 for example) and only allow tun0.<br />
If the OpenVPN connection drops, your computer will lose its internet access and therefore, avoid your programs to continue connecting through an insecure network adapter.<br />
<br />
Be sure to set up a script to restart OpenVPN if it goes down if you do not want to manually restart it.<br />
<br />
==== ufw ====<br />
<br />
# Default policies<br />
ufw default deny incoming<br />
ufw default deny outgoing<br />
<br />
# Openvpn interface (adjust interface accordingly to your configuration)<br />
ufw allow in on tun0<br />
ufw allow out on tun0<br />
<br />
# Local Network (adjust ip accordingly to your configuration)<br />
ufw allow in on enp3s0 from 192.168.1.0/24<br />
ufw allow out on enp3s0 to 192.168.1.0/24<br />
<br />
# Openvpn (adjust port accordingly to your configuration)<br />
ufw allow in on enp3s0 from any port 1194<br />
ufw allow out on enp3s0 to any port 1194<br />
<br />
<br />
{{Warning| DNS '''will not''' work '''unless''' you run your own DNS server like [[BIND]]<br />
Otherwise, you will need to allow dns leak. '''Be sure to trust your DNS server!'''<br />
# DNS<br />
ufw allow in from any to any port 53<br />
ufw allow out from any to any port 53<br />
}}<br />
<br />
==== vpnfailsafe ====<br />
<br />
Alternatively, the [https://github.com/wknapik/vpnfailsafe vpnfailsafe] ({{AUR|vpnfailsafe-git}}) script can be used by the client to prevent DNS leaks and ensure that all traffic to the internet goes over the VPN. If the VPN tunnel goes down, internet access will be cut off, except for connections to the VPN server(s). The script contains the functionality of [[#Update resolv-conf script|update-resolv-conf]], so the two do not need to be combined.<br />
<br />
== L3 IPv4 routing==<br />
<br />
This section describes how to connect client/server LANs to each other using L3 IPv4 routing.<br />
<br />
=== Prerequisites for routing a LAN ===<br />
<br />
For a host to be able to forward IPv4 packets between the LAN and VPN, it must be able to forward the packets between its NIC and its tun/tap device. See [[Internet sharing#Enable packet forwarding]] for configuration details.<br />
<br />
==== Routing tables ====<br />
<br />
{{Accuracy|Investigate if a routing protocol like RIP, QUAGGA, BIRD, etc can be used}}<br />
<br />
By default, all IP packets on a LAN addressed to a different subnet get sent to the default gateway. If the LAN/VPN gateway is also the default gateway, there is no problem and the packets get properly forwarded. If not, the gateway has no way of knowing where to send the packets. There are a couple of solutions to this problem.<br />
<br />
* Add a static route to the default gateway routing the VPN subnet to the LAN/VPN gateway's IP address.<br />
* Add a static route on each host on the LAN that needs to send IP packets back to the VPN.<br />
* Use [[iptables]]' NAT feature on the LAN/VPN gateway to masquerade the incoming VPN IP packets.<br />
<br />
=== Connect the server LAN to a client ===<br />
<br />
The server is on a LAN using the 10.66.0.0/24 subnet. To inform the client about the available subnet, add a push directive to the server configuration file:{{hc|/etc/openvpn/server/server.conf|push "route 10.66.0.0 255.255.255.0"}}<br />
<br />
{{Note|To route more LANs from the server to the client, add more push directives to the server configuration file, but keep in mind that the server side LANs will need to know how to route to the client.<br />
}}<br />
<br />
=== Connect the client LAN to a server ===<br />
<br />
Prerequisites:<br />
<br />
* Any subnets used on the client side, must be unique and not in use on the server or by any other client. In this example we will use 192.168.4.0/24 for the clients LAN.<br />
* Each client's certificate has a unique Common Name, in this case bugs.<br />
* The server may not use the duplicate-cn directive in its config file.<br />
<br />
Create a client configuration directory on the server. It will be searched for a file named the same as the client's common name, and the directives will be applied to the client when it connects.<br />
<br />
# mkdir -p /etc/openvpn/ccd<br />
<br />
Create a file in the client configuration directory called bugs, containing the {{ic|iroute 192.168.4.0 255.255.255.0}} directive. It tells the server what subnet should be routed to the client:<br />
<br />
{{hc|/etc/openvpn/ccd/bugs|iroute 192.168.4.0 255.255.255.0}}<br />
<br />
Add the client-config-dir and the {{ic|route 192.168.4.0 255.255.255.0}} directive to the server configuration file. It tells the server what subnet should be routed from the tun device to the server LAN:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
client-config-dir ccd<br />
route 192.168.4.0 255.255.255.0<br />
}}<br />
<br />
{{Note|To route more LANs from the client to the server, add more iroute and route directives to the appropriate configuration files, but keep in mind that the client side LANs will need to know how to route to the server.<br />
}}<br />
<br />
=== Connect both the client and server LANs ===<br />
<br />
Combine the two previous sections:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
push "route 10.66.0.0 255.255.255.0"<br />
.<br />
.<br />
client-config-dir ccd<br />
route 192.168.4.0 255.255.255.0<br />
}}<br />
<br />
{{hc|/etc/openvpn/ccd/bugs|iroute 192.168.4.0 255.255.255.0}}<br />
<br />
{{Note|Remember to make sure that all the LANs or the needed hosts can route to all the destinations.}}<br />
<br />
=== Connect clients and client LANs ===<br />
<br />
By default clients will not see each other. To allow IP packets to flow between clients and/or client LANs, add a client-to-client directive to the server configuration file: {{hc|/etc/openvpn/server/server.conf|client-to-client}}<br />
<br />
In order for another client or client LAN to see a specific client LAN, you will need to add a push directive for each client subnet to the server configuration file (this will make the server announce the available subnet(s) to other clients):<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
client-to-client<br />
push "route 192.168.4.0 255.255.255.0"<br />
push "route 192.168.5.0 255.255.255.0"<br />
.<br />
.<br />
}}<br />
<br />
{{Note|As always, make sure that the routing is properly configured.}}<br />
<br />
== DNS ==<br />
<br />
The DNS servers used by the system are defined in {{ic|/etc/resolv.conf}}. Traditionally, this file is the responsibility of whichever program deals with connecting the system to the network (e.g. Wicd, NetworkManager, etc.). However, OpenVPN will need to modify this file if you want to be able to resolve names on the remote side. To achieve this in a sensible way, install {{pkg|openresolv}}, which makes it possible for more than one program to modify {{ic|resolv.conf}} without stepping on each-other's toes.<br />
<br />
Before continuing, test openresolv by restarting your network connection and ensuring that {{ic|resolv.conf}} states that it was generated by ''resolvconf'', and that your DNS resolution still works as before. You should not need to configure openresolv; it should be automatically detected and used by your network system.<br />
<br />
For Linux, OpenVPN can send DNS host information, but expects an external process to act on it. This can be done with the {{ic|client.up}} and {{ic|client.down}} scripts packaged in {{ic|/usr/share/openvpn/contrib/pull-resolv-conf/}}. See their comments on how to install them to {{ic|/etc/openvpn/client/}}. The following is an excerpt of a resulting client configuration using the scripts in conjunction with ''resolvconf'' and options to [[#Run as unprivileged user]]:<br />
<br />
{{hc|/etc/openvpn/client/''clienttunnel''.conf|<br />
user nobody<br />
group nobody<br />
# Optional, choose a suitable path to chroot into for your system<br />
chroot /srv<br />
script-security 2<br />
up /etc/openvpn/client/client.up <br />
plugin /usr/lib/openvpn/plugins/openvpn-plugin-down-root.so "/etc/openvpn/client/client.down tun0"<br />
}}<br />
<br />
=== Update resolv-conf script ===<br />
<br />
The [https://github.com/masterkorp/openvpn-update-resolv-conf openvpn-update-resolv-conf] script is available as an alternative to packaged scripts. It needs to be saved for example at {{ic|/etc/openvpn/update-resolv-conf}} and made executable with [[chmod]].<br />
<br />
Once the script is installed add lines like the following into your OpenVPN client configuration file:<br />
<br />
script-security 2<br />
up /etc/openvpn/update-resolv-conf<br />
down /etc/openvpn/update-resolv-conf<br />
<br />
{{Note|If manually placing the script on the filesystem, be sure to have {{pkg|openresolv}} installed.}}<br />
<br />
Now, when you launch your OpenVPN connection, you should find that your {{ic|resolv.conf}} file is updated accordingly, and also returns to normal when you close the connection.<br />
<br />
{{Note|When using {{ic|openresolv}} with the ''-p'' or ''-x'' options in a script (as both the included {{ic|client.up}} and {{ic|update-resolv-conf}} scripts currently do), a DNS resolver like {{Pkg|dnsmasq}} or {{Pkg|unbound}} is required for {{ic|openresolv}} to correctly update {{ic|/etc/resolv.conf}}. In contrast, when using the default DNS resolution from {{ic|libc}} the ''-p'' and ''-x'' options must be removed in order for {{ic|/etc/resolv.conf}} to be correctly updated by {{ic|openresolv}}.<br />
For example, if the script contains a command like {{ic|resolvconf -p -a }} and the default DNS resolver from {{ic|libc}} is being used, change the command in the script to be {{ic|resolvconf -a }}.}}<br />
<br />
=== Update systemd-resolved script ===<br />
<br />
Since systemd-229, [[systemd-networkd]]'s {{ic|systemd-resolved.service}} has exposed an API through DBus allowing management of DNS configuration on a per-link basis. Tools such as {{pkg|openresolv}} may not work reliably when {{ic|/etc/resolv.conf}} is managed by {{ic|systemd-resolved}}, and will not work at all if you are using {{ic|resolve}} instead of {{ic|dns}} in your {{ic|/etc/nsswitch.conf}} file. The [https://github.com/jonathanio/update-systemd-resolved update-systemd-resolved] script is another alternative and links OpenVPN with {{ic|systemd-resolved}} via DBus to update the DNS records.<br />
<br />
If you copy the script into {{ic|/etc/openvpn}} and mark as executable with [[chmod]], or install it via the AUR package ({{AUR|openvpn-update-systemd-resolved}}), you can add lines like the following into your OpenVPN client configuration file:<br />
<br />
script-security 2<br />
setenv PATH /usr/bin<br />
up /etc/openvpn/scripts/update-systemd-resolved<br />
down /etc/openvpn/scripts/update-systemd-resolved<br />
down-pre<br />
<br />
== L2 Ethernet bridging ==<br />
<br />
{{Expansion|Please add a well thought out section on L2 bridging.}}<br />
<br />
For now see: [[OpenVPN Bridge]]<br />
<br />
== Config generators ==<br />
<br />
{{Warning|Users are highly recommended to pass through the manual configuration described above to gain knowledge about options and usage before using any additional automation scripts.}}<br />
<br />
=== ovpngen ===<br />
<br />
The {{AUR|ovpngen}} package provides a simple shell script that creates OpenVPN compatible tunnel profiles in the unified file format suitable for the iOS version of OpenVPN Connect as well as for the Android app.<br />
<br />
Simply invoke the script with 5 tokens:<br />
<br />
# Server Fully Qualified Domain Name of the OpenVPN server (or IP address).<br />
# Full path to the CA cert.<br />
# Full path to the client cert.<br />
# Full path to the client private key.<br />
# Full path to the server TLS shared secret key.<br />
# Optionally a port number.<br />
# Optionally a protocol (udp or tcp).<br />
<br />
Example:<br />
<br />
# ovpngen example.org /etc/openvpn/server/ca.crt /etc/easy-rsa/pki/signed/client1.crt /etc/easy-rsa/pki/private/client1.key /etc/openvpn/server/ta.key > iphone.ovpn<br />
<br />
The resulting {{ic|iphone.ovpn}} can be edited if desired as the script does insert some commented lines.<br />
<br />
The client expects this file to be located in {{ic|/etc/openvpn/client/iphone.conf}}. Note the change in file extension from 'ovpn' to 'conf' in this case.<br />
<br />
{{Tip|If the server.conf contains a specified cipher and/or auth line, it is highly recommended that users manually edit the generated .ovpn file adding matching lines for cipher and auth. Failure to do so may results in connection errors!}}<br />
<br />
=== openvpn-unroot ===<br />
<br />
The steps necessary for OpenVPN to [[#Run as unprivileged user]], can be performed automatically using [https://github.com/wknapik/openvpn-unroot openvpn-unroot] ({{AUR|openvpn-unroot-git}}).<br />
<br />
It automates the actions required for the [https://community.openvpn.net/openvpn/wiki/UnprivilegedUser OpenVPN howto] by adapting it to systemd, and also working around the bug for persistent tun devices mentioned in the note.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Client daemon not reconnecting after suspend ===<br />
<br />
{{AUR|openvpn-reconnect}}, available on the AUR, solves this problem by sending a SIGHUP to openvpn after waking up from suspend.<br />
<br />
Alternatively, you can kill and restart OpenVPN after suspend by creating the folowing systemd service:<br />
<br />
{{hc|1=/etc/systemd/system/openvpn-reconnect.service|2=<br />
[Unit]<br />
Description=Restart OpenVPN after suspend<br />
<br />
[Service]<br />
ExecStart=/usr/bin/pkill --signal SIGHUP --exact openvpn<br />
<br />
[Install]<br />
WantedBy=sleep.target<br />
}}<br />
<br />
[[Enable]] this service for it to take effect.<br />
<br />
=== Connection drops out after some time of inactivity ===<br />
<br />
If the VPN-Connection drops some seconds after it stopped transmitting data and, even though it states it is connected, no data can be transmitted through the tunnel, try adding a {{ic|keepalive}}directive to the server's configuration:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
.<br />
keepalive 10 120<br />
.<br />
.<br />
}}<br />
<br />
In this case the server will send ping-like messages to all of its clients every 10 seconds, thus keeping the tunnel up.<br />
If the server does not receive a response within 120 seconds from a specific client, it will assume this client is down.<br />
<br />
A small ping-interval can increase the stability of the tunnel, but will also cause slightly higher traffic. Depending on your connection, also try lower intervals than 10 seconds.<br />
<br />
=== PID files not present ===<br />
<br />
The default systemd service file for openvpn-client does not have the --writepid flag enabled, despite creating /var/run/openvpn-client. If this breaks a config (such as an i3bar VPN indicator), simply change {{ic|openvpn-client@.service}} using a [[drop-in snippet]]:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/sbin/openvpn --suppress-timestamps --nobind --config %i.conf --writepid /var/run/openvpn-client/%i.pid<br />
<br />
=== Route configuration fails with systemd-networkd ===<br />
<br />
When using [[systemd-networkd]] to manage network connections and attempting to tunnel all outgoing traffic through the VPN, OpenVPN may fail to add routes. This is a result of systemd-networkd attempting to manage the tun interface before OpenVPN finishes configuring the routes. When this happens, the following message will appear in the OpenVPN log.<br />
<br />
openvpn[458]: RTNETLINK answers: Network is unreachable<br />
openvpn[458]: ERROR: Linux route add command failed: external program exited with error status: 2<br />
<br />
With systemd-233 (currently in [[testing]]), systemd-networkd can be configured to ignore the tun connections and allow OpenVPN to manage them. To do this, create the following file:<br />
<br />
{{hc|1=/etc/systemd/network/90-tun-ignore.network|2=<br />
[Match]<br />
Name=tun*<br />
<br />
[Link]<br />
Unmanaged=true<br />
}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to apply the changes. To verify that the changes took effect, start the previously problematic OpenVPN connection and run {{ic|networkctl}}. The output should have a line similar to the following:<br />
<br />
7 tun0 none routable unmanaged<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:OpenVPN]]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=OpenVPN&diff=512374OpenVPN2018-03-01T13:23:13Z<p>Ketsui: /* Update resolv-conf script */ Typos</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[de:OpenVPN]]<br />
[[ja:OpenVPN]]<br />
[[ru:OpenVPN]]<br />
[[zh-hans:OpenVPN]]<br />
{{Related articles start}}<br />
{{Related|OpenVPN (client) in Linux containers}}<br />
{{Related|OpenVPN (server) in Linux containers}}<br />
{{Related|Easy-RSA}}<br />
{{Related articles end}}<br />
<br />
This article describes a basic installation and configuration of [http://openvpn.net OpenVPN], suitable for private and small business use. For more detailed information, please see the [https://community.openvpn.net/openvpn/wiki/Openvpn24ManPage OpenVPN 2.4 man page] and the [http://openvpn.net/index.php/open-source/documentation OpenVPN documentation]. OpenVPN is a robust and highly flexible [[Wikipedia:VPN|VPN]] daemon. It supports [[Wikipedia:SSL/TLS|SSL/TLS]] security, [[Wikipedia:Bridging_(networking)|Ethernet bridging]], [[Wikipedia:Transmission_Control_Protocol|TCP]] or [[Wikipedia:User_Datagram_Protocol|UDP]] [[Wikipedia:Tunneling_protocol|tunnel transport]] through [[Wikipedia:Proxy_server|proxies]] or [[Wikipedia:Network address translation|NAT]]. Additionally it has support for dynamic IP addresses and [[Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]], scalability to hundreds or thousands of users, and portability to most major OS platforms.<br />
<br />
OpenVPN is tightly bound to the [http://www.openssl.org OpenSSL] library, and derives much of its crypto capabilities from it. It supports conventional encryption using a [[Wikipedia:Pre-shared_key|pre-shared secret key]] (Static Key mode) or [[Wikipedia:Public_key|public key security]] ([[Wikipedia:SSL/TLS|SSL/TLS]] mode) using client & server certificates. Additionally it supports unencrypted TCP/UDP tunnels.<br />
<br />
OpenVPN is designed to work with the [[Wikipedia:TUN/TAP|TUN/TAP]] virtual networking interface that exists on most platforms. Overall, it aims to offer many of the key features of [[Wikipedia:Ipsec|IPSec]] but with a relatively lightweight footprint. OpenVPN was written by James Yonan and is published under the [[Wikipedia:GNU General Public License|GNU General Public License (GPL)]].<br />
<br />
== Install OpenVPN ==<br />
<br />
[[Install]] the {{Pkg|openvpn}} package, which provides both server and client mode.<br />
<br />
== Kernel configuration ==<br />
<br />
OpenVPN requires TUN/TAP support, which is already configured in the default kernel. Users of custom kernel should make sure to enable the {{ic|tun}} module:<br />
<br />
{{hc|Kernel config file|<br />
Device Drivers<br />
--> Network device support<br />
[M] Universal TUN/TAP device driver support<br />
}}<br />
<br />
Read [[Kernel modules]] for more information.<br />
<br />
== Connect to a VPN provided by a third party ==<br />
<br />
To connect to a VPN service provided by a third party, most of the following can most likely be ignored, especially regarding server setup. Begin with [[#The client config profile]] and skip ahead to [[#Starting OpenVPN]] after that. One should use the provider certificates and instructions, see [[:Category:VPN providers]] for examples that can be adapted to other providers. [[OpenVPN (client) in Linux containers]] also has general applicable instructions, while it goes a step further by isolating an OpenVPN client process into a container.<br />
<br />
{{Note|Most free VPN providers will (often only) offer [[PPTP server|PPTP]], which is drastically easier to setup and configure, but [http://poptop.sourceforge.net/dox/protocol-security.phtml not secure].}}<br />
<br />
== Create a Public Key Infrastructure (PKI) from scratch ==<br />
<br />
When setting up an OpenVPN server, users need to create a [[Wikipedia:Public key infrastructure|Public Key Infrastructure (PKI)]] which is detailed in the [[Easy-RSA]] article. Once the needed certificates, private keys, and associated files are created via following the steps in the separate article, one should have 5 files in {{ic|/etc/openvpn/server}} at this point:<br />
<br />
ca.crt<br />
dh.pem<br />
servername.crt<br />
servername.key<br />
ta.key<br />
<br />
Alternatively, as of OpenVPN 2.4, one can use Easy-RSA to generate certificates and keys using elliptic curves. See the OpenVPN documentation for details.<br />
<br />
== A basic L3 IP routing configuration ==<br />
<br />
{{Note|Unless otherwise explicitly stated, the rest of this article assumes a basic L3 IP routing configuration.}}<br />
<br />
OpenVPN is an extremely versatile piece of software and many configurations are possible, in fact machines can be both servers and clients.<br />
<br />
With the release of v2.4, server configurations are stored in {{ic|/etc/openvpn/server}} and client configurations are stored in {{ic|/etc/openvpn/client}} and each mode has its own respective systemd unit, namely, {{ic|openvpn-client@.service}} and {{ic|openvpn-server@.service}}.<br />
<br />
=== Example configuration ===<br />
<br />
The OpenVPN package comes with a collection of example configuration files for different purposes. The sample server and client configuration files make an ideal starting point for a basic OpenVPN setup with the following features:<br />
<br />
* Uses [[Wikipedia:Public key infrastructure|Public Key Infrastructure (PKI)]] for authentication.<br />
* Creates a VPN using a virtual TUN network interface (OSI L3 IP routing).<br />
* Listens for client connections on UDP port 1194 (OpenVPN's official IANA port number[https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=openvpn]).<br />
* Distributes virtual addresses to connecting clients from the 10.8.0.0/24 subnet.<br />
<br />
For more advanced configurations, please see the {{man|8|openvpn}} man page and the [http://openvpn.net/index.php/open-source/documentation OpenVPN documentation].<br />
<br />
=== The server configuration file ===<br />
<br />
{{Note|Note that if the server is behind a firewall or a NAT translating router, the OpenVPN port must be forwarded on to the server.}}<br />
<br />
Copy the example server configuration file {{ic|/usr/share/openvpn/examples/server.conf}} to {{ic|/etc/openvpn/server/server.conf}}.<br />
<br />
Edit the file making a minimum of the following changes:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
ca ca.crt<br />
cert servername.crt<br />
key servername.key # This file should be kept secret<br />
dh dh.pem<br />
.<br />
tls-crypt ta.key # Replaces ''tls-auth ta.key 0''<br />
.<br />
user nobody<br />
group nobody<br />
}}<br />
<br />
==== Hardening the server ====<br />
<br />
If security is a priority, additional configuration is recommended including: limiting the server to use a strong cipher/auth method and (optionally) limiting the set of enabled TLS ciphers to the newer ciphers.<br />
<br />
Add the following to {{ic|/etc/openvpn/server/server.conf}}:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
cipher AES-256-CBC<br />
auth SHA512<br />
tls-version-min 1.2<br />
tls-cipher TLS-DHE-RSA-WITH-AES-256-GCM-SHA384:TLS-DHE-RSA-WITH-AES-128-GCM-SHA256:TLS-DHE-RSA-WITH-AES-256-CBC-SHA:TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA:TLS-DHE-RSA-WITH-AES-128-CBC-SHA:TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA<br />
.<br />
}}<br />
<br />
{{Note|<br />
*The .ovpn client profile '''must''' contain a matching cipher and auth line to work properly (at least with the iOS and Android client).<br />
*Using {{ic|tls-cipher}} incorrectly may cause difficulty with debugging connections and may not be necessary. See [https://community.openvpn.net/openvpn/wiki/Hardening#Useof--tls-cipher OpenVPN’s community wiki] for more information.}}<br />
<br />
==== Enabling compression ====<br />
<br />
Since OpenVPN v2.4 it is possible to use LZ4 compression over lzo. LZ4 generally offering the best performance with least CPU usage. For backwards compatibility with OpenVPN versions before v2.4, use lzo {{ic|comp-lzo}}. Do '''not''' enable both compression options at the same time.<br />
<br />
To do so, configure {{ic|/etc/openvpn/server/server.conf}} as such:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
compress lz4-v2<br />
push "compress lz4-v2"<br />
.<br />
}}<br />
<br />
On the client set {{ic|--compress lz4}} [https://community.openvpn.net/openvpn/wiki/DeprecatedOptions], although this may be deprecated in the near future.<br />
<br />
==== Deviating from the standard port and/or protocol ====<br />
<br />
Some public/private network admins may not allow OpenVPN connections on its default port and/or protocol. One strategy to circumvent this is to mimic https/SSL traffic which is very likely unobstructed.<br />
<br />
To do so, configure {{ic|/etc/openvpn/server/server.conf}} as such:<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
port 443<br />
proto tcp<br />
.<br />
}}<br />
<br />
{{Note|The .ovpn client profile '''must''' contain a matching port and proto line to work properly!}}<br />
<br />
===== TCP vs UDP =====<br />
<br />
There are subtle differences between TCP and UDP.<br />
<br />
TCP<br />
<br />
* So-called "stateful protocol."<br />
* High reliability due to error correction (i.e. waits for packet acknowledgment).<br />
* Potentially slower than UDP.<br />
<br />
UDP<br />
<br />
* So-called "stateless protocol."<br />
* Less reliable than TCP as no error correction is in use.<br />
* Potentially faster than TCP.<br />
<br />
{{Note|It is generally a bad idea to use TCP for VPN unless your connection to the server is very stable. High reliability sounds great in theory but any disruption (packet drop, lag spikes, etc...) to the connection will potentially snowball into a [http://sites.inka.de/bigred/devel/tcp-tcp.html TCP Meltdown][http://adsabs.harvard.edu/abs/2005SPIE.6011..138H].}}<br />
<br />
=== The client config profile ===<br />
<br />
Copy the example client configuration file {{ic|/usr/share/openvpn/examples/client.conf}} to {{ic|/etc/openvpn/client/}}.<br />
<br />
Edit the following:<br />
<br />
* The {{ic|remote}} directive to reflect either the server's [[Wikipedia:Fully qualified domain name|Fully Qualified Domain Name]], hostname (as known to the client), or its IP address.<br />
* Uncomment the {{ic|user}} and {{ic|group}} directives to drop privileges.<br />
* The {{ic|ca}}, {{ic|cert}}, and {{ic|key}} parameters to reflect the path and names of the keys and certificates.<br />
* Enable the TLS HMAC handshake protection ({{ic|--tls-crypt}} or {{ic|--tls-auth}}).<br />
<br />
{{hc|/etc/openvpn/client/client.conf|<br />
client<br />
remote elmer.acmecorp.org 1194<br />
.<br />
user nobody<br />
group nobody<br />
ca ca.crt<br />
cert client.crt<br />
key client.key<br />
.<br />
tls-crypt ta.key # Replaces ''tls-auth ta.key 1''<br />
}}<br />
<br />
==== Run as unprivileged user ====<br />
<br />
Using the options {{ic|user nobody}} and {{ic|group nobody}} in the configuration file makes ''OpenVPN'' drop its {{ic|root}} privileges after establishing the connection. The downside is that upon VPN disconnect the daemon is unable to delete its set network routes again. If one wants to limit transmitting traffic without the VPN connection, then lingering routes may be considered beneficial. It can also happen, however, that the OpenVPN server pushes updates to routes at runtime of the tunnel. A client with dropped privileges will be unable to perform the update and exit with an error.<br />
<br />
As it could seem to require manual action to manage the routes, the options {{ic|user nobody}} and {{ic|group nobody}} might seem undesirable. Depending on setup, however, there are different ways to handle these situations: <br />
<br />
* For errors of the unit, a simple way is to [[edit]] it and add a {{ic|1=Restart=on-failure}} to the {{ic|[Service]}} section. Though, this alone will not delete any obsoleted routes, so it may happen that the restarted tunnel is not routed properly. <br />
* The package contains the {{ic|/usr/lib/openvpn/plugins/openvpn-plugin-down-root.so}}, which can be used to let ''openvpn'' fork a process with root privileges with the only task to execute a custom script when receiving a down signal from the main process, which is handling the tunnel with dropped privileges (see also its [https://community.openvpn.net/openvpn/browser/plugin/down-root/README?rev=d02a86d37bed69ee3fb63d08913623a86c88da15 README]).<br />
<br />
The OpenVPN HowTo's linked below go further by creating a dedicated non-privileged user/group, instead of the already existing {{ic|nobody}}. The advantage is that this avoids potential risks when sharing a user among daemons:<br />
* The [https://openvpn.net/index.php/open-source/documentation/howto.html#security OpenVPN HowTo] explains another way how to create an unprivileged user mode and wrapper script to have the routes restored automatically.<br />
* It is possible to let OpenVPN start as a non-privileged user in the first place, without ever running as root, see [https://community.openvpn.net/openvpn/wiki/UnprivilegedUser this OpenVPN wiki] (howto). The howto assumes the presence of System V init, rather than [[Systemd]] and does not cover the handling of {{ic|--up}}/{{ic|--down}} scripts - those should be handled the same way as the ''ip'' command, with additional attention to access rights.<br />
<br />
{{Note|Due to a [https://community.openvpn.net/openvpn/ticket/812 bug] in OpenVPN 2.4.0, the {{ic|persist-tun}} option mentioned in the howtos should '''not''' be used, otherwise new routes/IPs pushed on reconnect will be ignored by the client.}}<br />
<br />
{{Tip|[[#openvpn-unroot]] describes a tool to automate above setup.}}<br />
<br />
=== Converting certificates to encrypted .p12 format ===<br />
<br />
Some software will only read VPN certificates that are stored in a password-encrypted .p12 file. These can be generated with the following command:<br />
{{bc|# openssl pkcs12 -export -inkey keys/bugs.key -in keys/bugs.crt -certfile keys/ca.crt -out keys/bugs.p12}}<br />
<br />
=== Testing the OpenVPN configuration ===<br />
<br />
Run {{ic|# openvpn /etc/openvpn/server/server.conf}} on the server, and {{ic|# openvpn /etc/openvpn/client/client.conf}} on the client. Example output should be similar to the following:<br />
<br />
{{hc|# openvpn /etc/openvpn/server/server.conf|2=<br />
Wed Dec 28 14:41:26 2011 OpenVPN 2.2.1 x86_64-unknown-linux-gnu [SSL] [LZO2] [EPOLL] [eurephia] built on Aug 13 2011<br />
Wed Dec 28 14:41:26 2011 NOTE: OpenVPN 2.1 requires '--script-security 2' or higher to call user-defined scripts or executables<br />
Wed Dec 28 14:41:26 2011 Diffie-Hellman initialized with 2048 bit key<br />
.<br />
.<br />
Wed Dec 28 14:41:54 2011 bugs/95.126.136.73:48904 MULTI: primary virtual IP for bugs/95.126.136.73:48904: 10.8.0.6<br />
Wed Dec 28 14:41:57 2011 bugs/95.126.136.73:48904 PUSH: Received control message: 'PUSH_REQUEST'<br />
Wed Dec 28 14:41:57 2011 bugs/95.126.136.73:48904 SENT CONTROL [bugs]: 'PUSH_REPLY,route 10.8.0.1,topology net30,ping 10,ping-restart 120,ifconfig 10.8.0.6 10.8.0.5' (status=1)<br />
}}<br />
<br />
{{hc|# openvpn /etc/openvpn/client/client.conf|2=<br />
Wed Dec 28 14:41:50 2011 OpenVPN 2.2.1 i686-pc-linux-gnu [SSL] [LZO2] [EPOLL] [eurephia] built on Aug 13 2011<br />
Wed Dec 28 14:41:50 2011 NOTE: OpenVPN 2.1 requires '--script-security 2' or higher to call user-defined scripts or executables<br />
Wed Dec 28 14:41:50 2011 LZO compression initialized<br />
.<br />
.<br />
Wed Dec 28 14:41:57 2011 GID set to nobody<br />
Wed Dec 28 14:41:57 2011 UID set to nobody<br />
Wed Dec 28 14:41:57 2011 Initialization Sequence Completed<br />
}}<br />
<br />
On the server, find the IP address assigned to the tunX device:<br />
<br />
{{hc|# ip addr show|2=<br />
.<br />
.<br />
40: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 100<br />
link/none<br />
inet 10.8.0.1 peer 10.8.0.2/32 scope global tun0<br />
}}<br />
<br />
Here we see that the server end of the tunnel has been given the IP address 10.8.0.1.<br />
<br />
Do the same on the client:<br />
<br />
{{hc|# ip addr show|2=<br />
.<br />
.<br />
37: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 100<br />
link/none<br />
inet 10.8.0.6 peer 10.8.0.5/32 scope global tun0<br />
}}<br />
<br />
And the client side has been given the IP address 10.8.0.6.<br />
<br />
Now try pinging the interfaces.<br />
<br />
On the server:<br />
<br />
{{hc|# ping -c3 10.8.0.6|2=<br />
PING 10.8.0.6 (10.8.0.6) 56(84) bytes of data.<br />
64 bytes from 10.8.0.6: icmp_req=1 ttl=64 time=238 ms<br />
64 bytes from 10.8.0.6: icmp_req=2 ttl=64 time=237 ms<br />
64 bytes from 10.8.0.6: icmp_req=3 ttl=64 time=205 ms<br />
<br />
--- 10.8.0.6 ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2002ms<br />
rtt min/avg/max/mdev = 205.862/227.266/238.788/15.160 ms<br />
}}<br />
<br />
On the client:<br />
<br />
{{hc|# ping -c3 10.8.0.1|2=<br />
PING 10.8.0.1 (10.8.0.1) 56(84) bytes of data.<br />
64 bytes from 10.8.0.1: icmp_req=1 ttl=64 time=158 ms<br />
64 bytes from 10.8.0.1: icmp_req=2 ttl=64 time=158 ms<br />
64 bytes from 10.8.0.1: icmp_req=3 ttl=64 time=157 ms<br />
<br />
--- 10.8.0.1 ping statistics ---<br />
3 packets transmitted, 3 received, 0% packet loss, time 2001ms<br />
rtt min/avg/max/mdev = 157.426/158.278/158.940/0.711 ms<br />
}}<br />
<br />
{{Note|If using a firewall, make sure that IP packets on the TUN device are not blocked.}}<br />
<br />
=== Configure the MTU with Fragment and MSS ===<br />
<br />
If experiencing issues when using (remote) services over OpenVPN (e.g. web browsing, [[DNS]], [[NFS]]), it may be needed to set a MTU value manually.<br />
<br />
The following message may indicate the MTU value should be adjusted:<br />
<br />
read UDPv4 [EMSGSIZE Path-MTU=1407]: Message too long (code=90)<br />
<br />
In order to get the maximum segment size (MSS), the client needs to discover the smallest MTU along the path to the server. In order to do this ping the server and disable fragmentation, then specify the maximum packet size [https://www.sonassi.com/help/troubleshooting/setting-correct-mtu-for-openvpn]:<br />
<br />
# ping -M do -s 1500 -c 1 example.com<br />
<br />
Decrease the 1500 value by 10 each time, until the ping succeeds.<br />
<br />
{{Note|Clients that do not support the 'fragment' directive (e.g. OpenELEC, [https://forums.openvpn.net/topic13201.html#p31156 iOS app]) are not able to connect to a server that uses the {{ic|fragment}} directive. See {{ic|mtu-test}} as alternative solution.}}<br />
<br />
Update the client configuration to use the succeeded MTU value, e.g.:<br />
<br />
{{hc|/etc/openvpn/client/client.conf|<br />
remote example.com 1194<br />
...<br />
tun-mtu 1500<br />
fragment 1300<br />
mssfix # will take its default max parameter from the --fragment max option<br />
}}<br />
<br />
OpenVPN may be instructed to test the MTU every time on client connect. Be patient, since your client may not inform about the test being run and the connection may appear as nonfunctional until finished. The following will add about 3 minutes to OpenVPN start time. It is advisable to configure the fragment size unless a client will be connecting over many different networks and the bottle neck is not on the server side:<br />
<br />
{{hc|/etc/openvpn/client/client.conf|<br />
remote example.com 1194<br />
...<br />
mtu-test<br />
...<br />
}}<br />
<br />
=== IPv6 ===<br />
<br />
==== Connect to the server via IPv6 ====<br />
<br />
In order to enable Dual Stack for OpenVPN, you have to change {{ic|proto udp}} to {{ic|proto udp6}} in both server.conf and client.conf. Afterwards both IPv4 and IPv6 are enabled.<br />
<br />
==== Provide IPv6 inside the tunnel ====<br />
<br />
In order to provide IPv6 inside the tunnel, you need to have a IPv6 prefix routed to your OpenVPN server. Either set up a static route on your gateway (if you have a static block assigned), or use a DHCPv6 client to get a prefix with DHCPv6 Prefix delegation (see [[IPv6#Prefix delegation (DHCPv6-PD)|IPv6 Prefix delegation]] for details). You can also use a unique local address from the address block fc00::/7. Both methods have advantages and disadvantages:<br />
<br />
* Many ISPs only provide dynamically changing IPv6 prefixes. OpenVPN does not support prefix changes, so you need to change your server.conf every time the prefix is changed (Maybe can be automated with a script).<br />
* ULA addresses are not routed to the Internet, and setting up NAT is not as straightforward as with IPv4. So you cannot route the entire traffic over the tunnel. If you only want to connect two sites via IPv6, without the need to connect to the Internet over the tunnel, the ULA addresses may be easier to use.<br />
<br />
After you have received a prefix (a /64 is recommended), append the following to the server.conf:<br />
<br />
server-ipv6 2001:db8:0:123::/64<br />
<br />
This is the IPv6 equivalent to the default 10.8.0.0/24 network of OpenVPN and needs to be taken from the DHCPv6 client. Or use for example fd00:1234::/64.<br />
<br />
If you want to push a route to your home network (192.168.1.0/24 equivalent), also append:<br />
<br />
push "route-ipv6 2001:db8:0:abc::/64"<br />
<br />
OpenVPN does not yet include DHCPv6, so there is no method to e.g. push DNS server over IPv6. This needs to be done with IPv4. The [https://community.openvpn.net/openvpn/wiki/IPv6 OpenVPN Wiki] provides some other configuration options.<br />
<br />
== Starting OpenVPN ==<br />
<br />
=== Manual startup ===<br />
<br />
To troubleshoot a VPN connection, start the client's daemon manually with {{ic|openvpn /etc/openvpn/client/client.conf}} as root. The server can be started the same way using its own configuration file (e.g., {{ic|openvpn /etc/openvpn/server/server.conf}}).<br />
<br />
=== systemd service configuration ===<br />
<br />
To start the OpenVPN server automatically at system boot, [[enable]] {{ic|openvpn-server@''<configuration>''.service}} on the applicable machine. For a client, [[enable]] {{ic|openvpn-client@''<configuration>''.service}} instead. (Leave {{ic|.conf}} out of the {{ic|<configuration>}} string.)<br />
<br />
For example, if the client configuration file is {{ic|/etc/openvpn/client/''client''.conf}}, the service name is {{ic|openvpn-client@''client''.service}}. Or, if the server configuration file is {{ic|/etc/openvpn/server/''server''.conf}}, the service name is {{ic|openvpn-server@''server''.service}}.<br />
<br />
=== Letting NetworkManager start a connection ===<br />
<br />
On a client you might not always need to run a VPN tunnel and/or only want to establish it for a specific NetworkManager connection. This can be done by adding a script to {{ic|/etc/NetworkManager/dispatcher.d/}}. In the following example "Provider" is the name of the NetworkManager connection:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-openvpn|2=<br />
#!/bin/bash<br />
<br />
case "$2" in<br />
up)<br />
if [ "$CONNECTION_ID" == "Provider" ]; then<br />
systemctl start openvpn-client@''<configuration>''<br />
fi<br />
;;<br />
down)<br />
systemctl stop openvpn-client@''<configuration>''<br />
;;<br />
esac}}<br />
<br />
See [[NetworkManager#Network services with NetworkManager dispatcher]] for more details.<br />
<br />
=== Gnome configuration ===<br />
<br />
If you would like to connect a client to an OpenVPN server through Gnome's built-in network configuration do the following. First, install {{pkg|networkmanager-openvpn}}. Then go to the Settings menu and choose Network. Click the plus sign to add a new connection and choose VPN. From there you can choose OpenVPN and manually enter the settings. You can also choose to import [[#The client config profile]], if you have already created one. Yet, be aware NetworkManager does not show error messages for options it does not import. To connect to the VPN simply turn the connection on and check the options are applied as you configured (e.g. via {{ic|journalctl -b -u NetworkManager}}).<br />
<br />
== Routing all client traffic through the server ==<br />
<br />
{{Note|There are potential pitfalls when routing all traffic through a VPN server. Refer to [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect the OpenVPN documentation on this topic] for more information.}}<br />
<br />
By default only traffic directly to and from an OpenVPN server passes through the VPN. To have all traffic, including web traffic, pass through the VPN do the following. First add the following to your server's configuration file (i.e., {{ic|/etc/openvpn/server/server.conf}}) [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect]:<br />
<br />
push "redirect-gateway def1 bypass-dhcp"<br />
push "dhcp-option DNS 8.8.8.8"<br />
<br />
Change {{ic|8.8.8.8}} to your preferred DNS IP address if configured to run on the same box as the server or else leave it at 8.8.8.8 to use google's DNS.<br />
<br />
If you have problems with non responsive DNS after connecting to server, install [[BIND]] as simple DNS forwarder and push the IP address of the OpenVPN server as DNS to clients.<br />
<br />
After setting up the configuration file, one must [[Internet_sharing#Enable_packet_forwarding|enable packet forwarding]] on the server. Additionally, the server's firewall will need to be set up to allow VPN traffic through it, which is described below for both [[ufw]] and [[iptables]].<br />
<br />
To allow clients to be able to reach other (private) subnets behind the server, you may want to use the {{ic|push "route <address pool> <subnet>"}} option:<br />
<br />
push "route 172.10.142.0 255.255.255.0"<br />
push "route 172.20.142.0 255.255.255.0"<br />
<br />
=== Firewall configuration ===<br />
<br />
==== ufw ====<br />
<br />
In order to configure your ufw settings for VPN traffic first add the following to {{ic|/etc/default/ufw}}:<br />
<br />
{{hc|/etc/default/ufw|2=<br />
DEFAULT_FORWARD_POLICY="ACCEPT"<br />
}}<br />
<br />
Now change {{ic|/etc/ufw/before.rules}}, and add the following code after the header and before the "*filter" line. Do not forget to change the IP/subnet mask to match the one in {{ic|/etc/openvpn/server/server.conf}}. The adapter ID in the example is generically called {{ic|eth0}} so edit it for your system accordingly.<br />
<br />
{{hc|/etc/ufw/before.rules|2=<br />
# NAT (Network Address Translation) table rules<br />
*nat<br />
:POSTROUTING ACCEPT [0:0]<br />
<br />
# Allow traffic from clients to eth0<br />
-A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE<br />
<br />
# do not delete the "COMMIT" line or the NAT table rules above will not be processed<br />
COMMIT<br />
}}<br />
<br />
Open OpenVPN port 1194:<br />
<br />
# ufw allow 1194<br />
<br />
Lastly, reload UFW:<br />
<br />
# ufw reload<br />
<br />
==== iptables ====<br />
<br />
In order to allow VPN traffic through your iptables firewall of your server, first create an iptables rule for NAT forwarding [http://openvpn.net/index.php/open-source/documentation/howto.html#redirect] on the server, assuming the interface you want to forward to is named {{ic|eth0}}:<br />
<br />
iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE<br />
<br />
If you have difficulty pinging the server through the VPN, you may need to add explicit rules to open up TUN/TAP interfaces to all traffic. If that is the case, do the following [https://community.openvpn.net/openvpn/wiki/255-qconnection-initiated-with-xxxxq-but-i-cannot-ping-the-server-through-the-vpn]:<br />
<br />
{{Warning|There are security implications for the following rules if you do not trust all clients which connect to the server. Refer to the [https://community.openvpn.net/openvpn/wiki/255-qconnection-initiated-with-xxxxq-but-i-cannot-ping-the-server-through-the-vpn OpenVPN documentation on this topic] for more details.}}<br />
<br />
iptables -A INPUT -i tun+ -j ACCEPT<br />
iptables -A FORWARD -i tun+ -j ACCEPT<br />
iptables -A INPUT -i tap+ -j ACCEPT<br />
iptables -A FORWARD -i tap+ -j ACCEPT<br />
<br />
Additionally be sure to accept connections from the OpenVPN port (default 1194) and through the physical interface.<br />
<br />
When you are satisfied make the changes permanent as shown in [[iptables#Configuration and usage]].<br />
<br />
If you have multiple {{ic|tun}} or {{ic|tap}} interfaces, or more than one VPN configuration, you can "pin" the name of your interface by specifying it in the OpenVPN config file, e.g. {{ic|tun22}} instead of {{ic|tun}}. This is advantageous if you have different firewall rules for different interfaces or OpenVPN configurations.<br />
<br />
=== Prevent leaks if VPN goes down ===<br />
<br />
The idea is simple: prevent all traffic through our default interface (enp3s0 for example) and only allow tun0.<br />
If the OpenVPN connection drops, your computer will lose its internet access and therefore, avoid your programs to continue connecting through an insecure network adapter.<br />
<br />
Be sure to set up a script to restart OpenVPN if it goes down if you do not want to manually restart it.<br />
<br />
==== ufw ====<br />
<br />
# Default policies<br />
ufw default deny incoming<br />
ufw default deny outgoing<br />
<br />
# Openvpn interface (adjust interface accordingly to your configuration)<br />
ufw allow in on tun0<br />
ufw allow out on tun0<br />
<br />
# Local Network (adjust ip accordingly to your configuration)<br />
ufw allow in on enp3s0 from 192.168.1.0/24<br />
ufw allow out on enp3s0 to 192.168.1.0/24<br />
<br />
# Openvpn (adjust port accordingly to your configuration)<br />
ufw allow in on enp3s0 from any port 1194<br />
ufw allow out on enp3s0 to any port 1194<br />
<br />
<br />
{{Warning| DNS '''will not''' work '''unless''' you run your own DNS server like [[BIND]]<br />
Otherwise, you will need to allow dns leak. '''Be sure to trust your DNS server!'''<br />
# DNS<br />
ufw allow in from any to any port 53<br />
ufw allow out from any to any port 53<br />
}}<br />
<br />
==== vpnfailsafe ====<br />
<br />
Alternatively, the [https://github.com/wknapik/vpnfailsafe vpnfailsafe] ({{AUR|vpnfailsafe-git}}) script can be used by the client to prevent DNS leaks and ensure that all traffic to the internet goes over the VPN. If the VPN tunnel goes down, internet access will be cut off, except for connections to the VPN server(s). The script contains the functionality of [[#Update resolv-conf script|update-resolv-conf]], so the two do not need to be combined.<br />
<br />
== L3 IPv4 routing==<br />
<br />
This section describes how to connect client/server LANs to each other using L3 IPv4 routing.<br />
<br />
=== Prerequisites for routing a LAN ===<br />
<br />
For a host to be able to forward IPv4 packets between the LAN and VPN, it must be able to forward the packets between its NIC and its tun/tap device. See [[Internet sharing#Enable packet forwarding]] for configuration details.<br />
<br />
==== Routing tables ====<br />
<br />
{{Accuracy|Investigate if a routing protocol like RIP, QUAGGA, BIRD, etc can be used}}<br />
<br />
By default, all IP packets on a LAN addressed to a different subnet get sent to the default gateway. If the LAN/VPN gateway is also the default gateway, there is no problem and the packets get properly forwarded. If not, the gateway has no way of knowing where to send the packets. There are a couple of solutions to this problem.<br />
<br />
* Add a static route to the default gateway routing the VPN subnet to the LAN/VPN gateway's IP address.<br />
* Add a static route on each host on the LAN that needs to send IP packets back to the VPN.<br />
* Use [[iptables]]' NAT feature on the LAN/VPN gateway to masquerade the incoming VPN IP packets.<br />
<br />
=== Connect the server LAN to a client ===<br />
<br />
The server is on a LAN using the 10.66.0.0/24 subnet. To inform the client about the available subnet, add a push directive to the server configuration file:{{hc|/etc/openvpn/server/server.conf|push "route 10.66.0.0 255.255.255.0"}}<br />
<br />
{{Note|To route more LANs from the server to the client, add more push directives to the server configuration file, but keep in mind that the server side LANs will need to know how to route to the client.<br />
}}<br />
<br />
=== Connect the client LAN to a server ===<br />
<br />
Prerequisites:<br />
<br />
* Any subnets used on the client side, must be unique and not in use on the server or by any other client. In this example we will use 192.168.4.0/24 for the clients LAN.<br />
* Each client's certificate has a unique Common Name, in this case bugs.<br />
* The server may not use the duplicate-cn directive in its config file.<br />
<br />
Create a client configuration directory on the server. It will be searched for a file named the same as the client's common name, and the directives will be applied to the client when it connects.<br />
<br />
# mkdir -p /etc/openvpn/ccd<br />
<br />
Create a file in the client configuration directory called bugs, containing the {{ic|iroute 192.168.4.0 255.255.255.0}} directive. It tells the server what subnet should be routed to the client:<br />
<br />
{{hc|/etc/openvpn/ccd/bugs|iroute 192.168.4.0 255.255.255.0}}<br />
<br />
Add the client-config-dir and the {{ic|route 192.168.4.0 255.255.255.0}} directive to the server configuration file. It tells the server what subnet should be routed from the tun device to the server LAN:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
client-config-dir ccd<br />
route 192.168.4.0 255.255.255.0<br />
}}<br />
<br />
{{Note|To route more LANs from the client to the server, add more iroute and route directives to the appropriate configuration files, but keep in mind that the client side LANs will need to know how to route to the server.<br />
}}<br />
<br />
=== Connect both the client and server LANs ===<br />
<br />
Combine the two previous sections:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
push "route 10.66.0.0 255.255.255.0"<br />
.<br />
.<br />
client-config-dir ccd<br />
route 192.168.4.0 255.255.255.0<br />
}}<br />
<br />
{{hc|/etc/openvpn/ccd/bugs|iroute 192.168.4.0 255.255.255.0}}<br />
<br />
{{Note|Remember to make sure that all the LANs or the needed hosts can route to all the destinations.}}<br />
<br />
=== Connect clients and client LANs ===<br />
<br />
By default clients will not see each other. To allow IP packets to flow between clients and/or client LANs, add a client-to-client directive to the server configuration file: {{hc|/etc/openvpn/server/server.conf|client-to-client}}<br />
<br />
In order for another client or client LAN to see a specific client LAN, you will need to add a push directive for each client subnet to the server configuration file (this will make the server announce the available subnet(s) to other clients):<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
client-to-client<br />
push "route 192.168.4.0 255.255.255.0"<br />
push "route 192.168.5.0 255.255.255.0"<br />
.<br />
.<br />
}}<br />
<br />
{{Note|As always, make sure that the routing is properly configured.}}<br />
<br />
== DNS ==<br />
<br />
The DNS servers used by the system are defined in {{ic|/etc/resolv.conf}}. Traditionally, this file is the responsibility of whichever program deals with connecting the system to the network (e.g. Wicd, NetworkManager, etc.). However, OpenVPN will need to modify this file if you want to be able to resolve names on the remote side. To achieve this in a sensible way, install {{pkg|openresolv}}, which makes it possible for more than one program to modify {{ic|resolv.conf}} without stepping on each-other's toes.<br />
<br />
Before continuing, test openresolv by restarting your network connection and ensuring that {{ic|resolv.conf}} states that it was generated by ''resolvconf'', and that your DNS resolution still works as before. You should not need to configure openresolv; it should be automatically detected and used by your network system.<br />
<br />
For Linux, OpenVPN can send DNS host information, but expects an external process to act on it. This can be done with the {{ic|client.up}} and {{ic|client.down}} scripts packaged in {{ic|/usr/share/openvpn/contrib/pull-resolv-conf/}}. See their comments on how to install them to {{ic|/etc/openvpn/client/}}. The following is an excerpt of a resulting client configuration using the scripts in conjunction with ''resolvconf'' and options to [[#Run as unprivileged user]]:<br />
<br />
{{hc|/etc/openvpn/client/''clienttunnel''.conf|<br />
user nobody<br />
group nobody<br />
# Optional, choose a suitable path to chroot into for your system<br />
chroot /srv<br />
script-security 2<br />
up /etc/openvpn/client/client.up <br />
plugin /usr/lib/openvpn/plugins/openvpn-plugin-down-root.so "/etc/openvpn/client/client.down tun0"<br />
}}<br />
<br />
=== Update resolv-conf script ===<br />
<br />
The [https://github.com/masterkorp/openvpn-update-resolv-conf openvpn-update-resolv-conf] script is available as an alternative to packaged scripts. It needs to be saved for example at {{ic|/etc/openvpn/update-resolv-conf}} and made executable with [[chmod]].<br />
<br />
Once the script is installed add lines like the following into your OpenVPN client configuration file:<br />
<br />
script-security 2<br />
up /etc/openvpn/update-resolv-conf<br />
down /etc/openvpn/update-resolv-conf<br />
<br />
{{Note|If manually placing the script on the filesystem, be sure to have {{pkg|openresolv}} installed.}}<br />
<br />
Now, when you launch your OpenVPN connection, you should find that your resolv.conf file is updated accordingly, and also returns to normal when you close the connection.<br />
<br />
{{Note|When using {{ic|openresolv}} with the ''-p'' or ''-x'' options in a script (as both the included {{ic|client.up}} and {{ic|update-resolv-conf}} scripts currently do), a DNS resolver like {{Pkg|dnsmasq}} or {{Pkg|unbound}} is required for {{ic|openresolv}} to correctly update {{ic|/etc/resolv.conf}}. In contrast, when using the default DNS resolution from {{ic|libc}} the ''-p'' and ''-x'' options must be removed in order for {{ic|/etc/resolv.conf}} to be correctly updated by {{ic|openresolv}}.<br />
For example, if the script contains a command like {{ic|resolvconf -p -a }} and the default DNS resolver from {{ic|libc}} is being used, change the command in the script to be {{ic|resolvconf -a }}.}}<br />
<br />
=== Update systemd-resolved script ===<br />
<br />
Since systemd-229, [[systemd-networkd]]'s {{ic|systemd-resolved.service}} has exposed an API through DBus allowing management of DNS configuration on a per-link basis. Tools such as {{pkg|openresolv}} may not work reliably when {{ic|/etc/resolv.conf}} is managed by {{ic|systemd-resolved}}, and will not work at all if you are using {{ic|resolve}} instead of {{ic|dns}} in your {{ic|/etc/nsswitch.conf}} file. The [https://github.com/jonathanio/update-systemd-resolved update-systemd-resolved] script is another alternative and links OpenVPN with {{ic|systemd-resolved}} via DBus to update the DNS records.<br />
<br />
If you copy the script into {{ic|/etc/openvpn}} and mark as executable with [[chmod]], or install it via the AUR package ({{AUR|openvpn-update-systemd-resolved}}), you can add lines like the following into your OpenVPN client configuration file:<br />
<br />
script-security 2<br />
setenv PATH /usr/bin<br />
up /etc/openvpn/scripts/update-systemd-resolved<br />
down /etc/openvpn/scripts/update-systemd-resolved<br />
down-pre<br />
<br />
== L2 Ethernet bridging ==<br />
<br />
{{Expansion|Please add a well thought out section on L2 bridging.}}<br />
<br />
For now see: [[OpenVPN Bridge]]<br />
<br />
== Config generators ==<br />
<br />
{{Warning|Users are highly recommended to pass through the manual configuration described above to gain knowledge about options and usage before using any additional automation scripts.}}<br />
<br />
=== ovpngen ===<br />
<br />
The {{AUR|ovpngen}} package provides a simple shell script that creates OpenVPN compatible tunnel profiles in the unified file format suitable for the iOS version of OpenVPN Connect as well as for the Android app.<br />
<br />
Simply invoke the script with 5 tokens:<br />
<br />
# Server Fully Qualified Domain Name of the OpenVPN server (or IP address).<br />
# Full path to the CA cert.<br />
# Full path to the client cert.<br />
# Full path to the client private key.<br />
# Full path to the server TLS shared secret key.<br />
# Optionally a port number.<br />
# Optionally a protocol (udp or tcp).<br />
<br />
Example:<br />
<br />
# ovpngen example.org /etc/openvpn/server/ca.crt /etc/easy-rsa/pki/signed/client1.crt /etc/easy-rsa/pki/private/client1.key /etc/openvpn/server/ta.key > iphone.ovpn<br />
<br />
The resulting {{ic|iphone.ovpn}} can be edited if desired as the script does insert some commented lines.<br />
<br />
The client expects this file to be located in {{ic|/etc/openvpn/client/iphone.conf}}. Note the change in file extension from 'ovpn' to 'conf' in this case.<br />
<br />
{{Tip|If the server.conf contains a specified cipher and/or auth line, it is highly recommended that users manually edit the generated .ovpn file adding matching lines for cipher and auth. Failure to do so may results in connection errors!}}<br />
<br />
=== openvpn-unroot ===<br />
<br />
The steps necessary for OpenVPN to [[#Run as unprivileged user]], can be performed automatically using [https://github.com/wknapik/openvpn-unroot openvpn-unroot] ({{AUR|openvpn-unroot-git}}).<br />
<br />
It automates the actions required for the [https://community.openvpn.net/openvpn/wiki/UnprivilegedUser OpenVPN howto] by adapting it to systemd, and also working around the bug for persistent tun devices mentioned in the note.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Client daemon not reconnecting after suspend ===<br />
<br />
{{AUR|openvpn-reconnect}}, available on the AUR, solves this problem by sending a SIGHUP to openvpn after waking up from suspend.<br />
<br />
Alternatively, you can kill and restart OpenVPN after suspend by creating the folowing systemd service:<br />
<br />
{{hc|1=/etc/systemd/system/openvpn-reconnect.service|2=<br />
[Unit]<br />
Description=Restart OpenVPN after suspend<br />
<br />
[Service]<br />
ExecStart=/usr/bin/pkill --signal SIGHUP --exact openvpn<br />
<br />
[Install]<br />
WantedBy=sleep.target<br />
}}<br />
<br />
[[Enable]] this service for it to take effect.<br />
<br />
=== Connection drops out after some time of inactivity ===<br />
<br />
If the VPN-Connection drops some seconds after it stopped transmitting data and, even though it states it is connected, no data can be transmitted through the tunnel, try adding a {{ic|keepalive}}directive to the server's configuration:<br />
<br />
{{hc|/etc/openvpn/server/server.conf|<br />
.<br />
.<br />
keepalive 10 120<br />
.<br />
.<br />
}}<br />
<br />
In this case the server will send ping-like messages to all of its clients every 10 seconds, thus keeping the tunnel up.<br />
If the server does not receive a response within 120 seconds from a specific client, it will assume this client is down.<br />
<br />
A small ping-interval can increase the stability of the tunnel, but will also cause slightly higher traffic. Depending on your connection, also try lower intervals than 10 seconds.<br />
<br />
=== PID files not present ===<br />
<br />
The default systemd service file for openvpn-client does not have the --writepid flag enabled, despite creating /var/run/openvpn-client. If this breaks a config (such as an i3bar VPN indicator), simply change {{ic|openvpn-client@.service}} using a [[drop-in snippet]]:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/sbin/openvpn --suppress-timestamps --nobind --config %i.conf --writepid /var/run/openvpn-client/%i.pid<br />
<br />
=== Route configuration fails with systemd-networkd ===<br />
<br />
When using [[systemd-networkd]] to manage network connections and attempting to tunnel all outgoing traffic through the VPN, OpenVPN may fail to add routes. This is a result of systemd-networkd attempting to manage the tun interface before OpenVPN finishes configuring the routes. When this happens, the following message will appear in the OpenVPN log.<br />
<br />
openvpn[458]: RTNETLINK answers: Network is unreachable<br />
openvpn[458]: ERROR: Linux route add command failed: external program exited with error status: 2<br />
<br />
With systemd-233 (currently in [[testing]]), systemd-networkd can be configured to ignore the tun connections and allow OpenVPN to manage them. To do this, create the following file:<br />
<br />
{{hc|1=/etc/systemd/network/90-tun-ignore.network|2=<br />
[Match]<br />
Name=tun*<br />
<br />
[Link]<br />
Unmanaged=true<br />
}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to apply the changes. To verify that the changes took effect, start the previously problematic OpenVPN connection and run {{ic|networkctl}}. The output should have a line similar to the following:<br />
<br />
7 tun0 none routable unmanaged<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:OpenVPN]]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Systemd-boot&diff=512308Systemd-boot2018-02-28T16:43:24Z<p>Ketsui: /* BIOS boot */ Uppercase</p>
<hr />
<div>{{lowercase title}}<br />
[[Category:Boot loaders]]<br />
[[de:Gummiboot]]<br />
[[es:Systemd-boot]]<br />
[[ja:Systemd-boot]]<br />
[[ru:Systemd-boot]]<br />
[[zh-hans:Systemd-boot]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Boot loaders}}<br />
{{Related|Secure Boot}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related articles end}}<br />
<br />
'''systemd-boot''', previously called '''gummiboot''', is a simple UEFI boot manager which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu. It is included with {{pkg|systemd}}, which is installed on Arch system by default.<br />
<br />
It is simple to configure but it can only start EFI executables such as the Linux kernel [[EFISTUB]], UEFI Shell, GRUB, the Windows Boot Manager.<br />
<br />
== Installation ==<br />
<br />
=== EFI boot ===<br />
<br />
# Make sure you are booted in UEFI mode.<br />
# Verify [[Unified_Extensible_Firmware_Interface#Requirements_for_UEFI_variable_support|your EFI variables are accessible]].<br />
# Mount your [[EFI System Partition]] (ESP) properly. {{ic|''esp''}} is used to denote the mountpoint in this article. {{Note|''systemd-boot'' cannot load EFI binaries from other partitions. It is therefore recommended to mount your ESP to {{ic|/boot}}. In case you want to separate {{ic|/boot}} from the ESP see [[#Manually]] for more information.}}<br />
# If the ESP is '''not''' mounted at {{ic|/boot}}, then copy your kernel and initramfs onto that ESP. {{Note|For a way to automatically keep the kernel updated on the ESP, have a look at [[EFI System Partition#Using systemd]] for some systemd units that can be adapted. If your EFI System Partition is using automount, you may need to add {{ic|vfat}} to a file in {{ic|/etc/modules-load.d/}} to ensure the current running kernel has the {{ic|vfat}} module loaded at boot, before any kernel update happens that could replace the module for the currently running version making the mounting of {{ic|/boot/efi}} impossible until reboot.}}<br />
# Type the following command to install ''systemd-boot'': {{bc|1=# bootctl --path=''esp'' install}} It will copy the ''systemd-boot'' binary to your EFI System Partition ({{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} and {{ic|''esp''/EFI/Boot/BOOTX64.EFI}} – both of which are identical – on x86-64 systems) and add ''systemd-boot'' itself as the default EFI application (default boot entry) loaded by the EFI Boot Manager.<br />
# Finally you must [[#Configuration|configure]] the boot loader to function properly.<br />
<br />
=== BIOS boot ===<br />
<br />
{{Warning|This is not recommended.}}<br />
You can successfully install ''systemd-boot'' if booted with in BIOS mode. However, this process requires you to tell firmware to launch ''systemd-boot'''s EFI file at boot, usually via two ways:<br />
<br />
* you have a working EFI Shell somewhere else.<br />
* your firmware interface provides a way of properly setting the EFI file that needs to be loaded at boot time.<br />
<br />
If you can do it, the installation is easier: go into your EFI Shell or your firmware configuration interface and change your machine's default EFI file to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} ( or {{ic|systemd-bootia32.efi}} depending if your system firmware is 32 bit).<br />
<br />
{{Note|The firmware interface of Dell Latitude series provides everything you need to setup EFI boot but the EFI Shell won't be able to write to the computer's ROM.}}<br />
<br />
=== Updating ===<br />
<br />
Unlike the previous separate ''gummiboot'' package, which updated automatically on a new package release with a {{ic|post_install}} script, updates of new ''systemd-boot'' versions must now be done manually by the user. However the procedure can be automated using pacman hooks.<br />
<br />
==== Manually ====<br />
<br />
''systemd-boot'' ({{man|1|bootctl}}) assumes that your EFI System Partition is mounted on {{ic|/boot}}.<br />
<br />
# bootctl update<br />
<br />
If the ESP is not mounted on {{ic|/boot}}, the {{ic|1=--path=}} option can pass it. For example: <br />
<br />
# bootctl --path=''esp'' update<br />
<br />
{{Note|This is also the command to use when migrating from ''gummiboot'', before removing that package. If that package has already been removed, however, run {{ic|1=bootctl --path=''esp'' install}}.}}<br />
<br />
==== Automatically ====<br />
<br />
The [[AUR]] package {{AUR|systemd-boot-pacman-hook}} provides a [[Pacman#Hooks|Pacman hook]] to automate the update process. [[Install|Installing]] the package will add a hook which will be executed every time the {{Pkg|systemd}} package is upgraded.<br />
<br />
Alternatively, place the following pacman hook in the {{ic|/etc/pacman.d/hooks/}} directory:<br />
<br />
{{hc|/etc/pacman.d/hooks/systemd-boot.hook|2=<br />
[Trigger]<br />
Type = Package<br />
Operation = Upgrade<br />
Target = systemd<br />
<br />
[Action]<br />
Description = Updating systemd-boot...<br />
When = PostTransaction<br />
Exec = /usr/bin/bootctl update<br />
}}<br />
<br />
== Configuration ==<br />
<br />
=== Basic configuration ===<br />
<br />
{{Tip|A basic configuration file example is located at {{ic|/usr/share/systemd/bootctl/loader.conf}}.}}<br />
<br />
The basic configuration is stored in {{ic|''esp''/loader/loader.conf}} file and it is composed by three options:<br />
<br />
* {{ic|default}} – default entry to select (without the {{ic|.conf}} suffix); can be a wildcard like {{ic|arch-*}}.<br />
* {{ic|timeout}} – menu timeout in seconds. If this is not set, the menu will only be shown on {{ic|Space}} key (or most other keys actually work too) press during boot.<br />
* {{ic|editor}} – whether to enable the kernel parameters editor or not. {{ic|1}} (default) is enabled, {{ic|0}} is disabled; since the user can add {{ic|1=init=/bin/bash}} to bypass root password and gain root access, it is strongly recommended to set this option to {{ic|0}}.<br />
<br />
Example:<br />
<br />
{{hc|''esp''/loader/loader.conf|<br />
default arch<br />
timeout 4<br />
editor 0<br />
}}<br />
<br />
{{Note|The first 2 options can be changed in the boot menu itself and changes will be stored as EFI variables.}}<br />
<br />
=== Adding boot entries ===<br />
<br />
{{Note|<br />
* ''bootctl'' will automatically check for "'''Windows Boot Manager'''" ({{ic|\EFI\Microsoft\Boot\Bootmgfw.efi}}), "'''EFI Shell'''" ({{ic|\shellx64.efi}}) and "'''EFI Default Loader'''" ({{ic|\EFI\Boot\bootx64.efi}}) at boot time, as well as specially prepared kernel files found in {{ic|\EFI\Linux}}. When detected, corresponding entries with titles {{ic|auto-windows}}, {{ic|auto-efi-shell}} and {{ic|auto-efi-default}}, respectively, will be automatically generated. These entries do not require manual loader configuration. However, it does not auto-detect other EFI applications (unlike [[rEFInd]]), so for booting the Linux kernel, manual configuration entries must be created.<br />
* If you dual-boot Windows, it is strongly recommended to disable its default [[Dual boot with Windows#Fast_Start-Up|Fast Start-Up]] option.<br />
* Remember to load the intel [[microcode]] with {{ic|initrd}} if applicable.<br />
* You can find the {{ic|PARTUUID}} for your root partition with the command {{ic|1=blkid -s PARTUUID -o value /dev/sd''xY''}}, where {{ic|''x''}} is the device letter and {{ic|''Y''}} is the partition number. This is required only for your root partition, not {{ic|''esp''}}.<br />
}}<br />
<br />
''bootctl'' searches for boot menu items in {{ic|''esp''/loader/entries/*.conf}} – each file found must contain exactly one boot entry. The possible options are:<br />
<br />
* {{ic|title}} – operating system name. '''Required.'''<br />
* {{ic|version}} – kernel version, shown only when multiple entries with same title exist. Optional.<br />
* {{ic|machine-id}} – machine identifier from {{ic|/etc/machine-id}}, shown only when multiple entries with same title and version exist. Optional.<br />
* {{ic|efi}} – EFI program to start, relative to your ESP ({{ic|''esp''}}); e.g. {{ic|/vmlinuz-linux}}. Either this or {{ic|linux}} (see below) is '''required.'''<br />
* {{ic|options}} – command line options to pass to the EFI program or [[kernel parameters]]. Optional, but you will need at least {{ic|1=initrd=''efipath''}} and {{ic|1=root=''dev''}} if booting Linux.<br />
<br />
For Linux, you can specify {{ic|linux ''path-to-vmlinuz''}} and {{ic|initrd ''path-to-initramfs''}}; this will be automatically translated to {{ic|efi ''path''}} and {{ic|1=options initrd=''path''}} – this syntax is only supported for convenience and has no differences in function.<br />
<br />
{{Tip|The available boot entries which have been configured can be listed with the command {{ic|bootctl list}}.}}<br />
<br />
An example entry file is located at {{ic|/usr/share/systemd/bootctl/arch.conf}}. The [[kernel parameters]] for scenarios such as [[LVM]], [[LUKS]] or [[dm-crypt]] can be found on the relevant pages.<br />
<br />
==== EFI Shells or other EFI apps ====<br />
<br />
In case you installed EFI shells and other EFI application into the ESP, you can use the following snippets:<br />
<br />
{{hc|''esp''/loader/entries/uefi-shell-v1-x86_64.conf|2=<br />
title UEFI Shell x86_64 v1<br />
efi /EFI/shellx64_v1.efi<br />
}}<br />
<br />
{{hc|''esp''/loader/entries/uefi-shell-v2-x86_64.conf|2=<br />
title UEFI Shell x86_64 v2<br />
efi /EFI/shellx64_v2.efi<br />
}}<br />
<br />
{{Expansion|Add example on how to boot into EFI firmware setup.}}<br />
<br />
=== Preparing kernels for EFI\Linux ===<br />
<br />
{{Style|Does not belong here, not specific to systemd-boot.}}<br />
<br />
''EFI\Linux'' is searched for specially prepared kernel files, which bundle the kernel, the initrd, the kernel command line and {{ic|/etc/os-release}} into one file. This file can be easily signed for secure boot.<br />
<br />
{{Note|{{ic|systemd-boot}} requires that the {{ic|os-release}} file contain either {{ic|VERSION_ID}} or {{ic|BUILD_ID}} to generate an ID and automatically add the entry, which the Arch {{ic|os-release}} does not. Either maintain your own copy with one of them, or make your bundling script generate it automatically.}}<br />
<br />
Put the kernel command line you want to use in a file, and create the bundle file like this:<br />
<br />
{{hc|Kernel packaging command:|<nowiki>objcopy \<br />
--add-section .osrel="/usr/lib/os-release" --change-section-vma .osrel=0x20000 \<br />
--add-section .cmdline="kernel-command-line.txt" --change-section-vma .cmdline=0x30000 \<br />
--add-section .linux="vmlinuz-file" --change-section-vma .linux=0x40000 \<br />
--add-section .initrd="initrd-file" --change-section-vma .initrd=0x3000000 \<br />
"/usr/lib/systemd/boot/efi/linuxx64.efi.stub" "linux.efi"</nowiki>}}<br />
<br />
Optionally sign ''linux.efi'' now (e.g. using ''sbsigntools'' from AUR).<br />
<br />
Copying ''linux.efi'' into {{ic|''esp''\EFI\Linux}}.<br />
<br />
=== Support hibernation ===<br />
<br />
See [[Suspend and hibernate]].<br />
<br />
=== Kernel parameters editor with password protection ===<br />
<br />
Alternatively you can install {{AUR|systemd-boot-password}} which supports {{ic|password}} basic configuration option. Use {{ic|sbpctl generate}} to generate a value for this option.<br />
<br />
Install ''systemd-boot-password'' with the following command:<br />
<br />
{{bc|1=# sbpctl install ''esp''}}<br />
<br />
With enabled editor you will be prompted for your password before you can edit kernel parameters.<br />
<br />
== Keys inside the boot menu ==<br />
<br />
The following keys are used inside the menu:<br />
* {{ic|Up/Down}} - select entry<br />
* {{ic|Enter}} - boot the selected entry<br />
* {{ic|d}} - select the default entry to boot (stored in a non-volatile EFI variable)<br />
* {{ic|-/T}} - decrease the timeout (stored in a non-volatile EFI variable)<br />
* {{ic|+/t}} - increase the timeout (stored in a non-volatile EFI variable)<br />
* {{ic|e}} - edit the kernel command line. It has no effect if the {{ic|editor}} config option is set to {{ic|0}}.<br />
* {{ic|v}} - show the gummiboot and UEFI version<br />
* {{ic|Q}} - quit<br />
* {{ic|P}} - print the current configuration<br />
* {{ic|h/?}} - help<br />
<br />
These hotkeys will, when pressed inside the menu or during bootup, directly boot<br />
a specific entry:<br />
<br />
* {{ic|l}} - Linux<br />
* {{ic|w}} - Windows<br />
* {{ic|a}} - OS X<br />
* {{ic|s}} - EFI Shell<br />
* {{ic|1-9}} - number of entry<br />
<br />
== Troubleshooting ==<br />
<br />
=== Manual entry using efibootmgr ===<br />
<br />
If the {{ic|bootctl install}} command failed, you can create a EFI boot entry manually using {{Pkg|efibootmgr}}:<br />
<br />
# efibootmgr -c -d /dev/sdX -p Y -l "\EFI\systemd\systemd-bootx64.efi" -L "Linux Boot Manager"<br />
<br />
where {{ic|/dev/sdXY}} is the [[EFI System Partition]].<br />
<br />
{{Note|The path to the EFI image must use the backslash ({{ic|\}}) as the separator}}<br />
<br />
=== Menu does not appear after Windows upgrade ===<br />
<br />
See [[UEFI#Windows changes boot order]].<br />
<br />
== See also ==<br />
<br />
* http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Talk:Arch_User_Repository&diff=512288Talk:Arch User Repository2018-02-28T12:34:36Z<p>Ketsui: /* Redirect users to Makepkg#Improving_compile_times instead of linking just ccache? */ new section</p>
<hr />
<div>== <s>Warning about rebuilding your AUR packages</s> ==<br />
I thought at some point there was an explicit warning to the effect that rebuilding AUR packages against new official libraries was the individual's responsibility, not pacman's. I would like to see this reinstated at the top of the page as it is a constant source of confusion for new users. [[User:Jasonwryan|Jasonwryan]] ([[User talk:Jasonwryan|talk]]) 21:57, 24 November 2016 (UTC)<br />
<br />
Another approach would be to add it to the top of the [[Arch_User_Repository#FAQ|FAQ]], and then split that out to a separate page, with a warning at the top of the AUR page sugesting that new users read the entirety of the FAQ 'before' installing anything from the AUR [[User:Jasonwryan|Jasonwryan]] ([[User talk:Jasonwryan|talk]]) 04:58, 27 November 2016 (UTC)<br />
<br />
:Is this a user's responsibility completely or the package maintainer's to increment pkgrel to indicate that the package should be rebuilt? This might fit to the explanation when (not) to use the "Out of date" button. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:21, 27 November 2016 (UTC)<br />
<br />
::This is Arch -- it must be the user's responsibility :) [[User:Jasonwryan|Jasonwryan]] ([[User talk:Jasonwryan|talk]]) 02:21, 7 February 2018 (UTC)<br />
<br />
:::Updated main page [https://wiki.archlinux.org/index.php?title=Arch_User_Repository&type=revision&diff=510294&oldid=510108]. [[User:Jasonwryan|Jasonwryan]] ([[User talk:Jasonwryan|talk]]) 22:18, 9 February 2018 (UTC)<br />
<br />
== <s>AUR's history and future</s> ==<br />
<br />
Will part of [[Arch_User_Repository#AUR_4]] be moved to [[Arch_User_Repository#History]] in a day or two? We should also remove / archive notes about the old AUR once it's read-only.<br />
<br />
The article should also mention using git as an alternative to downloading the tarball. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 12:06, 7 August 2015 (UTC)<br />
<br />
:Part of this request has been fulfilled with [https://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=390646&oldid=389301]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:46, 9 August 2015 (UTC)<br />
<br />
::Moved the remaining bit of AUR3 information to the History section with [https://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=506963&oldid=506950]. -- [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 14:44, 12 January 2018 (UTC)<br />
<br />
== What is the correct AUR forum section? ==<br />
<br />
[[Arch_User_Repository#Submitting_packages]] says it's [https://bbs.archlinux.org/viewforum.php?id=4], but we also have [https://bbs.archlinux.org/viewforum.php?id=38]. One of them should be added to [[Arch_User_Repository#I_have_a_PKGBUILD_I_would_like_to_submit.3B_can_someone_check_it_to_see_if_there_are_any_errors.3F]]. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 12:30, 7 August 2015 (UTC)<br />
<br />
== AUR link ==<br />
<br />
The link to this page from the [https://aur.archlinux.org/ AUR homepage] is outdated.<br />
<br />
[https://wiki.archlinux.org/index.php/Arch_User_Repository#AUR_4 "Submitting packages"] located above the SSH keys directs to an AUR4 link, which has since become just AUR. I'm not knowledgeable of the methods to correct this.<br />
<br />
-- [[User:Ctag|Ctag]] ([[User talk:Ctag|talk]]) 00:05, 23 September 2015 (UTC)<br />
<br />
:You can submit a bug report for the [https://bugs.archlinux.org/index.php?project=2&do=index&switch=1 AUR web interface] project in the tracker. Or even provide a patch: sources are at [https://projects.archlinux.org/aurweb.git/]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:22, 23 September 2015 (UTC)<br />
<br />
== gitignore ==<br />
<br />
Adding {{ic|*}} to {{ic|.gitignore}} is an ugly workaround for something (in case of dotfiles, programs not respecting standards and e.g. storing cache and config files together). There isn't much to be excluded here - the only unpredictable part is the source tarballs and VCS directories, which can be easily put away by configuring {{ic|SRCDEST}} in {{ic|makepkg.conf}}. We can still recommend to add the source files explicitly.<br />
<br />
The recommendation will affect everybody using the given package, not only the user managing his personal config files, so I think an explicit blacklist is better than the {{ic|*}} wildcard here.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:58, 6 March 2016 (UTC)<br />
:I agree, as per my original recommendation. The simple thing to do is {{ic|git add .}}; some packages ''do have'' an annoying variety of files. Better to explicitly exclude download directories other known cruft in .gitignore. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 12:15, 6 March 2016 (UTC)<br />
<br />
::So the concern is you'd miss to whitelist some "annoying variety" of files, which you wouldn't with {{ic|git add .}}? You might as well argue that you'd miss to blacklist a file you wouldn't want to upload to the AUR... <br />
::Either way, I'd agree configuring SRCDEST is the better (and universal) solution here. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:05, 6 March 2016 (UTC)<br />
:::<strike>Good point, the whole reason for posting a guide indeed is to show users how to deal with AUR4 in the way Archlinux administration expects, this seems to be the more reliable solution[</strike><br />
::::Then I remembered what SRCDEST actually does and realized it wouldn't sufficiently resolve the issue (the source directory is not the only cruft to be avoided). [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 03:55, 13 March 2016 (UTC)<br />
<br />
:::::I have SRCDEST, PKGDEST, LOGDEST, and BUILDDEST set. Suffice to say there's no cruft in my .git dirs. It's not much a bother either, since the values are commented in makepkg.conf. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 12:35, 13 March 2016 (UTC)<br />
<br />
::::::What about the symlinks to the built packages and signatures? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:04, 13 March 2016 (UTC)<br />
<br />
:::::::Assuming only makepkg crates symlinks in the clone directory (correct me if I'm wrong), you can do something like {{ic|find -maxdepth 2 -type l -delete}} in the directory above, in my case a dedicated "AURDEST".<br />
:::::::Perhaps too specific for the general case, but the special type helps anyway. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 13:43, 13 March 2016 (UTC)<br />
<br />
::::::::That's cleanup, not prevention. Anyway, the point of {{ic|.gitignore}} is not to move the "cruft" away, but to keep the repo directory clean ''in git terms'', i.e. git should not report files created by makepkg as untracked. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:48, 14 March 2016 (UTC)<br />
<br />
:::::::::In that case, I refer to my comment below on just mentioning {{ic|.gitignore}}, but not recommending a specific method. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:47, 14 March 2016 (UTC)<br />
<br />
::::Recommending either way is problematic since this is more a question of git usage style rather than AUR usage. The maintainer should set up the .gitignore in an intuitive way ''depending'' on their git workflow and how the package is organized. If I had to recommend anything, it would be either: don't {{ic|git add .}} (because it's lazy and can easily backfire), or always check {{ic|git status}} before you commit to make sure you know what's staged (and we already recommend checking your commits before pushing). But again, those are more general git recommendations than anything AUR-specific. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 21:58, 9 March 2016 (UTC)<br />
<br />
:::::Using gitignore is useful not only for the comfort of the maintainer, but also of users building and installing the package. For example if {{ic|pkg/}}, {{ic|src/}} etc. are not gitignored, tools such as [https://github.com/kynikos/repocheck repocheck] will not work correctly. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:05, 9 March 2016 (UTC)<br />
<br />
::::::I still don't see how that is AUR-specific information. It is certainly good practice to have a gitignore for any git repo with files you don't want to track, but it is by no means necessary nor is it a practice specific to AUR repos. Adding git tricks to this article that are just general best practices is a slippery slope to creating a duplicate git tutorial like Quequotion did. I would much rather direct users to https://git-scm.com/doc and emphasize the importance of learning git properly before contributing AUR packages. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 17:58, 10 March 2016 (UTC)<br />
<br />
:::::::We know certain things could be .gitignored for every package, such as {{ic|src/}}, {{ic|pkg/}}, and {{ic|*.pkg.tar.xz}}; but we cannot know what files a packager may be using otherwise. I think having packagers create an explicit blacklist is the smallest and easiest of the available options. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 03:55, 13 March 2016 (UTC)<br />
<br />
::::::::Stuff makepkg creates can be moved automatically, as indicated above. The rest is an edge case, and the best way to handle it is subject to debate. If anything, just mention .gitignore, but not a specific approach to using it. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 12:35, 13 March 2016 (UTC)<br />
<br />
:::::::::I've changed my mind, and my perspective on this issue. I realized too late, after uploading several ridiculously large .gitignore files to AUR, that it's a huge waste of space (actually, you don't ''have to'' send .gitignore to AUR at all--but subsequent clones of your package will then not have a .gitignore). Putting an asterisk in it and using {{ic|git add -f}} is a better idea for the AUR's bandwidth and storage space. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 17:55, 17 July 2017 (UTC)<br />
<br />
== AUR search takes '%' literally ==<br />
<br />
[[Arch User Repository#Searching]] is marked by [[template:Accuracy]], though I couldn't see the discussion here. Did I missed something? There are some comments at [https://bbs.archlinux.org/viewtopic.php?id=226931 this forum thread]. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 14:21, 5 June 2017 (UTC)<br />
: I haven’t started the discussion, because I assume that the first person that has something to say should do that. Since all I had to say was stated in the {{ic|reason}}, I was not re-stating the problem here. Also I can’t fix that myself, because I have no idea how exactly AUR search works internally now and if this is just a bug or the current ''official'' status is that strings are taken literally. Therefore only marking it with [[Template:Accuracy]]. --[[User:Mpan|Mpan]] ([[User talk:Mpan|talk]]) 15:56, 5 June 2017 (UTC)<br />
<br />
== Markdown Syntax ==<br />
<br />
Should there be a Markdown syntax section? [https://lists.archlinux.org/pipermail/aur-general/2017-December/033697.html][https://git.archlinux.org/aurweb.git/log/?id=v4.6.0] All those seem to work: [https://aur.archlinux.org/packages/chromium-snapshot-bin/#comment-589706 link] —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 16:24, 5 December 2017 (UTC)<br />
<br />
:Oh wow, yes please. I had no idea that this was possible. And it's still unclear to me what syntax it uses. —[[User:Ostiensis|Ostiensis]] ([[User talk:Ostiensis|talk]]) 20:52, 5 December 2017 (UTC)<br />
<br />
::Well, there's a preliminary section: [[Arch_User_Repository#Comment_syntax]]. --'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 22:28, 13 December 2017 (UTC)<br />
<br />
:::[https://wiki.archlinux.org/index.php?title=Arch_User_Repository&diff=502556&oldid=502552] Well, I don't know how to do that, since they only implemented a small part of it? --'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 22:35, 13 December 2017 (UTC)<br />
<br />
::::[https://git.archlinux.org/aurweb.git/commit/?id=9aa4203c7efd5ef1015eb32eca5e0764a5afe183 Here] they use the [https://python-markdown.github.io/ Python-Markdown] library, which "is almost completely compliant with the reference implementation, though there are a few very minor [https://python-markdown.github.io/#differences differences]." -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:50, 13 December 2017 (UTC)<br />
<br />
:Thanks for that. FWIW I've never seen that multiline code syntax before, so I wonder if it *is* some strange home-brew markdown. —[[User:Ostiensis|Ostiensis]] ([[User talk:Ostiensis|talk]]) 22:37, 13 December 2017 (UTC)<br />
<br />
== FAQ - outdated package ==<br />
<br />
Do you understand what the comment means "When we are talking about a package which is flagged out of date for more than 3 months and is in general not updated for a long time, please add this in your orphan request. " ?<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 15:49, 13 January 2018 (UTC)<br />
<br />
:When people request a package to be orphaned because the current maintainer does not respond to out-of-date notifications, it should be clarified in the request to speed up the resolution. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:05, 13 January 2018 (UTC)<br />
<br />
::Yes indeed and what about the 2 weeks vs the 3 months difference in the comments? This is what I don't get, if this is more than 3 months we should say in the comments "it has been 4 months" but if it has been let say 2 months we should not mention it? The rule is not clear and I am wondering if it is more urgent to find an adopter for a package that has not been updated for 2 years or for 3 weeks. In the latter case it does seem more urgent, rather the opposite then. [[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 18:57, 13 January 2018 (UTC)<br />
<br />
:::I think that the 2 weeks are for the maintainers to react to the request, even if it is not due to out-of-date package. Anyway, the FAQ entries are not strict, I doubt that the 3 months are obligatory. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 13 January 2018 (UTC)<br />
::::I have rephrased providing some more details in line with the AUR request template. The 3 months does not seems to be anything official, the 2 weeks neither but sounds reasonable. Feel free to amend or revert. [[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 19:41, 13 January 2018 (UTC)<br />
<br />
== Redirect users to [[Makepkg#Improving_compile_times]] instead of linking just ccache? ==<br />
<br />
There's three methods (including ccache) listed in [[Makepkg#Improving_compile_times]] so it seems like it makes more sense to link to it instead of just ccache on [[Arch_User_Repository#How_can_I_speed_up_repeated_build_processes.3F]]. [[User:Ketsui|Ketsui]] ([[User talk:Ketsui|talk]]) 12:34, 28 February 2018 (UTC)</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=512158Pacman/Tips and tricks2018-02-27T02:43:07Z<p>Ketsui: /* Not in a specified group or repository */ Fix typo</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
To get a list of installed packages sorted by size, which may be useful when freeing space on your hard drive:<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(wget -q -O - https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | awk '/^.+(-cvs|-svn|-git|-hg|-bzr|-darcs)$/'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{AUR|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner:<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick and dirty solution, you can simply run a standalone webserver which other computers can use as a first mirror: {{ic|darkhttpd /var/cache/pacman/pkg}}. Just add this server at the top of your mirror list. Be aware that you might get a lot of 404 errors, due to cache misses, depending on what you do, but ''pacman'' will try the next (real) mirrors when that happens.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is included with ''pacman'') can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Custom options for the compression tools can be configured by exporting the relevant environment variable, for example {{ic|1=XZ_OPT="-T 0"}} will enable parallel compression for ''xz''.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|If you used {{ic|-Qqet}}, when reinstalling the list all the non-top-level packages would be set as dependencies.}}<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
In case the list includes foreign packages, such as [[AUR]] packages, remove them first:<br />
<br />
# pacman -S $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were got corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Database access speeds ===<br />
<br />
''Pacman'' stores all package information in a collection of small files, one for each package. Improving database access speeds reduces the time taken in database-related tasks, e.g. searching packages and resolving package dependencies. The safest and easiest method is to run as root:<br />
<br />
# pacman-optimize<br />
<br />
This will attempt to put all the small files together in one (physical) location on the hard disk so that the hard disk head does not have to move so much when accessing all the data. This method is safe, but is not foolproof: it depends on your filesystem, disk usage and empty space fragmentation. Another, more aggressive, option would be to first remove uninstalled packages from cache and to remove unused repositories before database optimization:<br />
<br />
# pacman -Sc && pacman-optimize<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget -c -q --show-progress --passive-ftp -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{AUR|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|Arch-Update| Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|A collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME packagekit|GTK based package management tool|http://www.freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Gnome Software App. (Curated selection for GNOME)|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|A small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pamac|A DBus daemon and Gtk3 frontend for libalpm written in Vala.|https://github.com/manjaro/pamac/|{{AUR|pamac-aur}}}}<br />
* {{App|pcurses|Package management in a curses frontend|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Polkit&diff=511723Polkit2018-02-23T05:15:28Z<p>Ketsui: /* Installation */ Linkify 'install'</p>
<hr />
<div>[[Category:Security]]<br />
[[de:PolicyKit]]<br />
[[ja:Polkit]]<br />
[[ru:Polkit]]<br />
[[zh-hans:Polkit]]<br />
{{Related articles start}}<br />
{{Related|Session}}<br />
{{Related|Sudo}}<br />
{{Related|Users and groups}}<br />
{{Related articles end}}<br />
From [http://www.freedesktop.org/wiki/Software/polkit/ polkit homepage]:<br />
<br />
:''polkit is an application-level toolkit for defining and handling the policy that allows unprivileged processes to speak to privileged processes: It is a framework for centralizing the decision making process with respect to granting access to privileged operations for unprivileged applications.''<br />
<br />
Polkit is used for controlling system-wide privileges. It provides an organized way for non-privileged processes to communicate with privileged ones. In contrast to systems such as sudo, it does not grant root permission to an entire process, but rather allows a finer level of control of centralized system policy.<br />
<br />
Polkit works by delimiting distinct actions, e.g. running GParted, and delimiting users by group or by name, e.g. members of the wheel group. It then defines how – if at all – those users are allowed those actions, e.g. by identifying as members of the group by typing in their passwords.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|polkit}} package.<br />
<br />
=== Authentication agents ===<br />
<br />
An authentication agent is used to make the user of a session prove that the user of the session really is the user (by authenticating as the user) or an administrative user (by authenticating as an administrator). The {{Pkg|polkit}} package contains a textual authentication agent called 'pkttyagent', which is used as a general fallback. <br />
<br />
If you are using a graphical environment, make sure that a graphical authentication agent is installed and [[autostarting|autostarted]] on login.<br />
<br />
[[Cinnamon]], [[Deepin]], [[GNOME]], [[GNOME Flashback]], [[KDE]], [[LXDE]], [[LXQt]], [[MATE]], theShell and [[Xfce]] have an authentication agent already.<br />
In other desktop environments, you have to choose one of the following implementations:<br />
* {{Pkg|lxqt-policykit}}, which provides {{ic|/usr/bin/lxqt-policykit-agent}}<br />
* {{Pkg|lxsession}}, which provides {{ic|/usr/bin/lxpolkit}}<br />
* {{Pkg|mate-polkit}}, which provides {{ic|/usr/lib/mate-polkit/polkit-mate-authentication-agent-1}}<br />
* {{AUR|polkit-efl-git}}, which provides {{ic|/usr/bin/polkit-efl-authentication-agent-1}}<br />
* {{Pkg|polkit-gnome}}, which provides {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}}<br />
* {{Pkg|polkit-kde-agent}}, which provides {{ic|/usr/lib/polkit-kde-authentication-agent-1}}<br />
* {{AUR|ts-polkitagent}}, which provides {{ic|/usr/lib/ts-polkitagent}}<br />
* {{AUR|xfce-polkit-git}}, which provides {{ic|/usr/lib/xfce-polkit/xfce-polkit}}<br />
<br />
== Configuration ==<br />
<br />
{{Warning|Do not amend the default permission files of packages, as these may be be overwritten on package upgrades.}}<br />
<br />
Polkit definitions can be divided into two kinds:<br />
* '''Actions''' are defined in XML {{ic|.policy}} files located in {{ic|/usr/share/polkit-1/actions}}. Each action has a set of default permissions attached to it (e.g. you need to identify as an administrator to use the GParted action). The defaults can be overruled but editing the actions files is NOT the correct way.<br />
*'''Authorization rules''' are defined in JavaScript {{ic|.rules}} files. They are found in two places: 3rd party packages can use {{ic|/usr/share/polkit-1/rules.d}} (though few if any do) and {{ic|/etc/polkit-1/rules.d}} is for local configuration. <br />
<br />
Polkit operates on top of the existing permissions systems in Linux – group membership, administrator status – it does not replace them. The .rules files designate a subset of users, refer to one (or more) of the actions specified in the actions files and determine with what restrictions these actions can be taken by that/those user(s). As an example, a rules file could overrule the default requirement for all users to authenticate as an admin when using GParted, determining that some specific user doesn't need to. Or isn't allowed to use GParted at all.<br />
<br />
{{Note|This does not preclude running GParted by means which do not respect polkit, such as the command line. Therefore, polkit should be used to expand access to privileged services for unprivileged users, rather than try to curtail the rights of (semi-)privileged users. For security purposes, [[Sudo|sudoers]] is still the way to go.}}<br />
<br />
=== Actions ===<br />
<br />
{{Tip|To display Policykit actions in a graphical interface, install the {{AUR|polkit-explorer}} package.}}<br />
<br />
The actions available to you via polkit will depend on the packages you have installed. Some are used in multiple desktop environments ''(org.freedesktop.*)'', some are DE-specific ''(org.gnome.*)'' and some are specific to a single program ''(org.archlinux.pkexec.gparted.policy)''. The command {{ic|pkaction}} lists all the actions defined in {{ic|/usr/share/polkit-1/actions}} for quick reference. <br />
<br />
To get an idea of what polkit can do, here are a few commonly used groups of actions:<br />
* '''[[Systemd|systemd-logind]]''' ''(org.freedesktop.login1.policy)'' actions regulated by polkit include powering off, rebooting, suspending and hibernating the system, including when other users may still be logged in.<br />
* '''[[udisks]]''' ''(org.freedesktop.udisks2.policy)'' actions regulated by polkit include mounting file systems and unlocking encrypted devices.<br />
* '''[[NetworkManager]]''' ''(org.freedesktop.NetworkManager.policy)'' actions regulated by polkit include turning on and off the network, wifi or mobile broadband.<br />
<br />
Each action is defined in an {{ic|<action>}} tag in a .policy file. The {{ic|org.archlinux.pkexec.gparted.policy}} contains a single action and looks like this:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<!DOCTYPE policyconfig PUBLIC<br />
"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"<br />
<nowiki>"http://www.freedesktop.org/software/polkit/policyconfig-1.dtd"></nowiki><br />
<policyconfig><br />
<br />
<action id="org.archlinux.pkexec.gparted"><br />
<message>Authentication is required to run the GParted Partition Editor</message><br />
<icon_name>gparted</icon_name><br />
<defaults><br />
<allow_any>auth_admin</allow_any><br />
<allow_inactive>auth_admin</allow_inactive><br />
<allow_active>auth_admin</allow_active><br />
</defaults><br />
<annotate key="org.freedesktop.policykit.exec.path">/usr/bin/gparted</annotate><br />
<annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate><br />
</action><br />
<br />
</policyconfig><br />
<br />
The attribute '''id''' is the actual command sent to [[D-Bus]], the '''message''' tag is the explanation to the user when authentication is required and the '''icon_name''' is sort of obvious. <br />
<br />
The '''defaults''' tag is where the permissions or lack thereof are located. It contains three settings: '''allow_any''', '''allow_inactive''', and '''allow_active'''. Inactive sessions are generally remote sessions (SSH, VNC, etc.) whereas active sessions are logged directly into the machine on a TTY or an X display. allow_any is the setting encompassing both scenarios. <br />
<br />
For each of these settings the following options are available:<br />
* ''no'': The user is not authorized to carry out the action. There is therefore no need for authentication.<br />
* ''yes'': The user is authorized to carry out the action without any authentication.<br />
* ''auth_self'': Authentication is required but the user need not be an administrative user.<br />
* ''auth_admin'': Authentication as an administrative user is required.<br />
* ''auth_self_keep'': The same as auth_self but, like sudo, the authorization lasts a few minutes.<br />
* ''auth_admin_keep'': The same as auth_admin but, like sudo, the authorization lasts a few minutes.<br />
These are default setting and unless overruled in later configuration will be valid for all users.<br />
<br />
As can be seen from the GParted action, users are required to authenticate as administrators in order to use GParted, regardless of whether the session is active or inactive.<br />
<br />
=== Authorization rules ===<br />
<br />
Authorization rules that overrule the default settings are laid out in a set of directories as described above. For all purposes relating to personal configuration of a single system, only {{ic|/etc/polkit-1/rules.d}} should be used. <br />
<br />
The {{ic|addRule()}} method is used for adding a function that may be called whenever an authorization check for action and subject is performed. Functions are called in the order they have been added until one of the functions returns a value. Hence, to add an authorization rule that is processed before other rules, put it in a file in {{ic|/etc/polkit-1/rules.d}} with a name that sorts before other rules files, for example {{ic|00-early-checks.rules}}.<br />
<br />
The layout of the .rules files is fairly self-explanatory:<br />
/* Allow users in admin group to run GParted without authentication */<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.archlinux.pkexec.gparted" &&<br />
subject.isInGroup("admin")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
<br />
Inside the function, we check for the specified action ID ''(org.archlinux.pkexec.gparted)'' and for the user's group ''(admin)'', then return a value "yes".<br />
<br />
=== Administrator identities ===<br />
<br />
The {{ic|addAdminRule()}} method is used for adding a function that may be called whenever administrator authentication is required. The function is used to specify what identities may be used for administrator authentication for the authorization check identified by action and subject. Functions added are called in the order they have been added until one of the functions returns a value. <br />
<br />
The default configuration for administrator identities is contained in the file {{ic|50-default.rules}} so any changes to that configuration should be made by copying the file to, say, {{ic|40-default.rules}} and editing that file.<br />
{{hc|/etc/polkit-1/rules.d/50-default.rules|<nowiki><br />
polkit.addAdminRule(function(action, subject) {<br />
return ["unix-group:wheel"];<br />
});</nowiki>}}<br />
<br />
The only part to edit (once copied) is the return array of the function: as whom should a user authenticate when asked to authenticate as an administrative user? If she herself is a member of the group designated as admins, she only need enter her own password. If some other user, e.g. root, is the only admin identity, she would need to enter in root's password. The format of the user identification is the same as the one used in designating authorities. <br />
<br />
The Arch default is to make all members of the group '''wheel''' administrators. A rule like below will have polkit ask for the root password instead of the users password for Admin authentication.<br />
<br />
{{hc|/etc/polkit-1/rules.d/49-rootpw_global.rules|<br />
/* Always authenticate Admins by prompting for the root<br />
* password, similar to the rootpw option in sudo<br />
*/<br />
polkit.addAdminRule(function(action, subject) {<br />
return ["unix-user:root"];<br />
});<br />
}}<br />
<br />
== Examples ==<br />
<br />
=== Debugging/logging ===<br />
<br />
The following rule logs detailed information about any requested access.<br />
{{hc|/etc/polkit-1/rules.d/00-log-access.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
polkit.log("action=" + action);<br />
polkit.log("subject=" + subject);<br />
});</nowiki>}}<br />
<br />
=== Disable suspend and hibernate ===<br />
<br />
The following rule disables suspend and hibernate for all users.<br />
{{hc|/etc/polkit-1/rules.d/10-disable-suspend.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.freedesktop.login1.suspend" ||<br />
action.id == "org.freedesktop.login1.suspend-multiple-sessions" ||<br />
action.id == "org.freedesktop.login1.hibernate" ||<br />
action.id == "org.freedesktop.login1.hibernate-multiple-sessions")<br />
{<br />
return polkit.Result.NO;<br />
}<br />
});</nowiki>}}<br />
<br />
=== Bypass password prompt ===<br />
<br />
To achieve something similar to the [[sudo]] {{ic|NOPASSWD}} option and get authorized solely based on [[Users_and_groups|user/group]] identity, you can create custom rules in {{ic|/etc/polkit-1/rules.d/}}. This allows you to override password authentication either [[#For_specific_actions|only for specific actions]] or [[#Globally|globally]]. See [https://gist.github.com/4013294/ccacedd69d54de7f2fd5881b546d5192d6a2bddb] for an example rule set.<br />
<br />
==== Globally ====<br />
<br />
Create the following file as root:<br />
{{hc|/etc/polkit-1/rules.d/49-nopasswd_global.rules|<br />
/* Allow members of the wheel group to execute any actions<br />
* without password authentication, similar to "sudo NOPASSWD:"<br />
*/<br />
polkit.addRule(function(action, subject) {<br />
if (subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
Replace {{ic|wheel}} by any group of your preference.<br />
<br />
This will result in automatic authentication for '''any''' action requiring admin rights via Polkit. As such, be careful with the group you choose to give such rights to.<br />
<br />
==== For specific actions ====<br />
<br />
Create the following file as root:<br />
{{hc|/etc/polkit-1/rules.d/49-nopasswd_limited.rules|<nowiki><br />
/* Allow members of the wheel group to execute the defined actions <br />
* without password authentication, similar to "sudo NOPASSWD:"<br />
*/<br />
polkit.addRule(function(action, subject) {<br />
if ((action.id == "org.archlinux.pkexec.gparted" ||<br />
action.id == "org.libvirt.unix.manage") &&<br />
subject.isInGroup("wheel"))<br />
{<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
The {{ic|action.id}}s selected here are just (working) examples for GParted and [[Libvirt]], but you can replace them by any other of your liking as long as they exist (custom made or supplied by a package), and so can you define any group instead of {{ic|wheel}}.<br />
<br />
The {{ic|<nowiki>||</nowiki>}} operator is used to delimit actions (logical OR), and {{ic|&&}} means logical AND and must be kept as the last operator.<br />
<br />
==== Udisks ====<br />
<br />
[[File manager]]s may ask for a password when trying to mount a storage device, or yield a ''Not authorized'' or similar error. See [[Udisks#Configuration]] for details.<br />
<br />
=== Allow management of individual systemd units by regular users ===<br />
<br />
By checking for certain values passed to the polkit policy check, you can give specific users or groups the ability to manage specific units. As an example, you might want regular users to start and stop [[wpa_supplicant]]:<br />
<br />
{{hc|/etc/polkit-1/rules.d/10-wifimanagement.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.freedesktop.systemd1.manage-units") {<br />
if (action.lookup("unit") == "wpa_supplicant.service") {<br />
var verb = action.lookup("verb");<br />
if (verb == "start" || verb == "stop" || verb == "restart") {<br />
return polkit.Result.YES;<br />
}<br />
}<br />
}<br />
});</nowiki><br />
}}<br />
<br />
== See also ==<br />
<br />
* [http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html Polkit manual page]<br />
* [https://doc.opensuse.org/documentation/leap/security/html/book.security/cha.security.policykit.html Authorization with PolKit] (openSUSE Leap 42.2 Security guide)</div>Ketsuihttps://wiki.archlinux.org/index.php?title=General_troubleshooting&diff=511722General troubleshooting2018-02-23T05:03:41Z<p>Ketsui: /* Kernel panics */ Fix typo</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:System recovery]]<br />
[[Category:Getting and installing Arch]]<br />
[[es:General troubleshooting]]<br />
[[ja:一般的なトラブルシューティング]]<br />
[[ru:General troubleshooting]]<br />
{{Related articles start}}<br />
{{Related|Reporting bug guidelines}}<br />
{{Related|Step-by-step debugging guide}}<br />
{{Related|Debug - Getting Traces}}<br />
{{Related|IRC Collaborative Debugging}}<br />
{{Related articles end}}<br />
<br />
This article explains some methods for general troubleshooting. For application specific issues, please reference the particular wiki page for that program.<br />
<br />
== General procedures ==<br />
<br />
=== Attention to detail ===<br />
<br />
In order to resolve an issue that you are having, it is ''absolutely crucial'' to have a firm basic understanding of how that specific subsystem functions. How does it work, and what does it need to run without error? If you cannot comfortably answer these question then you would best review the [[Table of contents|Archwiki]] article for the subsystem that you are having trouble with. Once you feel like you've understood it, it will be easier for you to pinpoint the cause of the problem.<br />
<br />
=== Questions/checklist ===<br />
<br />
The following gives a number of questions for you whenever dealing with a malfunctioning system. Under each question there are notes explaining how you should be answering each question, followed by some light examples on how to easily gather data output and what tools can be used to review logs and the journal.<br />
<br />
# What is the issue(s)?<br />
#: Be ''as precise as possible''. This will help you not get confused and/or side-tracked when looking up specific information.<br />
# Are there error messages? (if any)<br />
#: Copy and paste ''full outputs'' that contain '''error messages''' related to your issue into a separate file, such as {{ic|$HOME/issue.log}}. For example, to forward the output of the following [[mkinitcpio]] command to {{ic|$HOME/issue.log}}:<br />
#: {{bc|$ mkinitcpio -p linux >> $HOME/issue.log''}}<br />
# Can you reproduce the issue?<br />
#: If so, give ''exact'' '''step-by-step''' instructions/commands needed to do so.<br />
# When did you first encounter these issues and what was changed between then and when the system was operating without error?<br />
#:If it occurred right after an update then, list '''all packages that were updated'''. Include ''version numbers'', also, paste the entire update from [[pacman]].log ({{ic|/var/log/pacman.log}}). Also take note of the statuses of ''any'' service(s) needed to support the malfunctioning application(s) using [[systemd]]'s systemctl tools. For example, to forward the output of the following [[Systemd#Basic_systemctl_usage|systemd]] command to {{ic|$HOME/issue.log}}:<br />
#: {{bc|$ systemctl status dhcpcd@eth0.service >> $HOME/issue.log}}<br />
#: {{Note|Using {{ic|'''>>'''}} will ensure any previous text in {{ic|$HOME/issue.log}} will not be overwritten.}}<br />
<br />
=== Approach ===<br />
<br />
Rather than approaching an issue by stating,<br />
<br />
''Application X does not work.''<br />
<br />
you will find it more helpful to formulate your issue in the context of the system as a whole, as:<br />
<br />
''Application X produces Y error(s) when performing Z tasks under conditions A and B.<br />
<br />
=== Additional support ===<br />
<br />
With all the information in front of you you should have a good idea as to what is going on with the system and you can now start working on a proper fix.<br />
<br />
If you require any additional support, it can be found on [https://bbs.archlinux.org the forums] or IRC at irc.freenode.net #archlinux. See [[IRC channels]] for other options.<br />
<br />
{{Note|[[Code of conduct#Arch Linux distribution support .2Aonly.2A|Support is provided for Arch Linux ''only'']] and not [[Arch-based distributions]].}}<br />
<br />
When asking for support post the '''complete''' output/logs, not just what you think are the significant sections. Sources of information include:<br />
<br />
* Full output of any command involved - don't just select what you think is relevant.<br />
* Output from systemd's {{ic|journalctl}}. For more extensive output, use the {{ic|1=systemd.log_level=debug}} boot parameter.<br />
* Log files (have a look in {{ic|/var/log}})<br />
* Relevant configuration files<br />
* Drivers involved<br />
* Versions of packages involved<br />
* Kernel: {{ic|dmesg}}. For a boot problem, at least the last 10 lines displayed, preferably more<br />
* Networking: Exact output of commands involved, and any configuration files<br />
* Xorg: {{ic|/var/log/Xorg.0.log}}, and prior logs if you have overwritten the problematic one<br />
* Pacman: If a recent upgrade broke something, look in {{ic|/var/log/pacman.log}}<br />
<br />
One of the better ways to post this information is to use an online pastebin. You can [[install]] the {{pkg|pbpst}} or {{pkg|gist}} package to automatically upload information. For example, to upload the content of your systemd journal from this boot you would do:<br />
<br />
# journalctl -xb | pbpst -S<br />
<br />
A link will then be output that you can paste to the forum or IRC.<br />
<br />
Additionally, before posting your question, you may wish to review [http://www.catb.org/esr/faqs/smart-questions.html how to ask smart questions]. See also [[Code of conduct]].<br />
<br />
== Boot problems ==<br />
<br />
Diagnosing errors during the [[boot process]] involves changing the [[kernel parameters]], and rebooting the system.<br />
<br />
If booting the system is not possible, boot from a [https://www.archlinux.org/download/ live image] and [[change root]] to the existing system.<br />
<br />
=== Console messages ===<br />
<br />
After the boot process, the screen is cleared and the login prompt appears, leaving users unable to read init output and error messages. This default behavior may be modified using methods outlined in the sections below.<br />
<br />
Note that regardless of the chosen option, kernel messages can be displayed for inspection after booting by using {{ic|dmesg}} or all logs from the current boot with {{ic|journalctl -b}}.<br />
<br />
==== Flow control ====<br />
<br />
This is basic management that applies to most terminal emulators, including virtual consoles (vc):<br />
<br />
* Press {{ic|Ctrl+S}} to pause the output<br />
* And {{ic|Ctrl+Q}} to resume it<br />
<br />
This pauses not only the output, but also programs which try to print to the terminal, as they will block on the {{ic|write()}} calls for as long as the output is paused. If your ''init'' appears frozen, make sure the system console is not paused.<br />
<br />
To see error messages which are already displayed, see [[Getty#Have boot messages stay on tty1]].<br />
<br />
==== Scrollback ====<br />
<br />
Scrollback allows the user to go back and view text which has scrolled off the screen of a text console. This is made possible by a buffer created between the video adapter and the display device called the scrollback buffer. By default, the key combinations of {{ic|Shift+PageUp}} and {{ic|Shift+PageDown}} scroll the buffer up and down.<br />
<br />
If scrolling up all the way does not show you enough information, you need to expand your scrollback buffer to hold more output. This is done by tweaking the kernel's framebuffer console (fbcon) with the [[kernel parameter]] {{ic|1=fbcon=scrollback:Nk}} where {{ic|N}} is the desired buffer size is kilobytes. The default size is 32k.<br />
<br />
If this does not work, your framebuffer console may not be properly enabled. Check the [https://www.kernel.org/doc/Documentation/fb/fbcon.txt Framebuffer Console documentation] for other parameters, e.g. for changing the framebuffer driver.<br />
<br />
==== Debug output ====<br />
<br />
Most kernel messages are hidden during boot. You can see more of these messages by adding different kernel parameters. The simplest ones are:<br />
<br />
* {{ic|debug}} enables debug messages for both the kernel and [[systemd]]<br />
* {{ic|ignore_loglevel}} forces ''all'' kernel messages to be printed<br />
<br />
Other parameters you can add that might be useful in certain situations are:<br />
* {{ic|1=earlyprintk=vga,keep}} prints kernel messages very early in the boot process, in case the kernel would crash before output is shown. You must change {{ic|vga}} to {{ic|efi}} for [[EFI]] systems<br />
* {{ic|1=log_buf_len=16M}} allocates a larger (16MB) kernel message buffer, to ensure that debug output is not overwritten<br />
<br />
There are also a number of separate debug parameters for enabling debugging in specific subsystems e.g. {{ic|bootmem_debug}}, {{ic|sched_debug}}. Check the [https://www.kernel.org/doc/Documentation/kernel-parameters.txt kernel parameter documentation] for specific information.<br />
<br />
{{Note|If you cannot scroll back far enough to view the desired boot output, you should increase the size of the [[#Scrollback|scrollback buffer]].}}<br />
<br />
=== Recovery shells ===<br />
<br />
Getting an interactive shell at some stage in the boot process can help you pinpoint exactly where and why something is failing. There are several kernel parameters for doing so, but they all launch a normal shell which you can {{ic|exit}} to let the kernel resume what it was doing:<br />
* {{ic|rescue}} launches a shell shortly after the root filesystem is remounted read/write<br />
* {{ic|emergency}} launches a shell even earlier, before most filesystems are mounted<br />
* {{ic|1=init=/bin/sh}} (as a last resort) changes the init program to a root shell. {{ic|rescue}} and {{ic|emergency}} both rely on [[systemd]], but this should work even if ''systemd'' is broken<br />
<br />
Another option is systemd's debug-shell which adds a root shell on {{ic|tty9}} (accessible with Ctrl+Alt+F9). It can be enabled by either adding {{ic|systemd.debug-shell}} to the [[kernel parameters]], or by [[enabling]] {{ic|debug-shell.service}}. Take care to disable the service when done to avoid the security risk of leaving a root shell open on every boot.<br />
<br />
=== Blank screen with Intel video ===<br />
<br />
This is most likely due to a problem with [[kernel mode setting]]. Try [[Kernel mode setting#Disabling modesetting|disabling modesetting]] or changing the [[Intel#KMS Issue: console is limited to small area|video port]].<br />
<br />
=== Stuck while loading the kernel ===<br />
<br />
Try disabling ACPI by adding the {{ic|1=acpi=off}} kernel parameter.<br />
<br />
=== Debugging kernel modules ===<br />
<br />
See [[Kernel modules#Obtaining information]].<br />
<br />
=== Debugging hardware ===<br />
<br />
* You can display extra debugging information about your hardware by following [[udev#Debug output]].<br />
* Ensure that [[Microcode]] updates are applied on your system.<br />
* Test your device's RAM with [http://www.memtest.org/ Memtest86+]. Unstable RAM may lead to some extremely odd issues, ranging from random crashes to data corruption.<br />
<br />
== Kernel panics ==<br />
<br />
A ''kernel panic'' occurs when the Linux kernel enters an unrecoverable failure state. The state typically originates from buggy hardware drivers resulting in the machine being deadlocked, non-responsive, and requiring a reboot. Just prior to deadlock, a diagnostic message is generated, consisting of: the ''machine state'' when the failure ocurred, a ''call trace'' leading to the kernel function that recognized the failure, and a listing of currently loaded modules. Thankfully, kernel panics don't happen very often using ''mainline'' versions of the kernel--such as those supplied by the official repositories--but when they do happen, you need to know how to deal with them.<br />
<br />
{{Note|Kernel panics are sometimes referred to as ''oops'' or ''kernel oops''. While both panics and oops occur as the result of a failure state, an ''oops'' is more general in that it does not ''necessarily'' result in a deadlocked machine--sometimes the kernel can recover from an oops by killing the offending task and carrying on.}}<br />
<br />
{{Tip|Pass the kernel parameter {{ic|1=oops=panic}} at boot or write {{ic|1}} to {{ic|/proc/sys/kernel/panic_on_oops}} to force a recoverable oops to issue a panic instead. This is advisable if you are concerned about the small chance of system instability resulting from an oops recovery which may make future errors difficult to diagnose.}}<br />
<br />
=== Examine panic message ===<br />
<br />
If a kernel panic occurs very early in the boot process, you may see a message on the console containing "Kernel panic - not syncing:", but once [[Systemd]] is running, kernel messages will typically be captured and written to the system log. However, when a panic occurs, the diagnostic message output by the kernel is ''almost never'' written to the log file on disk because the machine deadlocks before {{ic|system-journald}} gets the chance. Therefore, the only way to examine the panic message is to view it on the console as it happens (without resorting to setting up a ''kdump crashkernel''). You can do this by booting with the following kernel parameters and attempting to reproduce the panic on tty1:<br />
<br />
{{bc|1=systemd.journald.forward_to_console=1 console=tty1}}<br />
<br />
{{Tip|In the event that the panic message scrolls away too quickly to examine, try passing the kernel parameter {{ic|1=pause_on_oops=''seconds''}} at boot.}}<br />
<br />
==== Example scenario: bad module ====<br />
<br />
It is possible to make a best guess as to what subsystem or module is causing the panic using the information in the diagnostic message. In this scenario, we have a panic on some imaginary machine during boot. Pay attention to the lines highlighted in '''bold''':<br />
<br />
{{bc|'''kernel: BUG: unable to handle kernel NULL pointer dereference at (null)''' [1]<br />
'''kernel: IP: fw_core_init+0x18/0x1000 [firewire_core]''' [2]<br />
kernel: PGD 718d00067 <br />
kernel: P4D 718d00067 <br />
kernel: PUD 7b3611067 <br />
kernel: PMD 0 <br />
kernel: <br />
kernel: Oops: 0002 [#1] PREEMPT SMP<br />
'''kernel: Modules linked in: firewire_core(+) crc_itu_t cfg80211 rfkill ipt_REJECT nf_reject_ipv4 nf_log_ipv4 nf_log_common xt_LOG nf_conntrack_ipv4 ...''' [3] <br />
kernel: CPU: 6 PID: 1438 Comm: modprobe Tainted: P O 4.13.3-1-ARCH #1<br />
kernel: Hardware name: Gigabyte Technology Co., Ltd. H97-D3H/H97-D3H-CF, BIOS F5 06/26/2014<br />
kernel: task: ffff9c667abd9e00 task.stack: ffffb53b8db34000<br />
kernel: RIP: 0010:fw_core_init+0x18/0x1000 [firewire_core]<br />
kernel: RSP: 0018:ffffb53b8db37c68 EFLAGS: 00010246<br />
kernel: RAX: 0000000000000000 RBX: 0000000000000000 RCX: 0000000000000000<br />
kernel: RDX: 0000000000000000 RSI: 0000000000000008 RDI: ffffffffc16d3af4<br />
kernel: RBP: ffffb53b8db37c70 R08: 0000000000000000 R09: ffffffffae113e95<br />
kernel: R10: ffffe93edfdb9680 R11: 0000000000000000 R12: ffffffffc16d9000<br />
kernel: R13: ffff9c6729bf8f60 R14: ffffffffc16d5710 R15: ffff9c6736e55840<br />
kernel: FS: 00007f301fc80b80(0000) GS:ffff9c675dd80000(0000) knlGS:0000000000000000<br />
kernel: CS: 0010 DS: 0000 ES: 0000 CR0: 0000000080050033<br />
kernel: CR2: 0000000000000000 CR3: 00000007c6456000 CR4: 00000000001406e0<br />
kernel: Call Trace:<br />
'''kernel: do_one_initcall+0x50/0x190''' [4]<br />
kernel: ? do_init_module+0x27/0x1f2<br />
kernel: do_init_module+0x5f/0x1f2<br />
kernel: load_module+0x23f3/0x2be0<br />
kernel: SYSC_init_module+0x16b/0x1a0<br />
kernel: ? SYSC_init_module+0x16b/0x1a0<br />
kernel: SyS_init_module+0xe/0x10<br />
kernel: entry_SYSCALL_64_fastpath+0x1a/0xa5<br />
kernel: RIP: 0033:0x7f301f3a2a0a<br />
kernel: RSP: 002b:00007ffcabbd1998 EFLAGS: 00000246 ORIG_RAX: 00000000000000af<br />
kernel: RAX: ffffffffffffffda RBX: 0000000000c85a48 RCX: 00007f301f3a2a0a<br />
kernel: RDX: 000000000041aada RSI: 000000000001a738 RDI: 00007f301e7eb010<br />
kernel: RBP: 0000000000c8a520 R08: 0000000000000001 R09: 0000000000000085<br />
kernel: R10: 0000000000000000 R11: 0000000000000246 R12: 0000000000c79208<br />
kernel: R13: 0000000000c8b4d8 R14: 00007f301e7fffff R15: 0000000000000030<br />
kernel: Code: <c7> 04 25 00 00 00 00 01 00 00 00 bb f4 ff ff ff e8 73 43 9c ec 48 <br />
kernel: RIP: fw_core_init+0x18/0x1000 [firewire_core] RSP: ffffb53b8db37c68<br />
kernel: CR2: 0000000000000000<br />
kernel: ---[ end trace 71f4306ea1238f17 ]---<br />
'''kernel: Kernel panic - not syncing: Fatal exception''' [5]<br />
kernel: Kernel Offset: 0x80000000 from 0xffffffff810000000 (relocation range: 0xffffffff800000000-0xfffffffffbffffffff<br />
kernel: ---[ end Kernel panic - not syncing: Fatal exception}}<br />
<br />
* [1] Indicates the type of error that caused the panic. In this case it was a programmer bug.<br />
* [2] Indicates that the panic happened in a function called ''fw_core_init'' in module ''firewire_core''.<br />
* [3] Indicates that ''firewire_core'' was the latest module to be loaded.<br />
* [4] Indicates that the function that called function ''fw_core_init'' was ''do_one_initcall''.<br />
* [5] Indicates that this ''oops'' message is, in fact, a kernel panic and the system is now deadlocked.<br />
<br />
We can surmise then, that the panic occurred during the initialization routine of module ''firewire_core'' as it was loaded. (We might assume then, that the machine's firewire hardware is incompatible with this version of the firewire driver module due to a programmer error, and will have to wait for a new release.) In the meantime, the easiest way to get the machine running again is to prevent the module from being loaded. We can do this in one of two ways:<br />
<br />
* If the module is being loaded during the execution of the ''initramfs'', reboot with the kernel parameter {{ic|1=rd.blacklist=firewire_core}}.<br />
* Otherwise reboot with the kernel parameter {{ic|1=module_blacklist=firewire_core}}.<br />
<br />
=== Reboot into root shell and fix problem ===<br />
<br />
You'll need a root shell to make changes to the system so the panic no longer occurs. If the panic occurs on boot, there are several strategies to obtain a root shell before the machine deadlocks:<br />
<br />
* Reboot with the kernel parameter {{ic|emergency}}, {{ic|rd.emergency}}, or {{ic|-b}} to receive a prompt to login just after the root filesystem is mounted and {{ic|systemd}} is started.<br />
: {{Note|At this point, the root filesystem will be mounted '''read-only'''. Execute {{ic|# mount -o remount,rw /}} to make changes.}}<br />
* Reboot with the kernel parameter {{ic|rescue}}, {{ic|rd.rescue}}, {{ic|single}}, {{ic|s}}, {{ic|S}}, or {{ic|1}} to receive a prompt to login just after local filesystems are mounted.<br />
* Reboot with the kernel parameter {{ic|1=systemd.debug-shell=1}} to obtain a very early root shell on tty9. Switch to it with by pressing {{ic|Ctrl-Alt-F9}}.<br />
* Experiment by rebooting with different sets of kernel parameters to possibly disable the kernel feature that is causing the panic. Try the "old standbys" {{ic|1=acpi=off}} and {{ic|nolapic}}.<br />
: {{Tip|See {{ic|Documentation/admin-guide/kernel-parameters.txt}} in the Linux kernel source tree for all parameters.}}<br />
* As a last resort, boot with the '''Arch Linux Installation CD''' and mount the root filesystem on {{ic|/mnt}} then execute {{ic|# arch-chroot /mnt}}.<br />
<br />
Disable the service or program that is causing the panic, roll-back a faulty update, or fix a configuration problem.<br />
<br />
== Package management ==<br />
<br />
See [[Pacman#Troubleshooting]] for general topics, and [[pacman/Package signing#Troubleshooting]] for issues with PGP keys.<br />
<br />
== fuser ==<br />
<br />
{{Expansion|Needs more information about its usage}}<br />
<br />
''fuser'' is a command-line utility for identifying processes using resources such as files, filesystems and TCP/UDP ports.<br />
<br />
''fuser'' is provided by the {{Pkg|psmisc}} package, which should be already installed as part of the {{Grp|base}} group. See {{man|1|fuser}} for detail.<br />
<br />
== Session permissions ==<br />
<br />
{{Note|You must be using [[systemd]] as your init system for local sessions to work.[https://www.archlinux.org/news/d-bus-now-launches-user-buses/] It is required for polkit permissions and ACLs for various devices (see {{ic|/usr/lib/udev/rules.d/70-uaccess.rules}} and [http://enotty.pipebreaker.pl/2012/05/23/linux-automatic-user-acl-management/])}}<br />
<br />
First, make sure you have a valid local session within X:<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
This should contain {{ic|1=Remote=no}} and {{ic|1=Active=yes}} in the output. If it does not, make sure that X runs on the same tty where the login occurred. This is required in order to preserve the logind session.<br />
<br />
A D-Bus session should also be started along with X. See [[D-Bus#Starting the user session]] for more information on this.<br />
<br />
Basic [[polkit]] actions do not require further set-up. Some polkit actions require further authentication, even with a local session. A polkit authentication agent needs to be running for this to work. See [[polkit#Authentication agents]] for more information on this.<br />
<br />
== Message: "error while loading shared libraries" ==<br />
<br />
{{Accuracy|Or the program needs to be rebuilt after a [[System_maintenance#Partial_upgrades_are_unsupported|soname bump]].}}<br />
<br />
If, while using a program, you get an error similar to: <br />
<br />
error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory<br />
<br />
Use [[pacman]] or [[pkgfile]] to search for the package that owns the missing library:<br />
<br />
{{hc|$ pacman -Fs libusb-0.1.so.4|<br />
extra/libusb-compat 0.1.5-1<br />
usr/lib/libusb-0.1.so.4<br />
}}<br />
<br />
In this case, the {{Pkg|libusb-compat}} package needs to be [[installed]].<br />
<br />
The error could also mean that the package that you used to install your program does not list the library as a dependency in its [[PKGBUILD]]: if it is an official package, [[report a bug]]; if it is an [[AUR]] package, report it to the maintainer using its page in the AUR website.<br />
<br />
== Message: "file: could not find any magic files!" ==<br />
<br />
If you see this message, it likely indicates that a package update has corrupted the dynamic linker run-time bindings file and your system is now essentially crippled. You will not be able to recompile or reinstall the package responsible or rebuild the [[initramfs]] until you fix it.<br />
<br />
=== Problem ===<br />
<br />
A package update likely added an invalid {{ic|''filename''.conf}} to the directory {{ic|/etc/ld.so.conf.d}} or edited {{ic|/etc/ld.so.conf}} incorrectly. The result is that the dynamic linker run-time bindings file {{ic|/etc/ld.so.cache}} is being re-generated with invalid data. This can potentially cause all programs on the system that depend on shared libraries to fail (ie. almost all of them).<br />
<br />
=== Solution ===<br />
<br />
# Boot with the '''''Arch Linux Installation CD'''''.<br />
# Mount your root {{ic|/}} filesystem on {{ic|/mnt}} and your {{ic|/boot}} filesystem on {{ic|/mnt/boot}} and chroot into the broken system by executing {{ic|# arch-chroot /mnt}}.<br />
# Examine the file {{ic|/etc/ld.so.conf}} and remove any invalid lines found.<br />
# Examine the files located in the directory {{ic|/etc/ld.so.conf.d/}} and remove any invalid files.<br />
# Rebuild the dynamic linker run-time bindings file {{ic|/etc/ld.so.cache}} by executing {{ic|# ldconfig}}.<br />
# Rebuild the [[Initramfs]] by executing {{ic|# mkinitcpio -p linux}}.<br />
# Exit the chroot, unmount filesystems, and reboot back into your installed system.<br />
<br />
== See also ==<br />
<br />
* [http://www.tuxradar.com/content/how-fix-most-common-linux-problems Fix the Most Common Problems]{{Dead link|2018|02|05}}<br />
* [https://www.reddit.com/r/archlinux/comments/tjjwr/archlinux_a_howto_in_troubleshooting_for_newcomers/ A how-to in troubleshooting for newcomers]<br />
* [http://wiki.ultimatebootcd.com/index.php?title=Tools List of Tools for UBCD] - Memtest-like tools to add to grub.cfg on UltimateBootCD.com<br />
* [[Wikipedia:BIOS Boot partition]]<br />
* [[REISUB]]<br />
* [http://freedesktop.org/wiki/Software/systemd/Debugging#Debug_Logging_to_a_Serial_Console Debug Logging to a Serial Console] on Freedesktop.org<br />
* [https://web.archive.org/web/20120217124742/http://www.lesswatts.org/projects/acpi/debug.php How to Isolate Linux ACPI Issues] on Archive.org</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Dhcpcd&diff=511681Dhcpcd2018-02-22T19:24:37Z<p>Ketsui: /* Timeout delay */ Fix typo</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network configuration]]<br />
[[ja:Dhcpcd]]<br />
[[ru:Dhcpcd]]<br />
[[zh-hans:Dhcpcd]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|dhcpd}}<br />
{{Related articles end}}<br />
<br />
''dhcpcd'' is a DHCP and DHCPv6 client. It is currently the most feature-rich open source DHCP client, see the [https://roy.marples.name/projects/dhcpcd home page] for the full list of features.<br />
<br />
{{Note|''dhcpcd'' (DHCP '''client''' daemon) is not the same as [[dhcpd]] (DHCP '''(server)''' daemon).}}<br />
<br />
== Installation ==<br />
<br />
The {{Pkg|dhcpcd}} package is part of the {{Grp|base}} group, so it is likely already installed on your system.<br />
<br />
{{AUR|dhcpcd-ui}} is a [[GTK+]] frontend for the ''dhcpcd'' daemon, and optionally [[WPA supplicant]]. It features a configuration dialogue and the ability to enter a pass phrase for wireless networks.<br />
<br />
== Running ==<br />
<br />
To start the daemon for ''all'' network interfaces, [[start/enable]] {{ic|dhcpcd.service}}.<br />
<br />
To start the daemon for a specific interface alone, [[start/enable]] the template unit {{ic|dhcpcd@''interface''.service}}, where ''interface'' can be found with [[Network configuration#Get current interface names]].<br />
<br />
Using the template unit is recommended; see [[#dhcpcd and systemd network interfaces]] for details.<br />
<br />
Alternatively, to start ''dhcpcd'' manually, run the following command:<br />
<br />
# dhcpcd ''interface''<br />
<br />
In all of the above, you will be assigned a dynamic IP address. To assign a static IP address, see [[#Static profile]].<br />
<br />
== Configuration ==<br />
<br />
The main configuration is done in {{ic|/etc/dhcpcd.conf}}. See {{man|5|dhcpcd.conf}} for details. Some of the frequently used options are highlighted below.<br />
<br />
=== DHCP static route(s) ===<br />
<br />
If you need to add a static route client-side, add it to {{ic|/etc/dhcpcd.exit-hook}}. The example shows a new hook-script which adds a static route to a VPN subnet on {{ic|10.11.12.0/24}} via a gateway machine at {{ic|192.168.192.5}}:<br />
<br />
{{hc|/etc/dhcpcd.exit-hook|<br />
ip route add 10.11.12.0/24 via 192.168.192.5<br />
}}<br />
<br />
You can add multiple routes to this file.<br />
=== DHCP Client Identifier ===<br />
<br />
The DHCP client may be uniquely identified in different ways by the server: <br />
# hostname (or the hostname value sent by the client), <br />
# MAC address of the network interface controller through which the connection is being made, linked to this is the third, <br />
# Identity Association ID (IAID), which is an abstraction layer to differentiate different use-cases and/or interfaces on a single host, <br />
# DHCP Unique Identifier (DUID). <br />
For a further description, see [https://tools.ietf.org/html/rfc3315#section-4.2 RFC 3315]. <br />
<br />
It depends on the DHCP-server configuration which options are optional or required to request a DHCP IP lease. <br />
{{Note|The ''dhcpcd'' default configuration should be sufficient usually. The listed identifiers are determined automatically and manual configuration changes only be required in case of problems.}} <br />
<br />
If the ''dhcpcd'' default configuration fails to obtain an IP, the following options are available to use in {{ic|dhcpcd.conf}}: <br />
* {{ic|hostname}} sends the hostname set in {{ic|/etc/hostname}}<br />
* {{ic|clientid}} sends the MAC address as identifier<br />
* {{ic|iaid <interface>}} derives the IAID to use for DHCP discovery. It has to be used in an interface block (started by {{ic|interface <interface>}}, see [https://bbs.archlinux.org/viewtopic.php?pid=1388376#p1388376]), but more frequently the next option is used: <br />
* {{ic|duid}} triggers using a combination of DUID and IAID as identifier. <br />
<br />
The DUID value is set in {{ic|/etc/dhcpcd.duid}}. For efficient DHCP lease operation it is important that it is unique for the system and applies to all network interfaces alike, while the IAID represents an identifier for each of the systems' interfaces (see [https://tools.ietf.org/html/rfc4361#section-6.1 RFC 4361]). <br />
<br />
Care must be taken on a network running [[Wikipedia:Dynamic DNS|Dynamic DNS]] to ensure that all three IDs are unique. If duplicate DUID values are presented to the DNS server, e.g. in the case where a virtual machine has been cloned and the hostname and MAC have been made unique but the DUID has not been changed, then the result will be that as each client with the duplicated DUID requests a lease the server will remove the predecessor from the DNS record.<br />
<br />
=== Static profile ===<br />
<br />
Required settings are explained in [[Network configuration#Static IP address]]. These typically include the [[Network_configuration#Device_names|device name]]{{Broken section link}}, ''IP address'', ''router address'', and ''name server''.<br />
<br />
Configure a static profile for ''dhcpcd'' in {{ic|/etc/dhcpcd.conf}}, for example: <br />
<br />
{{hc|1=/etc/dhcpcd.conf|2=<br />
interface eth0<br />
static ip_address=192.168.0.10/24 <br />
static routers=192.168.0.1<br />
static domain_name_servers=192.168.0.1 8.8.8.8<br />
}}<br />
<br />
More complicated configurations are possible, for example combining with the {{ic|arping}} option. See {{man|5|dhcpcd.conf}} for details.<br />
<br />
==== Fallback profile ====<br />
<br />
It is possible to configure a static profile within ''dhcpcd'' and fall back to it when DHCP lease fails. This is useful particularly for [[wikipedia:Headless computer|headless machines]], where the static profile can be used as "recovery" profile to ensure that it is always possible to connect to the machine.<br />
<br />
The following example configures a {{ic|static_eth0}} profile with {{ic|192.168.1.23}} as IP address, {{ic|192.168.1.1}} as gateway and name server, and makes this profile fallback for interface {{ic|eth0}}.<br />
<br />
{{hc|1=/etc/dhcpcd.conf|2=<br />
# define static profile<br />
profile static_eth0<br />
static ip_address=192.168.1.23/24<br />
static routers=192.168.1.1<br />
static domain_name_servers=192.168.1.1<br />
<br />
# fallback to static profile on eth0<br />
interface ''eth0''<br />
fallback static_eth0<br />
}}<br />
<br />
== Hooks ==<br />
<br />
''dhcpcd'' executes all scripts found in {{ic|/usr/lib/dhcpcd/dhcpcd-hooks/}} in a lexical order. See {{man|5|dhcpcd.conf}} and {{man|8|dhcpcd-run-hooks}} for details.<br />
<br />
{{Note|<br />
* Each script can be disabled using the {{ic|nohook}} option in {{ic|dhcpcd.conf}}.<br />
* The {{ic|env}} option can be used to set an environment variable for '''all''' hooks. For example, you can force the hostname hook to always set the hostname with {{ic|1=env force_hostname=YES}}.<br />
}}<br />
<br />
{{Expansion|describe (at least some) provided hooks.}}<br />
<br />
=== 10-wpa_supplicant ===<br />
<br />
Enable this hook by creating a symbolic link (to ensure that always the current version is used, even after package updates):<br />
<br />
# ln -s /usr/share/dhcpcd/hooks/10-wpa_supplicant /usr/lib/dhcpcd/dhcpcd-hooks/<br />
<br />
The {{ic|10-wpa_supplicant}} hook, if enabled, automatically launches [[WPA supplicant]] on wireless interfaces. It is started only if:<br />
<br />
* no ''wpa_supplicant'' process is already listening on that interface.<br />
* a ''wpa_supplicant'' configuration file exists. ''dhcpcd'' checks<br />
<br />
/etc/wpa_supplicant/wpa_supplicant-''interface''.conf<br />
/etc/wpa_supplicant/wpa_supplicant.conf<br />
/etc/wpa_supplicant-''interface''.conf<br />
/etc/wpa_supplicant.conf<br />
<br />
by default, in that order, but a custom path can be set by adding {{ic|1=env wpa_supplicant_conf=''configuration_file_path''}} into {{ic|/etc/dhcpcd.conf}}.<br />
<br />
{{Note|The hook stops at the first configuration file found, thus you should take this into consideration if you have several ''wpa_supplicant'' configuration files, otherwise ''dhcpcd'' might end up using the wrong file.}}<br />
<br />
If you manage wireless connections with ''wpa_supplicant'' itself, the hook may create unwanted connection events. For example, if you stop ''wpa_supplicant'' the hook may bring the interface up again. Also, if you use [[Netctl#Special systemd units|netctl-auto]], ''wpa_supplicant'' is started automatically with {{ic|/run/network/wpa_supplicant_''interface''.conf}} for config, so starting it again from the hook is unnecessary and may result in boot-time parse errors of the {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} file, which only contains dummy values in the default packaged version. <br />
<br />
To disable the hook, add {{ic|nohook wpa_supplicant}} to {{ic|dhcpcd.conf}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Speed up DHCP by disabling ARP probing ===<br />
<br />
''dhcpcd'' contains an implementation of a recommendation of the DHCP standard ([https://www.ietf.org/rfc/rfc2131.txt RFC2131] section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to {{ic|/etc/dhcpcd.conf}}:<br />
<br />
noarp<br />
<br />
This is equivalent to passing {{ic|--noarp}} to {{ic|dhcpcd}}, and disables the described ARP probing, speeding up connections to networks with DHCP.<br />
<br />
=== Remove old DHCP lease ===<br />
<br />
The file {{ic|/var/lib/dhcpcd/dhcpcd-''interface''.lease}}, where {{ic|''interface''}} is the name of the interface on which you have a lease, contains the actual DHCP lease reply sent by the DHCP server. It is used to determine the last lease from the server, and its {{ic|mtime}} attribute is used to determine when it was issued. This last lease information is then used to request the same IP address previously held on a network, if it is available. If you do not want that, simply delete this file. <br />
<br />
If the DHCP server still assigns the same IP address, this may happen because it is configured to keep the assignment stable and recognizes the requesting DHCP client id or DUID (see [[#DHCP Client Identifier]]). You can test it by stopping ''dhcpcd'' and removing or renaming {{ic|/etc/dhcpcd.duid}}. ''dhcpcd'' will generate a new one on next run. <br />
<br />
Keep in mind that the DUID is intended as persistent machine identifier across reboots and interfaces. If you are transferring the system to new computer, preserving this file should make it appear as old one.<br />
<br />
=== Different IPs when multi-booting ===<br />
<br />
If you are dualbooting Arch and OS X or Windows and want each to receive different IP addresses, you can exert control about the IPs leased by specifying a different DUID in each operating system installation. <br />
<br />
In Windows (post XP) the DUID should be stored in the <br />
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters\Dhcpv6DUID <br />
registry key. <br />
<br />
On OS X it is directly accessible in {{ic|Network\adapter\dhcp preferences panel}}.<br />
<br />
If you are using a [[dnsmasq]] DHCP server, the different DUIDs can be used in appropriate {{ic|1=dhcp-host=}} rules in its configuration.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Client ID ===<br />
<br />
If you are on a network with DHCPv4 that filters Client IDs based on MAC addresses, you may need to change the following line:<br />
<br />
{{hc|/etc/dhcpcd.conf|<br />
# Use the same DUID + IAID as set in DHCPv6 for DHCPv4 Client ID as per RFC4361. <br />
duid<br />
}}<br />
<br />
To:<br />
<br />
{{hc|/etc/dhcpcd.conf|<br />
# Use the hardware address of the interface for the Client ID (DHCPv4).<br />
clientid<br />
}}<br />
<br />
Else, you may not obtain a lease since the DHCP server may not read your [[wikipedia:DHCPv6|DHCPv6-style]] Client ID correctly. See [https://tools.ietf.org/html/rfc4361 RFC 4361] for more information.<br />
<br />
=== Check DHCP problem by releasing IP first ===<br />
<br />
A problem may occur when DHCP gets a wrong IP assignment, such as when two routers are tied together through a VPN. The router that is connected through the VPN may be assigning IP address. To fix it, as root, release the IP address:<br />
<br />
# dhcpcd -k<br />
<br />
Then request a new one:<br />
<br />
# dhcpcd<br />
<br />
You may have to run those two commands many times.<br />
<br />
=== Problems with noncompliant routers ===<br />
<br />
For some (noncompliant) routers, you will not be able to connect properly unless you comment the line<br />
<br />
require dhcp_server_identifier<br />
<br />
in {{ic|/etc/dhcpcd.conf}}. This should not cause issues unless you have multiple DHCP servers on your network (not typical); see [https://technet.microsoft.com/en-us/library/cc977442.aspx this page] for more information.<br />
<br />
=== dhcpcd and systemd network interfaces ===<br />
<br />
{{ic|dhcpcd.service}} can be [[enabled]] without specifying an interface. This may, however, create a race condition at boot with ''systemd-udevd'' trying to apply a predictable network interface name: <br />
error changing net interface name wlan0 to wlp4s0: Device or resource busy" <br />
<br />
To avoid it, enable ''dhcpcd'' per interface it should bind to as described in [[#Running]]. The downside of the template unit is, however, that it does not support hot-plugging of a wired connection and will fail if the network cable is not connected. To work-around the failure, see [[#Timeout delay]].<br />
<br />
=== Timeout delay ===<br />
<br />
If ''dhcpcd'' operates on a single interface and fails to obtain a lease after 30 seconds (for example when the server is not ready or the cable not plugged), it will exit with an error. <br />
<br />
To have ''dhcpcd'' wait indefinitely for one-time, set the {{ic|timeout}} option to {{ic|0}}:<br />
<br />
{{hc|/etc/systemd/system/dhcpcd@.service.d/timeout.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/dhcpcd -w -q '''-t 0''' %I<br />
}}<br />
<br />
To have it wait indefinitely, let the unit restart after it exited: <br />
<br />
{{hc|/etc/systemd/system/dhcpcd@.service.d/dhcpcdrestart.conf|2=<br />
[Service]<br />
Restart=always<br />
}}<br />
<br />
After making changes, [[systemd#Editing provided units|reload the configuration]].<br />
<br />
== Known issues ==<br />
<br />
=== dhcpcd@.service causes slow startup ===<br />
<br />
By default the {{ic|dhcpcd@.service}} waits to get an IP address before forking into the background via the {{ic|-w}} flag for ''dhcpcd''. If the unit is enabled, this may cause the boot to wait for an IP address before continuing. To fix this, create a [[systemd#Drop-in files|drop-in file]] for the unit with the following:<br />
<br />
{{hc|/etc/systemd/system/dhcpcd@.service.d/no-wait.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/dhcpcd -b -q %I<br />
}}<br />
<br />
See also {{Bug|49685}}.<br />
<br />
== See also ==<br />
<br />
* {{man|8|dhcpcd}}<br />
* {{man|5|dhcpcd.conf}}</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=510557RetroArch2018-02-12T13:08:54Z<p>Ketsui: /* Installation */ Linkify 'install' Help:Style#Package_management_instructions</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
[[Install]] the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install the {{Pkg|retroarch-assets-xmb}} package to allow the default menu driver (XMB) to work properly. Additionally, install the {{Pkg|retroarch-autoconfig-udev}} package to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enabling the ''Online Updater'' ===<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.<br />
<br />
=== Enabling ''SaveRAM Autosave Interval'' ===<br />
<br />
By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|autosave_interval}} to ''n''.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
autosave_interval = "600"<br />
}}<br />
<br />
With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.<br />
<br />
{{Warning|Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [https://github.com/libretro/RetroArch/issues/4901#issuecomment-300888019]}}<br />
<br />
=== Reset settings to their default value ===<br />
<br />
To reset a setting or keybind to its default value through the GUI, highlight it and press {{ic|Start}}. To remove a button from a keybind, highlight the keybind and press {{ic|Y}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
=== Save data is lost whenever RetroArch crashes ===<br />
<br />
See [[#Enabling SaveRAM Autosave Interval]].<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509968RetroArch2018-02-06T18:06:25Z<p>Ketsui: /* Troubleshooting */ Added /* Save data is lost whenever RetroArch crashes */ and a reword</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enabling the ''Online Updater'' ===<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.<br />
<br />
=== Enabling ''SaveRAM Autosave Interval'' ===<br />
<br />
By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|autosave_interval}} to ''n''.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
autosave_interval = "600"<br />
}}<br />
<br />
With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.<br />
<br />
{{Warning|Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [https://github.com/libretro/RetroArch/issues/4901#issuecomment-300888019]}}<br />
<br />
=== Reset settings to their default value ===<br />
<br />
To reset a setting or keybind to its default value through the GUI, highlight it and press {{ic|Start}}. To remove a button from a keybind, highlight the keybind and press {{ic|Y}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
=== Save data is lost whenever RetroArch crashes ===<br />
<br />
See [[#Enabling SaveRAM Autosave Interval]].<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509967RetroArch2018-02-06T17:57:46Z<p>Ketsui: /* Tips and tricks */ How to reset settings to their default value and how to remove a keybind</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enabling the ''Online Updater'' ===<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.<br />
<br />
=== Enabling ''SaveRAM Autosave Interval'' ===<br />
<br />
By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|autosave_interval}} to ''n''.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
autosave_interval = "600"<br />
}}<br />
<br />
With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.<br />
<br />
{{Warning|Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [https://github.com/libretro/RetroArch/issues/4901#issuecomment-300888019]}}<br />
<br />
=== Reset settings to their default value ===<br />
<br />
To reset a setting or keybind to its default value through the GUI, highlight it and press {{ic|Start}}. To remove a button from a keybind, highlight the keybind and press {{ic|Y}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509964RetroArch2018-02-06T17:01:40Z<p>Ketsui: /* Tips and tricks */ Added a workaround to prevent save data loss when using crash-prone emulator</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enabling the ''Online Updater'' ===<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.<br />
<br />
=== Enabling ''SaveRAM Autosave Interval'' ===<br />
<br />
By default, RetroArch only writes SRAM onto disk when it exits without error, which means that there's a risk of losing save data when using crash-prone cores. To change this behavior, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|autosave_interval}} to ''n''.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
autosave_interval = "600"<br />
}}<br />
<br />
With the example above, RetroArch will write SRAM changes onto disk every 600 seconds.<br />
<br />
{{Warning|Setting this value too low will cause all sorts of issue, most notably hardware degradation. See [https://github.com/libretro/RetroArch/issues/4901#issuecomment-300888019]}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509952RetroArch2018-02-06T15:23:35Z<p>Ketsui: Moved the Online Updater section to /* Tips and tricks */ also a small reword</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Enabling the ''Online Updater'' ===<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an update.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Nestopia&diff=509660Nestopia2018-02-04T11:06:35Z<p>Ketsui: Retroarch > RetroArch</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[https://github.com/0ldsk00l/nestopia Nestopia] is an open-source NES emulator that tries to emulate the NES hardware as accurately as possible. It's available for Windows, macOS, Linux and the BSDs. There is a libretro port as well, see [[RetroArch]] for more information.<br />
<br />
== Installation == <br />
Install the {{Aur|nestopia}} package from the [[AUR]]. Alternatively, install {{Aur|nestopia-git}} for the development version.<br />
<br />
== Troubleshooting ==<br />
=== No audio with libao backend ===<br />
Currently the libao backend is broken. It's recommended to change the audio API to ''SDL'' in ''Emulator -> Configuration -> Audio ''.<br />
<br />
== See also ==<br />
* [http://0ldsk00l.ca/nestopia/ Offical website]<br />
* [https://github.com/0ldsk00l/nestopia GitHub Page]<br />
* [https://nesdir.github.io/ List of NES games]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Touchpad_Synaptics&diff=509657Touchpad Synaptics2018-02-04T10:55:14Z<p>Ketsui: /* evtest */ Ctrl + Alt + F2 instead of Ctrl + Alt + 2 to switch tty</p>
<hr />
<div>[[Category:Input devices]]<br />
[[de:Synaptics Touchpad Treiber]]<br />
[[es:Touchpad Synaptics]]<br />
[[fr:Touchpad Synaptics]]<br />
[[it:Touchpad Synaptics]]<br />
[[ja:Synaptics タッチパッド]]<br />
[[ru:Touchpad Synaptics]]<br />
[[zh-hans:Touchpad Synaptics]]<br />
{{Related articles start}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
This article details the installation and configuration process of the '''''Synaptics input driver''''' for Synaptics (and ALPS) touchpads found on most notebooks.<br />
<br />
{{Warning|{{pkg|xf86-input-synaptics}} is no longer actively updated. If possible, use [[libinput]].}}<br />
<br />
{{Note|1=If you want to configure touchpad via GNOME control center, you need to use the [[libinput]] driver.[https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12]}}<br />
<br />
== Installation ==<br />
<br />
The Synaptics driver can be [[installed]] with the package {{Pkg|xf86-input-synaptics}}.<br />
<br />
== Configuration ==<br />
<br />
The primary method of configuration for the touchpad is through an [[Xorg]] server configuration file. After installation of {{ic|xf86-input-synaptics}}, a default configuration file is located at {{ic|/usr/share/X11/xorg.conf.d/70-synaptics.conf}}. Users can copy this file to {{ic|/etc/X11/xorg.conf.d/}} and edit it to configure the various driver options available. Refer to the {{man|4|synaptics}} manual page for a complete list of available options. Machine-specific options can be discovered using [[#Synclient]].<br />
<br />
=== Frequently used options ===<br />
<br />
The following example file configures some common options, including vertical, horizontal and circular scrolling as well as tap-to-click:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
Option "TapButton1" "1"<br />
Option "TapButton2" "3"<br />
Option "TapButton3" "2"<br />
Option "VertEdgeScroll" "on"<br />
Option "VertTwoFingerScroll" "on"<br />
Option "HorizEdgeScroll" "on"<br />
Option "HorizTwoFingerScroll" "on"<br />
Option "CircularScrolling" "on"<br />
Option "CircScrollTrigger" "2"<br />
Option "EmulateTwoFingerMinZ" "40"<br />
Option "EmulateTwoFingerMinW" "8"<br />
Option "CoastingSpeed" "0"<br />
Option "FingerLow" "30"<br />
Option "FingerHigh" "50"<br />
Option "MaxTapTime" "125"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
; TapButton1: (integer) configures which mouse-button is reported on a non-corner, one finger tap.<br />
; TapButton2: (integer) configures which mouse-button is reported on a non-corner, two finger tap<br />
; TapButton3: (integer) configures which mouse-button is reported on a non-corner, three finger tap<br />
; RBCornerButton: (integer) configures which mouse-button is reported on a right bottom corner, one finger tap (use {{ic|Option "RBCornerButton" "3"}} to achieve Ubuntu style tap behaviour for right mouse button in lower right corner)<br />
; RTCornerButton: (integer) as above, but for top right corner, one finger tap.<br />
; VertEdgeScroll: (boolean) enables vertical scrolling while dragging across the right edge of the touch pad.<br />
; HorizEdgeScroll: (boolean) enables horizontal scrolling while dragging across the bottom edge of the touch pad.<br />
; VertTwoFingerScroll: (boolean) enables vertical scrolling using two fingers.<br />
; HorizTwoFingerScroll: (boolean) enables horizontal scrolling using two fingers.<br />
; EmulateTwoFingerMinZ/W: (integer) play with this value to set the precision of two finger scroll.<br />
; FingerLow: (integer) when finger pressure drops below this value, the driver counts it as a release.<br />
; FingerHigh: (integer) when finger pressure goes above this value, the driver counts it as a touch.<br />
; MaxTapTime: Determines how "crisp" a tap must be to be considered a real tap. Decrease the value to require a more crisp tap. Properly adjusting this parameter can reduce false positives when the hands hover over or lightly touch the pad.<br />
; VertScrollDelta and HorizScrollDelta: (integer) configures the speed of scrolling, it is a bit counter-intuitive because higher values produce greater precision and thus slower scrolling. Negative values cause natural scrolling like in macOS.<br />
<br />
{{Note|<br />
* If you find that your hand frequently brushes your touchpad, causing the {{ic|TapButton2}} option to be triggered (which will more than likely paste from your clipboard), and you do not mind losing two-finger-tap functionality, set {{ic|TapButton2}} to {{ic|0}}. Alternatively, see [[#Disable touchpad while typing]].<br />
* Recent versions include a "Coasting" feature, enabled by default, which may have the undesired effect of continuing almost any scrolling until the next tap or click, even if you are no longer touching the touchpad. This means that to scroll just a bit, you need to scroll (by using the edge, or a multitouch option) and then almost immediately tap the touchpad, otherwise scrolling will continue forever. If wish to avoid this, set {{ic|CoastingSpeed}} to {{ic|0}}.<br />
* If your touchpad is too sensitive, use higher values for {{ic|FingerLow}} and {{ic|FingerHigh}} and vice versa. Remember that {{ic|FingerLow}} should be smaller than {{ic|FingerHigh}}<br />
}}<br />
<br />
=== Configuration on the fly ===<br />
<br />
Next to the traditional method of configuration, the Synaptics driver also supports on the fly configuration. This means that users can set certain options through a software application, these options are applied immediately without needing to restart Xorg. This is useful to test configuration options before you include them in the configuration file or a script. Note that on the fly configuration is not persistent and lasts only until the Xorg server exists.<br />
<br />
==== Console tools ====<br />
<br />
* {{App|[[#Synclient|Synclient]]|command line utility to configure and query Synaptics driver settings|http://xorg.freedesktop.org/|{{Pkg|xf86-input-synaptics}}}}<br />
* {{App|[[#Using xinput to determine touchpad capabilities|xinput]]|general-purpose utility to configure X input devices|http://xorg.freedesktop.org/|{{Pkg|xorg-xinput}}}}<br />
<br />
==== Graphical tools ====<br />
<br />
* {{App|GPointing Device Settings|Provides graphical on the fly configuration for several pointing devices connected to the system, including your synaptics touch pad. This application replaces GSynaptics as the preferred tool for graphical touchpad configuration through the synaptics driver.|https://wiki.gnome.org/Attic/GPointingDeviceSettings|{{AUR|gpointing-device-settings}}}}<br />
* {{App|kcm_touchpad|New configuration tool for [[KDE]] Plasma 5. It provides a module under input devices in System Settings. It is to be considered a replacement for ''synaptiks'' and the old ''kcm-touchpad'' module.|https://cgit.kde.org/plasma-desktop.git/tree/kcms/touchpad|4={{Pkg|plasma-desktop}}}}<br />
<br />
=== Xfce4/Cinnamon ===<br />
<br />
To change these settings in ''XFCE 4''':<br />
<br />
# Open ''System Settings''.<br />
# Click ''Mouse and Touchpad''.<br />
# Change the settings on the ''Touchpad'' tab.<br />
<br />
To change these settings in '''Cinnamon''':<br />
<br />
# Open ''Cinnamon System Settings''.<br />
# Click ''Mouse and Touchpad''.<br />
# Change the settings on the ''Touchpad'' tab.<br />
<br />
=== MATE ===<br />
<br />
It is possible configure the way MATE handles the touchpad:<br />
<br />
# Run {{ic|dconf-editor}}<br />
# Edit the keys in the {{ic|org.mate.desktop.peripherals.touchpad}} folder.<br />
<br />
To prevent Mate settings daemon from overriding existing settings, do as follows:<br />
<br />
# Run {{ic|dconf-editor}}<br />
# Edit {{ic|org.mate.SettingsDaemon.plugins.mouse}}<br />
# Uncheck the '''active''' setting.<br />
<br />
== Advanced configuration ==<br />
<br />
=== Using xinput to determine touchpad capabilities ===<br />
<br />
Depending on your model, synaptic touchpads may have or lack capabilities. We can determine which capabilities your hardware supports by using {{ic|xinput}}.<br />
<br />
* left, middle and right hardware buttons<br />
* two finger detection<br />
* three finger detection<br />
* configurable resolution<br />
<br />
First, find the name of your touchpad:<br />
<br />
$ xinput list<br />
<br />
You can now use {{ic|xinput}} to find your touchpad's capabilities:<br />
<br />
{{hc|$ xinput list-props "SynPS/2 Synaptics TouchPad" {{!}} grep Capabilities|<br />
Synaptics Capabilities (309): 1, 0, 1, 0, 0, 1, 1<br />
}}<br />
<br />
From left to right, this shows:<br />
* {{ic|1}}: device has a physical left button<br />
* {{ic|0}}: device does not have a physical middle button<br />
* {{ic|1}}: device has a physical right button<br />
* {{ic|0}}: device does not support two-finger detection<br />
* {{ic|0}}: device does not support three-finger detection<br />
* {{ic|1}}: device can configure vertical resolution<br />
* {{ic|1}}: device can configure horizontal resolution<br />
<br />
Use {{ic|xinput list-props "SynPS/2 Synaptics TouchPad"}} to list all device properties. See {{man|4|synaptics}} for full documentation of the Synaptics properties.<br />
<br />
=== Synclient ===<br />
<br />
Synclient can configure every option available to the user as documented in {{man|4|synaptics}}. A full list of the current user settings can be brought up:<br />
<br />
$ synclient -l<br />
<br />
Every listed configuration option can be controlled through synclient, for example:<br />
<br />
* Enable palm detection: {{ic|1=$ synclient PalmDetect=1}} <br />
* Configure button events (right button event for two finger tap here): {{ic|1=$ synclient TapButton2=3}} <br />
* Disable the touchpad: {{ic|1=$ synclient TouchpadOff=1}} <br />
<br />
After you have successfully tried and tested your options through synclient, you can make these changes permanent by adding them to {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}.<br />
<br />
=== evtest ===<br />
<br />
The tool {{Pkg|evtest}} can display pressure and placement on the touchpad in real-time, allowing further refinement of the default Synaptics settings. The evtest monitoring can be started with:<br />
<br />
$ evtest /dev/input/event''X''<br />
<br />
''X'' denotes the touchpad's ID. It can be found by looking at the output of {{ic|cat /proc/bus/input/devices}}.<br />
<br />
evtest needs exclusive access to the device which means it cannot be run together with an X server instance. You can either kill the X server or run evtest from a different virtual terminal (e.g., by pressing {{ic|Ctrl+Alt+F2}}).<br />
<br />
=== xev ===<br />
<br />
The tool {{Pkg|xorg-xev}} can display taps, clicks, pressure, placement and other measured parameters in real-time, allowing still further refinement of the default Synaptics settings. xev can be run in X and needs no specifics. using the "-event" parameter, it is possible to restrict the types of events that are reported.<br />
<br />
=== Circular Scrolling ===<br />
<br />
Circular scrolling is a feature that Synaptics offers which closely resembles the behaviour of iPods. Instead of (or additional to) scrolling horizontally or vertically, you can scroll circularly. Some users find this faster and more precise.<br />
To enable circular scrolling, add the following options to the touchpad device section of {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}:<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
...<br />
Option "CircularScrolling" "on"<br />
Option "CircScrollTrigger" "0"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
The option '''CircScrollTrigger''' may be one of the following values, determining which edge circular scrolling should start:<br />
<br />
0 All Edges<br />
1 Top Edge<br />
2 Top Right Corner<br />
3 Right Edge<br />
4 Bottom Right Corner<br />
5 Bottom Edge<br />
6 Bottom Left Corner<br />
7 Left Edge<br />
8 Top Left Corner<br />
<br />
Specifying something different from zero may be useful if you want to use circular scrolling in conjunction with horizontal and/or vertical scrolling. If you do so, the type of scrolling is determined by the edge you start from.<br />
<br />
To scroll fast, draw small circles in the center of your touchpad. To scroll slowly and more precise, draw large circles.<br />
<br />
=== Natural scrolling ===<br />
<br />
It is possible to enable natural scrolling through synaptics. Simply use negative values for {{ic|VertScrollDelta}} and {{ic|HorizScrollDelta}} like so:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
...<br />
Option "VertScrollDelta" "-111"<br />
Option "HorizScrollDelta" "-111"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
=== Software toggle ===<br />
<br />
You might want to turn the touchpad on and off with a simple button click or shortcut. This can be done by binding the following ''xinput''-based script to a keyboard event as explained in [[Extra keyboard keys in Xorg]]:<br />
<br />
{{hc|/usr/local/bin/touchpad_toggle.sh|2=<nowiki><br />
#!/bin/bash<br />
<br />
declare -i ID<br />
ID=`xinput list | grep -Eio '(touchpad|glidepoint)\s*id\=[0-9]{1,2}' | grep -Eo '[0-9]{1,2}'`<br />
declare -i STATE<br />
STATE=`xinput list-props $ID|grep 'Device Enabled'|awk '{print $4}'`<br />
if [ $STATE -eq 1 ]<br />
then<br />
xinput disable $ID<br />
# echo "Touchpad disabled."<br />
# notify-send -a 'Touchpad' 'Disabled' -i /usr/share/icons/Adwaita/48x48/devices/input-touchpad.png<br />
else<br />
xinput enable $ID<br />
# echo "Touchpad enabled."<br />
# notify-send -a 'Touchpad' 'Enabled' -i /usr/share/icons/Adwaita/48x48/devices/input-touchpad.png<br />
fi<br />
</nowiki>}}<br />
<br />
{{Tip|When using external monitors with [[bumblebee]], the touchpad can be configured on the second X server by prepending {{ic|1=DISPLAY=:8}} to the command.}} <br />
<br />
Alternatively, {{ic|synclient}} can be used to toggle the touchpad. However, it can only turn off touch events but not physical clickpad button usage:<br />
<br />
{{hc|/usr/local/bin/touchpad.sh|<nowiki><br />
#!/bin/bash<br />
<br />
synclient TouchpadOff=$(synclient -l | grep -c 'TouchpadOff.*=.*0')<br />
</nowiki>}}<br />
<br />
=== Disable touchpad while typing ===<br />
<br />
==== Using the driver's automatic palm detection ====<br />
<br />
First of all you should test if it works properly for your touchpad and if the settings are accurate. Enable palm detection with<br />
<br />
$ synclient PalmDetect=1<br />
<br />
Then test the typing. You can tweak the detection by setting the minimum width for the touch to be considered a palm, for example<br />
<br />
$ synclient PalmMinWidth=8<br />
<br />
And you can tweak the minimum pressure required for the touch to be considered a palm, for example<br />
<br />
$ synclient PalmMinZ=100<br />
<br />
{{Tip|To help find the best values for palm detection, you can use {{pkg|evtest}} to see the width and Z values reported during touchpad use.}}<br />
<br />
Once you have found the correct settings, you can add them to your [[#Configuration|config file]]:<br />
<br />
{{bc|<nowiki><br />
Option "PalmDetect" "1"<br />
Option "PalmMinWidth" "8"<br />
Option "PalmMinZ" "100"<br />
</nowiki>}}<br />
<br />
{{Warning|1=For some touchpads, an [https://bugzilla.kernel.org/show_bug.cgi?id=77161 issue] with the kernel can cause the palm width to always be reported as 0. This breaks palm detection in a majority of cases. Pending an actual fix, you can [https://gist.github.com/silverhammermba/a231c8156ecaa63c86f1 patch] the synaptics package to use only Z for palm detection.}}<br />
<br />
{{Tip|If you experience problems with consistent palm detection for your hardware, an alternative to try is [[libinput]].}}<br />
<br />
==== Using syndaemon ====<br />
<br />
{{ic|syndaemon}} monitors keyboard activity and disables the touchpad while typing. It has several options to control when the disabling occurs. View them with<br />
<br />
$ syndaemon -h<br />
<br />
For example, to disable tapping and scrolling for 0.5 seconds after each keypress (ignoring modifier keys like Ctrl), use<br />
<br />
$ syndaemon -i 0.5 -t -K -R<br />
<br />
Once you have determined the options you like, you should use your login manager or [[xinitrc]] to have it run automatically when X starts. The {{ic|-d}} option will make it start in the background as a daemon.<br />
<br />
=== Disable touchpad on mouse detection ===<br />
<br />
With the assistance of [[udev]], it is possible to automatically disable the touchpad if an external mouse has been plugged in. To achieve this, use one of the following rules.<br />
<br />
==== Basic desktop ====<br />
<br />
This is a basic rule generally for non-"desktop environment" sessions:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="add", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/synclient TouchpadOff=1"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="remove", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/synclient TouchpadOff=0"<br />
}}<br />
<br />
If the touchpad is always deactivated at startup, even when no mouse is plugged in, try adding the following criteria between the KERNEL and ACTION parameters above:<br />
<br />
ATTRS{name}!="*TouchPad", ATTRS{name}!="*Stick",<br />
<br />
==== GDM ====<br />
<br />
{{Accuracy|saying that GDM ''usually'' does something does not make sense}}<br />
<br />
GDM usually stores the Xauthority files in {{ic|/var/run/gdm}} in a randomly-named directory. You should find your actual path to the Xauthority file which can be done using {{ic|ps ax}}. For some reason multiple authority files may appear for a user, so a rule like will be necessary:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="add", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print0 -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/usr/bin/synclient TouchpadOff=1"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="remove", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print0 -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/usr/bin/synclient TouchpadOff=0"<br />
}}<br />
<br />
Furthermore, you should validate that your udev script is running properly! You can check for the conditions using {{ic| udevadm monitor -p}} which must be run as root.<br />
<br />
===== With syndaemon running =====<br />
<br />
{{ic|syndaemon}} whether started by the [[#Using syndaemon|user]] or the desktop environment can conflict with synclient and will need to be disabled. A rule like this will be needed:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="add", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/bin/sh -c '/usr/bin/synclient TouchpadOff=1 ; sleep 1; /bin/killall syndaemon; '"<br />
}}<br />
<br />
===== touchpad-state =====<br />
<br />
An AUR package {{aur|touchpad-state-git}} has been created around the udev rules above. It includes a udev rule and script:<br />
<br />
touchpad-state [--off] [--on]<br />
<br />
==== GNOME ====<br />
<br />
GNOME users can install GNOME shell extension [https://extensions.gnome.org/extension/131/touchpad-indicator/ Touchpad Indicator], change "Switch Method" to "Synclient" and enable "Automatically switch Touchpad On/Off" in its preferences.<br />
<br />
==== KDE ====<br />
<br />
If using Plasma, the package {{Pkg|plasma-desktop}} can be used to manage the touchpad.<br />
<br />
==== System with multiple X sessions ====<br />
<br />
{{Accuracy|Hard-coded {{ic|DISPLAY}} variable does not work with multiple X sessions.}} <br />
<br />
For an environment where multiple users are present, a slightly different approach is needed to detect the current users X environment. This script will help achieving this:<br />
<br />
{{hc|/usr/bin/mouse-pnp-event-handler.sh|<nowiki><br />
#!/bin/sh<br />
## $1 = "add" / "remove"<br />
## $2 = %k from udev <br />
<br />
## Set TRACKPAD_NAME according to your configuration. <br />
## Check your trackpad name with: <br />
## find /sys/class/input/ -name mouse* -exec udevadm info -a {} \; | grep 'ATTRS{name}'<br />
TRACKPAD_NAME="SynPS/2 Synaptics TouchPad"<br />
<br />
USERLIST=$(w -h | cut -d' ' -f1 | sort | uniq)<br />
MOUSELIST=$(find /sys/class/input/ -name mouse*)<br />
<br />
for CUR_USER in ${USERLIST}; do<br />
CUR_USER_XAUTH="$(sudo -Hiu ${CUR_USER} env | grep -e "^HOME=" | cut -d'=' -f2)/.Xauthority"<br />
<br />
<br />
## Can't find a way to get another users DISPLAY variable from an isolated root environment. Have to set it manually.<br />
#CUR_USER_DISPL="$(sudo -Hiu ${CUR_USER} env | grep -e "^DISPLAY=" | cut -d'=' -f2)"<br />
CUR_USER_DISPL=":0"<br />
<br />
export XAUTHORITY="${CUR_USER_XAUTH}"<br />
export DISPLAY="${CUR_USER_DISPL}"<br />
<br />
if [ -f "${CUR_USER_XAUTH}" ]; then<br />
case "$1" in<br />
"add")<br />
/usr/bin/synclient TouchpadOff=1<br />
/usr/bin/logger "USB mouse plugged. Disabling touchpad for $CUR_USER. ($XAUTHORITY - $DISPLAY)"<br />
;;<br />
"remove")<br />
## Only execute synclient if there are no external USB mice connected to the system.<br />
EXT_MOUSE_FOUND="0"<br />
for CUR_MOUSE in ${MOUSELIST}; do<br />
if [ "$(cat ${CUR_MOUSE}/device/name)" != "${TRACKPAD_NAME}" ]; then<br />
EXT_MOUSE_FOUND="1"<br />
fi<br />
done<br />
if [ "${EXT_MOUSE_FOUND}" == "0" ]; then<br />
/usr/bin/synclient TouchpadOff=0<br />
/usr/bin/logger "No additional external mice found. Enabling touchpad for $CUR_USER."<br />
else<br />
logger "Additional external mice found. Won't enable touchpad yet for $CUR_USER."<br />
fi<br />
;;<br />
esac<br />
fi<br />
done<br />
</nowiki>}}<br />
<br />
Update the {{ic|TRACKPAD_NAME}} variable for your system configuration.<br />
Run {{ic|<nowiki>find /sys/class/input/ -name mouse* -exec udevadm info -a {} \; | grep 'ATTRS{name}'</nowiki>}} to get a list of useful mice-names. Choose the one for your trackpad.<br />
<br />
Then have udev run this script when USB mices are plugged in or out, with these udev rules:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="add", RUN+="/usr/bin/mouse-pnp-event-handler.sh add %k"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="remove", RUN+="/usr/bin/mouse-pnp-event-handler.sh remove %k"<br />
}}<br />
<br />
=== Buttonless touchpads (aka ClickPads) ===<br />
<br />
Ever more laptops have a special kind of touchpad which has a single mouse button as part of the tracking plate, instead of external buttons. For example, the 2015 Dell XPS 13, HP series 4500 ProBooks, ThinkPad X220 and X1 ThinkPad series have this kind of a touchpad. By default, the whole button area is detected as a left button, so right and middle-click functions and click + drag will not work. It is possible to define two and three finger clicks as right and middle button clicks, and/or to define parts of the click pad surface as right and middle buttons. Note that although the driver registers multiple touches, it does not track individual fingers (as of version 1.7.1) which results in confusing behavior when using physical buttons of a clickpad for drag-and-drop and other gestures: you have to click with two or three fingers but then only move one of them while holding the button down with another. You can look into the {{AUR|xf86-input-mtrack}} driver for better multitouch support.<br />
<br />
Some desktop environments (KDE and GNOME at least) define sane and useful default configurations for clickpads, providing a right button at the bottom right of the pad, recognising two and three-finger clicks anywhere on the pad as right and middle clicks, and providing configuration options to define two and three-finger taps as right and middle clicks. If your desktop does not do this, or if you want more control, you can modify the touchpad section in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} (or better, of your custom synaptics configuration file prefixed with a higher number). For example:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
# Enable clickpad/multitouch support<br />
Option "ClickPad" "true"<br />
# Middle-button emulation is not supported<br />
Option "EmulateMidButtonTime" "0"<br />
# Define right soft button at the bottom<br />
Option "SoftButtonAreas" "50% 0 82% 0 0 0 0 0"<br />
EndSection<br />
</nowiki>}}<br />
<br />
The format for the SoftButtonAreas option is (from {{man|4|synaptics}}):<br />
{{bc|RightButtonAreaLeft RightButtonAreaRight RightButtonAreaTop RightButtonAreaBottom MiddleButtonAreaLeft MiddleButtonAreaRight MiddleButtonAreaTop MiddleButtonAreaBottom}}<br />
<br />
The above "SoftButtonAreas" option is commonly found in documentation or synaptics packages, and it defines the right half of the bottom 18% of the touchpad as a right button. There is '''no middle button''' defined. If you want to define a middle button remember one key piece of information from the manual; '''edge set to 0 extends to infinity in that direction.'''<br />
<br />
In the following example the right button will occupy the rightmost 40% of the button area and the middle button 20% of it in the center. The leftmost 40% remains as a left button (as does the rest of the clickpad):<br />
<br />
...<br />
Option "SoftButtonAreas" "60% 0 82% 0 40% 59% 82% 0"<br />
...<br />
<br />
You can use {{ic|<nowiki>synclient</nowiki>}} to check the soft button areas: <br />
<br />
{{hc|<nowiki>$ synclient -l | grep -i ButtonArea</nowiki>|<nowiki><br />
RightButtonAreaLeft = 3914<br />
RightButtonAreaRight = 0<br />
RightButtonAreaTop = 3918<br />
RightButtonAreaBottom = 0<br />
MiddleButtonAreaLeft = 3100<br />
MiddleButtonAreaRight = 3873<br />
MiddleButtonAreaTop = 3918<br />
MiddleButtonAreaBottom = 0<br />
</nowiki>}}<br />
<br />
If your buttons are not working, soft button areas are not changing, ensure you do not have a synaptics configuration file distributed by a package which is overriding your custom settings (ie. some AUR packages distribute configurations prefixed with very high numbers).<br />
<br />
These settings cannot be modified on the fly with {{ic|<nowiki>synclient</nowiki>}}, however, {{ic|<nowiki>xinput</nowiki>}} works:<br />
<br />
xinput set-prop "SynPS/2 Synaptics TouchPad" "Synaptics Soft Button Areas" 4000 0 4063 0 3000 4000 4063 0<br />
<br />
You cannot use percentages with this command, so look at {{ic|/var/log/Xorg.0.log}} to figure out the touchpad x and y-axis ranges.<br />
<br />
==== Bottom edge correction ====<br />
<br />
In some cases, for example Toshiba Satellite P50, everything work out of the box except often your click are seen as mouse movement and the cursor will jump away just before registering the click.<br />
This can be easily solved running<br />
<br />
$ synclient -l | grep BottomEdge<br />
<br />
take the BottomEdge value and subtract a the wanted height of your button, then temporary apply with<br />
<br />
$ synclient AreaBottomEdge=4000<br />
<br />
when a good value has been found make it a fixed correction with<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
...<br />
Option "AreaBottomEdge" "4000"<br />
...<br />
</nowiki>}}<br />
<br />
{{Note|The area will not act as touchpad if the touch '''begins''' in that area, but it can still be used if the touch has originated outside.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad does not work after resuming from hibernate/suspend ===<br />
<br />
Occasionally touchpads will fail to work when the computer resumes from sleep or hibernation. This can often be corrected without rebooting by<br />
<br />
* Switching to a console and back again,<br />
* entering sleep mode again, and resuming again, or<br />
* locating the correct kernel module, then removing it and inserting it again. <br />
* blacklisting kernel module psmouse may be a permanent option (when the touchpad is handled by another module, eg i2c_designware_platform)<br />
<br />
{{Note|You can use Ctrl-Alt-F1 through F8 to switch to a console without using the mouse.}}<br />
<br />
modprobe -r psmouse #psmouse happens to be the kernel module for my touchpad (Alps DualPoint)<br />
modprobe psmouse<br />
<br />
Now switch back to the tty that X is running on. If you chose the right module, your touchpad should be working again.<br />
<br />
=== xorg.conf.d/70-synaptics.conf does not seem to apply in MATE ===<br />
<br />
[[MATE]] will by default overwrite various options for your touchpad. This includes configurable features for which there is no graphical configuration within MATE's system control panel. This may cause it to appear that {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} is not applied. Follow [[#MATE]] to prevent this behavior.<br />
<br />
=== The touchpad is not working, Xorg.0.log shows "Query no Synaptics: 6003C8" ===<br />
<br />
Due to the way synaptics is currently set-up, 2 instances of the synaptics module are loaded. We can recognize this situation by opening the xorg log file ({{ic|/var/log/Xorg.0.log}}) and noticing this:<br />
<br />
{{hc|/var/log/Xorg.0.log|<nowiki><br />
[ 9304.803] (**) SynPS/2 Synaptics TouchPad: Applying InputClass "evdev touchpad catchall"<br />
[ 9304.803] (**) SynPS/2 Synaptics TouchPad: Applying InputClass "touchpad catchall"<br />
</nowiki>}}<br />
<br />
Notice how 2 differently named instances of the module are being loaded. In some cases, this causes the touchpad to become nonfunctional.<br />
<br />
We can prevent this double loading by adding {{ic|MatchDevicePath "/dev/input/event*"}} to our {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} file:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad catchall"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
MatchDevicePath "/dev/input/event*"<br />
Option "TapButton1" "1"<br />
Option "TapButton2" "2"<br />
Option "TapButton3" "3"<br />
EndSection <br />
</nowiki>}}<br />
<br />
Restart X and check xorg logs again, the error should be gone and the touchpad should be functional.<br />
<br />
related bugreport: {{Bug|20830}}<br />
<br />
related forum topics:<br />
<br />
* https://bbs.archlinux.org/viewtopic.php?id=104769<br />
* https://bbs.archlinux.org/viewtopic.php?pid=825690<br />
<br />
=== Touchpad detected as "PS/2 Generic Mouse" or "Logitech PS/2 mouse" ===<br />
<br />
This can be caused by a number of issues;<br />
<br />
==== Elantech touchpads ====<br />
<br />
This can happen with some laptops with an Elantech touchpad, for example the ASUS x53s. In this situation you need {{AUR|psmouse-alps-driver}}{{Broken package link|{{aur-mirror|psmouse-alps-driver}}}} package from [[AUR]].<br />
<br />
==== Laptops with touchscreen & touchpad ====<br />
<br />
There also seems to be a problem with laptops which have both a touchscreen & a touchpad, such as the Dell XPS 12 or Dell XPS 13. To fix this, you can [[blacklisting|blacklist]] the {{ic|i2c_hid}} driver, this does have the side-effect of disabling the touchscreen though.<br />
<br />
This [http://www.spinics.net/lists/linux-input/msg27768.html seems to be a known problem]. Also see [https://bbs.archlinux.org/viewtopic.php?pid=1419078 this thread].<br />
<br />
Post kernel 3.15, having the module blacklisted may cause touchpad to stop working completely. Removing the blacklist should allow this to start working with limited functionality, see {{Bug|40921}}.<br />
<br />
=== Non-functional Synaptics special abilities (multi-tap, scrolling, etc.) ===<br />
<br />
In some cases Synaptics touchpads only work partially. Features like two-finger scrolling or two-finger middle-click do not work even if properly enabled. This is probably related to the [[#The touchpad is not working, Xorg.0.log shows "Query no Synaptics: 6003C8"|The touchpad is not working]] problem mentioned above. Fix is the same, prevent double module loading.<br />
<br />
If preventing the module from loading twice does not solve your issue, try commenting out the toggle {{ic|MatchIsTouchpad}} (which is now included by default in the synaptics config).<br />
<br />
If clicking with either 2 or 3 fingers is interpreted as a right-click, so you cannot get a middle click either way regardless of configuration, this bug is probably the culprit: https://bugs.freedesktop.org/show_bug.cgi?id=55365<br />
<br />
====No Multi-touch in some Elantech touchpads====<br />
<br />
See [http://unix.stackexchange.com/questions/28736/what-does-the-i8042-nomux-1-kernel-option-do-during-booting-of-ubuntu].<br />
<br />
=== Cursor jump ===<br />
<br />
Some users have their cursor inexplicably ''jump'' around the screen. There currently no patch for this, but the developers are aware of the problem and are working on it.<br />
<br />
Another posibility is that you are experiencing ''IRQ losses'' related to the i8042 controller (this device handles the keyboard and the touchpad of many laptops), so you have two possibilities here:<br />
<br />
1. rmmod && insmod the psmouse module.<br />
<br />
2. append {{ic|1=i8042.nomux=1}} to your [[kernel parameters]] and reboot your machine.<br />
<br />
=== Touchpad device is not located at {{ic|/dev/input/*}} ===<br />
<br />
If that is the case, you can use this command to display information about your input devices:<br />
<br />
$ cat /proc/bus/input/devices<br />
<br />
Search for an input device which has the name "SynPS/2 Synaptics TouchPad". The "Handlers" section of the output specifies what device you need to specify.<br />
<br />
'''Example output:'''<br />
<br />
{{hc|$ cat /proc/bus/input/devices|<nowiki><br />
I: Bus=0011 Vendor=0002 Product=0007 Version=0000<br />
N: Name="SynPS/2 Synaptics TouchPad"<br />
P: Phys=isa0060/serio4/input0<br />
S: Sysfs=/class/input/input1<br />
H: Handlers=mouse0 event1<br />
B: EV=b<br />
B: KEY=6420 0 7000f 0<br />
</nowiki>}}<br />
<br />
In this case, the {{ic|Handlers}} are {{ic|mouse0}} and {{ic|event1}}, so {{ic|/dev/input/mouse0}} would be used.<br />
<br />
{{Expansion|TODO: explain how to apply this in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}}}<br />
<br />
=== Firefox and special touchpad events ===<br />
<br />
You can enable/disable some special events that Firefox handles upon tapping or scrolling certain parts of your touchpad by editing the settings of those actions.<br />
Type {{ic|about:config}} in your Firefox address bar.<br />
To alter options, double-click on the line in question.<br />
<br />
==== Firefox 17.0 and later ====<br />
<br />
Horizontal scrolling will now by default scroll through pages and not through your history. To reenable Mac-style forward/backward with two-finger swiping, edit:<br />
<br />
mousewheel.default.action.override_x = 2<br />
<br />
You may encounter accidental forwards/backwards while scrolling vertically. To change Firefox's sensitivity to horizontal swipes, edit:<br />
<br />
mousewheel.default.delta_multiplier_x<br />
<br />
The optimum value will depend on your touchpad and how you use it, try starting with {{ic|10}}. A negative value will reverse the swipe directions.<br />
<br />
=== Opera: horizontal scrolling issues ===<br />
<br />
Same as above.<br />
To fix it, go to ''Tools > Preferences > Advanced > Shortcuts''. Select "Opera Standard" mouse setup and click "Edit". In "Application" section:<br />
<br />
{{Accuracy|Description here is not so clear and i don't use Opera,Please make it clear :)}}<br />
<br />
* assign key "Button 6" to command "Scroll left"<br />
* assign key "Button 7" to command "Scroll right"<br />
<br />
=== Scrolling and multiple actions with Synaptics on LG laptops ===<br />
<br />
These problems seem to be occurring on several models of LG laptops.<br />
Symptoms include: when pressing Mouse Button 1, Synaptics interprets it as ScrollUP and a regular button 1 click; same goes for button 2.<br />
<br />
The scrolling issue can be resolved by entering in {{ic|xorg.conf}}:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "UpDownScrolling" "0"<br />
}}<br />
<br />
{{Note|This will make Synaptics interpret one button push as three. There is a patch written by Oskar Sandberg [http://www.math.chalmers.se/~ossa/linux/lg_tx_express.html] that removes these clicks.}}<br />
<br />
Apparently, when trying to compile this against the latest version of Synaptics it fails. The solution to this is using the GIT repository for Synaptics [http://web.telia.com/~u89404340/touchpad/synaptics/.git].<br />
<br />
To build the package after downloading the tarball and unpacking it, execute:<br />
<br />
$ cd synaptics-git<br />
$ makepkg<br />
<br />
=== Other external mouse issues ===<br />
<br />
First, make sure your section describing the external mouse contains this line (or that the line looks like this):<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "Device" "/dev/input/mice"<br />
}}<br />
<br />
If the "Device" line is different, change it to the above and try to restart X. If this does not solve your problem, make your '''touchpad''' is the CorePointer in the "Server Layout" section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
InputDevice "Touchpad" "CorePointer"<br />
}}<br />
<br />
and make your external device "SendCoreEvents":<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
InputDevice "USB Mouse" "SendCoreEvents"<br />
}}<br />
<br />
finally add this to your external device's section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "SendCoreEvents" "true"<br />
}}<br />
<br />
If all of the above does not work for you, please check relevant bug trackers for possible bugs, or go through the forums to see if anyone has found a better solution.<br />
<br />
=== Touchpad synchronization issues ===<br />
<br />
{{Out of date|section=Outdated "Touchpad synchronization issues" section}}<br />
<br />
Sometimes the cursor may freeze for several seconds or start acting on its own for no apparent reason. This behavior is accompanied by records in {{ic|/var/log/messages.log}}<br />
<br />
{{hc|/var/log/messages.log|<br />
psmouse.c: TouchPad at isa0060/serio1/input0 lost synchronization, throwing 3 bytes away<br />
}}<br />
<br />
This problem has no general solution, but there are several possible workarounds.<br />
* If you use CPU frequency scaling, avoid using the "ondemand" governor and use the "performance" governor when possible, as the touchpad may lose sync when the CPU frequency changes.<br />
* Avoid using an ACPI battery monitor.<br />
* Attempt to load psmouse with "proto=imps" option. To do that, add this line to your {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/modprobe.conf|2=<br />
options psmouse proto=imps<br />
}}<br />
<br />
* Try another desktop environment. Some users report that this problem only occurs when using XFCE or GNOME, for whatever reason<br />
<br />
=== Xorg.log.0 shows SynPS/2 Synaptics touchpad can not grab event device, errno=16 ===<br />
<br />
If you are using Xorg 7.4, you may get a warning like this from {{ic|/var/log/Xorg.0.log}}, thais is because the driver will grab the event device for exclusive use when using the Linux 2.6 event protocol. When it fails, X will return this error message.<br />
<br />
Grabbing the event device means that no other user space or kernel space program sees the touchpad events. This is desirable if the X config file includes {{ic|/dev/input/mice}} as an input device, but is undesirable if you want to monitor the device from user space.<br />
<br />
If you want to control it, add or modify the "GrabEventDevice" option in you touchpad section in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|2=<br />
...<br />
Option "GrabEventDevice" "''boolean''"<br />
...<br />
}}<br />
<br />
This will come into effect when X is restarted, though you can also change it by using synclient. When changing this parameter with the synclient program, the change will not take effect until the Synaptics driver is disabled and re-enabled. This can be achieved by switching to a text console and then switching back to X.<br />
<br />
=== Synaptics loses multitouch detection after rebooting from Windows ===<br />
<br />
Many drivers include a firmware that is loaded into flash memory when the computer boots. This firmware is not necessarily cleared upon shutdown, and is not always compatible with Linux drivers. The only way to clear the flash memory is to shutdown completely rather than using reboot. It is generally considered best practice to never use reboot when switching between operating systems.<br />
<br />
=== Touchpad not recognized after shutdown from Arch ===<br />
<br />
Certain touchpads (elantech in particular) will fail to be recognized as a device of any sort after a standard shutdown from Arch linux. There are multiple possible solutions to this problem:<br />
<br />
* Boot into a Windows partition/install disk and shutdown from there.<br />
* Wait approximately 1 minute before turning on the computer after shutdown.<br />
* As discussed in https://bugzilla.kernel.org/show_bug.cgi?id=81331#c186 a patch has been merged into the stable kernel that provides a fix for Elantech touchpads. Gigabyte P34, P35v2 and X3 models are supported by default, for others (especially rebranded Gigabyte laptops, like XMG's) {{ic|1=i8042.kbdreset=1}} can be set as kernel parameter.<br />
<br />
=== Trackpoint and Clickpad ===<br />
<br />
Newer Thinkpads do not have physical buttons for their Trackpoint anymore and instead use the upper area of the Clickpad for buttons (Left, Middle, Right). <br />
Apart from the ergonomic viewpoint this works quite well with current Xorg. Unfortunately mouse wheel emulation using the middle button is not supported yet. Install {{AUR|xf86-input-evdev-trackpoint}} from the AUR for a patched and properly configured version if you intend to use the Trackpoint.<br />
<br />
== See also ==<br />
<br />
* [http://cgit.freedesktop.org/xorg/driver/xf86-input-synaptics/ Synaptics touchpad driver]<br />
* [http://www.x.org/archive/X11R7.5/doc/man/man4/synaptics.4.html Synaptics manual on x.org ]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Touchpad_Synaptics&diff=509656Touchpad Synaptics2018-02-04T10:49:59Z<p>Ketsui: Undo revision 509655 by Ketsui (talk) synclient should be Synclient</p>
<hr />
<div>[[Category:Input devices]]<br />
[[de:Synaptics Touchpad Treiber]]<br />
[[es:Touchpad Synaptics]]<br />
[[fr:Touchpad Synaptics]]<br />
[[it:Touchpad Synaptics]]<br />
[[ja:Synaptics タッチパッド]]<br />
[[ru:Touchpad Synaptics]]<br />
[[zh-hans:Touchpad Synaptics]]<br />
{{Related articles start}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
This article details the installation and configuration process of the '''''Synaptics input driver''''' for Synaptics (and ALPS) touchpads found on most notebooks.<br />
<br />
{{Warning|{{pkg|xf86-input-synaptics}} is no longer actively updated. If possible, use [[libinput]].}}<br />
<br />
{{Note|1=If you want to configure touchpad via GNOME control center, you need to use the [[libinput]] driver.[https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12]}}<br />
<br />
== Installation ==<br />
<br />
The Synaptics driver can be [[installed]] with the package {{Pkg|xf86-input-synaptics}}.<br />
<br />
== Configuration ==<br />
<br />
The primary method of configuration for the touchpad is through an [[Xorg]] server configuration file. After installation of {{ic|xf86-input-synaptics}}, a default configuration file is located at {{ic|/usr/share/X11/xorg.conf.d/70-synaptics.conf}}. Users can copy this file to {{ic|/etc/X11/xorg.conf.d/}} and edit it to configure the various driver options available. Refer to the {{man|4|synaptics}} manual page for a complete list of available options. Machine-specific options can be discovered using [[#Synclient]].<br />
<br />
=== Frequently used options ===<br />
<br />
The following example file configures some common options, including vertical, horizontal and circular scrolling as well as tap-to-click:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
Option "TapButton1" "1"<br />
Option "TapButton2" "3"<br />
Option "TapButton3" "2"<br />
Option "VertEdgeScroll" "on"<br />
Option "VertTwoFingerScroll" "on"<br />
Option "HorizEdgeScroll" "on"<br />
Option "HorizTwoFingerScroll" "on"<br />
Option "CircularScrolling" "on"<br />
Option "CircScrollTrigger" "2"<br />
Option "EmulateTwoFingerMinZ" "40"<br />
Option "EmulateTwoFingerMinW" "8"<br />
Option "CoastingSpeed" "0"<br />
Option "FingerLow" "30"<br />
Option "FingerHigh" "50"<br />
Option "MaxTapTime" "125"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
; TapButton1: (integer) configures which mouse-button is reported on a non-corner, one finger tap.<br />
; TapButton2: (integer) configures which mouse-button is reported on a non-corner, two finger tap<br />
; TapButton3: (integer) configures which mouse-button is reported on a non-corner, three finger tap<br />
; RBCornerButton: (integer) configures which mouse-button is reported on a right bottom corner, one finger tap (use {{ic|Option "RBCornerButton" "3"}} to achieve Ubuntu style tap behaviour for right mouse button in lower right corner)<br />
; RTCornerButton: (integer) as above, but for top right corner, one finger tap.<br />
; VertEdgeScroll: (boolean) enables vertical scrolling while dragging across the right edge of the touch pad.<br />
; HorizEdgeScroll: (boolean) enables horizontal scrolling while dragging across the bottom edge of the touch pad.<br />
; VertTwoFingerScroll: (boolean) enables vertical scrolling using two fingers.<br />
; HorizTwoFingerScroll: (boolean) enables horizontal scrolling using two fingers.<br />
; EmulateTwoFingerMinZ/W: (integer) play with this value to set the precision of two finger scroll.<br />
; FingerLow: (integer) when finger pressure drops below this value, the driver counts it as a release.<br />
; FingerHigh: (integer) when finger pressure goes above this value, the driver counts it as a touch.<br />
; MaxTapTime: Determines how "crisp" a tap must be to be considered a real tap. Decrease the value to require a more crisp tap. Properly adjusting this parameter can reduce false positives when the hands hover over or lightly touch the pad.<br />
; VertScrollDelta and HorizScrollDelta: (integer) configures the speed of scrolling, it is a bit counter-intuitive because higher values produce greater precision and thus slower scrolling. Negative values cause natural scrolling like in macOS.<br />
<br />
{{Note|<br />
* If you find that your hand frequently brushes your touchpad, causing the {{ic|TapButton2}} option to be triggered (which will more than likely paste from your clipboard), and you do not mind losing two-finger-tap functionality, set {{ic|TapButton2}} to {{ic|0}}. Alternatively, see [[#Disable touchpad while typing]].<br />
* Recent versions include a "Coasting" feature, enabled by default, which may have the undesired effect of continuing almost any scrolling until the next tap or click, even if you are no longer touching the touchpad. This means that to scroll just a bit, you need to scroll (by using the edge, or a multitouch option) and then almost immediately tap the touchpad, otherwise scrolling will continue forever. If wish to avoid this, set {{ic|CoastingSpeed}} to {{ic|0}}.<br />
* If your touchpad is too sensitive, use higher values for {{ic|FingerLow}} and {{ic|FingerHigh}} and vice versa. Remember that {{ic|FingerLow}} should be smaller than {{ic|FingerHigh}}<br />
}}<br />
<br />
=== Configuration on the fly ===<br />
<br />
Next to the traditional method of configuration, the Synaptics driver also supports on the fly configuration. This means that users can set certain options through a software application, these options are applied immediately without needing to restart Xorg. This is useful to test configuration options before you include them in the configuration file or a script. Note that on the fly configuration is not persistent and lasts only until the Xorg server exists.<br />
<br />
==== Console tools ====<br />
<br />
* {{App|[[#Synclient|Synclient]]|command line utility to configure and query Synaptics driver settings|http://xorg.freedesktop.org/|{{Pkg|xf86-input-synaptics}}}}<br />
* {{App|[[#Using xinput to determine touchpad capabilities|xinput]]|general-purpose utility to configure X input devices|http://xorg.freedesktop.org/|{{Pkg|xorg-xinput}}}}<br />
<br />
==== Graphical tools ====<br />
<br />
* {{App|GPointing Device Settings|Provides graphical on the fly configuration for several pointing devices connected to the system, including your synaptics touch pad. This application replaces GSynaptics as the preferred tool for graphical touchpad configuration through the synaptics driver.|https://wiki.gnome.org/Attic/GPointingDeviceSettings|{{AUR|gpointing-device-settings}}}}<br />
* {{App|kcm_touchpad|New configuration tool for [[KDE]] Plasma 5. It provides a module under input devices in System Settings. It is to be considered a replacement for ''synaptiks'' and the old ''kcm-touchpad'' module.|https://cgit.kde.org/plasma-desktop.git/tree/kcms/touchpad|4={{Pkg|plasma-desktop}}}}<br />
<br />
=== Xfce4/Cinnamon ===<br />
<br />
To change these settings in ''XFCE 4''':<br />
<br />
# Open ''System Settings''.<br />
# Click ''Mouse and Touchpad''.<br />
# Change the settings on the ''Touchpad'' tab.<br />
<br />
To change these settings in '''Cinnamon''':<br />
<br />
# Open ''Cinnamon System Settings''.<br />
# Click ''Mouse and Touchpad''.<br />
# Change the settings on the ''Touchpad'' tab.<br />
<br />
=== MATE ===<br />
<br />
It is possible configure the way MATE handles the touchpad:<br />
<br />
# Run {{ic|dconf-editor}}<br />
# Edit the keys in the {{ic|org.mate.desktop.peripherals.touchpad}} folder.<br />
<br />
To prevent Mate settings daemon from overriding existing settings, do as follows:<br />
<br />
# Run {{ic|dconf-editor}}<br />
# Edit {{ic|org.mate.SettingsDaemon.plugins.mouse}}<br />
# Uncheck the '''active''' setting.<br />
<br />
== Advanced configuration ==<br />
<br />
=== Using xinput to determine touchpad capabilities ===<br />
<br />
Depending on your model, synaptic touchpads may have or lack capabilities. We can determine which capabilities your hardware supports by using {{ic|xinput}}.<br />
<br />
* left, middle and right hardware buttons<br />
* two finger detection<br />
* three finger detection<br />
* configurable resolution<br />
<br />
First, find the name of your touchpad:<br />
<br />
$ xinput list<br />
<br />
You can now use {{ic|xinput}} to find your touchpad's capabilities:<br />
<br />
{{hc|$ xinput list-props "SynPS/2 Synaptics TouchPad" {{!}} grep Capabilities|<br />
Synaptics Capabilities (309): 1, 0, 1, 0, 0, 1, 1<br />
}}<br />
<br />
From left to right, this shows:<br />
* {{ic|1}}: device has a physical left button<br />
* {{ic|0}}: device does not have a physical middle button<br />
* {{ic|1}}: device has a physical right button<br />
* {{ic|0}}: device does not support two-finger detection<br />
* {{ic|0}}: device does not support three-finger detection<br />
* {{ic|1}}: device can configure vertical resolution<br />
* {{ic|1}}: device can configure horizontal resolution<br />
<br />
Use {{ic|xinput list-props "SynPS/2 Synaptics TouchPad"}} to list all device properties. See {{man|4|synaptics}} for full documentation of the Synaptics properties.<br />
<br />
=== Synclient ===<br />
<br />
Synclient can configure every option available to the user as documented in {{man|4|synaptics}}. A full list of the current user settings can be brought up:<br />
<br />
$ synclient -l<br />
<br />
Every listed configuration option can be controlled through synclient, for example:<br />
<br />
* Enable palm detection: {{ic|1=$ synclient PalmDetect=1}} <br />
* Configure button events (right button event for two finger tap here): {{ic|1=$ synclient TapButton2=3}} <br />
* Disable the touchpad: {{ic|1=$ synclient TouchpadOff=1}} <br />
<br />
After you have successfully tried and tested your options through synclient, you can make these changes permanent by adding them to {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}.<br />
<br />
=== evtest ===<br />
<br />
The tool {{Pkg|evtest}} can display pressure and placement on the touchpad in real-time, allowing further refinement of the default Synaptics settings. The evtest monitoring can be started with:<br />
<br />
$ evtest /dev/input/event''X''<br />
<br />
''X'' denotes the touchpad's ID. It can be found by looking at the output of {{ic|cat /proc/bus/input/devices}}.<br />
<br />
evtest needs exclusive access to the device which means it cannot be run together with an X server instance. You can either kill the X server or run evtest from a different virtual terminal (e.g., by pressing {{ic|Ctrl+Alt+2}}).<br />
<br />
=== xev ===<br />
<br />
The tool {{Pkg|xorg-xev}} can display taps, clicks, pressure, placement and other measured parameters in real-time, allowing still further refinement of the default Synaptics settings. xev can be run in X and needs no specifics. using the "-event" parameter, it is possible to restrict the types of events that are reported.<br />
<br />
=== Circular Scrolling ===<br />
<br />
Circular scrolling is a feature that Synaptics offers which closely resembles the behaviour of iPods. Instead of (or additional to) scrolling horizontally or vertically, you can scroll circularly. Some users find this faster and more precise.<br />
To enable circular scrolling, add the following options to the touchpad device section of {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}:<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
...<br />
Option "CircularScrolling" "on"<br />
Option "CircScrollTrigger" "0"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
The option '''CircScrollTrigger''' may be one of the following values, determining which edge circular scrolling should start:<br />
<br />
0 All Edges<br />
1 Top Edge<br />
2 Top Right Corner<br />
3 Right Edge<br />
4 Bottom Right Corner<br />
5 Bottom Edge<br />
6 Bottom Left Corner<br />
7 Left Edge<br />
8 Top Left Corner<br />
<br />
Specifying something different from zero may be useful if you want to use circular scrolling in conjunction with horizontal and/or vertical scrolling. If you do so, the type of scrolling is determined by the edge you start from.<br />
<br />
To scroll fast, draw small circles in the center of your touchpad. To scroll slowly and more precise, draw large circles.<br />
<br />
=== Natural scrolling ===<br />
<br />
It is possible to enable natural scrolling through synaptics. Simply use negative values for {{ic|VertScrollDelta}} and {{ic|HorizScrollDelta}} like so:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
...<br />
Option "VertScrollDelta" "-111"<br />
Option "HorizScrollDelta" "-111"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
=== Software toggle ===<br />
<br />
You might want to turn the touchpad on and off with a simple button click or shortcut. This can be done by binding the following ''xinput''-based script to a keyboard event as explained in [[Extra keyboard keys in Xorg]]:<br />
<br />
{{hc|/usr/local/bin/touchpad_toggle.sh|2=<nowiki><br />
#!/bin/bash<br />
<br />
declare -i ID<br />
ID=`xinput list | grep -Eio '(touchpad|glidepoint)\s*id\=[0-9]{1,2}' | grep -Eo '[0-9]{1,2}'`<br />
declare -i STATE<br />
STATE=`xinput list-props $ID|grep 'Device Enabled'|awk '{print $4}'`<br />
if [ $STATE -eq 1 ]<br />
then<br />
xinput disable $ID<br />
# echo "Touchpad disabled."<br />
# notify-send -a 'Touchpad' 'Disabled' -i /usr/share/icons/Adwaita/48x48/devices/input-touchpad.png<br />
else<br />
xinput enable $ID<br />
# echo "Touchpad enabled."<br />
# notify-send -a 'Touchpad' 'Enabled' -i /usr/share/icons/Adwaita/48x48/devices/input-touchpad.png<br />
fi<br />
</nowiki>}}<br />
<br />
{{Tip|When using external monitors with [[bumblebee]], the touchpad can be configured on the second X server by prepending {{ic|1=DISPLAY=:8}} to the command.}} <br />
<br />
Alternatively, {{ic|synclient}} can be used to toggle the touchpad. However, it can only turn off touch events but not physical clickpad button usage:<br />
<br />
{{hc|/usr/local/bin/touchpad.sh|<nowiki><br />
#!/bin/bash<br />
<br />
synclient TouchpadOff=$(synclient -l | grep -c 'TouchpadOff.*=.*0')<br />
</nowiki>}}<br />
<br />
=== Disable touchpad while typing ===<br />
<br />
==== Using the driver's automatic palm detection ====<br />
<br />
First of all you should test if it works properly for your touchpad and if the settings are accurate. Enable palm detection with<br />
<br />
$ synclient PalmDetect=1<br />
<br />
Then test the typing. You can tweak the detection by setting the minimum width for the touch to be considered a palm, for example<br />
<br />
$ synclient PalmMinWidth=8<br />
<br />
And you can tweak the minimum pressure required for the touch to be considered a palm, for example<br />
<br />
$ synclient PalmMinZ=100<br />
<br />
{{Tip|To help find the best values for palm detection, you can use {{pkg|evtest}} to see the width and Z values reported during touchpad use.}}<br />
<br />
Once you have found the correct settings, you can add them to your [[#Configuration|config file]]:<br />
<br />
{{bc|<nowiki><br />
Option "PalmDetect" "1"<br />
Option "PalmMinWidth" "8"<br />
Option "PalmMinZ" "100"<br />
</nowiki>}}<br />
<br />
{{Warning|1=For some touchpads, an [https://bugzilla.kernel.org/show_bug.cgi?id=77161 issue] with the kernel can cause the palm width to always be reported as 0. This breaks palm detection in a majority of cases. Pending an actual fix, you can [https://gist.github.com/silverhammermba/a231c8156ecaa63c86f1 patch] the synaptics package to use only Z for palm detection.}}<br />
<br />
{{Tip|If you experience problems with consistent palm detection for your hardware, an alternative to try is [[libinput]].}}<br />
<br />
==== Using syndaemon ====<br />
<br />
{{ic|syndaemon}} monitors keyboard activity and disables the touchpad while typing. It has several options to control when the disabling occurs. View them with<br />
<br />
$ syndaemon -h<br />
<br />
For example, to disable tapping and scrolling for 0.5 seconds after each keypress (ignoring modifier keys like Ctrl), use<br />
<br />
$ syndaemon -i 0.5 -t -K -R<br />
<br />
Once you have determined the options you like, you should use your login manager or [[xinitrc]] to have it run automatically when X starts. The {{ic|-d}} option will make it start in the background as a daemon.<br />
<br />
=== Disable touchpad on mouse detection ===<br />
<br />
With the assistance of [[udev]], it is possible to automatically disable the touchpad if an external mouse has been plugged in. To achieve this, use one of the following rules.<br />
<br />
==== Basic desktop ====<br />
<br />
This is a basic rule generally for non-"desktop environment" sessions:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="add", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/synclient TouchpadOff=1"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="remove", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/synclient TouchpadOff=0"<br />
}}<br />
<br />
If the touchpad is always deactivated at startup, even when no mouse is plugged in, try adding the following criteria between the KERNEL and ACTION parameters above:<br />
<br />
ATTRS{name}!="*TouchPad", ATTRS{name}!="*Stick",<br />
<br />
==== GDM ====<br />
<br />
{{Accuracy|saying that GDM ''usually'' does something does not make sense}}<br />
<br />
GDM usually stores the Xauthority files in {{ic|/var/run/gdm}} in a randomly-named directory. You should find your actual path to the Xauthority file which can be done using {{ic|ps ax}}. For some reason multiple authority files may appear for a user, so a rule like will be necessary:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="add", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print0 -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/usr/bin/synclient TouchpadOff=1"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="remove", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print0 -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/usr/bin/synclient TouchpadOff=0"<br />
}}<br />
<br />
Furthermore, you should validate that your udev script is running properly! You can check for the conditions using {{ic| udevadm monitor -p}} which must be run as root.<br />
<br />
===== With syndaemon running =====<br />
<br />
{{ic|syndaemon}} whether started by the [[#Using syndaemon|user]] or the desktop environment can conflict with synclient and will need to be disabled. A rule like this will be needed:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="add", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/bin/sh -c '/usr/bin/synclient TouchpadOff=1 ; sleep 1; /bin/killall syndaemon; '"<br />
}}<br />
<br />
===== touchpad-state =====<br />
<br />
An AUR package {{aur|touchpad-state-git}} has been created around the udev rules above. It includes a udev rule and script:<br />
<br />
touchpad-state [--off] [--on]<br />
<br />
==== GNOME ====<br />
<br />
GNOME users can install GNOME shell extension [https://extensions.gnome.org/extension/131/touchpad-indicator/ Touchpad Indicator], change "Switch Method" to "Synclient" and enable "Automatically switch Touchpad On/Off" in its preferences.<br />
<br />
==== KDE ====<br />
<br />
If using Plasma, the package {{Pkg|plasma-desktop}} can be used to manage the touchpad.<br />
<br />
==== System with multiple X sessions ====<br />
<br />
{{Accuracy|Hard-coded {{ic|DISPLAY}} variable does not work with multiple X sessions.}} <br />
<br />
For an environment where multiple users are present, a slightly different approach is needed to detect the current users X environment. This script will help achieving this:<br />
<br />
{{hc|/usr/bin/mouse-pnp-event-handler.sh|<nowiki><br />
#!/bin/sh<br />
## $1 = "add" / "remove"<br />
## $2 = %k from udev <br />
<br />
## Set TRACKPAD_NAME according to your configuration. <br />
## Check your trackpad name with: <br />
## find /sys/class/input/ -name mouse* -exec udevadm info -a {} \; | grep 'ATTRS{name}'<br />
TRACKPAD_NAME="SynPS/2 Synaptics TouchPad"<br />
<br />
USERLIST=$(w -h | cut -d' ' -f1 | sort | uniq)<br />
MOUSELIST=$(find /sys/class/input/ -name mouse*)<br />
<br />
for CUR_USER in ${USERLIST}; do<br />
CUR_USER_XAUTH="$(sudo -Hiu ${CUR_USER} env | grep -e "^HOME=" | cut -d'=' -f2)/.Xauthority"<br />
<br />
<br />
## Can't find a way to get another users DISPLAY variable from an isolated root environment. Have to set it manually.<br />
#CUR_USER_DISPL="$(sudo -Hiu ${CUR_USER} env | grep -e "^DISPLAY=" | cut -d'=' -f2)"<br />
CUR_USER_DISPL=":0"<br />
<br />
export XAUTHORITY="${CUR_USER_XAUTH}"<br />
export DISPLAY="${CUR_USER_DISPL}"<br />
<br />
if [ -f "${CUR_USER_XAUTH}" ]; then<br />
case "$1" in<br />
"add")<br />
/usr/bin/synclient TouchpadOff=1<br />
/usr/bin/logger "USB mouse plugged. Disabling touchpad for $CUR_USER. ($XAUTHORITY - $DISPLAY)"<br />
;;<br />
"remove")<br />
## Only execute synclient if there are no external USB mice connected to the system.<br />
EXT_MOUSE_FOUND="0"<br />
for CUR_MOUSE in ${MOUSELIST}; do<br />
if [ "$(cat ${CUR_MOUSE}/device/name)" != "${TRACKPAD_NAME}" ]; then<br />
EXT_MOUSE_FOUND="1"<br />
fi<br />
done<br />
if [ "${EXT_MOUSE_FOUND}" == "0" ]; then<br />
/usr/bin/synclient TouchpadOff=0<br />
/usr/bin/logger "No additional external mice found. Enabling touchpad for $CUR_USER."<br />
else<br />
logger "Additional external mice found. Won't enable touchpad yet for $CUR_USER."<br />
fi<br />
;;<br />
esac<br />
fi<br />
done<br />
</nowiki>}}<br />
<br />
Update the {{ic|TRACKPAD_NAME}} variable for your system configuration.<br />
Run {{ic|<nowiki>find /sys/class/input/ -name mouse* -exec udevadm info -a {} \; | grep 'ATTRS{name}'</nowiki>}} to get a list of useful mice-names. Choose the one for your trackpad.<br />
<br />
Then have udev run this script when USB mices are plugged in or out, with these udev rules:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="add", RUN+="/usr/bin/mouse-pnp-event-handler.sh add %k"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="remove", RUN+="/usr/bin/mouse-pnp-event-handler.sh remove %k"<br />
}}<br />
<br />
=== Buttonless touchpads (aka ClickPads) ===<br />
<br />
Ever more laptops have a special kind of touchpad which has a single mouse button as part of the tracking plate, instead of external buttons. For example, the 2015 Dell XPS 13, HP series 4500 ProBooks, ThinkPad X220 and X1 ThinkPad series have this kind of a touchpad. By default, the whole button area is detected as a left button, so right and middle-click functions and click + drag will not work. It is possible to define two and three finger clicks as right and middle button clicks, and/or to define parts of the click pad surface as right and middle buttons. Note that although the driver registers multiple touches, it does not track individual fingers (as of version 1.7.1) which results in confusing behavior when using physical buttons of a clickpad for drag-and-drop and other gestures: you have to click with two or three fingers but then only move one of them while holding the button down with another. You can look into the {{AUR|xf86-input-mtrack}} driver for better multitouch support.<br />
<br />
Some desktop environments (KDE and GNOME at least) define sane and useful default configurations for clickpads, providing a right button at the bottom right of the pad, recognising two and three-finger clicks anywhere on the pad as right and middle clicks, and providing configuration options to define two and three-finger taps as right and middle clicks. If your desktop does not do this, or if you want more control, you can modify the touchpad section in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} (or better, of your custom synaptics configuration file prefixed with a higher number). For example:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
# Enable clickpad/multitouch support<br />
Option "ClickPad" "true"<br />
# Middle-button emulation is not supported<br />
Option "EmulateMidButtonTime" "0"<br />
# Define right soft button at the bottom<br />
Option "SoftButtonAreas" "50% 0 82% 0 0 0 0 0"<br />
EndSection<br />
</nowiki>}}<br />
<br />
The format for the SoftButtonAreas option is (from {{man|4|synaptics}}):<br />
{{bc|RightButtonAreaLeft RightButtonAreaRight RightButtonAreaTop RightButtonAreaBottom MiddleButtonAreaLeft MiddleButtonAreaRight MiddleButtonAreaTop MiddleButtonAreaBottom}}<br />
<br />
The above "SoftButtonAreas" option is commonly found in documentation or synaptics packages, and it defines the right half of the bottom 18% of the touchpad as a right button. There is '''no middle button''' defined. If you want to define a middle button remember one key piece of information from the manual; '''edge set to 0 extends to infinity in that direction.'''<br />
<br />
In the following example the right button will occupy the rightmost 40% of the button area and the middle button 20% of it in the center. The leftmost 40% remains as a left button (as does the rest of the clickpad):<br />
<br />
...<br />
Option "SoftButtonAreas" "60% 0 82% 0 40% 59% 82% 0"<br />
...<br />
<br />
You can use {{ic|<nowiki>synclient</nowiki>}} to check the soft button areas: <br />
<br />
{{hc|<nowiki>$ synclient -l | grep -i ButtonArea</nowiki>|<nowiki><br />
RightButtonAreaLeft = 3914<br />
RightButtonAreaRight = 0<br />
RightButtonAreaTop = 3918<br />
RightButtonAreaBottom = 0<br />
MiddleButtonAreaLeft = 3100<br />
MiddleButtonAreaRight = 3873<br />
MiddleButtonAreaTop = 3918<br />
MiddleButtonAreaBottom = 0<br />
</nowiki>}}<br />
<br />
If your buttons are not working, soft button areas are not changing, ensure you do not have a synaptics configuration file distributed by a package which is overriding your custom settings (ie. some AUR packages distribute configurations prefixed with very high numbers).<br />
<br />
These settings cannot be modified on the fly with {{ic|<nowiki>synclient</nowiki>}}, however, {{ic|<nowiki>xinput</nowiki>}} works:<br />
<br />
xinput set-prop "SynPS/2 Synaptics TouchPad" "Synaptics Soft Button Areas" 4000 0 4063 0 3000 4000 4063 0<br />
<br />
You cannot use percentages with this command, so look at {{ic|/var/log/Xorg.0.log}} to figure out the touchpad x and y-axis ranges.<br />
<br />
==== Bottom edge correction ====<br />
<br />
In some cases, for example Toshiba Satellite P50, everything work out of the box except often your click are seen as mouse movement and the cursor will jump away just before registering the click.<br />
This can be easily solved running<br />
<br />
$ synclient -l | grep BottomEdge<br />
<br />
take the BottomEdge value and subtract a the wanted height of your button, then temporary apply with<br />
<br />
$ synclient AreaBottomEdge=4000<br />
<br />
when a good value has been found make it a fixed correction with<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
...<br />
Option "AreaBottomEdge" "4000"<br />
...<br />
</nowiki>}}<br />
<br />
{{Note|The area will not act as touchpad if the touch '''begins''' in that area, but it can still be used if the touch has originated outside.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad does not work after resuming from hibernate/suspend ===<br />
<br />
Occasionally touchpads will fail to work when the computer resumes from sleep or hibernation. This can often be corrected without rebooting by<br />
<br />
* Switching to a console and back again,<br />
* entering sleep mode again, and resuming again, or<br />
* locating the correct kernel module, then removing it and inserting it again. <br />
* blacklisting kernel module psmouse may be a permanent option (when the touchpad is handled by another module, eg i2c_designware_platform)<br />
<br />
{{Note|You can use Ctrl-Alt-F1 through F8 to switch to a console without using the mouse.}}<br />
<br />
modprobe -r psmouse #psmouse happens to be the kernel module for my touchpad (Alps DualPoint)<br />
modprobe psmouse<br />
<br />
Now switch back to the tty that X is running on. If you chose the right module, your touchpad should be working again.<br />
<br />
=== xorg.conf.d/70-synaptics.conf does not seem to apply in MATE ===<br />
<br />
[[MATE]] will by default overwrite various options for your touchpad. This includes configurable features for which there is no graphical configuration within MATE's system control panel. This may cause it to appear that {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} is not applied. Follow [[#MATE]] to prevent this behavior.<br />
<br />
=== The touchpad is not working, Xorg.0.log shows "Query no Synaptics: 6003C8" ===<br />
<br />
Due to the way synaptics is currently set-up, 2 instances of the synaptics module are loaded. We can recognize this situation by opening the xorg log file ({{ic|/var/log/Xorg.0.log}}) and noticing this:<br />
<br />
{{hc|/var/log/Xorg.0.log|<nowiki><br />
[ 9304.803] (**) SynPS/2 Synaptics TouchPad: Applying InputClass "evdev touchpad catchall"<br />
[ 9304.803] (**) SynPS/2 Synaptics TouchPad: Applying InputClass "touchpad catchall"<br />
</nowiki>}}<br />
<br />
Notice how 2 differently named instances of the module are being loaded. In some cases, this causes the touchpad to become nonfunctional.<br />
<br />
We can prevent this double loading by adding {{ic|MatchDevicePath "/dev/input/event*"}} to our {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} file:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad catchall"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
MatchDevicePath "/dev/input/event*"<br />
Option "TapButton1" "1"<br />
Option "TapButton2" "2"<br />
Option "TapButton3" "3"<br />
EndSection <br />
</nowiki>}}<br />
<br />
Restart X and check xorg logs again, the error should be gone and the touchpad should be functional.<br />
<br />
related bugreport: {{Bug|20830}}<br />
<br />
related forum topics:<br />
<br />
* https://bbs.archlinux.org/viewtopic.php?id=104769<br />
* https://bbs.archlinux.org/viewtopic.php?pid=825690<br />
<br />
=== Touchpad detected as "PS/2 Generic Mouse" or "Logitech PS/2 mouse" ===<br />
<br />
This can be caused by a number of issues;<br />
<br />
==== Elantech touchpads ====<br />
<br />
This can happen with some laptops with an Elantech touchpad, for example the ASUS x53s. In this situation you need {{AUR|psmouse-alps-driver}}{{Broken package link|{{aur-mirror|psmouse-alps-driver}}}} package from [[AUR]].<br />
<br />
==== Laptops with touchscreen & touchpad ====<br />
<br />
There also seems to be a problem with laptops which have both a touchscreen & a touchpad, such as the Dell XPS 12 or Dell XPS 13. To fix this, you can [[blacklisting|blacklist]] the {{ic|i2c_hid}} driver, this does have the side-effect of disabling the touchscreen though.<br />
<br />
This [http://www.spinics.net/lists/linux-input/msg27768.html seems to be a known problem]. Also see [https://bbs.archlinux.org/viewtopic.php?pid=1419078 this thread].<br />
<br />
Post kernel 3.15, having the module blacklisted may cause touchpad to stop working completely. Removing the blacklist should allow this to start working with limited functionality, see {{Bug|40921}}.<br />
<br />
=== Non-functional Synaptics special abilities (multi-tap, scrolling, etc.) ===<br />
<br />
In some cases Synaptics touchpads only work partially. Features like two-finger scrolling or two-finger middle-click do not work even if properly enabled. This is probably related to the [[#The touchpad is not working, Xorg.0.log shows "Query no Synaptics: 6003C8"|The touchpad is not working]] problem mentioned above. Fix is the same, prevent double module loading.<br />
<br />
If preventing the module from loading twice does not solve your issue, try commenting out the toggle {{ic|MatchIsTouchpad}} (which is now included by default in the synaptics config).<br />
<br />
If clicking with either 2 or 3 fingers is interpreted as a right-click, so you cannot get a middle click either way regardless of configuration, this bug is probably the culprit: https://bugs.freedesktop.org/show_bug.cgi?id=55365<br />
<br />
====No Multi-touch in some Elantech touchpads====<br />
<br />
See [http://unix.stackexchange.com/questions/28736/what-does-the-i8042-nomux-1-kernel-option-do-during-booting-of-ubuntu].<br />
<br />
=== Cursor jump ===<br />
<br />
Some users have their cursor inexplicably ''jump'' around the screen. There currently no patch for this, but the developers are aware of the problem and are working on it.<br />
<br />
Another posibility is that you are experiencing ''IRQ losses'' related to the i8042 controller (this device handles the keyboard and the touchpad of many laptops), so you have two possibilities here:<br />
<br />
1. rmmod && insmod the psmouse module.<br />
<br />
2. append {{ic|1=i8042.nomux=1}} to your [[kernel parameters]] and reboot your machine.<br />
<br />
=== Touchpad device is not located at {{ic|/dev/input/*}} ===<br />
<br />
If that is the case, you can use this command to display information about your input devices:<br />
<br />
$ cat /proc/bus/input/devices<br />
<br />
Search for an input device which has the name "SynPS/2 Synaptics TouchPad". The "Handlers" section of the output specifies what device you need to specify.<br />
<br />
'''Example output:'''<br />
<br />
{{hc|$ cat /proc/bus/input/devices|<nowiki><br />
I: Bus=0011 Vendor=0002 Product=0007 Version=0000<br />
N: Name="SynPS/2 Synaptics TouchPad"<br />
P: Phys=isa0060/serio4/input0<br />
S: Sysfs=/class/input/input1<br />
H: Handlers=mouse0 event1<br />
B: EV=b<br />
B: KEY=6420 0 7000f 0<br />
</nowiki>}}<br />
<br />
In this case, the {{ic|Handlers}} are {{ic|mouse0}} and {{ic|event1}}, so {{ic|/dev/input/mouse0}} would be used.<br />
<br />
{{Expansion|TODO: explain how to apply this in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}}}<br />
<br />
=== Firefox and special touchpad events ===<br />
<br />
You can enable/disable some special events that Firefox handles upon tapping or scrolling certain parts of your touchpad by editing the settings of those actions.<br />
Type {{ic|about:config}} in your Firefox address bar.<br />
To alter options, double-click on the line in question.<br />
<br />
==== Firefox 17.0 and later ====<br />
<br />
Horizontal scrolling will now by default scroll through pages and not through your history. To reenable Mac-style forward/backward with two-finger swiping, edit:<br />
<br />
mousewheel.default.action.override_x = 2<br />
<br />
You may encounter accidental forwards/backwards while scrolling vertically. To change Firefox's sensitivity to horizontal swipes, edit:<br />
<br />
mousewheel.default.delta_multiplier_x<br />
<br />
The optimum value will depend on your touchpad and how you use it, try starting with {{ic|10}}. A negative value will reverse the swipe directions.<br />
<br />
=== Opera: horizontal scrolling issues ===<br />
<br />
Same as above.<br />
To fix it, go to ''Tools > Preferences > Advanced > Shortcuts''. Select "Opera Standard" mouse setup and click "Edit". In "Application" section:<br />
<br />
{{Accuracy|Description here is not so clear and i don't use Opera,Please make it clear :)}}<br />
<br />
* assign key "Button 6" to command "Scroll left"<br />
* assign key "Button 7" to command "Scroll right"<br />
<br />
=== Scrolling and multiple actions with Synaptics on LG laptops ===<br />
<br />
These problems seem to be occurring on several models of LG laptops.<br />
Symptoms include: when pressing Mouse Button 1, Synaptics interprets it as ScrollUP and a regular button 1 click; same goes for button 2.<br />
<br />
The scrolling issue can be resolved by entering in {{ic|xorg.conf}}:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "UpDownScrolling" "0"<br />
}}<br />
<br />
{{Note|This will make Synaptics interpret one button push as three. There is a patch written by Oskar Sandberg [http://www.math.chalmers.se/~ossa/linux/lg_tx_express.html] that removes these clicks.}}<br />
<br />
Apparently, when trying to compile this against the latest version of Synaptics it fails. The solution to this is using the GIT repository for Synaptics [http://web.telia.com/~u89404340/touchpad/synaptics/.git].<br />
<br />
To build the package after downloading the tarball and unpacking it, execute:<br />
<br />
$ cd synaptics-git<br />
$ makepkg<br />
<br />
=== Other external mouse issues ===<br />
<br />
First, make sure your section describing the external mouse contains this line (or that the line looks like this):<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "Device" "/dev/input/mice"<br />
}}<br />
<br />
If the "Device" line is different, change it to the above and try to restart X. If this does not solve your problem, make your '''touchpad''' is the CorePointer in the "Server Layout" section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
InputDevice "Touchpad" "CorePointer"<br />
}}<br />
<br />
and make your external device "SendCoreEvents":<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
InputDevice "USB Mouse" "SendCoreEvents"<br />
}}<br />
<br />
finally add this to your external device's section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "SendCoreEvents" "true"<br />
}}<br />
<br />
If all of the above does not work for you, please check relevant bug trackers for possible bugs, or go through the forums to see if anyone has found a better solution.<br />
<br />
=== Touchpad synchronization issues ===<br />
<br />
{{Out of date|section=Outdated "Touchpad synchronization issues" section}}<br />
<br />
Sometimes the cursor may freeze for several seconds or start acting on its own for no apparent reason. This behavior is accompanied by records in {{ic|/var/log/messages.log}}<br />
<br />
{{hc|/var/log/messages.log|<br />
psmouse.c: TouchPad at isa0060/serio1/input0 lost synchronization, throwing 3 bytes away<br />
}}<br />
<br />
This problem has no general solution, but there are several possible workarounds.<br />
* If you use CPU frequency scaling, avoid using the "ondemand" governor and use the "performance" governor when possible, as the touchpad may lose sync when the CPU frequency changes.<br />
* Avoid using an ACPI battery monitor.<br />
* Attempt to load psmouse with "proto=imps" option. To do that, add this line to your {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/modprobe.conf|2=<br />
options psmouse proto=imps<br />
}}<br />
<br />
* Try another desktop environment. Some users report that this problem only occurs when using XFCE or GNOME, for whatever reason<br />
<br />
=== Xorg.log.0 shows SynPS/2 Synaptics touchpad can not grab event device, errno=16 ===<br />
<br />
If you are using Xorg 7.4, you may get a warning like this from {{ic|/var/log/Xorg.0.log}}, thais is because the driver will grab the event device for exclusive use when using the Linux 2.6 event protocol. When it fails, X will return this error message.<br />
<br />
Grabbing the event device means that no other user space or kernel space program sees the touchpad events. This is desirable if the X config file includes {{ic|/dev/input/mice}} as an input device, but is undesirable if you want to monitor the device from user space.<br />
<br />
If you want to control it, add or modify the "GrabEventDevice" option in you touchpad section in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|2=<br />
...<br />
Option "GrabEventDevice" "''boolean''"<br />
...<br />
}}<br />
<br />
This will come into effect when X is restarted, though you can also change it by using synclient. When changing this parameter with the synclient program, the change will not take effect until the Synaptics driver is disabled and re-enabled. This can be achieved by switching to a text console and then switching back to X.<br />
<br />
=== Synaptics loses multitouch detection after rebooting from Windows ===<br />
<br />
Many drivers include a firmware that is loaded into flash memory when the computer boots. This firmware is not necessarily cleared upon shutdown, and is not always compatible with Linux drivers. The only way to clear the flash memory is to shutdown completely rather than using reboot. It is generally considered best practice to never use reboot when switching between operating systems.<br />
<br />
=== Touchpad not recognized after shutdown from Arch ===<br />
<br />
Certain touchpads (elantech in particular) will fail to be recognized as a device of any sort after a standard shutdown from Arch linux. There are multiple possible solutions to this problem:<br />
<br />
* Boot into a Windows partition/install disk and shutdown from there.<br />
* Wait approximately 1 minute before turning on the computer after shutdown.<br />
* As discussed in https://bugzilla.kernel.org/show_bug.cgi?id=81331#c186 a patch has been merged into the stable kernel that provides a fix for Elantech touchpads. Gigabyte P34, P35v2 and X3 models are supported by default, for others (especially rebranded Gigabyte laptops, like XMG's) {{ic|1=i8042.kbdreset=1}} can be set as kernel parameter.<br />
<br />
=== Trackpoint and Clickpad ===<br />
<br />
Newer Thinkpads do not have physical buttons for their Trackpoint anymore and instead use the upper area of the Clickpad for buttons (Left, Middle, Right). <br />
Apart from the ergonomic viewpoint this works quite well with current Xorg. Unfortunately mouse wheel emulation using the middle button is not supported yet. Install {{AUR|xf86-input-evdev-trackpoint}} from the AUR for a patched and properly configured version if you intend to use the Trackpoint.<br />
<br />
== See also ==<br />
<br />
* [http://cgit.freedesktop.org/xorg/driver/xf86-input-synaptics/ Synaptics touchpad driver]<br />
* [http://www.x.org/archive/X11R7.5/doc/man/man4/synaptics.4.html Synaptics manual on x.org ]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=Touchpad_Synaptics&diff=509655Touchpad Synaptics2018-02-04T10:48:24Z<p>Ketsui: /* Configuration */ Help:Editing#Links_to_sections_of_a_document</p>
<hr />
<div>[[Category:Input devices]]<br />
[[de:Synaptics Touchpad Treiber]]<br />
[[es:Touchpad Synaptics]]<br />
[[fr:Touchpad Synaptics]]<br />
[[it:Touchpad Synaptics]]<br />
[[ja:Synaptics タッチパッド]]<br />
[[ru:Touchpad Synaptics]]<br />
[[zh-hans:Touchpad Synaptics]]<br />
{{Related articles start}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
This article details the installation and configuration process of the '''''Synaptics input driver''''' for Synaptics (and ALPS) touchpads found on most notebooks.<br />
<br />
{{Warning|{{pkg|xf86-input-synaptics}} is no longer actively updated. If possible, use [[libinput]].}}<br />
<br />
{{Note|1=If you want to configure touchpad via GNOME control center, you need to use the [[libinput]] driver.[https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12]}}<br />
<br />
== Installation ==<br />
<br />
The Synaptics driver can be [[installed]] with the package {{Pkg|xf86-input-synaptics}}.<br />
<br />
== Configuration ==<br />
<br />
The primary method of configuration for the touchpad is through an [[Xorg]] server configuration file. After installation of {{ic|xf86-input-synaptics}}, a default configuration file is located at {{ic|/usr/share/X11/xorg.conf.d/70-synaptics.conf}}. Users can copy this file to {{ic|/etc/X11/xorg.conf.d/}} and edit it to configure the various driver options available. Refer to the {{man|4|synaptics}} manual page for a complete list of available options. Machine-specific options can be discovered using [[#synclient]].<br />
<br />
=== Frequently used options ===<br />
<br />
The following example file configures some common options, including vertical, horizontal and circular scrolling as well as tap-to-click:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
Option "TapButton1" "1"<br />
Option "TapButton2" "3"<br />
Option "TapButton3" "2"<br />
Option "VertEdgeScroll" "on"<br />
Option "VertTwoFingerScroll" "on"<br />
Option "HorizEdgeScroll" "on"<br />
Option "HorizTwoFingerScroll" "on"<br />
Option "CircularScrolling" "on"<br />
Option "CircScrollTrigger" "2"<br />
Option "EmulateTwoFingerMinZ" "40"<br />
Option "EmulateTwoFingerMinW" "8"<br />
Option "CoastingSpeed" "0"<br />
Option "FingerLow" "30"<br />
Option "FingerHigh" "50"<br />
Option "MaxTapTime" "125"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
; TapButton1: (integer) configures which mouse-button is reported on a non-corner, one finger tap.<br />
; TapButton2: (integer) configures which mouse-button is reported on a non-corner, two finger tap<br />
; TapButton3: (integer) configures which mouse-button is reported on a non-corner, three finger tap<br />
; RBCornerButton: (integer) configures which mouse-button is reported on a right bottom corner, one finger tap (use {{ic|Option "RBCornerButton" "3"}} to achieve Ubuntu style tap behaviour for right mouse button in lower right corner)<br />
; RTCornerButton: (integer) as above, but for top right corner, one finger tap.<br />
; VertEdgeScroll: (boolean) enables vertical scrolling while dragging across the right edge of the touch pad.<br />
; HorizEdgeScroll: (boolean) enables horizontal scrolling while dragging across the bottom edge of the touch pad.<br />
; VertTwoFingerScroll: (boolean) enables vertical scrolling using two fingers.<br />
; HorizTwoFingerScroll: (boolean) enables horizontal scrolling using two fingers.<br />
; EmulateTwoFingerMinZ/W: (integer) play with this value to set the precision of two finger scroll.<br />
; FingerLow: (integer) when finger pressure drops below this value, the driver counts it as a release.<br />
; FingerHigh: (integer) when finger pressure goes above this value, the driver counts it as a touch.<br />
; MaxTapTime: Determines how "crisp" a tap must be to be considered a real tap. Decrease the value to require a more crisp tap. Properly adjusting this parameter can reduce false positives when the hands hover over or lightly touch the pad.<br />
; VertScrollDelta and HorizScrollDelta: (integer) configures the speed of scrolling, it is a bit counter-intuitive because higher values produce greater precision and thus slower scrolling. Negative values cause natural scrolling like in macOS.<br />
<br />
{{Note|<br />
* If you find that your hand frequently brushes your touchpad, causing the {{ic|TapButton2}} option to be triggered (which will more than likely paste from your clipboard), and you do not mind losing two-finger-tap functionality, set {{ic|TapButton2}} to {{ic|0}}. Alternatively, see [[#Disable touchpad while typing]].<br />
* Recent versions include a "Coasting" feature, enabled by default, which may have the undesired effect of continuing almost any scrolling until the next tap or click, even if you are no longer touching the touchpad. This means that to scroll just a bit, you need to scroll (by using the edge, or a multitouch option) and then almost immediately tap the touchpad, otherwise scrolling will continue forever. If wish to avoid this, set {{ic|CoastingSpeed}} to {{ic|0}}.<br />
* If your touchpad is too sensitive, use higher values for {{ic|FingerLow}} and {{ic|FingerHigh}} and vice versa. Remember that {{ic|FingerLow}} should be smaller than {{ic|FingerHigh}}<br />
}}<br />
<br />
=== Configuration on the fly ===<br />
<br />
Next to the traditional method of configuration, the Synaptics driver also supports on the fly configuration. This means that users can set certain options through a software application, these options are applied immediately without needing to restart Xorg. This is useful to test configuration options before you include them in the configuration file or a script. Note that on the fly configuration is not persistent and lasts only until the Xorg server exists.<br />
<br />
==== Console tools ====<br />
<br />
* {{App|[[#Synclient|Synclient]]|command line utility to configure and query Synaptics driver settings|http://xorg.freedesktop.org/|{{Pkg|xf86-input-synaptics}}}}<br />
* {{App|[[#Using xinput to determine touchpad capabilities|xinput]]|general-purpose utility to configure X input devices|http://xorg.freedesktop.org/|{{Pkg|xorg-xinput}}}}<br />
<br />
==== Graphical tools ====<br />
<br />
* {{App|GPointing Device Settings|Provides graphical on the fly configuration for several pointing devices connected to the system, including your synaptics touch pad. This application replaces GSynaptics as the preferred tool for graphical touchpad configuration through the synaptics driver.|https://wiki.gnome.org/Attic/GPointingDeviceSettings|{{AUR|gpointing-device-settings}}}}<br />
* {{App|kcm_touchpad|New configuration tool for [[KDE]] Plasma 5. It provides a module under input devices in System Settings. It is to be considered a replacement for ''synaptiks'' and the old ''kcm-touchpad'' module.|https://cgit.kde.org/plasma-desktop.git/tree/kcms/touchpad|4={{Pkg|plasma-desktop}}}}<br />
<br />
=== Xfce4/Cinnamon ===<br />
<br />
To change these settings in ''XFCE 4''':<br />
<br />
# Open ''System Settings''.<br />
# Click ''Mouse and Touchpad''.<br />
# Change the settings on the ''Touchpad'' tab.<br />
<br />
To change these settings in '''Cinnamon''':<br />
<br />
# Open ''Cinnamon System Settings''.<br />
# Click ''Mouse and Touchpad''.<br />
# Change the settings on the ''Touchpad'' tab.<br />
<br />
=== MATE ===<br />
<br />
It is possible configure the way MATE handles the touchpad:<br />
<br />
# Run {{ic|dconf-editor}}<br />
# Edit the keys in the {{ic|org.mate.desktop.peripherals.touchpad}} folder.<br />
<br />
To prevent Mate settings daemon from overriding existing settings, do as follows:<br />
<br />
# Run {{ic|dconf-editor}}<br />
# Edit {{ic|org.mate.SettingsDaemon.plugins.mouse}}<br />
# Uncheck the '''active''' setting.<br />
<br />
== Advanced configuration ==<br />
<br />
=== Using xinput to determine touchpad capabilities ===<br />
<br />
Depending on your model, synaptic touchpads may have or lack capabilities. We can determine which capabilities your hardware supports by using {{ic|xinput}}.<br />
<br />
* left, middle and right hardware buttons<br />
* two finger detection<br />
* three finger detection<br />
* configurable resolution<br />
<br />
First, find the name of your touchpad:<br />
<br />
$ xinput list<br />
<br />
You can now use {{ic|xinput}} to find your touchpad's capabilities:<br />
<br />
{{hc|$ xinput list-props "SynPS/2 Synaptics TouchPad" {{!}} grep Capabilities|<br />
Synaptics Capabilities (309): 1, 0, 1, 0, 0, 1, 1<br />
}}<br />
<br />
From left to right, this shows:<br />
* {{ic|1}}: device has a physical left button<br />
* {{ic|0}}: device does not have a physical middle button<br />
* {{ic|1}}: device has a physical right button<br />
* {{ic|0}}: device does not support two-finger detection<br />
* {{ic|0}}: device does not support three-finger detection<br />
* {{ic|1}}: device can configure vertical resolution<br />
* {{ic|1}}: device can configure horizontal resolution<br />
<br />
Use {{ic|xinput list-props "SynPS/2 Synaptics TouchPad"}} to list all device properties. See {{man|4|synaptics}} for full documentation of the Synaptics properties.<br />
<br />
=== Synclient ===<br />
<br />
Synclient can configure every option available to the user as documented in {{man|4|synaptics}}. A full list of the current user settings can be brought up:<br />
<br />
$ synclient -l<br />
<br />
Every listed configuration option can be controlled through synclient, for example:<br />
<br />
* Enable palm detection: {{ic|1=$ synclient PalmDetect=1}} <br />
* Configure button events (right button event for two finger tap here): {{ic|1=$ synclient TapButton2=3}} <br />
* Disable the touchpad: {{ic|1=$ synclient TouchpadOff=1}} <br />
<br />
After you have successfully tried and tested your options through synclient, you can make these changes permanent by adding them to {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}.<br />
<br />
=== evtest ===<br />
<br />
The tool {{Pkg|evtest}} can display pressure and placement on the touchpad in real-time, allowing further refinement of the default Synaptics settings. The evtest monitoring can be started with:<br />
<br />
$ evtest /dev/input/event''X''<br />
<br />
''X'' denotes the touchpad's ID. It can be found by looking at the output of {{ic|cat /proc/bus/input/devices}}.<br />
<br />
evtest needs exclusive access to the device which means it cannot be run together with an X server instance. You can either kill the X server or run evtest from a different virtual terminal (e.g., by pressing {{ic|Ctrl+Alt+2}}).<br />
<br />
=== xev ===<br />
<br />
The tool {{Pkg|xorg-xev}} can display taps, clicks, pressure, placement and other measured parameters in real-time, allowing still further refinement of the default Synaptics settings. xev can be run in X and needs no specifics. using the "-event" parameter, it is possible to restrict the types of events that are reported.<br />
<br />
=== Circular Scrolling ===<br />
<br />
Circular scrolling is a feature that Synaptics offers which closely resembles the behaviour of iPods. Instead of (or additional to) scrolling horizontally or vertically, you can scroll circularly. Some users find this faster and more precise.<br />
To enable circular scrolling, add the following options to the touchpad device section of {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}:<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
...<br />
Option "CircularScrolling" "on"<br />
Option "CircScrollTrigger" "0"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
The option '''CircScrollTrigger''' may be one of the following values, determining which edge circular scrolling should start:<br />
<br />
0 All Edges<br />
1 Top Edge<br />
2 Top Right Corner<br />
3 Right Edge<br />
4 Bottom Right Corner<br />
5 Bottom Edge<br />
6 Bottom Left Corner<br />
7 Left Edge<br />
8 Top Left Corner<br />
<br />
Specifying something different from zero may be useful if you want to use circular scrolling in conjunction with horizontal and/or vertical scrolling. If you do so, the type of scrolling is determined by the edge you start from.<br />
<br />
To scroll fast, draw small circles in the center of your touchpad. To scroll slowly and more precise, draw large circles.<br />
<br />
=== Natural scrolling ===<br />
<br />
It is possible to enable natural scrolling through synaptics. Simply use negative values for {{ic|VertScrollDelta}} and {{ic|HorizScrollDelta}} like so:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
...<br />
Option "VertScrollDelta" "-111"<br />
Option "HorizScrollDelta" "-111"<br />
...<br />
EndSection<br />
</nowiki>}}<br />
<br />
=== Software toggle ===<br />
<br />
You might want to turn the touchpad on and off with a simple button click or shortcut. This can be done by binding the following ''xinput''-based script to a keyboard event as explained in [[Extra keyboard keys in Xorg]]:<br />
<br />
{{hc|/usr/local/bin/touchpad_toggle.sh|2=<nowiki><br />
#!/bin/bash<br />
<br />
declare -i ID<br />
ID=`xinput list | grep -Eio '(touchpad|glidepoint)\s*id\=[0-9]{1,2}' | grep -Eo '[0-9]{1,2}'`<br />
declare -i STATE<br />
STATE=`xinput list-props $ID|grep 'Device Enabled'|awk '{print $4}'`<br />
if [ $STATE -eq 1 ]<br />
then<br />
xinput disable $ID<br />
# echo "Touchpad disabled."<br />
# notify-send -a 'Touchpad' 'Disabled' -i /usr/share/icons/Adwaita/48x48/devices/input-touchpad.png<br />
else<br />
xinput enable $ID<br />
# echo "Touchpad enabled."<br />
# notify-send -a 'Touchpad' 'Enabled' -i /usr/share/icons/Adwaita/48x48/devices/input-touchpad.png<br />
fi<br />
</nowiki>}}<br />
<br />
{{Tip|When using external monitors with [[bumblebee]], the touchpad can be configured on the second X server by prepending {{ic|1=DISPLAY=:8}} to the command.}} <br />
<br />
Alternatively, {{ic|synclient}} can be used to toggle the touchpad. However, it can only turn off touch events but not physical clickpad button usage:<br />
<br />
{{hc|/usr/local/bin/touchpad.sh|<nowiki><br />
#!/bin/bash<br />
<br />
synclient TouchpadOff=$(synclient -l | grep -c 'TouchpadOff.*=.*0')<br />
</nowiki>}}<br />
<br />
=== Disable touchpad while typing ===<br />
<br />
==== Using the driver's automatic palm detection ====<br />
<br />
First of all you should test if it works properly for your touchpad and if the settings are accurate. Enable palm detection with<br />
<br />
$ synclient PalmDetect=1<br />
<br />
Then test the typing. You can tweak the detection by setting the minimum width for the touch to be considered a palm, for example<br />
<br />
$ synclient PalmMinWidth=8<br />
<br />
And you can tweak the minimum pressure required for the touch to be considered a palm, for example<br />
<br />
$ synclient PalmMinZ=100<br />
<br />
{{Tip|To help find the best values for palm detection, you can use {{pkg|evtest}} to see the width and Z values reported during touchpad use.}}<br />
<br />
Once you have found the correct settings, you can add them to your [[#Configuration|config file]]:<br />
<br />
{{bc|<nowiki><br />
Option "PalmDetect" "1"<br />
Option "PalmMinWidth" "8"<br />
Option "PalmMinZ" "100"<br />
</nowiki>}}<br />
<br />
{{Warning|1=For some touchpads, an [https://bugzilla.kernel.org/show_bug.cgi?id=77161 issue] with the kernel can cause the palm width to always be reported as 0. This breaks palm detection in a majority of cases. Pending an actual fix, you can [https://gist.github.com/silverhammermba/a231c8156ecaa63c86f1 patch] the synaptics package to use only Z for palm detection.}}<br />
<br />
{{Tip|If you experience problems with consistent palm detection for your hardware, an alternative to try is [[libinput]].}}<br />
<br />
==== Using syndaemon ====<br />
<br />
{{ic|syndaemon}} monitors keyboard activity and disables the touchpad while typing. It has several options to control when the disabling occurs. View them with<br />
<br />
$ syndaemon -h<br />
<br />
For example, to disable tapping and scrolling for 0.5 seconds after each keypress (ignoring modifier keys like Ctrl), use<br />
<br />
$ syndaemon -i 0.5 -t -K -R<br />
<br />
Once you have determined the options you like, you should use your login manager or [[xinitrc]] to have it run automatically when X starts. The {{ic|-d}} option will make it start in the background as a daemon.<br />
<br />
=== Disable touchpad on mouse detection ===<br />
<br />
With the assistance of [[udev]], it is possible to automatically disable the touchpad if an external mouse has been plugged in. To achieve this, use one of the following rules.<br />
<br />
==== Basic desktop ====<br />
<br />
This is a basic rule generally for non-"desktop environment" sessions:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="add", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/synclient TouchpadOff=1"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="remove", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="/home/''username''/.Xauthority", RUN+="/usr/bin/synclient TouchpadOff=0"<br />
}}<br />
<br />
If the touchpad is always deactivated at startup, even when no mouse is plugged in, try adding the following criteria between the KERNEL and ACTION parameters above:<br />
<br />
ATTRS{name}!="*TouchPad", ATTRS{name}!="*Stick",<br />
<br />
==== GDM ====<br />
<br />
{{Accuracy|saying that GDM ''usually'' does something does not make sense}}<br />
<br />
GDM usually stores the Xauthority files in {{ic|/var/run/gdm}} in a randomly-named directory. You should find your actual path to the Xauthority file which can be done using {{ic|ps ax}}. For some reason multiple authority files may appear for a user, so a rule like will be necessary:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="add", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print0 -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/usr/bin/synclient TouchpadOff=1"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="remove", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print0 -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/usr/bin/synclient TouchpadOff=0"<br />
}}<br />
<br />
Furthermore, you should validate that your udev script is running properly! You can check for the conditions using {{ic| udevadm monitor -p}} which must be run as root.<br />
<br />
===== With syndaemon running =====<br />
<br />
{{ic|syndaemon}} whether started by the [[#Using syndaemon|user]] or the desktop environment can conflict with synclient and will need to be disabled. A rule like this will be needed:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]", ACTION=="add", PROGRAM="/usr/bin/find /var/run/gdm -name ''username'' -print -quit", ENV{DISPLAY}=":0", ENV{XAUTHORITY}="$result/database", RUN+="/bin/sh -c '/usr/bin/synclient TouchpadOff=1 ; sleep 1; /bin/killall syndaemon; '"<br />
}}<br />
<br />
===== touchpad-state =====<br />
<br />
An AUR package {{aur|touchpad-state-git}} has been created around the udev rules above. It includes a udev rule and script:<br />
<br />
touchpad-state [--off] [--on]<br />
<br />
==== GNOME ====<br />
<br />
GNOME users can install GNOME shell extension [https://extensions.gnome.org/extension/131/touchpad-indicator/ Touchpad Indicator], change "Switch Method" to "Synclient" and enable "Automatically switch Touchpad On/Off" in its preferences.<br />
<br />
==== KDE ====<br />
<br />
If using Plasma, the package {{Pkg|plasma-desktop}} can be used to manage the touchpad.<br />
<br />
==== System with multiple X sessions ====<br />
<br />
{{Accuracy|Hard-coded {{ic|DISPLAY}} variable does not work with multiple X sessions.}} <br />
<br />
For an environment where multiple users are present, a slightly different approach is needed to detect the current users X environment. This script will help achieving this:<br />
<br />
{{hc|/usr/bin/mouse-pnp-event-handler.sh|<nowiki><br />
#!/bin/sh<br />
## $1 = "add" / "remove"<br />
## $2 = %k from udev <br />
<br />
## Set TRACKPAD_NAME according to your configuration. <br />
## Check your trackpad name with: <br />
## find /sys/class/input/ -name mouse* -exec udevadm info -a {} \; | grep 'ATTRS{name}'<br />
TRACKPAD_NAME="SynPS/2 Synaptics TouchPad"<br />
<br />
USERLIST=$(w -h | cut -d' ' -f1 | sort | uniq)<br />
MOUSELIST=$(find /sys/class/input/ -name mouse*)<br />
<br />
for CUR_USER in ${USERLIST}; do<br />
CUR_USER_XAUTH="$(sudo -Hiu ${CUR_USER} env | grep -e "^HOME=" | cut -d'=' -f2)/.Xauthority"<br />
<br />
<br />
## Can't find a way to get another users DISPLAY variable from an isolated root environment. Have to set it manually.<br />
#CUR_USER_DISPL="$(sudo -Hiu ${CUR_USER} env | grep -e "^DISPLAY=" | cut -d'=' -f2)"<br />
CUR_USER_DISPL=":0"<br />
<br />
export XAUTHORITY="${CUR_USER_XAUTH}"<br />
export DISPLAY="${CUR_USER_DISPL}"<br />
<br />
if [ -f "${CUR_USER_XAUTH}" ]; then<br />
case "$1" in<br />
"add")<br />
/usr/bin/synclient TouchpadOff=1<br />
/usr/bin/logger "USB mouse plugged. Disabling touchpad for $CUR_USER. ($XAUTHORITY - $DISPLAY)"<br />
;;<br />
"remove")<br />
## Only execute synclient if there are no external USB mice connected to the system.<br />
EXT_MOUSE_FOUND="0"<br />
for CUR_MOUSE in ${MOUSELIST}; do<br />
if [ "$(cat ${CUR_MOUSE}/device/name)" != "${TRACKPAD_NAME}" ]; then<br />
EXT_MOUSE_FOUND="1"<br />
fi<br />
done<br />
if [ "${EXT_MOUSE_FOUND}" == "0" ]; then<br />
/usr/bin/synclient TouchpadOff=0<br />
/usr/bin/logger "No additional external mice found. Enabling touchpad for $CUR_USER."<br />
else<br />
logger "Additional external mice found. Won't enable touchpad yet for $CUR_USER."<br />
fi<br />
;;<br />
esac<br />
fi<br />
done<br />
</nowiki>}}<br />
<br />
Update the {{ic|TRACKPAD_NAME}} variable for your system configuration.<br />
Run {{ic|<nowiki>find /sys/class/input/ -name mouse* -exec udevadm info -a {} \; | grep 'ATTRS{name}'</nowiki>}} to get a list of useful mice-names. Choose the one for your trackpad.<br />
<br />
Then have udev run this script when USB mices are plugged in or out, with these udev rules:<br />
<br />
{{hc|/etc/udev/rules.d/01-touchpad.rules|2=<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="add", RUN+="/usr/bin/mouse-pnp-event-handler.sh add %k"<br />
SUBSYSTEM=="input", KERNEL=="mouse[0-9]*", ACTION=="remove", RUN+="/usr/bin/mouse-pnp-event-handler.sh remove %k"<br />
}}<br />
<br />
=== Buttonless touchpads (aka ClickPads) ===<br />
<br />
Ever more laptops have a special kind of touchpad which has a single mouse button as part of the tracking plate, instead of external buttons. For example, the 2015 Dell XPS 13, HP series 4500 ProBooks, ThinkPad X220 and X1 ThinkPad series have this kind of a touchpad. By default, the whole button area is detected as a left button, so right and middle-click functions and click + drag will not work. It is possible to define two and three finger clicks as right and middle button clicks, and/or to define parts of the click pad surface as right and middle buttons. Note that although the driver registers multiple touches, it does not track individual fingers (as of version 1.7.1) which results in confusing behavior when using physical buttons of a clickpad for drag-and-drop and other gestures: you have to click with two or three fingers but then only move one of them while holding the button down with another. You can look into the {{AUR|xf86-input-mtrack}} driver for better multitouch support.<br />
<br />
Some desktop environments (KDE and GNOME at least) define sane and useful default configurations for clickpads, providing a right button at the bottom right of the pad, recognising two and three-finger clicks anywhere on the pad as right and middle clicks, and providing configuration options to define two and three-finger taps as right and middle clicks. If your desktop does not do this, or if you want more control, you can modify the touchpad section in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} (or better, of your custom synaptics configuration file prefixed with a higher number). For example:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
# Enable clickpad/multitouch support<br />
Option "ClickPad" "true"<br />
# Middle-button emulation is not supported<br />
Option "EmulateMidButtonTime" "0"<br />
# Define right soft button at the bottom<br />
Option "SoftButtonAreas" "50% 0 82% 0 0 0 0 0"<br />
EndSection<br />
</nowiki>}}<br />
<br />
The format for the SoftButtonAreas option is (from {{man|4|synaptics}}):<br />
{{bc|RightButtonAreaLeft RightButtonAreaRight RightButtonAreaTop RightButtonAreaBottom MiddleButtonAreaLeft MiddleButtonAreaRight MiddleButtonAreaTop MiddleButtonAreaBottom}}<br />
<br />
The above "SoftButtonAreas" option is commonly found in documentation or synaptics packages, and it defines the right half of the bottom 18% of the touchpad as a right button. There is '''no middle button''' defined. If you want to define a middle button remember one key piece of information from the manual; '''edge set to 0 extends to infinity in that direction.'''<br />
<br />
In the following example the right button will occupy the rightmost 40% of the button area and the middle button 20% of it in the center. The leftmost 40% remains as a left button (as does the rest of the clickpad):<br />
<br />
...<br />
Option "SoftButtonAreas" "60% 0 82% 0 40% 59% 82% 0"<br />
...<br />
<br />
You can use {{ic|<nowiki>synclient</nowiki>}} to check the soft button areas: <br />
<br />
{{hc|<nowiki>$ synclient -l | grep -i ButtonArea</nowiki>|<nowiki><br />
RightButtonAreaLeft = 3914<br />
RightButtonAreaRight = 0<br />
RightButtonAreaTop = 3918<br />
RightButtonAreaBottom = 0<br />
MiddleButtonAreaLeft = 3100<br />
MiddleButtonAreaRight = 3873<br />
MiddleButtonAreaTop = 3918<br />
MiddleButtonAreaBottom = 0<br />
</nowiki>}}<br />
<br />
If your buttons are not working, soft button areas are not changing, ensure you do not have a synaptics configuration file distributed by a package which is overriding your custom settings (ie. some AUR packages distribute configurations prefixed with very high numbers).<br />
<br />
These settings cannot be modified on the fly with {{ic|<nowiki>synclient</nowiki>}}, however, {{ic|<nowiki>xinput</nowiki>}} works:<br />
<br />
xinput set-prop "SynPS/2 Synaptics TouchPad" "Synaptics Soft Button Areas" 4000 0 4063 0 3000 4000 4063 0<br />
<br />
You cannot use percentages with this command, so look at {{ic|/var/log/Xorg.0.log}} to figure out the touchpad x and y-axis ranges.<br />
<br />
==== Bottom edge correction ====<br />
<br />
In some cases, for example Toshiba Satellite P50, everything work out of the box except often your click are seen as mouse movement and the cursor will jump away just before registering the click.<br />
This can be easily solved running<br />
<br />
$ synclient -l | grep BottomEdge<br />
<br />
take the BottomEdge value and subtract a the wanted height of your button, then temporary apply with<br />
<br />
$ synclient AreaBottomEdge=4000<br />
<br />
when a good value has been found make it a fixed correction with<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
...<br />
Option "AreaBottomEdge" "4000"<br />
...<br />
</nowiki>}}<br />
<br />
{{Note|The area will not act as touchpad if the touch '''begins''' in that area, but it can still be used if the touch has originated outside.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad does not work after resuming from hibernate/suspend ===<br />
<br />
Occasionally touchpads will fail to work when the computer resumes from sleep or hibernation. This can often be corrected without rebooting by<br />
<br />
* Switching to a console and back again,<br />
* entering sleep mode again, and resuming again, or<br />
* locating the correct kernel module, then removing it and inserting it again. <br />
* blacklisting kernel module psmouse may be a permanent option (when the touchpad is handled by another module, eg i2c_designware_platform)<br />
<br />
{{Note|You can use Ctrl-Alt-F1 through F8 to switch to a console without using the mouse.}}<br />
<br />
modprobe -r psmouse #psmouse happens to be the kernel module for my touchpad (Alps DualPoint)<br />
modprobe psmouse<br />
<br />
Now switch back to the tty that X is running on. If you chose the right module, your touchpad should be working again.<br />
<br />
=== xorg.conf.d/70-synaptics.conf does not seem to apply in MATE ===<br />
<br />
[[MATE]] will by default overwrite various options for your touchpad. This includes configurable features for which there is no graphical configuration within MATE's system control panel. This may cause it to appear that {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} is not applied. Follow [[#MATE]] to prevent this behavior.<br />
<br />
=== The touchpad is not working, Xorg.0.log shows "Query no Synaptics: 6003C8" ===<br />
<br />
Due to the way synaptics is currently set-up, 2 instances of the synaptics module are loaded. We can recognize this situation by opening the xorg log file ({{ic|/var/log/Xorg.0.log}}) and noticing this:<br />
<br />
{{hc|/var/log/Xorg.0.log|<nowiki><br />
[ 9304.803] (**) SynPS/2 Synaptics TouchPad: Applying InputClass "evdev touchpad catchall"<br />
[ 9304.803] (**) SynPS/2 Synaptics TouchPad: Applying InputClass "touchpad catchall"<br />
</nowiki>}}<br />
<br />
Notice how 2 differently named instances of the module are being loaded. In some cases, this causes the touchpad to become nonfunctional.<br />
<br />
We can prevent this double loading by adding {{ic|MatchDevicePath "/dev/input/event*"}} to our {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}} file:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|<nowiki><br />
Section "InputClass"<br />
Identifier "touchpad catchall"<br />
Driver "synaptics"<br />
MatchIsTouchpad "on"<br />
MatchDevicePath "/dev/input/event*"<br />
Option "TapButton1" "1"<br />
Option "TapButton2" "2"<br />
Option "TapButton3" "3"<br />
EndSection <br />
</nowiki>}}<br />
<br />
Restart X and check xorg logs again, the error should be gone and the touchpad should be functional.<br />
<br />
related bugreport: {{Bug|20830}}<br />
<br />
related forum topics:<br />
<br />
* https://bbs.archlinux.org/viewtopic.php?id=104769<br />
* https://bbs.archlinux.org/viewtopic.php?pid=825690<br />
<br />
=== Touchpad detected as "PS/2 Generic Mouse" or "Logitech PS/2 mouse" ===<br />
<br />
This can be caused by a number of issues;<br />
<br />
==== Elantech touchpads ====<br />
<br />
This can happen with some laptops with an Elantech touchpad, for example the ASUS x53s. In this situation you need {{AUR|psmouse-alps-driver}}{{Broken package link|{{aur-mirror|psmouse-alps-driver}}}} package from [[AUR]].<br />
<br />
==== Laptops with touchscreen & touchpad ====<br />
<br />
There also seems to be a problem with laptops which have both a touchscreen & a touchpad, such as the Dell XPS 12 or Dell XPS 13. To fix this, you can [[blacklisting|blacklist]] the {{ic|i2c_hid}} driver, this does have the side-effect of disabling the touchscreen though.<br />
<br />
This [http://www.spinics.net/lists/linux-input/msg27768.html seems to be a known problem]. Also see [https://bbs.archlinux.org/viewtopic.php?pid=1419078 this thread].<br />
<br />
Post kernel 3.15, having the module blacklisted may cause touchpad to stop working completely. Removing the blacklist should allow this to start working with limited functionality, see {{Bug|40921}}.<br />
<br />
=== Non-functional Synaptics special abilities (multi-tap, scrolling, etc.) ===<br />
<br />
In some cases Synaptics touchpads only work partially. Features like two-finger scrolling or two-finger middle-click do not work even if properly enabled. This is probably related to the [[#The touchpad is not working, Xorg.0.log shows "Query no Synaptics: 6003C8"|The touchpad is not working]] problem mentioned above. Fix is the same, prevent double module loading.<br />
<br />
If preventing the module from loading twice does not solve your issue, try commenting out the toggle {{ic|MatchIsTouchpad}} (which is now included by default in the synaptics config).<br />
<br />
If clicking with either 2 or 3 fingers is interpreted as a right-click, so you cannot get a middle click either way regardless of configuration, this bug is probably the culprit: https://bugs.freedesktop.org/show_bug.cgi?id=55365<br />
<br />
====No Multi-touch in some Elantech touchpads====<br />
<br />
See [http://unix.stackexchange.com/questions/28736/what-does-the-i8042-nomux-1-kernel-option-do-during-booting-of-ubuntu].<br />
<br />
=== Cursor jump ===<br />
<br />
Some users have their cursor inexplicably ''jump'' around the screen. There currently no patch for this, but the developers are aware of the problem and are working on it.<br />
<br />
Another posibility is that you are experiencing ''IRQ losses'' related to the i8042 controller (this device handles the keyboard and the touchpad of many laptops), so you have two possibilities here:<br />
<br />
1. rmmod && insmod the psmouse module.<br />
<br />
2. append {{ic|1=i8042.nomux=1}} to your [[kernel parameters]] and reboot your machine.<br />
<br />
=== Touchpad device is not located at {{ic|/dev/input/*}} ===<br />
<br />
If that is the case, you can use this command to display information about your input devices:<br />
<br />
$ cat /proc/bus/input/devices<br />
<br />
Search for an input device which has the name "SynPS/2 Synaptics TouchPad". The "Handlers" section of the output specifies what device you need to specify.<br />
<br />
'''Example output:'''<br />
<br />
{{hc|$ cat /proc/bus/input/devices|<nowiki><br />
I: Bus=0011 Vendor=0002 Product=0007 Version=0000<br />
N: Name="SynPS/2 Synaptics TouchPad"<br />
P: Phys=isa0060/serio4/input0<br />
S: Sysfs=/class/input/input1<br />
H: Handlers=mouse0 event1<br />
B: EV=b<br />
B: KEY=6420 0 7000f 0<br />
</nowiki>}}<br />
<br />
In this case, the {{ic|Handlers}} are {{ic|mouse0}} and {{ic|event1}}, so {{ic|/dev/input/mouse0}} would be used.<br />
<br />
{{Expansion|TODO: explain how to apply this in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}}}<br />
<br />
=== Firefox and special touchpad events ===<br />
<br />
You can enable/disable some special events that Firefox handles upon tapping or scrolling certain parts of your touchpad by editing the settings of those actions.<br />
Type {{ic|about:config}} in your Firefox address bar.<br />
To alter options, double-click on the line in question.<br />
<br />
==== Firefox 17.0 and later ====<br />
<br />
Horizontal scrolling will now by default scroll through pages and not through your history. To reenable Mac-style forward/backward with two-finger swiping, edit:<br />
<br />
mousewheel.default.action.override_x = 2<br />
<br />
You may encounter accidental forwards/backwards while scrolling vertically. To change Firefox's sensitivity to horizontal swipes, edit:<br />
<br />
mousewheel.default.delta_multiplier_x<br />
<br />
The optimum value will depend on your touchpad and how you use it, try starting with {{ic|10}}. A negative value will reverse the swipe directions.<br />
<br />
=== Opera: horizontal scrolling issues ===<br />
<br />
Same as above.<br />
To fix it, go to ''Tools > Preferences > Advanced > Shortcuts''. Select "Opera Standard" mouse setup and click "Edit". In "Application" section:<br />
<br />
{{Accuracy|Description here is not so clear and i don't use Opera,Please make it clear :)}}<br />
<br />
* assign key "Button 6" to command "Scroll left"<br />
* assign key "Button 7" to command "Scroll right"<br />
<br />
=== Scrolling and multiple actions with Synaptics on LG laptops ===<br />
<br />
These problems seem to be occurring on several models of LG laptops.<br />
Symptoms include: when pressing Mouse Button 1, Synaptics interprets it as ScrollUP and a regular button 1 click; same goes for button 2.<br />
<br />
The scrolling issue can be resolved by entering in {{ic|xorg.conf}}:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "UpDownScrolling" "0"<br />
}}<br />
<br />
{{Note|This will make Synaptics interpret one button push as three. There is a patch written by Oskar Sandberg [http://www.math.chalmers.se/~ossa/linux/lg_tx_express.html] that removes these clicks.}}<br />
<br />
Apparently, when trying to compile this against the latest version of Synaptics it fails. The solution to this is using the GIT repository for Synaptics [http://web.telia.com/~u89404340/touchpad/synaptics/.git].<br />
<br />
To build the package after downloading the tarball and unpacking it, execute:<br />
<br />
$ cd synaptics-git<br />
$ makepkg<br />
<br />
=== Other external mouse issues ===<br />
<br />
First, make sure your section describing the external mouse contains this line (or that the line looks like this):<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "Device" "/dev/input/mice"<br />
}}<br />
<br />
If the "Device" line is different, change it to the above and try to restart X. If this does not solve your problem, make your '''touchpad''' is the CorePointer in the "Server Layout" section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
InputDevice "Touchpad" "CorePointer"<br />
}}<br />
<br />
and make your external device "SendCoreEvents":<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
InputDevice "USB Mouse" "SendCoreEvents"<br />
}}<br />
<br />
finally add this to your external device's section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/xorg.conf|<br />
Option "SendCoreEvents" "true"<br />
}}<br />
<br />
If all of the above does not work for you, please check relevant bug trackers for possible bugs, or go through the forums to see if anyone has found a better solution.<br />
<br />
=== Touchpad synchronization issues ===<br />
<br />
{{Out of date|section=Outdated "Touchpad synchronization issues" section}}<br />
<br />
Sometimes the cursor may freeze for several seconds or start acting on its own for no apparent reason. This behavior is accompanied by records in {{ic|/var/log/messages.log}}<br />
<br />
{{hc|/var/log/messages.log|<br />
psmouse.c: TouchPad at isa0060/serio1/input0 lost synchronization, throwing 3 bytes away<br />
}}<br />
<br />
This problem has no general solution, but there are several possible workarounds.<br />
* If you use CPU frequency scaling, avoid using the "ondemand" governor and use the "performance" governor when possible, as the touchpad may lose sync when the CPU frequency changes.<br />
* Avoid using an ACPI battery monitor.<br />
* Attempt to load psmouse with "proto=imps" option. To do that, add this line to your {{ic|/etc/modprobe.d/modprobe.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/modprobe.conf|2=<br />
options psmouse proto=imps<br />
}}<br />
<br />
* Try another desktop environment. Some users report that this problem only occurs when using XFCE or GNOME, for whatever reason<br />
<br />
=== Xorg.log.0 shows SynPS/2 Synaptics touchpad can not grab event device, errno=16 ===<br />
<br />
If you are using Xorg 7.4, you may get a warning like this from {{ic|/var/log/Xorg.0.log}}, thais is because the driver will grab the event device for exclusive use when using the Linux 2.6 event protocol. When it fails, X will return this error message.<br />
<br />
Grabbing the event device means that no other user space or kernel space program sees the touchpad events. This is desirable if the X config file includes {{ic|/dev/input/mice}} as an input device, but is undesirable if you want to monitor the device from user space.<br />
<br />
If you want to control it, add or modify the "GrabEventDevice" option in you touchpad section in {{ic|/etc/X11/xorg.conf.d/70-synaptics.conf}}:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/70-synaptics.conf|2=<br />
...<br />
Option "GrabEventDevice" "''boolean''"<br />
...<br />
}}<br />
<br />
This will come into effect when X is restarted, though you can also change it by using synclient. When changing this parameter with the synclient program, the change will not take effect until the Synaptics driver is disabled and re-enabled. This can be achieved by switching to a text console and then switching back to X.<br />
<br />
=== Synaptics loses multitouch detection after rebooting from Windows ===<br />
<br />
Many drivers include a firmware that is loaded into flash memory when the computer boots. This firmware is not necessarily cleared upon shutdown, and is not always compatible with Linux drivers. The only way to clear the flash memory is to shutdown completely rather than using reboot. It is generally considered best practice to never use reboot when switching between operating systems.<br />
<br />
=== Touchpad not recognized after shutdown from Arch ===<br />
<br />
Certain touchpads (elantech in particular) will fail to be recognized as a device of any sort after a standard shutdown from Arch linux. There are multiple possible solutions to this problem:<br />
<br />
* Boot into a Windows partition/install disk and shutdown from there.<br />
* Wait approximately 1 minute before turning on the computer after shutdown.<br />
* As discussed in https://bugzilla.kernel.org/show_bug.cgi?id=81331#c186 a patch has been merged into the stable kernel that provides a fix for Elantech touchpads. Gigabyte P34, P35v2 and X3 models are supported by default, for others (especially rebranded Gigabyte laptops, like XMG's) {{ic|1=i8042.kbdreset=1}} can be set as kernel parameter.<br />
<br />
=== Trackpoint and Clickpad ===<br />
<br />
Newer Thinkpads do not have physical buttons for their Trackpoint anymore and instead use the upper area of the Clickpad for buttons (Left, Middle, Right). <br />
Apart from the ergonomic viewpoint this works quite well with current Xorg. Unfortunately mouse wheel emulation using the middle button is not supported yet. Install {{AUR|xf86-input-evdev-trackpoint}} from the AUR for a patched and properly configured version if you intend to use the Trackpoint.<br />
<br />
== See also ==<br />
<br />
* [http://cgit.freedesktop.org/xorg/driver/xf86-input-synaptics/ Synaptics touchpad driver]<br />
* [http://www.x.org/archive/X11R7.5/doc/man/man4/synaptics.4.html Synaptics manual on x.org ]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509372RetroArch2018-02-02T17:24:59Z<p>Ketsui: Linkify FFmpeg.</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding and video recording (using [[FFmpeg]]), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an upstream change.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509369RetroArch2018-02-02T17:19:07Z<p>Ketsui: Update the description, courtesy of Wikipedia and upstream description. https://github.com/libretro/RetroArch/blob/master/README.md</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is the reference implementation of the libretro API. It is a modular front-end for video game system emulators, game engines, video games, media players and other applications that offers several uncommon technical features such as multi-pass shader support, real-time rewinding (Braid-style) and video recording (using FFmpeg), it also features a gamepad-driven UI on top of a full-featured command-line interface.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an upstream change.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509368RetroArch2018-02-02T16:53:18Z<p>Ketsui: /* Troubleshooting *//* No option to update or download cores in the menu */ Moved to the Online Updater section because it's not a 'trouble' per se, just a matter of enabling what's disabled by default. Also a small update.</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is a modular, command-line driven, multi-system emulator that is designed to be fast, lightweight, and portable. Some of its features can be found on few other emulators, such as real-time rewinding and game-aware shading based on the libretro API.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating and downloading core files and various assets from the [https://buildbot.libretro.com/ libretro Buildbot]. To enable it, open {{ic|~/.config/retroarch/retroarch.cfg}} and set {{ic|menu_show_core_updater}} to {{ic|"true"}}.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
menu_show_core_updater = "true"<br />
}}<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Thumbnails Updater<br />
Content Downloader<br />
Update Core Info Files<br />
Update Assets<br />
Update Joypad Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
Update Slang Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater any time there's an upstream change.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509363RetroArch2018-02-02T16:26:50Z<p>Ketsui: /* No cores found */ Italicize "Online Updater"</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is a modular, command-line driven, multi-system emulator that is designed to be fast, lightweight, and portable. Some of its features can be found on few other emulators, such as real-time rewinding and game-aware shading based on the libretro API.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating core files and various assets from the [https://buildbot.libretro.com/ RetroArch Buildbot]. It can be accessed from the main menu at ''Online Updater''.<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Update Core Info Files<br />
Update Assets<br />
Update Autoconfig Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater at any time.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in ''Online Updater'' will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== No option to update or download cores in the menu ===<br />
<br />
Open {{ic|~/.config/retroarch/retroarch.cfg}} or {{ic|/etc/retroarch.cfg}} and make sure that {{ic|menu_show_core_updater}} is set to {{ic|true}}. This should then allow you to update cores in the ''Online Updater'' menu and download cores in the ''Load Core'' menu.<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509361RetroArch2018-02-02T16:20:41Z<p>Ketsui: /* No cores found */ Reword sentences.</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is a modular, command-line driven, multi-system emulator that is designed to be fast, lightweight, and portable. Some of its features can be found on few other emulators, such as real-time rewinding and game-aware shading based on the libretro API.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating core files and various assets from the [https://buildbot.libretro.com/ RetroArch Buildbot]. It can be accessed from the main menu at ''Online Updater''.<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Update Core Info Files<br />
Update Assets<br />
Update Autoconfig Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater at any time.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in Online Updater will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use a user-owned directory instead, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory when obtaining cores from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) when using the ''Online Updater''.}}<br />
<br />
=== No option to update or download cores in the menu ===<br />
<br />
Open {{ic|~/.config/retroarch/retroarch.cfg}} or {{ic|/etc/retroarch.cfg}} and make sure that {{ic|menu_show_core_updater}} is set to {{ic|true}}. This should then allow you to update cores in the ''Online Updater'' menu and download cores in the ''Load Core'' menu.<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509359RetroArch2018-02-02T16:10:48Z<p>Ketsui: /* Usage */ buildbot > Buildbot</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is a modular, command-line driven, multi-system emulator that is designed to be fast, lightweight, and portable. Some of its features can be found on few other emulators, such as real-time rewinding and game-aware shading based on the libretro API.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro Buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating core files and various assets from the [https://buildbot.libretro.com/ RetroArch Buildbot]. It can be accessed from the main menu at ''Online Updater''.<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Update Core Info Files<br />
Update Assets<br />
Update Autoconfig Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater at any time.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in Online Updater will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use cores from the Online Updater, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory for cores obtained from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) for cores obtained from the Online Updater.}}<br />
<br />
=== No option to update or download cores in the menu ===<br />
<br />
Open {{ic|~/.config/retroarch/retroarch.cfg}} or {{ic|/etc/retroarch.cfg}} and make sure that {{ic|menu_show_core_updater}} is set to {{ic|true}}. This should then allow you to update cores in the ''Online Updater'' menu and download cores in the ''Load Core'' menu.<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsuihttps://wiki.archlinux.org/index.php?title=RetroArch&diff=509347RetroArch2018-02-02T14:28:18Z<p>Ketsui: /* Troubleshooting */ /* No cores found */ Added a note explaining the incompatibility of the various methods of obtaining cores.</p>
<hr />
<div>[[Category:Gaming]]<br />
[[Category:Emulation]]<br />
[[es:RetroArch]]<br />
[[ja:RetroArch]]<br />
{{Note|RetroArch is not affiliated with [[Arch Linux]].}}<br />
<br />
[http://www.retroarch.com/ RetroArch] is a modular, command-line driven, multi-system emulator that is designed to be fast, lightweight, and portable. Some of its features can be found on few other emulators, such as real-time rewinding and game-aware shading based on the libretro API.<br />
<br />
== Installation ==<br />
Install the {{Pkg|retroarch}} package or alternatively {{AUR|retroarch-git}} for the development version.<br />
{{Tip|Install {{Pkg|retroarch-assets-xmb}} to allow the default menu driver (XMB) to work properly. Additionally, install {{Pkg|retroarch-autoconfig-udev}} to enable RetroArch to automatically map buttons to joypads when they are plugged.}}<br />
<br />
== Usage ==<br />
<br />
RetroArch relies on separate libraries, called "cores", available from the [https://www.archlinux.org/packages/?q=libretro Community] repository, the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] and the [https://buildbot.libretro.com/ libretro buildbot], for most of its functionalities.<br />
<br />
Each libretro core package will install a library to {{ic|/usr/lib/libretro/}}. The syntax to choose one when executing ''retroarch'' is:<br />
<br />
$ retroarch --libretro /usr/lib/libretro/''core''-libretro.so ''/path/to/rom''<br />
<br />
A default core can be defined in the configuration, obviating the need to specify it on every run.<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_path = "/usr/lib/libretro/''core''-libretro.so"<br />
}}<br />
<br />
== Configuration ==<br />
<br />
RetroArch provides a very well commented skeleton configuration file located at {{ic|/etc/retroarch.cfg}}.<br />
<br />
Copy the skeleton configuration file to your home directory<br />
<br />
$ cp /etc/retroarch.cfg ~/.config/retroarch/retroarch.cfg<br />
<br />
It supports split configuration files using the {{ic|#include "foo.cfg"}} directive within the main configuration file, {{ic|retroarch.cfg}}. This can be overridden using the {{ic|--appendconfig ''/path/to/config''}} parameter and is beneficial if different keybinds, video configurations or audio settings are required for the various cores.<br />
<br />
{{Tip|RetroArch is capable of loading [https://gitorious.org/bsnes/xml-shaders bsnes xml filters] and [https://github.com/libretro/common-shaders cg shaders] that can be defined in {{ic|retroarch.cfg}} as {{ic|video_bsnes_shader}} and {{ic|video_cg_shader}} respectively.}}<br />
{{Note|<br />
* {{AUR|retroarch-git}} requires {{pkg|nvidia-cg-toolkit}} in order to use the ''cg shaders''.<br />
* When using [[ALSA]] it is necessary for the {{ic|audio_out_rate}} to be equal to the system's default output rate, usually {{ic|48000}}.<br />
}}<br />
<br />
== Online updater ==<br />
<br />
Recent versions of RetroArch have introduced a built-in menu for updating core files and various assets from the [https://buildbot.libretro.com/ RetroArch Buildbot]. It can be accessed from the main menu at ''Online Updater''.<br />
<br />
{{hc|1=Online Updater|2=<br />
Core Updater<br />
Update Core Info Files<br />
Update Assets<br />
Update Autoconfig Profiles<br />
Update Cheats<br />
Update Databases<br />
Update Overlays<br />
Update GLSL Shaders<br />
}}<br />
<br />
These cores and assets are kept up to date and can be pulled from the updater at any time.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No cores found ===<br />
<br />
By default RetroArch will attempt to find cores in {{ic|/usr/lib/libretro/}}. Cores downloaded using the built-in Online Updater will fail to save unless RetroArch is run as root (not recommended, as it may overwrite cores installed by [[pacman]] and also because it poses a security risk.[https://bugzilla.gnome.org//show_bug.cgi?id=772875#c5]) because users do not normally have permission to modify this directory. To use cores from the Online Updater, edit these lines:<br />
<br />
{{hc|~/.config/retroarch/retroarch.cfg|2=<br />
libretro_directory = "~/.config/retroarch/cores"<br />
libretro_info_path = "~/.config/retroarch/cores/info"<br />
}}<br />
{{Note|1=Cores obtained from the [https://www.archlinux.org/packages/?q=libretro Community] repository or the [https://aur.archlinux.org/packages/?O=0&K=libretro AUR] will be installed to {{ic|/usr/lib/libretro/}} regardless of this setting, because of this, it's recommended to stick to one method of obtaining cores, use the default directory for cores obtained from the Community repository or the AUR or a user-owned directory (such as {{ic|~/.config/retroarch/cores}}) for cores obtained from the Online Updater.}}<br />
<br />
=== No option to update or download cores in the menu ===<br />
<br />
Open {{ic|~/.config/retroarch/retroarch.cfg}} or {{ic|/etc/retroarch.cfg}} and make sure that {{ic|menu_show_core_updater}} is set to {{ic|true}}. This should then allow you to update cores in the ''Online Updater'' menu and download cores in the ''Load Core'' menu.<br />
<br />
=== Input devices do not operate ===<br />
<br />
You may encounter problems if running on a CLI or a display server other than [[Xorg]] or if you use the [[udev]] input driver, because {{ic|/dev/input}} nodes are limited to root-only access. Try adding your user to the "input" [[group]] then logging in again.<br />
<br />
Alternatively, manually add a rule in {{ic|/etc/udev/rules.d/99-evdev.rules}}, with {{ic|1=KERNEL=="event*", NAME="input/%k", MODE="666"}} as its contents. Reload [[udev rules]] by running:<br />
<br />
# udevadm control --reload-rules<br />
<br />
If rebooting the system or replugging the devices are not options, permissions may be forced using:<br />
<br />
# chmod 666 /dev/input/event*<br />
<br />
=== Poor video performance ===<br />
<br />
If poor video performance is met, RetroArch may be run on a separate thread by setting {{ic|1=video_threaded = true}} in {{ic|~/.config/retroarch/retroarch.cfg}}.<br />
<br />
This is, however, a solution that should be not be used if tweaking RetroArch's video resolution/refresh rate fixes the problem, as it makes perfect V-Sync impossible, and slightly increases latency.<br />
<br />
== See also ==<br />
<br />
* [http://www.retroarch.com/ Official Website]<br />
* [https://github.com/libretro/RetroArch/wiki RetroArch wiki on GitHub]<br />
* [https://github.com/libretro/libretro.github.com/wiki/Documentation-devs Documentation for developers]</div>Ketsui