https://wiki.archlinux.org/api.php?action=feedcontributions&user=PXf&feedformat=atomArchWiki - User contributions [en]2024-03-29T10:33:48ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Session_lock&diff=775838Session lock2023-04-20T11:09:58Z<p>PXf: /* systemd events */ add "loginctl lock-sessions"</p>
<hr />
<div>[[Category:Security]]<br />
[[ja:セッションをロック]]<br />
[[ru:Session lock]]<br />
There are numerous utilities to lock the screen of a session. But it is important to note that the utility to use is highly dependent on the environment you are in, either the virtual console, or a specific display server (Xorg or Wayland).<br />
<br />
See [[List of applications#Screen lockers]].<br />
<br />
== By environment ==<br />
<br />
{{Merge|List of applications#Screen lockers|Same purpose, only split into categories.}}<br />
<br />
=== Virtual console ===<br />
<br />
You can use {{ic|vlock}} or {{Pkg|physlock}} to lock a virtual console.<br />
<br />
=== Xorg ===<br />
<br />
There are many ways to lock the session under Xorg, so this section is likely to be incomplete. Some methods however include:<br />
* {{ic|xlock}}, in the {{Pkg|xlockmore}} package - <br />
* {{ic|xsecurelock}}, in the {{Pkg|xsecurelock}} package<br />
* {{ic|xscreensaver-command -lock}} in the {{Pkg|xscreensaver}} package<br />
* {{Pkg|xss-lock}}<br />
* [[slock]] in the {{Pkg|slock}} package<br />
* {{Pkg|kscreenlocker}}<br />
* {{Pkg|i3lock}}<br />
* {{AUR|i3lock-color}}<br />
* {{AUR|alock}}<br />
<br />
Most desktop environments come with some way to lock the session.<br />
<br />
=== Wayland ===<br />
<br />
You can lock the session with {{Pkg|swaylock}} or {{Pkg|waylock}}.<br />
<br />
== Triggering the lock ==<br />
<br />
You can lock a session using different methods:<br />
* from a terminal<br />
* using a GUI:<br />
** from a desktop icon<br />
** using hot corners<br />
** from a menu (mouse or keyboard driven)<br />
* from a [[Keyboard shortcuts|shortcut]]<br />
* from an event:<br />
** inactivity (using [[#Inactivity|systemd]], [[#xss-lock|xss-lock]] or [[#xautolock|xautolock]])<br />
** [[#systemd events|systemd events]] (suspend, hibernate, etc.)<br />
<br />
The last point (triggering a lock from an event) is the trickiest, because you can do it in one of two ways:<br />
* get the action trigger to execute your lock, then to execute the initial action.<br />
* from the event trigger, add the lock to the event chain. So far this can only be done using systemd.<br />
<br />
=== Shell triggers ===<br />
<br />
==== Zsh ====<br />
<br />
To execute a command after terminal inactivity, you can use the TMOUT environment variable.<br />
<br />
You can combine it with a trap on the ALARM signal to execute the lock. Without a trap, it will just terminate the shell.<br />
<br />
You might want to detect if you are in a graphical environment, otherwise your GUI terminals might start disappearing without you understanding why.<br />
<br />
=== Xorg triggers ===<br />
<br />
==== xss-lock ====<br />
<br />
{{pkg|xss-lock}} is triggered by one of two things:<br />
* systemd events<br />
* [[DPMS]]<br />
<br />
The advantage of this is that you can control a lock issued manually, by inactivity, and by a suspend command at the same place.<br />
<br />
To execute an action on one of those events:<br />
$ xss-lock <locker-utility><br />
<br />
===== systemd events =====<br />
<br />
By default, xss-lock subscribes to {{ic|suspend}}, {{ic|hibernate}}, {{ic|lock-session}}, and {{ic|unlock-session}} with appropriate actions (run locker and wait for user to unlock or kill locker).<br />
<br />
You can prevent xss-lock from being triggered by {{ic|suspend}} and {{ic|hibernate}} using {{ic|--ignore-sleep}}.<br />
<br />
You can trigger a manual lock using {{ic|loginctl lock-session}}, or lock all current sessions with {{ic|loginctl lock-sessions}}.<br />
<br />
===== DPMS =====<br />
<br />
To configure DPMS signaling timeout:<br />
<br />
# Trigger screensaver after 10 minutes of inactivity<br />
xset s on<br />
xset s 600<br />
<br />
DPMS signaling can also be configured in {{ic|/etc/X11/xorg.conf.d/}} in the {{ic|Monitor}} section.<br />
<br />
Using DPMS signaling, you can set a second timer, for example to notify the user or to dim the screen. For example (from {{man|1|xss-lock}}):<br />
<br />
# Dim the screen after three minutes of inactivity, lock the screen two minutes later using i3lock:<br />
xset s 180 120<br />
xss-lock -n dim-screen.sh -- i3lock -n<br />
<br />
An example {{ic|dim-screen.sh}} script can be found in {{ic|/usr/share/doc/xss-lock}}.<br />
<br />
{{Note|When using xss-lock with [[DPMS]], you will have to blank the screen yourself. It will not be triggered when looking at videos.}}<br />
<br />
==== xautolock ====<br />
<br />
$ xautolock -time 12 -locker "systemctl suspend" -detectsleep<br />
<br />
{{Note|1=<br />
xautolock has restrictive timer limits:<br />
<br />
* 1 min to 1 hour for {{ic|time}}<br />
* 10 min to 2 hour for {{ic|killtime}}<br />
<br />
It might be necessary to add {{ic|-detectsleep}} to prevent xautolock from locking the session after resuming. One nice feature of xautolock is the {{ic|corners}}.<br />
}}<br />
<br />
=== Wayland triggers ===<br />
<br />
==== swayidle ====<br />
<br />
{{Pkg|swayidle}} listens for idle activity from the Wayland compositor, as well as systemd events, and executes commands accordingly. See [[Sway#Idle]].<br />
<br />
==== D-Bus notification ====<br />
<br />
Using {{ic|loginctl lock-session}}, or the {{ic|lock}} action in {{man|5|logind.conf}}, you can notify the system through DBUS that you want to lock. This notification can then be processed, for example by xss-lock.<br />
<br />
==== Inactivity ====<br />
<br />
In {{man|5|logind.conf}}, you can configure the {{ic|IdleAction}} to {{ic|lock}}. This will trigger a DBUS notification, that will have to be processed (for example by xsslock) to lock the session.<br />
<br />
Note that this is for a global system (so this is not ideal for a multi user environment).<br />
<br />
Note also that "this requires that user sessions correctly report the idle status to the system".<br />
<br />
==== Units ====<br />
<br />
===== Before suspend or hibernate =====<br />
<br />
You can use a [[Power management#Sleep hooks|Sleep hook]].<br />
<br />
{{bc|1=<br />
[Unit]<br />
Description=Lock the screen<br />
Before=sleep.target<br />
<br />
[Service]<br />
User=%I<br />
Type=forking<br />
Environment=DISPLAY=:0<br />
ExecStart=/usr/bin/i3lock -c 000000<br />
<br />
[Install]<br />
WantedBy=sleep.target<br />
}}<br />
<br />
To enable it for a certain user, [[enable]] {{ic|sleep@''Username''.service}}.<br />
<br />
===== Lid closing =====<br />
<br />
You can use the {{ic|lock}} action using the related [[Power management#ACPI events|ACPI event]].<br />
<br />
== See also ==<br />
<br />
* [https://geoff.greer.fm/2018/01/02/linux-laptop-locking/ Geoff Greer's site: Linux Laptop Locking]</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:Archiso&diff=771442Talk:Archiso2023-03-07T07:34:25Z<p>PXf: /* mention mkosi */ workaround caregory link</p>
<hr />
<div>==Archiso doesn't work on non stock kernel==<br />
<br />
I've been having on and off issues when building ISOs with archiso and the other day when I was working on one I did a pacman -Syu before working but didn't reboot. I was running on the stock kernel at that point because the linux-ck kernel had not updated yet. My ISO built fine. Later that day I rebooted and was now running on the updated linux-ck kernel and suddenly the build process would simply die without any errors, even with the -v option. Right after installing all the custom packages, a dd output appears and then a mkfs.vfat version message appears and that's where it dies. Rebooting back to the stock arch kernel fixed the issue. I'm guessing it has something to do with hardcoded names or something like that in the build scripts.<br />
<br />
Is this normal behaviour? I don't mind using the stock kernel on the ISOs I build but I figured I'd at least be able to build them on a different one.<br />
<br />
On that note, is it possible to use a kernel other than the stock one within the ISOs we build? <br />
[[User:Biltong|Biltong]] ([[User talk:Biltong|talk]]) Sun May 6 2012, 21:47 SAST<br />
<br />
== Estimating size? Starting over? ==<br />
<br />
How do you best estimate the size?<br />
<br />
How do you start over? Suppose just take `etc/`, delete the `releng/` directory recopy, put stuff back. [[User:Jasper1984|Jasper1984]] ([[User talk:Jasper1984|talk]]) 13:46, 1 July 2013 (UTC)<br />
<br />
:Best way to start over is delete releng/{work,out} it keeps cached packages, and there is no need to do every step from the beginning. {{Unsigned|14:08, 5 October 2013|Jqvillanova}}<br />
<br />
== Encryption ==<br />
<br />
<br />
* with «cryptsetup», encrypt the file «airootfs.sfs» built with «mkarchiso» :<br />
<br />
# cd /path/to/buildir/<br />
# cd ./work/iso/arch/x86_64/<br />
# cryptsetup --verify-passphrase plainOpen ./airootfs.sfs encrypt<br />
# dd < ./airootfs.sfs > /dev/mapper/encrypt<br />
# sync<br />
# cryptsetup plainClose encrypt<br />
# md5sum ./airootfs.sfs > ./airootfs.md5<br />
# cd -<br />
<br />
''(note that you can't decrypt the encrypted file «airootfs.sfs» in the same «dd» way, instead use {{ic|1=dd of=./airootfs.sfs conv=nocreat,notrunc < /dev/mapper/encrypt}})''<br />
<br />
* add the hook «encrypt» in «mkinitcpio.conf» :<br />
<br />
# grep HOOKS ./work/airootfs/etc/mkinitcpio.conf<br />
HOOKS="... encrypt"<br />
<br />
<br />
* insert these lines in «archiso» hook :<br />
<br />
--- a/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
+++ b/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
@@ -65,6 +65,10 @@<br />
fi<br />
sfs_dev=$(losetup --find --show --read-only "${img}")<br />
echo ${sfs_dev} >> /run/archiso/used_block_devices<br />
+ msg ":: Mapping encrypted squashfs..."<br />
+ local map="${sfs_dev##*/}.map"<br />
+ cryptsetup plainOpen "${sfs_dev}" "${map}"<br />
+ sfs_dev="/dev/mapper/${map}"<br />
_mnt_dev "${sfs_dev}" "${mnt}" "-r" "defaults"<br />
}<br />
<br />
<br />
* rebuild initramfs and iso with «mkarchiso» and test :<br />
<br />
# mkarchiso -r "mkinitcpio -p linux" run<br />
# mkarchiso iso encrypted.iso<br />
# qemu ... ./out/encrypted.iso<br />
<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 21:51, 20 Feb 2016 (UTC)<br />
<br />
: @Lacsap Can't manage to make it working. I managed to build the iso but it can't find <code>/run/iso_name/bootmnt</code>. I think I have missed the decryption part. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 11:43, 17 October 2021 (UTC)<br />
<br />
== Example configurations ==<br />
<br />
Where should sets of ArchISO customizations go? Should there be an "Examples" header added to the bottom? Like for how to enable remote {{ic|ssh}} login, boot with serial console support for headless systems, etc? Or a separate page? [Archiso offline] is a separate page, but it was marked for possible merging since it's an (out of date) clone of this page. [[User:Jamespharvey20|Jamespharvey20]] ([[User talk:Jamespharvey20|talk]]) 02:38, 25 April 2019 (UTC)<br />
:I guess your changes (adding ssh configs) should be done airootfs directory. But I did not yet explored how to add another systemd services to archiso. Adding info about how to enable ssh login to this page seems useful for me. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 17:42, 25 April 2019 (UTC)<br />
<br />
== ISO does not build with secure boot enabled ==<br />
<br />
It seems that if you have secure boot enabled and have signed the Linux kernel, the ISO will fail to build, saying that /boot/vmlinuz-linux does not exist. However, once you disable secure boot, the ISO starts getting built again. Just tried this, and it appears to go back at least to archiso version 36.<br />
<br />
[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 18:58, 26 May 2020 (UTC)<br />
<br />
:To clarify, I don't really know why it doesn't work. If possible, could someone else test this, to see if it's just a problem on my computer or more widespread. If so, then maybe we should add a warning to the wiki page.<br />
:[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 04:54, 27 May 2020 (UTC)<br />
<br />
::I don't use secure boot myself, so I don't know how it works. Since [https://github.com/archlinux/svntogit-packages/commit/43c5745a17e2ebe413a7140d4ef9326e26d6cb20 5.3.8.1] the {{pkg|linux}} package does not install the kernel to {{ic|/boot/vmlinuz-linux}}, but to {{ic|/usr/lib/modules/VERSION/vmlinuz}} and [https://github.com/archlinux/mkinitcpio/tree/master/libalpm/hooks mkinitcpio's pacman hooks] copy it to {{ic|/boot/}}. If the kernel image is not getting copied somewhere in the ISO's chroot, maybe there is something wrong with the hooks... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:39, 30 May 2020 (UTC)<br />
<br />
== Please add a warning with regards to syncthing interoperability ==<br />
<br />
When mkarchiso is executed to use a working directory (e.g. -w ./tmp) inside a folder that is observed by syncthing, there are 2 issues: mkarchiso will fail and a restart is required in order to be able to delete the working directory. As a simple workaround, the working directory can be added to the syncthing ignore patterns.<br />
<br />
I do not know what causes these errors - especially since mkarchiso does not throw any error message. Deleting the working directory fails due to missing rights although it is run as root. After a restart the working directory can be deleted. [[User:ente|ente]] ([[User talk:ente|talk]]) 11:09, 17 September 2020 (UTC)<br />
<br />
== Add a section to Tips and Tricks to build an ISO for installation entirely over a serial console ==<br />
<br />
I've been looking all over for a good way to do this. I think I have an approach that could work (although it's still to be tried). What do we think about adding this? Has anyone got a recipe? If not, I'm happy to give it a go.<br />
<br />
[[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 11:33, 14 November 2020 (UTC)<br />
<br />
:The solution is to simply add a [[Working with the serial console#Kernel|console=ttyS* kernel parameter]] to boot loader configuration. As for why it's not done by default in releng, see https://gitlab.archlinux.org/archlinux/archiso/-/issues/75. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:28, 14 November 2020 (UTC)<br />
<br />
::I get that, but you need to _get_ to the bootloader menu first, and that currently doesn't happen over the console to my knowledge... [[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 13:55, 14 November 2020 (UTC)<br />
<br />
:::I meant editing the boot loader configuration for the ISO and then building the ISO. As for seeing the boot loader over serial, it should work when booting in BIOS mode (this doesn't prevent installing the system for UEFI booting, you just need to install the boot loader to the default/fallback boot path). -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 05:23, 15 November 2020 (UTC)<br />
<br />
== <s>Permissions and File Additions</s> ==<br />
<br />
Would suggest we document the new changes to permissions requirements as implemented on 11/30/20 in Commit c10004df :<br />
<br />
profiledef.sh needs to have explicit permissions now which is quite different than before.<br />
<br />
file_permissions=(<br />
["/etc/shadow"]="0:0:400"<br />
["/root"]="0:0:750"<br />
["/root/.automated_script.sh"]="0:0:755"<br />
["/usr/local/bin/choose-mirror"]="0:0:755"<br />
["/usr/local/bin/Installation_guide"]="0:0:755"<br />
["/usr/local/bin/livecd-sound"]="0:0:755"<br />
<br />
<br />
Also, the fact that a /skel folder cannot be added to airootfs now is different and requires users to put everything in /etc/skel/<br />
<br />
Users can still add services, but I found the best way to add them was to put them in /usr/local/bin and then add a line to profiledef.sh to give them 755.<br />
<br />
[[User:Jdfthetech|Jdfthetech]] ([[User talk:Jdfthetech|talk]]) 05:34, 2 December 2020 (UTC)<br />
<br />
:Thanks for this update, I've just reached this pitfall attempting to create a non-root user with their own home directory, but failing with {{ic|[mkarchiso] ERROR: Failed to set permissions on 'work/x86_64/airootfs/home/myuser'. Outside of valid path.}} Any thoughts on how to get this working? [[User:Yuvadm|Yuvadm]] ([[User talk:Yuvadm|talk]]) 20:34, 14 December 2020 (UTC)<br />
<br />
::https://gitlab.archlinux.org/archlinux/archiso/-/issues/84. The workaround for now is to explicitly set the work dir with the {{ic|-w}} option. If all goes well, it should be fixed in the next archiso version. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:03, 15 December 2020 (UTC)<br />
<br />
:::[[Archiso#Adding files to image]] mentions permissions and links to the docs. Closing. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 08:22, 22 February 2023 (UTC)<br />
<br />
== mention mkosi ==<br />
<br />
It seems that [[mkosi]] offers similar functionalities.<br />
What about mentioning [[mkosi]] in [https://wiki.archlinux.org/title/Category:Live_Arch_systems Category:Live_Arch_systems] and under [[archiso#See_also]]?<br />
[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 07:33, 7 March 2023 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:Archiso&diff=771441Talk:Archiso2023-03-07T07:33:16Z<p>PXf: /* mention mkosi */ new section</p>
<hr />
<div>==Archiso doesn't work on non stock kernel==<br />
<br />
I've been having on and off issues when building ISOs with archiso and the other day when I was working on one I did a pacman -Syu before working but didn't reboot. I was running on the stock kernel at that point because the linux-ck kernel had not updated yet. My ISO built fine. Later that day I rebooted and was now running on the updated linux-ck kernel and suddenly the build process would simply die without any errors, even with the -v option. Right after installing all the custom packages, a dd output appears and then a mkfs.vfat version message appears and that's where it dies. Rebooting back to the stock arch kernel fixed the issue. I'm guessing it has something to do with hardcoded names or something like that in the build scripts.<br />
<br />
Is this normal behaviour? I don't mind using the stock kernel on the ISOs I build but I figured I'd at least be able to build them on a different one.<br />
<br />
On that note, is it possible to use a kernel other than the stock one within the ISOs we build? <br />
[[User:Biltong|Biltong]] ([[User talk:Biltong|talk]]) Sun May 6 2012, 21:47 SAST<br />
<br />
== Estimating size? Starting over? ==<br />
<br />
How do you best estimate the size?<br />
<br />
How do you start over? Suppose just take `etc/`, delete the `releng/` directory recopy, put stuff back. [[User:Jasper1984|Jasper1984]] ([[User talk:Jasper1984|talk]]) 13:46, 1 July 2013 (UTC)<br />
<br />
:Best way to start over is delete releng/{work,out} it keeps cached packages, and there is no need to do every step from the beginning. {{Unsigned|14:08, 5 October 2013|Jqvillanova}}<br />
<br />
== Encryption ==<br />
<br />
<br />
* with «cryptsetup», encrypt the file «airootfs.sfs» built with «mkarchiso» :<br />
<br />
# cd /path/to/buildir/<br />
# cd ./work/iso/arch/x86_64/<br />
# cryptsetup --verify-passphrase plainOpen ./airootfs.sfs encrypt<br />
# dd < ./airootfs.sfs > /dev/mapper/encrypt<br />
# sync<br />
# cryptsetup plainClose encrypt<br />
# md5sum ./airootfs.sfs > ./airootfs.md5<br />
# cd -<br />
<br />
''(note that you can't decrypt the encrypted file «airootfs.sfs» in the same «dd» way, instead use {{ic|1=dd of=./airootfs.sfs conv=nocreat,notrunc < /dev/mapper/encrypt}})''<br />
<br />
* add the hook «encrypt» in «mkinitcpio.conf» :<br />
<br />
# grep HOOKS ./work/airootfs/etc/mkinitcpio.conf<br />
HOOKS="... encrypt"<br />
<br />
<br />
* insert these lines in «archiso» hook :<br />
<br />
--- a/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
+++ b/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
@@ -65,6 +65,10 @@<br />
fi<br />
sfs_dev=$(losetup --find --show --read-only "${img}")<br />
echo ${sfs_dev} >> /run/archiso/used_block_devices<br />
+ msg ":: Mapping encrypted squashfs..."<br />
+ local map="${sfs_dev##*/}.map"<br />
+ cryptsetup plainOpen "${sfs_dev}" "${map}"<br />
+ sfs_dev="/dev/mapper/${map}"<br />
_mnt_dev "${sfs_dev}" "${mnt}" "-r" "defaults"<br />
}<br />
<br />
<br />
* rebuild initramfs and iso with «mkarchiso» and test :<br />
<br />
# mkarchiso -r "mkinitcpio -p linux" run<br />
# mkarchiso iso encrypted.iso<br />
# qemu ... ./out/encrypted.iso<br />
<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 21:51, 20 Feb 2016 (UTC)<br />
<br />
: @Lacsap Can't manage to make it working. I managed to build the iso but it can't find <code>/run/iso_name/bootmnt</code>. I think I have missed the decryption part. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 11:43, 17 October 2021 (UTC)<br />
<br />
== Example configurations ==<br />
<br />
Where should sets of ArchISO customizations go? Should there be an "Examples" header added to the bottom? Like for how to enable remote {{ic|ssh}} login, boot with serial console support for headless systems, etc? Or a separate page? [Archiso offline] is a separate page, but it was marked for possible merging since it's an (out of date) clone of this page. [[User:Jamespharvey20|Jamespharvey20]] ([[User talk:Jamespharvey20|talk]]) 02:38, 25 April 2019 (UTC)<br />
:I guess your changes (adding ssh configs) should be done airootfs directory. But I did not yet explored how to add another systemd services to archiso. Adding info about how to enable ssh login to this page seems useful for me. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 17:42, 25 April 2019 (UTC)<br />
<br />
== ISO does not build with secure boot enabled ==<br />
<br />
It seems that if you have secure boot enabled and have signed the Linux kernel, the ISO will fail to build, saying that /boot/vmlinuz-linux does not exist. However, once you disable secure boot, the ISO starts getting built again. Just tried this, and it appears to go back at least to archiso version 36.<br />
<br />
[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 18:58, 26 May 2020 (UTC)<br />
<br />
:To clarify, I don't really know why it doesn't work. If possible, could someone else test this, to see if it's just a problem on my computer or more widespread. If so, then maybe we should add a warning to the wiki page.<br />
:[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 04:54, 27 May 2020 (UTC)<br />
<br />
::I don't use secure boot myself, so I don't know how it works. Since [https://github.com/archlinux/svntogit-packages/commit/43c5745a17e2ebe413a7140d4ef9326e26d6cb20 5.3.8.1] the {{pkg|linux}} package does not install the kernel to {{ic|/boot/vmlinuz-linux}}, but to {{ic|/usr/lib/modules/VERSION/vmlinuz}} and [https://github.com/archlinux/mkinitcpio/tree/master/libalpm/hooks mkinitcpio's pacman hooks] copy it to {{ic|/boot/}}. If the kernel image is not getting copied somewhere in the ISO's chroot, maybe there is something wrong with the hooks... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:39, 30 May 2020 (UTC)<br />
<br />
== Please add a warning with regards to syncthing interoperability ==<br />
<br />
When mkarchiso is executed to use a working directory (e.g. -w ./tmp) inside a folder that is observed by syncthing, there are 2 issues: mkarchiso will fail and a restart is required in order to be able to delete the working directory. As a simple workaround, the working directory can be added to the syncthing ignore patterns.<br />
<br />
I do not know what causes these errors - especially since mkarchiso does not throw any error message. Deleting the working directory fails due to missing rights although it is run as root. After a restart the working directory can be deleted. [[User:ente|ente]] ([[User talk:ente|talk]]) 11:09, 17 September 2020 (UTC)<br />
<br />
== Add a section to Tips and Tricks to build an ISO for installation entirely over a serial console ==<br />
<br />
I've been looking all over for a good way to do this. I think I have an approach that could work (although it's still to be tried). What do we think about adding this? Has anyone got a recipe? If not, I'm happy to give it a go.<br />
<br />
[[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 11:33, 14 November 2020 (UTC)<br />
<br />
:The solution is to simply add a [[Working with the serial console#Kernel|console=ttyS* kernel parameter]] to boot loader configuration. As for why it's not done by default in releng, see https://gitlab.archlinux.org/archlinux/archiso/-/issues/75. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:28, 14 November 2020 (UTC)<br />
<br />
::I get that, but you need to _get_ to the bootloader menu first, and that currently doesn't happen over the console to my knowledge... [[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 13:55, 14 November 2020 (UTC)<br />
<br />
:::I meant editing the boot loader configuration for the ISO and then building the ISO. As for seeing the boot loader over serial, it should work when booting in BIOS mode (this doesn't prevent installing the system for UEFI booting, you just need to install the boot loader to the default/fallback boot path). -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 05:23, 15 November 2020 (UTC)<br />
<br />
== <s>Permissions and File Additions</s> ==<br />
<br />
Would suggest we document the new changes to permissions requirements as implemented on 11/30/20 in Commit c10004df :<br />
<br />
profiledef.sh needs to have explicit permissions now which is quite different than before.<br />
<br />
file_permissions=(<br />
["/etc/shadow"]="0:0:400"<br />
["/root"]="0:0:750"<br />
["/root/.automated_script.sh"]="0:0:755"<br />
["/usr/local/bin/choose-mirror"]="0:0:755"<br />
["/usr/local/bin/Installation_guide"]="0:0:755"<br />
["/usr/local/bin/livecd-sound"]="0:0:755"<br />
<br />
<br />
Also, the fact that a /skel folder cannot be added to airootfs now is different and requires users to put everything in /etc/skel/<br />
<br />
Users can still add services, but I found the best way to add them was to put them in /usr/local/bin and then add a line to profiledef.sh to give them 755.<br />
<br />
[[User:Jdfthetech|Jdfthetech]] ([[User talk:Jdfthetech|talk]]) 05:34, 2 December 2020 (UTC)<br />
<br />
:Thanks for this update, I've just reached this pitfall attempting to create a non-root user with their own home directory, but failing with {{ic|[mkarchiso] ERROR: Failed to set permissions on 'work/x86_64/airootfs/home/myuser'. Outside of valid path.}} Any thoughts on how to get this working? [[User:Yuvadm|Yuvadm]] ([[User talk:Yuvadm|talk]]) 20:34, 14 December 2020 (UTC)<br />
<br />
::https://gitlab.archlinux.org/archlinux/archiso/-/issues/84. The workaround for now is to explicitly set the work dir with the {{ic|-w}} option. If all goes well, it should be fixed in the next archiso version. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:03, 15 December 2020 (UTC)<br />
<br />
:::[[Archiso#Adding files to image]] mentions permissions and links to the docs. Closing. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 08:22, 22 February 2023 (UTC)<br />
<br />
== mention mkosi ==<br />
<br />
It seems that [[mkosi]] offers similar functionalities.<br />
What about mentioning [[mkosi]] in [[Category:Live_Arch_systems]] and under [[archiso#See_also]]?<br />
[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 07:33, 7 March 2023 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Waydroid&diff=756858Waydroid2022-11-12T20:49:15Z<p>PXf: /* Network */ hint network packet forwarding</p>
<hr />
<div>[[Category:Sandboxing]]<br />
[[Category:Virtualization]]<br />
[[Category:Android]]<br />
{{Related articles start}}<br />
{{Related|Anbox}}<br />
{{Related|Linux Containers}}<br />
{{Related articles end}}<br />
<br />
{{Style|Need to improve style.}}<br />
<br />
Waydroid is a container-based approach to boot a full Android system on a regular GNU/Linux system.<br />
<br />
== Prerequisites ==<br />
<br />
=== CPU Requirements ===<br />
<br />
The requirements depend on the CPU architecture. You can check [https://developer.android.com/ndk/guides/abis#sa table] for more information.<br />
<br />
You can check if you have the required CPU instructions with {{ic|cat /proc/cpuinfo}}.<br />
<br />
=== GPU Requirements ===<br />
<br />
Waydroid currently works best with Intel GPUs. They should work out of the box.<br />
<br />
AMD GPUs appear to have mixed results (in particular, the ''RX 6800'' does not work using official images as of 2022-09-29); if Waydroid does ''not'' work you might also want to try to build a new Waydroid image (which works for Radeon 680M), or try the NVIDIA instructions below.<br />
<br />
NVIDIA GPUs do ''not'' work currently, but there are 2 workarounds:<br />
<br />
* Switch to integrated graphic card if possible;<br />
* Use software rendering:<br />
** Make sure that you have already run {{ic|waydroid init}} (see [[#Installation]] section)<br />
** Edit {{ic|/var/lib/waydroid/waydroid_base.prop}} and set:{{bc|<nowiki>ro.hardware.gralloc=default<br />
ro.hardware.egl=swiftshader</nowiki>}}<br />
** [[Restart]] the {{ic|waydroid-container.service}}.<br />
<br />
=== Wayland session manager ===<br />
<br />
Waydroid only works in a [[Wayland]] session manager, so make sure you are in a Wayland session.<br />
<br />
Note that even if you are in X11, many Wayland session managers support nested session (so you can run it inside your X11 session), the simplest example is {{pkg|weston}}.<br />
<br />
=== Kernel Modules ===<br />
<br />
You need to run a kernel which comes with the binder modules and optionally the ashmem one. They are not part of Arch Linux's default kernel ({{Pkg|linux}}), thus you need to install a kernel which ships these modules.<br />
<br />
You might also need to configure your bootloader to use a different kernel. Please refer to the wiki page of your bootloader how to boot with the new kernel. Booting into another kernel (version) is one of the few occasions when you have to reboot a Linux system. You should boot into the kernel with these modules before starting Waydroid.<br />
<br />
{{Note|1=Since {{aur|waydroid}} 1.2.1 ''ashmem'' is not needed anymore, ''memfd'' can be used instead, see [https://github.com/waydroid/waydroid/issues/406 issue]. This because ''ashmem'' has been completely replaced by ''memfd'' in ''mainline Linux'' since version 5.18, see [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=721412ed3d819e767cac2b06646bf03aa158aaec commit].}}<br />
<br />
To get a compatible kernel, you have multiple options:<br />
<br />
==== Using Linux-Zen ====<br />
<br />
The {{Pkg|linux-zen}} kernel includes the necessary modules. This might be the most comfortable way, as you do not have to compile the kernel (which takes a long time) and will receive updated versions regularly.<br />
<br />
==== DKMS modules ====<br />
<br />
You can install {{aur|anbox-modules-dkms-git}} and load kernel modules with: {{bc|# modprobe ashmem_linux<br />
# modprobe binder_linux<br />
}}<br />
<br />
Alternatively, if your kernel is 5.18 or newer, install {{aur|binder_linux-dkms}}, which provides just binder_linux.<br />
<br />
==== Building a kernel ====<br />
<br />
Alternatively, you can recompile the {{Pkg|linux}} kernel — or other kernel packages (>=5.7) — with the necessary options. Also see [[Kernel#Compilation]].<br />
<br />
When setting compilation options, you have 2 options available; ''binder'' and ''binderfs''. Instructions for both are provided below.<br />
<br />
===== Using binder =====<br />
<br />
The modules can either be compiled into the kernel ({{ic|y}}), into modules ({{ic|m}}), or not at all ({{ic|n}}). Also, not all combinations in the configuration are possible, and some options will require other options.<br />
<br />
The configuration options below will compile binder as a module, while the last option specifies that there will be three devices created in the {{ic|/dev/}} directory, when the binder module is loaded.<br />
<br />
{{bc|1=<br />
CONFIG_ANDROID=y<br />
CONFIG_ANDROID_BINDER_IPC=m<br />
CONFIG_ANDROID_BINDERFS=n<br />
CONFIG_ANDROID_BINDER_DEVICES="binder,hwbinder,vndbinder"<br />
}}<br />
<br />
When building a kernel from the AUR, one can update the configuration with the following steps:<br />
<br />
# run {{ic|makepkg --nobuild}}, which will download the sources, verify and extract them and run the {{ic|prepare()}} function.<br />
# edit the {{ic|.config}} file (with the dot in the filename), which is located at the base of the kernel directory.<br />
# at the end of the {{ic|prepare()}} function was probably a command which regenerates the makefiles with information from the configuration, possibly {{ic|make olddefconfig}}. Move that to the {{ic|build()}} function, or execute it yourself.<br />
# run {{ic|makepkg --noextract}}, which will continue from the place where {{ic|makepkg --nobuild}} stopped.<br />
<br />
===== Using binderfs =====<br />
<br />
The binder kernel module is known to cause some issues to several users. To address these issues, binderfs was created. One has to choose between the old and the new way when compiling the kernel. With the options below, one will use binderfs instead.<br />
<br />
With the kernel sources comes also a simple script to set configuration options. It will not do dependency checks, just like when editing the configuration by hand. When being in the same directory where the {{ic|.config}} file lies, one can execute the following commands:<br />
<br />
{{bc|<br />
$ scripts/config --enable CONFIG_ANDROID<br />
$ scripts/config --enable CONFIG_ANDROID_BINDER_IPC<br />
$ scripts/config --enable CONFIG_ANDROID_BINDERFS<br />
$ scripts/config --set-str CONFIG_ANDROID_BINDER_DEVICES ""<br />
}}<br />
<br />
When building a kernel from the AUR, it is enough to insert these lines at the right place in the [[PKGBUILD]], usually in {{ic|prepare()}}.<br />
<br />
==== Setup binder devices ====<br />
<br />
Make sure you have the latest version of Waydroid package, and Waydroid will take automatically care of this.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{AUR|waydroid}} package.<br />
<br />
Optionally, install {{AUR|waydroid-image}} or {{AUR|waydroid-image-gapps}} to provide the needed Android image through AUR.<br />
<br />
Afterwards init Waydroid, this will automatically download the latest Android image if it is not yet available.<br />
# waydroid init<br />
<br />
To init with GApps support:<br />
# waydroid init -s GAPPS -f<br />
Next [[start/enable]] the {{ic|waydroid-container.service}}.<br />
<br />
Waydroid should now work.<br />
<br />
== Usage ==<br />
<br />
Make sure that {{ic|waydroid-container.service}} is running then run:<br />
$ waydroid session start<br />
<br />
The Waydroid session is now active, here are a couple of useful commands to interact with it:<br />
<br />
''Launch GUI'':<br />
$ waydroid show-full-ui<br />
''Launch shell'':<br />
# waydroid shell<br />
''Install an application'':<br />
$ waydroid app install $path_to_apk<br />
''Run an application'':<br />
$ waydroid app launch $package-name #Can be retrieved with `waydroid app list`<br />
<br />
== Network ==<br />
<br />
The network should work out of the box, if its not you might need to make sure [[internet sharing#Enable_packet_forwarding|packet forwarding]] is enabled in kernel and allow the following rules through your firewall ''before'' running ''Waydroid session start''.<br />
<br />
Taking {{pkg|ufw}} as an example:<br />
<br />
* Dns traffic needs to be allowed:<br />
** {{bc|# ufw allow 67}}<br />
** {{bc|# ufw allow 53}}<br />
* Packet forwarding needs to be allowed:<br />
** {{bc|# ufw default allow FORWARD}}<br />
<br />
For {{pkg|firewalld}}, you can use those commands:<br />
<br />
* DNS:<br />
** {{bc|1=# firewall-cmd --zone=trusted --add-port=67/udp}}<br />
** {{bc|1=# firewall-cmd --zone=trusted --add-port=53/udp}}<br />
* Packet forwarding:<br />
** {{bc|1=# firewall-cmd --zone=trusted --add-forward}}<br />
<br />
{{Note|We assume that interface {{ic|waydroid0}} created by waydroid should be in the firewalld zone {{ic|trusted}} automatically. If not so, please adjust those commands above or move interface {{ic|waydroid0}} to {{ic|trusted}}. You may also need {{bc|# firewall-cmd --runtime-to-permanent}} to make your changes exist after a restart.}}<br />
<br />
== Troubleshooting ==<br />
<br />
If you run into issues, take a look at the official Issue Tracker: [https://github.com/waydroid/waydroid/issues Waydroid issue tracker]<br />
<br />
=== General tips ===<br />
<br />
Waydroid is in rapid developement so if you face issues, here is a good list of steps to do first:<br />
<br />
# Make sure your Waydroid package is up to date;<br />
# Make sure you have the latest Waydroid image by running {{bc|# waydroid upgrade}}<br />
# Reset Waydroid: [[stop]] the {{ic|waydroid-container.service}}, run {{bc|# waydroid init -f}} and [[start]] the service again. <br />
# You may also want to do little cleanup, run {{bc|# rm -rf /var/lib/waydroid /home/.waydroid}} {{bc|$ rm -rf ~/waydroid ~/.share/waydroid ~/.local/share/applications/*aydroid* ~/.local/share/waydroid}}<br />
<br />
=== Rotated apps are unusable ===<br />
<br />
See https://github.com/waydroid/waydroid/issues/70<br />
<br />
Click ''F11'' to switch the current app to windowed mode.<br />
<br />
=== Failed to start Clipboard manager service ===<br />
<br />
Install {{aur|python-pyclip}}<br />
<br />
=== Sometimes the physical keyboard does not work ===<br />
<br />
Press ''Left Alt'' key.<br />
<br />
=== Commands inside Waydroid shell outputs inaccessible or not found ===<br />
<br />
On Arch based distributions there's a [[Linux Containers#Basic usage|"bug" that may appear while working with lxc-attach]] that may cause this issue with commands inside {{ic|waydroid shell}} like {{ic|adbd}} or {{ic|settings}}.<br />
A possible workaround for this would be replace the {{bc|# waydroid shell}} command with {{bc|# lxc-attach -P /var/lib/waydroid/lxc/ -n waydroid --clear-env}}<br />
<br />
=== WARNING: Service manager /dev/binder has died ===<br />
<br />
See https://github.com/waydroid/waydroid/issues/136<br />
<br />
You should enable [https://docs.kernel.org/accounting/psi.html PSI].<br />
Add {{ic|1=psi=1}} to the [[kernel command line]].<br />
<br />
== See also ==<br />
<br />
* [https://github.com/waydroid/waydroid Waydroid GitHub repo]<br />
* [https://docs.waydro.id/ Waydroid documentation]<br />
* [https://matrix.to/#/#waydroid:connolly.tech Waydroid Matrix group]<br />
* [https://t.me/WayDroid Waydroid Telegram group]</div>PXfhttps://wiki.archlinux.org/index.php?title=Dm-crypt&diff=746635Dm-crypt2022-09-16T14:37:50Z<p>PXf: /* Usage */ please either list the subpage dm-crypt/Mounting at login here or merge it somewhere else</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[de:dm-crypt]]<br />
[[es:Dm-crypt]]<br />
[[ja:Dm-crypt]]<br />
[[pl:Dm-crypt]]<br />
[[pt:Dm-crypt]]<br />
[[ru:Dm-crypt]]<br />
[[uk:Dm-crypt]]<br />
[[zh-hans:Dm-crypt]]<br />
[[zh-hant:Dm-crypt]]<br />
{{Related articles start}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|Removing system encryption}}<br />
{{Related articles end}}<br />
<br />
dm-crypt is the Linux kernel's [[Wikipedia:device mapper|device mapper]] crypto target. From [[Wikipedia:dm-crypt]], it is:<br />
:a transparent disk encryption subsystem in [the] Linux kernel... [It is] implemented as a device mapper target and may be stacked on top of other device mapper transformations. It can thus encrypt whole disks (including removable media), partitions, software RAID volumes, logical volumes, as well as files. It appears as a block device, which can be used to back file systems, swap or as an LVM physical volume.<br />
<br />
== Usage ==<br />
<br />
; [[/Drive preparation]]: Deals with operations like [[/Drive preparation#Secure erasure of the hard disk drive|securely erasing the drive]] and ''dm-crypt'' specific points for [[/Drive preparation#Partitioning|partitioning it]].<br />
; [[/Device encryption]]: Covers how to manually utilize dm-crypt to encrypt a system through the [[cryptsetup]] command. It covers examples of the [[/Device encryption#Encryption options with dm-crypt|Encryption options with dm-crypt]], deals with the creation of [[/Device encryption#Keyfiles|keyfiles]], LUKS specific commands for [[/Device encryption#Key management|key management]] as well as for [[/Device encryption#Backup and restore|Backup and restore]].<br />
; [[/System configuration]]: Illustrates how to configure [[/System configuration#mkinitcpio|mkinitcpio]], [[/System configuration#Kernel parameters|kernel parameters]] and the [[crypttab]] file when encrypting a system.<br />
; [[/Swap encryption]]: Covers how to add a swap partition to an encrypted system, if required. The swap partition must be encrypted as well to protect any data swapped out by the system. This part details methods [[/Swap encryption#Without suspend-to-disk support|without]] and [[/Swap encryption#With suspend-to-disk support|with]] suspend-to-disk support.<br />
; [[/Specialties]]: Deals with special operations like [[/Specialties#Securing the unencrypted boot partition|securing the unencrypted boot partition]], [[/Specialties#Using GPG, LUKS, or OpenSSL Encrypted Keyfiles|using GPG or OpenSSL encrypted keyfiles]], a method to [[/Specialties#Remote unlocking of the root (or other) partition|boot and unlock via the network]], another for [[/Specialties#Discard/TRIM support for solid state drives (SSD)|setting up discard/TRIM for a SSD]], and sections dealing with [[/Specialties#The encrypt hook and multiple disks|the encrypt hook and multiple disks]].<br />
; [[/Mounting at login]]<br />
<br />
== Example scenarios ==<br />
<br />
; [[/Encrypting a non-root file system]]: If you need to encrypt a device that is not used for booting a system, like a [[/Encrypting a non-root file system#Partition|partition]] or a [[/Encrypting a non-root file system#File_container|file container]].<br />
; [[/Encrypting an entire system]]: If you want to encrypt an entire system, in particular a root partition. Several scenarios are covered, including the use of ''dm-crypt'' with the ''LUKS'' extension, ''plain'' mode encryption and encryption and ''LVM''.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt dm-crypt] - The project homepage <br />
* [https://gitlab.com/cryptsetup/cryptsetup cryptsetup] - The LUKS homepage and [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions FAQ] - the main and foremost help resource.</div>PXfhttps://wiki.archlinux.org/index.php?title=Dm-crypt/System_configuration&diff=746529Dm-crypt/System configuration2022-09-16T10:17:58Z<p>PXf: /* mkinitcpio */ make words easier to read</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[es:Dm-crypt (Español)/System configuration]]<br />
[[ja:dm-crypt/システム設定]]<br />
[[pt:Dm-crypt (Português)/System configuration]]<br />
{{Expansion|Aggregate here all the generic information on system configuration from the other sub-articles of [[dm-crypt]].}}<br />
<br />
{{Tip|<br />
* If in need to remotely unlock root or other early-boot filesystems (headless machine, distant servers...), follow the specific instructions from [[dm-crypt/Specialties#Remote unlocking of the root (or other) partition]].<br />
* To ease inputting UUIDs, PARTUUIDs, etc. in configuration files, you can install and use a [[text editor]] that supports inserting command output (e.g. [[nano]] with {{ic|Ctrl+t}}, [[Vim]] or [[Neovim]] with {{ic|:read}} or [[mcedit]] with {{ic|Alt+u}}) and pass it [[Persistent block device naming#Persistent naming methods|the apropriate lsblk or blkid command]]. Alternatively, you can install a [[List of applications/Utilities#Terminal multiplexers|terminal multiplexer]] and use its copy and paste functionality.<br />
}}<br />
<br />
== Unlocking in early userspace ==<br />
<br />
Booting an encrypted root volume requires that the [[initramfs]] contains the necessary tools for early userspace to unlock the volume. The instructions on what to unlock are topically passed via [[kernel parameters]].<br />
<br />
The following sections describe how to configure mkinitcpio and list which kernel parameters are required.<br />
<br />
=== mkinitcpio ===<br />
<br />
Depending on the particular scenarios, a subset of the following [[mkinitcpio#HOOKS|mkinitcpio hooks]] will have to be enabled:<br />
<br />
{| class="wikitable"<br />
! busybox !! systemd !! Use case<br />
|-<br />
|style="text-align: center;white-space:nowrap;"| {{ic|encrypt}}<br />
|style="text-align: center;white-space:nowrap;"| {{ic|sd-encrypt}}<br />
| Needed when the root partition is encrypted or when an encrypted partition needs to be mounted ''before'' the root partition. Not needed in other cases as system initialization scripts like {{ic|/etc/crypttab}} already take care of unlocking other non-root partitions. This hook must be placed ''after'' the {{ic|udev}} or {{ic|systemd}} hook.<br />
|-<br />
|colspan="2" style="text-align: center;white-space:nowrap;"| {{ic|keyboard}}<br />
| Needed to make keyboards work in early userspace.<br />
<br />
{{Tip|For systems that are booted with different hardware configurations (e.g. laptops with external keyboard vs. internal keyboard or [[Wikipedia:Headless computer|headless systems]]), it is helpful to place this hook before {{ic|autodetect}} in order to always include all keyboard drivers. Otherwise the external keyboard only works in early userspace if it was connected when creating the image.}}<br />
|-<br />
|style="text-align: center;white-space:nowrap;"| {{ic|keymap}}<br />
|rowspan="2" style="text-align: center;white-space:nowrap;"| {{ic|sd-vconsole}}<br />
| Provides support for non-US keymaps for typing encryption passwords; it must come ''before'' the {{ic|encrypt}} hook, otherwise you will need to enter your encryption password using the default US keymap. Set your keymap in {{ic|/etc/vconsole.conf}}, see [[Keyboard configuration in console#Persistent configuration]].<br />
|-<br />
|style="text-align: center;white-space:nowrap;"| {{ic|consolefont}}<br />
| Loads an alternative console font in early userspace. Set your font in {{ic|/etc/vconsole.conf}}, see [[Linux console#Persistent configuration]].<br />
|}<br />
<br />
[[mkinitcpio#Common hooks|Other hooks]] needed should be clear from other manual steps followed during the installation of the system.<br />
<br />
{{Note|Remember to [[regenerate the initramfs]] after making any changes to {{ic|/etc/mkinitcpio.conf}}.}}<br />
<br />
==== Examples ====<br />
<br />
A typical {{ic|/etc/mkinitcpio.conf}} configuration using {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
HOOKS=(base '''udev''' autodetect keyboard '''keymap''' '''consolefont''' modconf block '''encrypt''' lvm2 filesystems fsck)<br />
...<br />
}}<br />
<br />
A configuration with systemd-based initramfs using {{ic|sd-encrypt}} hook:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
HOOKS=(base '''systemd''' autodetect keyboard '''sd-vconsole''' modconf block '''sd-encrypt''' lvm2 filesystems fsck)<br />
...<br />
}}<br />
<br />
=== Kernel parameters ===<br />
<br />
The [[kernel parameters]] you need to specify depend on whether the {{ic|encrypt}} hook or the {{ic|sd-encrypt}} hook is being used. {{ic|root}} and {{ic|resume}} are specified the same way for both.<br />
<br />
For example, if using [[GRUB]], the relevant parameters are added to {{ic|/etc/default/grub}} before [[GRUB#Generate_the_main_configuration_file|generating the main configuration file]]. See also [[GRUB#Warning when installing in chroot]] as another point to be aware of when installing the GRUB loader.<br />
<br />
==== root ====<br />
<br />
The {{ic|1=root=}} parameter specifies the {{ic|''device''}} of the actual (decrypted) root file system:<br />
<br />
root=''device''<br />
<br />
* If the file system is formatted directly on the decrypted device file this will be {{ic|/dev/mapper/''dmname''}}.<br />
* If a LVM gets activated first and contains an [[dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|encrypted logical rootvolume]], the above form applies as well. <br />
* If the root file system is contained in a logical volume of a fully [[encrypted LVM]], the device mapper for it will be in the general form of {{ic|1=root=/dev/''volumegroup''/''logicalvolume''}}.<br />
<br />
{{Tip|When using [[GRUB]] and generating {{ic|grub.cfg}} with ''grub-mkconfig'', this parameter does not need to be specified manually. ''grub-mkconfig'' will determine the correct UUID of the decrypted root filesystem and add it to {{ic|grub.cfg}} automatically.}}<br />
<br />
==== resume ====<br />
<br />
resume=''device''<br />
<br />
* {{ic|''device''}} is the device file of the decrypted (swap) filesystem used for [[Power management/Suspend and hibernate#Hibernation|suspend to disk]]. If swap is on a separate partition, it will be in the form of {{ic|/dev/mapper/swap}}. See also [[dm-crypt/Swap encryption]].<br />
<br />
==== Using encrypt hook ====<br />
<br />
{{Note|Compared to the [[sd-encrypt]] hook, the {{ic|encrypt}} hook does not support:<br />
* Unlocking [[dm-crypt/Specialties#The encrypt hook and multiple disks|multiple encrypted disks]] ({{Bug|23182}}). Only '''one''' device can be unlocked in the initramfs.<br />
* Using a [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|detached LUKS header]] ({{Bug|42851}}).<br />
* Setting additional options that are supported by [[#crypttab|crypttab]], e.g. {{ic|sector-size}} ({{Bug|72119}}).<br />
}}<br />
<br />
===== cryptdevice =====<br />
<br />
This parameter will make the system prompt for the passphrase to unlock the device containing the encrypted root on a cold boot. It is parsed by the {{ic|encrypt}} hook to identify which device contains the encrypted system:<br />
<br />
cryptdevice=''device'':''dmname'':''options''<br />
<br />
* {{ic|''device''}} is the path to the device backing the encrypted device. Usage of [[persistent block device naming]] is strongly recommended.<br />
* {{ic|''dmname''}} is the '''d'''evice-'''m'''apper name given to the device after decryption, which will be available as {{ic|/dev/mapper/''dmname''}}.<br />
* {{ic|''options''}} (optional) are comma separated options, e.g. for TRIM support. If no options are required, omit this parameter (use {{ic|1=cryptdevice=''device'':''dmname''}}).<br />
* If a LVM contains the [[dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|encrypted root]], the LVM gets activated first and the volume group containing the logical volume of the encrypted root serves as ''device''. It is then followed by the respective volume group to be mapped to root. The parameter follows the form of {{ic|1=cryptdevice=''/dev/vgname/lvname'':''dmname''}}.<br />
<br />
{{Tip|One may want to [[Dm-crypt/Specialties#Discard/TRIM_support_for_solid_state_drives_(SSD)|enable Discard/TRIM support]] for solid state drives (SSD).}}<br />
<br />
===== cryptkey =====<br />
<br />
This parameter specifies the location of a keyfile and is required by the {{ic|''encrypt''}} hook for reading such a keyfile to unlock the {{ic|''cryptdevice''}} (unless a key is in the default location, see below). It can have three parameter sets, depending on whether the keyfile exists as a file in a particular device, a bitstream starting on a specific location, or a file in the initramfs. <br />
<br />
For a file in a device the format is:<br />
<br />
cryptkey=''device'':''fstype'':''path''<br />
<br />
* {{ic|''device''}} is the raw block device where the key exists. Usage of [[persistent block device naming]] is strongly recommended.<br />
* {{ic|''fstype''}} is the filesystem type of {{ic|''device''}} (or auto).<br />
* {{ic|''path''}} is the absolute path of the keyfile within the device.<br />
<br />
Example: {{ic|1=cryptkey=LABEL=usbstick:vfat:/secretkey}}<br />
<br />
For a bitstream on a device the key's location is specified with the following: <br />
<br />
cryptkey=''device'':''offset'':''size'' <br />
<br />
where the offset and size are in bytes. For example, {{ic|1=cryptkey=UUID=''ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ'':0:512}} reads a 512 byte keyfile starting at the beginning of the device. <br />
<br />
{{Tip|If the device path you want to access contains the character {{ic|:}}, you have to escape it with a backslash {{ic|\}}. In that case the cryptkey parameter would be as follow: {{ic|1=cryptkey=/dev/disk/by-id/usb-123456-0\:0:0:512}} for a usb key with the id {{ic|usb-123456-0:0}}.}}<br />
<br />
For a file [[mkinitcpio#BINARIES and FILES|included]] in the initramfs the format is[https://github.com/archlinux/svntogit-packages/blob/packages/cryptsetup/trunk/hooks-encrypt#L14]:<br />
<br />
cryptkey=rootfs:''path''<br />
<br />
Example: {{ic|1=cryptkey=rootfs:/secretkey}}<br />
<br />
Also note that if {{ic|cryptkey}} is not specified, it defaults to {{ic|/crypto_keyfile.bin}} (in the initramfs).[https://github.com/archlinux/svntogit-packages/blob/packages/cryptsetup/trunk/hooks-encrypt#L8]<br />
<br />
See also [[dm-crypt/Device encryption#Keyfiles]].<br />
<br />
===== crypto =====<br />
<br />
This parameter is specific to pass ''dm-crypt'' plain mode options to the ''encrypt'' hook. <br />
<br />
It takes the form<br />
<br />
crypto=''hash'':''cipher'':''keysize'':''offset'':''skip''<br />
<br />
The arguments relate directly to the ''cryptsetup'' options. See [[dm-crypt/Device encryption#Encryption options for plain mode]].<br />
<br />
For a disk encrypted with just ''plain'' default options, the {{ic|crypto}} arguments must be specified, but each entry can be left blank: <br />
<br />
crypto=::::<br />
<br />
A specific example of arguments is <br />
<br />
crypto=sha512:twofish-xts-plain64:512:0:<br />
<br />
==== Using systemd-cryptsetup-generator ====<br />
<br />
''systemd-cryptsetup-generator'' is a [[systemd]] unit generator that reads a subset of [[kernel parameters]], and {{ic|/etc/crypttab}}, for the purpose of unlocking encrypted devices during the [[Arch boot process#initramfs|initramfs stage]]. See the {{man|8|systemd-cryptsetup-generator}} man page for more details about it and all options it supports. ''systemd-cryptsetup-generator'' is run when using the {{ic|sd-encrypt}} [[Mkinitcpio#HOOKS|mkinitcpio hook]] or the {{ic|systemd}} [[Dracut#Dracut modules|dracut module]].<br />
<br />
In what follows, we describe some of the [[kernel parameters]] that ''systemd-cryptsetup-generator'' interprets.<br />
<br />
{{Tip|<br />
* If the file {{ic|/etc/crypttab.initramfs}} exists, it will be added to the initramfs as {{ic|/etc/crypttab}}, there you can specify devices that need to be unlocked at the initramfs phase. See [[#crypttab]] for the syntax.<br />
* {{ic|/etc/crypttab.initramfs}} is not limited to using only UUID like {{ic|rd.luks}}. You can use any of the [[Persistent block device naming#Persistent naming methods|persistent block device naming methods]].<br />
* Passwords entered during boot are cached in the kernel keyring by {{man|8|systemd-cryptsetup}}, so if multiple devices can be unlocked with the same password (this includes devices in [[#crypttab|crypttab]] that are unlocked after boot), then you will only need to input each password once.<br />
}}<br />
<br />
{{Note|<br />
* All of the {{ic|rd.luks}} parameters can be specified multiple times to unlock multiple LUKS encrypted volumes.<br />
* The {{ic|rd.luks}} parameters only support unlocking LUKS devices. To unlock a plain dm-crypt device, you must specify it in {{ic|/etc/crypttab.initramfs}}. See [[#crypttab]] for the syntax.<br />
}}<br />
<br />
{{Warning|If you are using {{ic|/etc/crypttab}} or {{ic|/etc/crypttab.initramfs}} together with {{ic|luks.*}} or {{ic|rd.luks.*}} parameters, only those devices specified on the kernel command line will be activated and you will see {{ic|Not creating device 'devicename' because it was not specified on the kernel command line.}}. This is because the {{ic|luks.*}} or {{ic|rd.luks.*}} parameters control which devices from the crypttab get activated. To activate all devices in {{ic|/etc/crypttab}} do not specify any {{ic|luks.*}} parameters and use {{ic|rd.luks.*}}. To activate all devices in {{ic|/etc/crypttab.initramfs}} do not specify any {{ic|luks.*}} or {{ic|rd.luks.*}} parameters.}}<br />
<br />
===== rd.luks.uuid =====<br />
<br />
{{Tip|{{ic|rd.luks.uuid}} can be omitted when using {{ic|rd.luks.name}}.}}<br />
<br />
rd.luks.uuid=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''<br />
<br />
Specify the [[UUID]] of the device to be decrypted on boot with this flag.<br />
<br />
By default the mapped device will be located at {{ic|/dev/mapper/luks-''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''}} where ''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' is the UUID of the LUKS partition.<br />
<br />
===== rd.luks.name =====<br />
<br />
{{Tip|When using this parameter you can omit {{ic|rd.luks.uuid}}.}}<br />
<br />
rd.luks.name=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''=''name''<br />
<br />
Specify the name of the mapped device after the LUKS partition is open, where ''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' is the UUID of the LUKS partition. This is equivalent to the second parameter of {{ic|encrypt}}'s {{ic|cryptdevice}}.<br />
<br />
For example, specifying {{ic|1=rd.luks.name=12345678-9abc-def0-1234-56789abcdef0=root}} causes the unlocked LUKS device with UUID {{ic|12345678-9ABC-DEF0-1234-56789ABCDEF0}} to be located at {{ic|/dev/mapper/root}}.<br />
<br />
===== rd.luks.key =====<br />
<br />
Specify the location of a password file used to decrypt the device specified by its UUID. There is no default location like there is with the {{ic|encrypt}} hook parameter {{ic|cryptkey}}.<br />
<br />
If the keyfile is [[mkinitcpio#BINARIES and FILES|included in the initramfs]]:<br />
<br />
rd.luks.key=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''=''/path/to/keyfile''<br />
<br />
or<br />
<br />
rd.luks.key=''/path/to/keyfile''<br />
<br />
{{Tip|The whole {{ic|rd.luks.key}} parameter can be omitted if the keyfile is included as {{ic|/etc/cryptsetup-keys.d/''name''.key}}.}}<br />
<br />
If the keyfile is on another device:<br />
<br />
rd.luks.key=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''=''/path/to/keyfile'':UUID=''ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ''<br />
<br />
Replace {{ic|1=UUID=''ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ''}} with the identifier of the device on which the keyfile is located.<br />
<br />
{{Warning|<br />
* If the type of file system is different than your root file system, you must [[mkinitcpio#MODULES|include the kernel module for it in the initramfs]].<br />
* {{ic|rd.luks.key}} with a keyfile on another device by default does not fallback to asking for a password if the device is not available. To fallback to a password prompt, specify the {{ic|1=keyfile-timeout=}} option in {{ic|rd.luks.options}}. E.g. for a 10 second timeout: {{bc|1=rd.luks.options=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''=keyfile-timeout=10s}}<br />
}}<br />
<br />
===== rd.luks.options =====<br />
<br />
rd.luks.options=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX''=''options''<br />
<br />
or<br />
<br />
rd.luks.options=''options''<br />
<br />
Set options for the device specified by it UUID or, if not specified, for all UUIDs not specified elsewhere (e.g., crypttab).<br />
<br />
This parameter is the analogue of [[#crypttab|crypttab's]] options field. The format is the same—options are separated by commas, options with values are specified using {{ic|1=''option''=''value''}}. This is roughly equivalent to the third parameter of {{ic|encrypt}}'s {{ic|cryptdevice}}.<br />
<br />
For example:<br />
<br />
rd.luks.options=timeout=10s,discard,password-echo=no,tries=1<br />
<br />
====== Timeout ======<br />
<br />
There are two options that affect the timeout for entering the password during boot:<br />
<br />
* {{ic|1=rd.luks.options=timeout=''mytimeout''}} specifies the timeout for querying for a password<br />
* {{ic|1=rootflags=x-systemd.device-timeout=''mytimeout''}} specifies how long systemd should wait for the rootfs device to show up before giving up (defaults to 90 seconds)<br />
<br />
If you want to disable the timeout altogether, then set both timeouts to zero:<br />
<br />
rd.luks.options=timeout=0 rootflags=x-systemd.device-timeout=0<br />
<br />
====== Password echo ======<br />
<br />
When the user is typing the password, ''systemd-cryptsetup'' by default outputs asterisks ({{ic|*}}) for each typed character. This is unlike the {{ic|encrypt}} hook, which does not output anything. To silence the output, set the {{ic|1=password-echo=no}} option:<br />
<br />
rd.luks.options=password-echo=no<br />
<br />
====== Trusted Platform Module ======<br />
<br />
If a TPM2 chip is available in your system, you can use it to automatically unlock your volume instead of using a password or a keyfile. Further information and detailed instructions on doing so can be found at [[Trusted Platform Module#Data-at-rest encryption with LUKS]].<br />
<br />
===== rd.luks.data =====<br />
<br />
When using a detached LUKS header, specify the block device with the encrypted data. Must be used together with {{ic|rd.luks.options}} to specify the header file location.<br />
<br />
See [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] for details and instructions.<br />
<br />
== Unlocking in late userspace ==<br />
<br />
=== crypttab ===<br />
<br />
The {{ic|/etc/crypttab}} (encrypted device table) file is similar to the [[fstab]] file and contains a list of encrypted devices to be unlocked during system boot up. This file can be used for automatically mounting encrypted swap devices or secondary file systems.<br />
<br />
{{ic|crypttab}} is read ''before'' {{ic|fstab}}, so that dm-crypt containers can be unlocked before the file system inside is mounted. Note that {{ic|crypttab}} is read ''after'' the system has booted up, therefore it is not a replacement for unlocking encrypted partitions by using [[#mkinitcpio|mkinitcpio]] hooks and [[#Kernel_parameters|configuring them by using kernel parameters]] as in the case of [[dm-crypt/Encrypting an entire system|encrypting the root partition]]. {{ic|crypttab}} processing at boot time is made by the {{ic|systemd-cryptsetup-generator}} automatically.<br />
<br />
See {{man|5|crypttab}} for details, read below for some examples, and the [[#Mounting at boot time]] section for instructions on how to use UUIDs to mount an encrypted device.<br />
<br />
{{Warning|<br />
* If the {{ic|nofail}} option is specified, the password entry screen may disappear while typing the password. {{ic|nofail}} should therefore only be used together with keyfiles.<br />
* For [[dm-crypt/Device encryption#Encryption options for plain mode|dm-crypt plain mode]] devices, the {{ic|plain}} option must be explicitly set to force {{ic|systemd-cryptsetup}} to recognize them. See [https://github.com/systemd/systemd/issues/442 systemd issue 442].<br />
}}<br />
<br />
{{hc|/etc/crypttab|2=<br />
# Example crypttab file. Fields are: name, underlying device, passphrase, cryptsetup options.<br />
<br />
# Mount /dev/lvm/swap re-encrypting it with a fresh key each reboot<br />
swap /dev/lvm/swap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
<br />
# Mount /dev/lvm/tmp as /dev/mapper/tmp using plain dm-crypt with a random passphrase, making its contents unrecoverable after it is dismounted.<br />
tmp /dev/lvm/tmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256 <br />
<br />
# Mount /dev/lvm/home as /dev/mapper/home using LUKS, and prompt for the passphrase at boot time.<br />
home /dev/lvm/home<br />
<br />
# Mount /dev/sdb1 as /dev/mapper/backup using LUKS, with a passphrase stored in a file.<br />
backup /dev/sdb1 /home/alice/backup.key<br />
}}<br />
<br />
To test your crypttab immediately after editing it, reload the systemd manager configuration with a [[daemon-reload]] and [[start]] the newly generated {{ic|systemd-cryptsetup@''name''.service}}.<br />
<br />
{{hc|# cryptsetup status ''name''|2=<br />
/dev/mapper/''name'' is active.<br />
type: ...<br />
cipher: ...<br />
keysize: ... bits<br />
key location: ...<br />
device: /dev/sdxN<br />
sector size: ...<br />
offset: ... sectors<br />
size: ... sectors<br />
mode: ...<br />
flags: ... <br />
}}<br />
<br />
For more on {{ic|systemd-cryptsetup@''name''.service}}, see [[#Mounting on demand]].<br />
<br />
{{Tip|If you use GPT and specific partition type UUIDs, you can avoid using crypttab and fstab for some mount points with systemd. For more information, see [[systemd#GPT partition automounting]].}}<br />
<br />
==== Mounting at boot time ====<br />
<br />
{{Merge|#crypttab|There is no need for two sections to explain the use of one file.}}<br />
<br />
If you want to mount an encrypted drive at boot time, enter the device's UUID in {{ic|/etc/crypttab}}. You get the UUID (partition) by using the command {{ic|lsblk -f}} and adding it to {{ic|crypttab}} in the form:<br />
<br />
{{hc|/etc/crypttab|2=<br />
externaldrive UUID=2f9a8428-ac69-478a-88a2-4aa458565431 none timeout=180<br />
}}<br />
<br />
The first parameter is your preferred device mapper's name for the encrypted drive. The option {{ic|none}} will trigger a prompt during boot to type the passphrase for unlocking the partition. The {{ic|timeout}} option defines a timeout in seconds for entering the decryption password during boot.<br />
<br />
{{Tip|Passwords entered in the password prompt are cached in the kernel keyring by {{man|8|systemd-cryptsetup}} (when [[#Using sd-encrypt hook|using the sd-encrypt hook]], this also includes passwords entered in the initramfs stage). If a device in {{ic|crypttab}} uses a previously entered password, the third parameter can be set to {{ic|none}} and the cached password will be automatically used.}}<br />
<br />
{{Note|Keep in mind that the {{ic|timeout}} option in {{ic|crypttab}} only determines the amount of time allowed for ''entering the password'' of the encrypted device. In addition, [[systemd]] also has a default timeout which determines the amount of time allowed for ''the device to be available'' (defaulting to 90 seconds), which is independent of the password timer. In consequence, even when the {{ic|timeout}} option in {{ic|crypttab}} is set to a value larger than 90 seconds (or it is at its default value of 0, meaning unlimited time), ''systemd'' will still only wait a maximum of 90 seconds for the device to be unlocked. In order to change the time ''systemd'' will wait for a device to be available, the option {{ic|x-systemd.device-timeout}} (see {{man|5|systemd.mount}}) can be set in [[fstab]] for said device. It is probably desired, then, that the amount of time of the {{ic|timeout}} option in {{ic|crypttab}} is equal to the amount of time of the {{ic|x-systemd.device-timeout}} option in {{ic|fstab}} for each device mounted at boot time.}}<br />
<br />
===== Unlocking with a keyfile =====<br />
<br />
If the [[dm-crypt/Device_encryption#Keyfiles|keyfile]] for a secondary file system is itself stored inside an encrypted root, it is safe while the system is powered off and can be sourced to automatically unlock the mount during with boot via [[#crypttab|crypttab]]. For example, unlock a crypt specified by [[UUID]]:<br />
<br />
{{hc|/etc/crypttab|2=<br />
home-crypt UUID=''UUID-identifier'' /etc/cryptsetup-keys.d/home-crypt.key<br />
}}<br />
<br />
{{Tip|<br />
* If a keyfile is not specified, {{man|8|systemd-cryptsetup}} will automatically try to load it from {{ic|/etc/cryptsetup-keys.d/''name''.key}} and {{ic|/run/cryptsetup-keys.d/''name''.key}}.[https://github.com/systemd/systemd/pull/15637]<br />
* If you prefer to use a {{ic|--plain}} mode blockdevice, the encryption options necessary to unlock it are specified in {{ic|/etc/crypttab}}. Take care to apply the systemd workaround mentioned in [[#crypttab|crypttab]] in this case.<br />
}}<br />
<br />
Then use the device mapper's name (defined in {{ic|/etc/crypttab}}) to make an entry in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home-crypt /home ext4 defaults 0 2<br />
}}<br />
<br />
Since {{ic|/dev/mapper/externaldrive}} already is the result of a unique partition mapping, there is no need to specify an UUID for it. In any case, the mapper with the filesystem will have a different UUID than the partition it is encrypted in.<br />
<br />
===== Mounting a stacked blockdevice =====<br />
<br />
The systemd generators also automatically process stacked block devices at boot. <br />
<br />
For example, you can create a [[RAID]] setup, use cryptsetup on it and create an [[LVM]] logical volume with respective filesystem inside the encrypted block device. A resulting: <br />
<br />
{{hc|$ lsblk -f|<br />
─sdXX linux_raid_member <br />
│ └─md0 crypto_LUKS <br />
│ └─cryptedbackup LVM2_member <br />
│ └─vgraid-lvraid ext4 /mnt/backup<br />
└─sdYY linux_raid_member <br />
└─md0 crypto_LUKS <br />
└─cryptedbackup LVM2_member <br />
└─vgraid-lvraid ext4 /mnt/backup<br />
}}<br />
<br />
will ask for the passphrase and mount automatically at boot. <br />
<br />
Given you specify the correct corresponding crypttab (e.g. UUID for the {{ic|crypto_LUKS}} device) and fstab ({{ic|/dev/vgraid/lvraid}}) entries, there is no need to add additional mkinitcpio hooks/configuration, because {{ic|/etc/crypttab}} processing applies to non-root mounts only. One exception is when the {{ic|mdadm_udev}} hook is used ''already'' (e.g. for the root device). In this case {{ic|/etc/madadm.conf}} and the initramfs need updating to achieve the correct root raid is picked first.<br />
<br />
==== Mounting on demand ====<br />
<br />
Instead of using<br />
<br />
# cryptsetup open UUID=... externaldrive<br />
<br />
you can [[start]] {{ic|systemd-cryptsetup@externaldrive.service}} when you have an entry as follows in your {{ic|/etc/crypttab}}:<br />
<br />
{{hc|/etc/crypttab|output=<br />
externaldrive UUID=... none noauto<br />
}}<br />
<br />
That way you do not need to remember the exact crypttab options. It will prompt you for the passphrase if needed.<br />
<br />
The corresponding unit file is generated automatically by {{man|8|systemd-cryptsetup-generator}}. You can list all generated unit files using:<br />
<br />
$ systemctl list-unit-files | grep systemd-cryptsetup<br />
<br />
== Troubleshooting ==<br />
<br />
=== System stuck on boot/password prompt does not show ===<br />
<br />
If you are using [[Plymouth]], make sure to use the correct modules (see: [[Plymouth#The plymouth hook]]) or disable it. Otherwise Plymouth will swallow the password prompt, making a system boot impossible.</div>PXfhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Device_encryption&diff=746501Dm-crypt/Device encryption2022-09-16T08:51:00Z<p>PXf: /* Conversion from LUKS1 to LUKS2 and back */ 2->16, not 16->2</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[es:Dm-crypt (Español)/Device encryption]]<br />
[[ja:Dm-crypt/デバイスの暗号化]]<br />
[[pl:Dm-crypt (Polski)/Device encryption]]<br />
[[pt:Dm-crypt (Português)/Device encryption]]<br />
[[zh-hans:Dm-crypt (简体中文)/Device encryption]]<br />
This section covers how to manually utilize ''dm-crypt'' from the command line to encrypt a system.<br />
<br />
== Preparation ==<br />
<br />
Before using {{pkg|cryptsetup}}, always make sure the {{ic|dm_crypt}} [[kernel module]] is loaded.<br />
<br />
== Cryptsetup usage ==<br />
<br />
''Cryptsetup'' is the command line tool to interface with ''dm-crypt'' for creating, accessing and managing encrypted devices. The tool was later expanded to support different encryption types that rely on the Linux kernel '''d'''evice-'''m'''apper and the '''crypt'''ographic modules. The most notable expansion was for the Linux Unified Key Setup (LUKS) extension, which stores all of the needed setup information for dm-crypt on the disk itself and abstracts partition and key management in an attempt to improve ease of use. Devices accessed via the device-mapper are called block devices. For further information see [[Data-at-rest encryption#Block device encryption]]. <br />
<br />
The tool is used as follows: <br />
<br />
# cryptsetup ''OPTIONS'' ''action'' ''action-specific-options'' ''device'' ''dmname''<br />
<br />
It has compiled-in defaults for the options and the encryption mode, which will be used if no others are specified on the command line. Have a look at <br />
<br />
$ cryptsetup --help <br />
<br />
which lists options, actions and the default parameters for the encryption modes in that order. A full list of options can be found on the man page.<br />
Since different parameters are required or optional, depending on encryption mode and action, the following sections point out differences further. Block device encryption is fast, but speed matters a lot too. Since changing an encryption cipher of a block device after setup is difficult, it is important to check ''dm-crypt'' performance for the individual parameters in advance: <br />
<br />
$ cryptsetup benchmark <br />
<br />
can give guidance on deciding for an algorithm and key-size prior to installation. If certain AES ciphers excel with a considerable higher throughput, these are probably the ones with hardware support in the CPU.<br />
<br />
{{Tip|You may want to practise encrypting a virtual hard drive in a [[virtual machine]] when learning.}}<br />
<br />
=== Cryptsetup passphrases and keys ===<br />
<br />
An encrypted block device is protected by a key. A key is either: <br />
<br />
* a passphrase: see [[Security#Passwords]].<br />
* a keyfile, see [[#Keyfiles]].<br />
<br />
Both key types have default maximum sizes: passphrases can be up to 512 characters and keyfiles up to 8192 KiB. <br />
<br />
An important distinction of ''LUKS'' to note at this point is that the key is used to unlock the master-key of a LUKS-encrypted device and can be changed with root access. Other encryption modes do not support changing the key after setup, because they do not employ a master-key for the encryption. See [[Data-at-rest encryption#Block device encryption]] for details.<br />
<br />
== Encryption options with dm-crypt ==<br />
<br />
''Cryptsetup'' supports different encryption operating modes to use with ''dm-crypt'': <br />
<br />
* {{ic|--type luks}} for using the default LUKS format version (LUKS1 with {{Pkg|cryptsetup}} < 2.1.0, LUKS2 with {{Pkg|cryptsetup}} ≥ 2.1.0),<br />
* {{ic|--type luks1}} for using LUKS1, the most common version of LUKS,<br />
* {{ic|--type luks2}} for using LUKS2, the latest available version of LUKS that allows additional extensions,<br />
* {{ic|--type plain}} for using dm-crypt plain mode, <br />
* {{ic|--type loopaes}} for a loopaes legacy mode, <br />
* {{ic|--type tcrypt}} for a [[TrueCrypt]] compatibility mode.<br />
* {{ic|--type bitlk}} for a [[Wikipedia:BitLocker|BitLocker]] compatibility mode. See {{man|8|cryptsetup|BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL)}}.<br />
<br />
The basic cryptographic options for encryption cipher and hashes available can be used for all modes and rely on the kernel cryptographic backend features. All that are loaded and available to use as options at runtime can be viewed with:<br />
<br />
$ less /proc/crypto <br />
<br />
{{Tip|If the list is short, execute {{ic|$ cryptsetup benchmark}} which will trigger loading available modules.}}<br />
<br />
The following introduces encryption options for the {{ic|luks}}, {{ic|luks1}}, {{ic|luks2}} and {{ic|plain}} modes. Note that the tables list options used in the respective examples in this article and not all available ones.<br />
<br />
=== Encryption options for LUKS mode ===<br />
<br />
The ''cryptsetup'' action to set up a new dm-crypt device in LUKS encryption mode is {{ic|luksFormat}}. Unlike what the name implies, it does not format the device, but sets up the LUKS device header and encrypts the master-key with the desired cryptographic options. <br />
<br />
In order to create a new LUKS container with the compiled-in defaults listed by {{ic|cryptsetup --help}}, simply execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
As of cryptsetup 2.4.0, this is equivalent to: <br />
<br />
# cryptsetup --type luks2 --cipher aes-xts-plain64 --hash sha256 --iter-time 2000 --key-size 256 --pbkdf argon2id --use-urandom --verify-passphrase luksFormat ''device''<br />
<br />
Defaults are compared with a cryptographically higher specification example in the table below, with accompanying comments: <br />
<br />
{| class="wikitable"<br />
! Options !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-xts-plain64}}<br />
| {{ic|aes-xts-plain64}}<br />
| [https://www.kernel.org/pub/linux/utils/cryptsetup/v1.6/v1.6.0-ReleaseNotes Release 1.6.0] changed the defaults to an AES [[Data-at-rest encryption#Ciphers and modes of operation|cipher]] in [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS]] mode (see item 5.16 [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects of the FAQ]). It is advised against using the previous default {{ic|--cipher aes-cbc-essiv}} because of its known [[wikipedia:Disk encryption theory#Cipher-block chaining (CBC)|issues]] and practical [https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ attacks] against them.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
| {{ic|256}} ({{ic|512}} for XTS)<br />
| {{ic|512}}<br />
| By default a 512 bit key-size is used for XTS ciphers. Note however that [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS splits the supplied key in half]], so this results in AES-256 being used.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|sha256}}<br />
| {{ic|sha512}}<br />
| Hash algorithm used for [[Data-at-rest encryption#Cryptographic metadata|key derivation]]. Release 1.7.0 changed defaults from {{ic|sha1}} to {{ic|sha256}} "''not for security reasons [but] mainly to prevent compatibility problems on hardened systems where SHA1 is already [being] phased out''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. The former default of {{ic|sha1}} can still be used for compatibility with older versions of ''cryptsetup'' since it is [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects considered secure] (see item 5.20). <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --iter-time<br />
-i<br />
| {{ic|2000}}<br />
| {{ic|5000}}<br />
| Number of milliseconds to spend with PBKDF2 passphrase processing. Release 1.7.0 changed defaults from {{ic|1000}} to {{ic|2000}} to "''try to keep PBKDF2 iteration count still high enough and also still acceptable for users.''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. This option is only relevant for LUKS operations that set or change passphrases, such as {{ic|luksFormat}} or {{ic|luksAddKey}}. Specifying 0 as parameter selects the compiled-in default..<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --use-urandom<br />
| {{ic|--use-urandom}}<br />
| {{ic|--use-random}}<br />
| Selects which [[random number generator]] to use. Note that [https://lwn.net/Articles/808575/ /dev/random blocking pool has been removed]. Therefore, {{ic|--use-random}} flag is now equivalent to {{ic|--use-urandom}}.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --verify-passphrase<br />
-y<br />
| Yes<br />
| -<br />
| Enabled by default in Arch Linux for {{ic|luksFormat}} and {{ic|luksAddKey}}.<br />
|}<br />
<br />
The properties of LUKS features and options are described in the [https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification LUKS1] (pdf) and [https://gitlab.com/cryptsetup/cryptsetup/blob/master/docs/on-disk-format-luks2.pdf LUKS2] (pdf) specifications.<br />
<br />
{{Tip|The project developers' [https://mbroz.fedorapeople.org/talks/DevConf2016/devconf2016-luks2.pdf devconfcz2016] (pdf) presentation summarizes the motivation for the major specification update to LUKS2.}}<br />
<br />
==== Iteration time ====<br />
<br />
From [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#2-setup cryptsetup FAQ§2.1] and [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#3-common-problems §3.4]:<br />
<br />
:The unlock time for a key-slot [...] is calculated when setting a passphrase. By default it is 1 second (2 seconds for LUKS2). [...]<br />
:Passphrase iteration count is based on time and hence security level depends on CPU power of the system the LUKS container is created on. [...]<br />
:If you set a passphrase on a fast machine and then unlock it on a slow machine, the unlocking time can be much longer.<br />
<br />
As such, it is better to always create a container on the machine where it will be most often accessed.<br />
<br />
Read the rest of those sections for advice on how to correctly adjust the iteration count should the need arise.<br />
<br />
==== Sector size ====<br />
<br />
See [[Advanced Format#dm-crypt]].<br />
<br />
=== Encryption options for plain mode ===<br />
<br />
In dm-crypt ''plain'' mode, there is no master-key on the device, hence, there is no need to set it up. Instead the encryption options to be employed are used directly to create the mapping between an encrypted disk and a named device. The mapping can be created against a partition or a full device. In the latter case not even a partition table is needed. <br />
<br />
To create a ''plain'' mode mapping with cryptsetup's default parameters: <br />
<br />
# cryptsetup ''options'' open --type plain ''device'' ''dmname''<br />
<br />
Executing it will prompt for a password, which should have very high entropy. Below a comparison of default parameters with the example in [[dm-crypt/Encrypting an entire system#Plain dm-crypt]].<br />
<br />
{| class="wikitable"<br />
! Option !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|ripemd160}}<br />
| -<br />
| The hash is used to create the key from the passphrase; it is not used on a keyfile. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-cbc-essiv:sha256}}<br />
| {{ic|aes-xts-plain64}}<br />
| The cipher consists of three parts: cipher-chainmode-IV generator. Please see [[Data-at-rest encryption#Ciphers and modes of operation]] for an explanation of these settings, and the [https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt DMCrypt documentation] for some of the options available. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
|{{ic|256}}<br />
|{{ic|512}}<br />
|The key size (in bits). The size will depend on the cipher being used and also the chainmode in use. Xts mode requires twice the key size of cbc. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --size<br />
-b<br />
|real size of target disk<br />
|{{ic|2048}} (mapped device will be 512B×2048=1MiB)<br />
|Limit the maximum size of the device (in 512-byte sectors).<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --offset<br />
-o<br />
|{{ic|0}}<br />
|{{ic|0}}<br />
|The offset from the beginning of the target disk (in 512-byte sectors) from which to start the mapping.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --skip<br />
-p<br />
|{{ic|0}}<br />
|{{ic|2048}} (512B×2048=1MiB will be skipped)<br />
|The number of 512-byte sectors of encrypted data to skip at the beginning.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-file<br />
-d<br />
| default uses a passphrase<br />
| {{ic|/dev/sd''Z''}} (or e.g. {{ic|/boot/keyfile.enc}})<br />
|The device or file to be used as a key. See [[#Keyfiles]] for further details.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-offset<br />
| {{ic|0}}<br />
| {{ic|0}}<br />
| Offset from the beginning of the file where the key starts (in bytes). This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-size<br />
-l<br />
|{{ic|8192kB}}<br />
| - (default applies)<br />
| Limits the bytes read from the key file. This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|}<br />
<br />
Using the device {{ic|/dev/sd''X''}}, the above right column example results in:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sd''Z'' --key-size=512 open --type=plain /dev/sdX enc<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, hash and key file details. We can now check that the mapping has been made:<br />
<br />
# fdisk -l<br />
<br />
An entry should now exist for {{ic|/dev/mapper/enc}}.<br />
<br />
== Encrypting devices with cryptsetup ==<br />
<br />
This section shows how to employ the options for creating new encrypted block devices and accessing them manually. <br />
<br />
{{Warning|GRUB's support for LUKS2 is limited; see [[GRUB#Encrypted /boot]] for details. Use LUKS1 ({{ic|1=cryptsetup luksFormat --type luks1}}) for partitions that GRUB will need to unlock.}}<br />
<br />
=== Encrypting devices with LUKS mode ===<br />
<br />
==== Formatting LUKS partitions ====<br />
<br />
In order to setup a partition as an encrypted LUKS partition execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
You will then be prompted to enter a password and verify it.<br />
<br />
See [[#Encryption options for LUKS mode]] for command line options.<br />
<br />
You can check the results with:<br />
<br />
# cryptsetup luksDump ''device''<br />
<br />
You will note that the dump not only shows the cipher header information, but also the key-slots in use for the LUKS partition. <br />
<br />
The following example will create an encrypted root partition on {{ic|/dev/sda1}} using the default AES cipher in XTS mode with an effective 256-bit encryption <br />
<br />
# cryptsetup -s 512 luksFormat /dev/sda1<br />
<br />
===== Using LUKS to format partitions with a keyfile =====<br />
<br />
When creating a new LUKS encrypted partition, a keyfile may be associated with the partition on its creation using:<br />
<br />
# cryptsetup luksFormat ''device'' ''/path/to/mykeyfile''<br />
<br />
See [[#Keyfiles]] for instructions on how to generate and manage keyfiles.<br />
<br />
==== Unlocking/Mapping LUKS partitions with the device mapper ====<br />
<br />
Once the LUKS partitions have been created, they can then be unlocked.<br />
<br />
The unlocking process will map the partitions to a new device name using the device mapper. This alerts the kernel that {{ic|''device''}} is actually an encrypted device and should be addressed through LUKS using the {{ic|/dev/mapper/''dm_name''}} so as not to overwrite the encrypted data. To guard against accidental overwriting, read about the possibilities to [[#Backup and restore|backup the cryptheader]] after finishing setup.<br />
<br />
In order to open an encrypted LUKS partition execute:<br />
<br />
# cryptsetup open ''device'' ''dm_name''<br />
<br />
You will then be prompted for the password to unlock the partition. Usually the device mapped name is descriptive of the function of the partition that is mapped. For example the following unlocks a root luks partition {{ic|/dev/sda1}} and maps it to device mapper named {{ic|root}}:<br />
<br />
# cryptsetup open /dev/sda1 root <br />
<br />
Once opened, the root partition device address would be {{ic|/dev/mapper/root}} instead of the partition (e.g. {{ic|/dev/sda1}}). <br />
<br />
For setting up LVM ontop the encryption layer the device file for the decrypted volume group would be anything like {{ic|/dev/mapper/root}} instead of {{ic|/dev/sda1}}. LVM will then give additional names to all logical volumes created, e.g. {{ic|/dev/lvmpool/root}} and {{ic|/dev/lvmpool/swap}}.<br />
<br />
In order to write encrypted data into the partition it must be accessed through the device mapped name. The first step of access will typically be to [[create a file system]]. For example:<br />
<br />
# mkfs -t ext4 /dev/mapper/root<br />
<br />
The device {{ic|/dev/mapper/root}} can then be [[mount]]ed like any other partition.<br />
<br />
To close the LUKS container, unmount the partition and do:<br />
<br />
# cryptsetup close root<br />
<br />
==== Using a TPM to store keys ====<br />
<br />
See [[Trusted Platform Module#Data-at-rest encryption with LUKS]].<br />
<br />
=== Encrypting devices with plain mode ===<br />
<br />
The creation and subsequent access of a ''dm-crypt'' plain mode encryption both require not more than using the ''cryptsetup'' {{ic|open}} action with correct [[#Encryption options for plain mode|parameters]]. The following shows that with two examples of non-root devices, but adds a quirk by stacking both (i.e. the second is created inside the first). Obviously, stacking the encryption doubles overhead. The usecase here is simply to illustrate another example of the cipher option usage. <br />
<br />
A first mapper is created with ''cryptsetup's'' plain-mode defaults, as described in the table's left column above <br />
<br />
{{hc|# cryptsetup --type plain -v open /dev/sdaX plain1|<br />
Enter passphrase: <br />
Command successful.<br />
}}<br />
<br />
Now we add the second block device inside it, using different encryption parameters and with an (optional) offset, create a file system and mount it <br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
/dev/sda <br />
├─/dev/sdaX <br />
│ └─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
# mkfs -t ext2 /dev/mapper/plain2<br />
# mount -t ext2 /dev/mapper/plain2 /mnt<br />
# echo "This is stacked. one passphrase per foot to shoot." > /mnt/stacked.txt<br />
<br />
We close the stack to check access works<br />
<br />
# cryptsetup close plain2<br />
# cryptsetup close plain1<br />
<br />
First, let us try to open the file system directly: <br />
<br />
# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/sdaX plain2<br />
<br />
{{hc|# mount -t ext2 /dev/mapper/plain2 /mnt|<br />
mount: wrong fs type, bad option, bad superblock on /dev/mapper/plain2,<br />
missing codepage or helper program, or other error<br />
}}<br />
<br />
Why that did not work? Because the "plain2" starting block ({{ic|10}}) is still encrypted with the cipher from "plain1". It can only be accessed via the stacked mapper. The error is arbitrary though, trying a wrong passphrase or wrong options will yield the same. For ''dm-crypt'' plain mode, the {{ic|open}} action will not error out itself. <br />
<br />
Trying again in correct order: <br />
<br />
# cryptsetup close plain2 # dysfunctional mapper from previous try<br />
<br />
{{hc|# cryptsetup --type plain open /dev/sdaX plain1|<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# mount /dev/mapper/plain2 /mnt && cat /mnt/stacked.txt|<br />
This is stacked. one passphrase per foot to shoot.<br />
}}<br />
<br />
''dm-crypt'' will handle stacked encryption with some mixed modes too. For example LUKS mode could be stacked on the "plain1" mapper. Its header would then be encrypted inside "plain1" when that is closed.<br />
<br />
Available for plain mode only is the option {{ic|--shared}}. With it a single device can be segmented into different non-overlapping mappers. We do that in the next example, using a ''loopaes'' compatible cipher mode for "plain2" this time: <br />
<br />
{{hc|# cryptsetup --type plain --offset 0 --size 1000 open /dev/sdaX plain1|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --offset 1000 --size 1000 --shared --cipher=aes-cbc-lmk --hash=sha256 open /dev/sdaX plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
dev/sdaX <br />
├─/dev/sdaX <br />
│ ├─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
As the device tree shows both reside on the same level, i.e. are not stacked and "plain2" can be opened individually.<br />
<br />
== Cryptsetup actions specific for LUKS ==<br />
<br />
=== Key management ===<br />
<br />
It is possible to define additional keys for the LUKS partition. This enables the user to create access keys for safe backup storage In so-called key escrow, one key is used for daily usage, another kept in escrow to gain access to the partition in case the daily passphrase is forgotten or a keyfile is lost/damaged. A different key-slot could also be used to grant access to a partition to a user by issuing a second key and later revoking it again. <br />
<br />
Once an encrypted partition has been created, the initial keyslot 0 is created (if no other was specified manually). Additional keyslots are numbered from 1 to 7. Which keyslots are used can be seen by issuing <br />
<br />
# cryptsetup luksDump /dev/''device''<br />
<br />
Where {{ic|''device''}} is the block device containing the LUKS header. This and all the following commands in this section work on header backup files as well.<br />
<br />
==== Adding LUKS keys ====<br />
<br />
Adding new keyslots is accomplished with the {{ic|luksAddKey}} action. For safety it will always, even for already unlocked devices, ask for a valid existing key (a passphrase for any existing slot) before a new one may be entered:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' [''/path/to/additionalkeyfile'']|<br />
Enter any passphrase:<br />
Enter new passphrase for key slot:<br />
Verify passphrase: <br />
}}<br />
<br />
If {{ic|''/path/to/additionalkeyfile''}} is given, cryptsetup will add a new keyslot for {{ic|''additionalkeyfile''}}. Otherwise it prompts for a new passphrase. To authorize the action with an existing ''keyfile'', the {{ic|--key-file}} or {{ic|-d}} option followed by the "old" {{ic|''keyfile''}} will try to unlock all available keyfile keyslots:<br />
<br />
# cryptsetup luksAddKey /dev/''device'' [''/path/to/additionalkeyfile''] -d ''/path/to/keyfile''<br />
<br />
If it is intended to use multiple keys and change or revoke them, the {{ic|--key-slot}} or {{ic|-S}} option may be used to specify the slot: <br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' -S 6|<br />
Enter any passphrase: <br />
Enter new passphrase for key slot: <br />
Verify passphrase:<br />
}}<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: ENABLED<br />
}}<br />
<br />
To show an associated action in this example, we decide to change the key right away: <br />
<br />
{{hc|# cryptsetup luksChangeKey /dev/''device'' -S 6|<br />
Enter LUKS passphrase to be changed: <br />
Enter new LUKS passphrase:<br />
}}<br />
<br />
before continuing to remove it.<br />
<br />
==== Removing LUKS keys ====<br />
<br />
There are three different actions to remove keys from the header: <br />
<br />
* {{ic|luksRemoveKey}} removes a key by specifying its passphrase/key-file. <br />
* {{ic|luksKillSlot}} removes a key by specifying its slot (needs another valid key). Obviously, this is extremely useful if you have forgotten a passphrase, lost a key-file, or have no access to it. <br />
* {{ic|luksErase}} removes '''all''' active keys. <br />
<br />
{{warning|<br />
* All above actions can be used to irrevocably delete the last active key for an encrypted device! <br />
* The {{ic|luksErase}} command was added in version 1.6.4 to quickly nuke access to the device. This action '''will not''' prompt for a valid passphrase! It will not [[dm-crypt/Drive preparation#Wipe LUKS header|wipe the LUKS header]], but all keyslots at once and you will, therefore, not be able to regain access unless you have a valid backup of the LUKS header.<br />
}}<br />
<br />
For above warning it is good to know the key we want to '''keep''' is valid. An easy check is to unlock the device with the {{ic|-v}} option, which will specify which slot it occupies: <br />
<br />
{{hc|# cryptsetup --test-passphrase -v open /dev/''device''|<br />
Enter passphrase for /dev/''device'': <br />
Key slot 1 unlocked.<br />
Command successful.<br />
}}<br />
<br />
Now we can remove the key added in the previous subsection using its passphrase: <br />
<br />
{{hc|# cryptsetup luksRemoveKey /dev/''device''|<br />
Enter LUKS passphrase to be deleted:<br />
}}<br />
<br />
If we had used the same passphrase for two keyslots, the first slot would be wiped now. Only executing it again would remove the second one. <br />
<br />
Alternatively, we can specify the key slot: <br />
<br />
{{hc|# cryptsetup luksKillSlot /dev/''device'' 6|<br />
Enter any remaining LUKS passphrase:<br />
}}<br />
<br />
Note that in both cases, no confirmation was required.<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: DISABLED<br />
}}<br />
<br />
To re-iterate the warning above: If the same passphrase had been used for key slots 1 and 6, both would be gone now.<br />
<br />
=== Backup and restore ===<br />
<br />
If the header of a LUKS encrypted partition gets destroyed, you will not be able to decrypt your data. It is just as much of a dilemma as forgetting the passphrase or damaging a key-file used to unlock the partition. Damage may occur by your own fault while re-partitioning the disk later or by third-party programs misinterpreting the partition table. Therefore, having a backup of the header and storing it on another disk might be a good idea.<br />
<br />
{{Note|If one of the LUKS-encrypted partitions' passphrases becomes compromised, you must revoke it on ''every'' copy of the cryptheader, even those you have backed up. Otherwise, a copy of the backed-up cryptheader that uses the compromised passphrase can be used to determine the master key which in turn can be used to decrypt the associated partition (even your actual partition, not only the backed-up version). On the other hand, if the master key gets compromised, you have to reencrypt your whole partition. See [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#6-backup-and-data-recovery LUKS FAQ] for further details.}}<br />
<br />
==== Backup using cryptsetup ====<br />
<br />
Cryptsetup's {{ic|luksHeaderBackup}} action stores a binary backup of the LUKS header and keyslot area:<br />
<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file ''/mnt/backup/file.img''<br />
<br />
where {{ic|''device''}} is the partition containing the LUKS volume.<br />
<br />
You can also back up the plain text header into ramfs and encrypt it with e.g. [[GPG]] before writing it to persistent storage:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/''tmp''<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file /root/''tmp''/''file''.img<br />
# gpg2 --recipient ''User_ID'' --encrypt /root/''tmp''/''file''.img <br />
# cp /root/''tmp''/''file''.img.gpg /mnt/''backup''/<br />
# umount /root/''tmp''<br />
<br />
{{Warning|[[tmpfs]] can swap to the disk in low memory situations, so it is not recommended here.}}<br />
<br />
==== Restore using cryptsetup ====<br />
<br />
{{Warning|Restoring the wrong header or restoring to an unencrypted partition will cause data loss! The action can not perform a check whether the header is actually the ''correct'' one for that particular device.}} <br />
<br />
In order to evade restoring a wrong header, you can ensure it does work by using it as a remote {{ic|--header}} first: <br />
<br />
{{hc|# cryptsetup -v --header /mnt/''backup''/''file''.img open /dev/''device'' test|<br />
Key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
# mount /dev/mapper/test /mnt/test && ls /mnt/test <br />
# umount /mnt/test <br />
# cryptsetup close test <br />
<br />
Now that the check succeeded, the restore may be performed: <br />
<br />
# cryptsetup luksHeaderRestore /dev/''device'' --header-backup-file ./mnt/''backup''/''file''.img<br />
<br />
Now that all the keyslot areas are overwritten; only active keyslots from the backup file are available after issuing the command.<br />
<br />
==== Manual backup and restore ====<br />
<br />
The header always resides at the beginning of the device and a backup can be performed without access to ''cryptsetup'' as well. First you have to find out the payload offset of the crypted partition:<br />
<br />
{{hc|# cryptsetup luksDump /dev/''device'' {{!}} grep "Payload offset"|<br />
Payload offset: 4040<br />
}}<br />
<br />
Second check the sector size of the drive<br />
<br />
{{hc|# fdisk -l /dev/''device'' {{!}} grep "Sector size"|<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
}}<br />
<br />
Now that you know the values, you can backup the header with a simple [[dd]] command:<br />
<br />
# dd if=/dev/''device'' of=/path/to/''file''.img bs=512 count=4040<br />
<br />
and store it safely.<br />
<br />
A restore can then be performed using the same values as when backing up:<br />
<br />
# dd if=./''file''.img of=/dev/''device'' bs=512 count=4040<br />
<br />
=== Re-encrypting devices ===<br />
<br />
{{Expansion|cryptsetup 2.2 using LUKS2 (with a 16 MiB header) supports online encryption/decryption/reencryption.[https://mirrors.edge.kernel.org/pub/linux/utils/cryptsetup/v2.2/v2.2.0-ReleaseNotes]}}<br />
<br />
{{Out of date|cryptsetup-reencrypt was removed in cryptsetup 2.5.0.[https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/v2.5.0-ReleaseNotes]}}<br />
<br />
The {{Pkg|cryptsetup}} package features two options for re-encryption.<br />
<br />
; cryptsetup reencrypt: Argument to {{ic|cryptsetup}} itself: Preferred method. Currently LUKS2 devices only. Actions can be performed online. Supports multiple parallel re-encryption jobs. Resilient to system failures. See {{man|8|cryptsetup}} for more information.<br />
<br />
; cryptsetup-reencrypt: Legacy tool, supports LUKS1 in addition to LUKS2. Actions can be performed on unmounted devices only. Single process at a time. Sensitive to system failures. See {{man|8|cryptsetup-reencrypt}} for more information. <br />
<br />
Both can be used to convert an existing unencrypted file system to a LUKS encrypted one or permanently remove LUKS encryption from a device (using {{ic|--decrypt}}). As its name suggests it can also be used to re-encrypt an existing LUKS encrypted device, though, re-encryption is not possible for a detached LUKS header or other encryption modes (e.g. plain-mode). For re-encryption it is possible to change the [[#Encryption options for LUKS mode]]. <br />
<br />
One application of re-encryption may be to secure the data again after a passphrase or [[#Keyfiles|keyfile]] has been compromised ''and'' one cannot be certain that no copy of the LUKS header has been obtained. For example, if only a passphrase has been shoulder-surfed but no physical/logical access to the device happened, it would be enough to change the respective passphrase/key only ([[#Key management]]). <br />
<br />
{{Warning|Always make sure a '''reliable backup''' is available and double-check options you specify before using the tool!}}<br />
<br />
The following shows an example to encrypt an unencrypted file system partition and a re-encryption of an existing LUKS device.<br />
<br />
==== Encrypt an existing unencrypted file system ====<br />
<br />
{{Tip|If you are trying to encrypt an existing root partition, you might want to create a separate and unencrypted boot partition which will be mounted to {{ic|/boot}} (see [[Dm-crypt/Encrypting an entire system#Preparing the boot partition]]). It is not strictly necessary but has a number of advantages:<br />
<br />
* If {{ic|/boot}} is located inside an encrypted root partition, the system will ask for the passphrase twice when the machine is powered on. The first time will happen when the boot loader attempts to read the files located inside encrypted {{ic|/boot}}, the second time will be when the kernel tries to mount the encrypted partition [https://opencraft.com/blog/tutorial-encrypting-an-existing-root-partition-in-ubuntu-with-dm-crypt-and-luks/]. This might not be the desired behaviour and can be prevented by having a separate and unencryted boot partition.<br />
* Some system restore applications (e.g., {{AUR|timeshift}}) will not work if {{ic|/boot}} is located inside an encryted partition [https://github.com/teejee2008/timeshift/issues/280].<br />
<br />
In short, create a partition with the size of at least 260 MiB if needed. See [[Partitioning#/boot]].}}<br />
<br />
A LUKS encryption header is always stored at the beginning of the device. Since an existing file system will usually be allocated all partition sectors, the first step is to shrink it to make space for the LUKS header.<br />
<br />
{{Expansion|cryptsetup man pages suggest using twice the LUKS2 header size. That implies 32 MiB and using {{ic|--reduce-device-size 32M}}}}<br />
<br />
The [[#Encryption options for LUKS mode|default]] LUKS2 header requires 16 MiB. If the current file system occupies all the available space, we will have to shrink it at least that much. To shrink an existing {{ic|ext4}} file system on {{ic|/dev/sdaX}} to its current possible minimum:<br />
<br />
# umount /mnt<br />
<br />
{{hc|# e2fsck -f /dev/sdaX|<br />
e2fsck 1.43-WIP (18-May-2015)<br />
Pass 1: Checking inodes, blocks, and sizes<br />
...<br />
/dev/sda6: 12/166320 files (0.0% non-contiguous), 28783/665062 blocks<br />
}}<br />
<br />
{{hc|# resize2fs -p -M /dev/sdaX|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/sdaX to 26347 (4k) blocks.<br />
The filesystem on /dev/sdaX is now 26347 (4k) blocks long.<br />
}}<br />
<br />
{{Tip|Shrinking to the minimum size with {{ic|-M}} might take very long. You might want to calculate a size just 32 MiB smaller than the current size instead of using {{ic|-M}}.}}<br />
<br />
{{Warning|The file system should be shrunk while the underlying device (e.g., a partition) should be kept at its original size. Some graphical tools (e.g., [[GParted]]) may resize both the file system and the partition, and data loss may occur after encryption.}}<br />
<br />
Now we encrypt it, using the default cipher we do not have to specify it explicitly:<br />
<br />
{{hc|# cryptsetup reencrypt --encrypt --reduce-device-size 16M /dev/sdaX|<nowiki><br />
<br />
WARNING!<br />
<br />
========<br />
<br />
This will overwrite data on LUKS2-temp-12345678-9012-3456-7890-123456789012.new irrevocably.<br />
<br />
Are you sure? (Type 'yes' in capital letters): YES<br />
Enter passphrase for LUKS2-temp-12345678-9012-3456-7890-123456789012.new: <br />
Verify passphrase: <br />
</nowiki>}}<br />
<br />
After it finished, the whole {{ic|/dev/sdaX}} partition is encrypted, not only the space the file system was shrunk to. As a final step we extend the original {{ic|ext4}} file system to occupy all available space again, on the now encrypted partition:<br />
<br />
{{hc|# cryptsetup open /dev/sdaX recrypt|<br />
Enter passphrase for /dev/sdaX: <br />
...<br />
}}<br />
<br />
{{hc|# resize2fs /dev/mapper/recrypt|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/mapper/recrypt to 664807 (4k) blocks.<br />
The filesystem on /dev/mapper/recrypt is now 664807 (4k) blocks long.<br />
}}<br />
<br />
# mount /dev/mapper/recrypt /mnt<br />
<br />
The file system is now ready to use. You may want to add it to your [[crypttab]].<br />
<br />
{{Tip|If you have just encrypted your root partition, you might need to perform a number of post-encryption adjustments.<br />
<br />
See [[Dm-crypt/Encrypting an entire system#Configuring mkinitcpio]], [[Dm-crypt/Encrypting an entire system#Configuring the boot loader]], and [[Dm-crypt/Encrypting an entire system#Configuring GRUB]].}}<br />
<br />
==== Re-encrypting an existing LUKS partition ====<br />
<br />
In this example an existing LUKS device is re-encrypted. <br />
<br />
{{Warning|Double-check you specify encryption options for correctly and ''never'' re-encrypt without a '''reliable backup'''!}}<br />
<br />
In order to re-encrypt a device with its existing encryption options, they do not need to be specified:<br />
{{bc|# cryptsetup reencrypt /dev/sdaX}}<br />
{{Note|For LUKS1 we will need to use the legacy tool:{{bc|# cryptsetup-reencrypt /dev/sdaX}}}}<br />
<br />
Existing keys are retained when re-encrypting a device with a different cipher and/or hash. Another use case is to re-encrypt LUKS devices which have non-current encryption options. Apart from above warning on specifying options correctly, the ability to change the LUKS header may also be limited by its size. For example, if the device was initially encrypted using a CBC mode cipher and 128 bit key-size, the LUKS header will be half the size of above mentioned {{ic|4096}} sectors: <br />
<br />
{{hc|# cryptsetup luksDump /dev/sdaX {{!}} grep -e "mode" -e "Payload" -e "MK bits"|<br />
Cipher mode: cbc-essiv:sha256<br />
Payload offset: '''2048'''<br />
MK bits: 128<br />
}}<br />
<br />
While it is possible to upgrade the encryption of such a device, it is currently only feasible in two steps. First, re-encrypting with the same encryption options, but using the {{ic|--reduce-device-size}} option to make further space for the larger LUKS header. Second, re-encypt the whole device again with the desired cipher. For this reason and the fact that a backup should be created in any case, creating a new, fresh encrypted device to restore into is always the faster option.<br />
<br />
=== Conversion from LUKS1 to LUKS2 and back ===<br />
<br />
The {{Pkg|cryptsetup}} package has {{ic|convert}} option that needed for conversion between LUKS1 and LUKS2 container types. The argument {{ic|--type}} is '''required'''.<br />
<br />
Migration from LUKS1 to LUKS2:<br />
<br />
# cryptsetup convert --type luks2 /dev/sdaX<br />
<br />
{{Note|The LUKS header size will be 16 MiB instead of 2 MiB.}}<br />
<br />
Rollback to LUKS1 (for example, to boot from [[GRUB#Encrypted /boot|GRUB with encrypted /boot]]):<br />
<br />
# cryptsetup convert --type luks1 /dev/sdaX<br />
<br />
{{Note|Conversion from LUKS2 to LUKS1 is '''not''' always possible. You may get the following error:<br />
Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible.<br />
}}<br />
<br />
== Resizing encrypted devices ==<br />
<br />
{{Expansion|This section should be rewritten to introduce resizing more generically. Perhaps work on it together with [[Resizing LVM-on-LUKS]].}}<br />
<br />
If a storage device encrypted with dm-crypt is being cloned (with a tool like dd) to another larger device, the underlying dm-crypt device must be resized to use the whole space. <br />
<br />
The destination device is /dev/sdX2 in this example, the whole available space adjacent to the partition will be used:<br />
<br />
# cryptsetup luksOpen /dev/sdX2 sdX2<br />
# cryptsetup resize sdX2<br />
<br />
Then the underlying file system must be resized.<br />
<br />
=== Loopback file system ===<br />
<br />
Assume that an encrypted loopback file system is stored in a file {{ic|/bigsecret}}, looped to {{ic|/dev/loop0}}, mapped to {{ic|secret}} and mounted on {{ic|/mnt/secret}}, as in the example at [[dm-crypt/Encrypting a non-root file system#File container]].<br />
<br />
If the container file is currently mapped and/or mounted, unmount and/or close it:<br />
<br />
# umount /mnt/secret<br />
# cryptsetup close secret<br />
# losetup -d /dev/loop0<br />
<br />
Next, expand the container file with the size of the data you want to add. In this example, the file will be expanded with 1M * 1024, which is 1G.<br />
<br />
{{Warning|Make absolutely sure to use '''two''' {{ic|>}}, instead of just one, or else you will overwrite the file instead of appending to it. Making a backup before this step is strongly recommended.}}<br />
<br />
# dd if=/dev/urandom bs=1M count=1024 | cat - >> /bigsecret<br />
<br />
Now map the container to the loop device:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
# cryptsetup open /dev/loop0 secret<br />
<br />
After this, resize the encrypted part of the container to the new maximum size of the container file:<br />
<br />
# cryptsetup resize secret<br />
<br />
Finally, perform a file system check and, if it is ok, resize it (example for ext2/3/4):<br />
<br />
# e2fsck -f /dev/mapper/secret<br />
# resize2fs /dev/mapper/secret<br />
<br />
You can now mount the container again:<br />
<br />
# mount /dev/mapper/secret /mnt/secret<br />
<br />
=== Integrity protected device ===<br />
<br />
If the device was formatted with integrity support (e.g., {{ic|--integrity hmac-sha256}}) and the backing block device is shrinked, it cannot be opened with this error: {{ic|device-mapper: reload ioctl on failed: Invalid argument}}.<br />
<br />
To fix this issue without wiping the device again, it can be formatted with the previous master key (keeping the per-sector tags valid).<br />
<br />
# cryptsetup luksDump /dev/sdX2 --dump-master-key --master-key-file=/tmp/masterkey-in-tmpfs.key<br />
# cryptsetup luksFormat /dev/sdX2 --type luks2 --integrity hmac-sha256 --master-key-file=/tmp/masterkey-in-tmpfs.key --integrity-no-wipe<br />
# rm /tmp/masterkey-in-tmpfs.key<br />
<br />
== Keyfiles ==<br />
<br />
{{Note|This section describes using a plaintext keyfile. If you want to encrypt your keyfile giving you two factor authentication see [[dm-crypt/Specialties#Using GPG, LUKS, or OpenSSL Encrypted Keyfiles|Using GPG or OpenSSL Encrypted Keyfiles]] for details, but please still read this section.}}<br />
<br />
'''What is a keyfile?'''<br />
<br />
A keyfile is a file whose data is used as the passphrase to unlock an encrypted volume.<br />
That means if such a file is lost or changed, decrypting the volume may no longer be possible.<br />
<br />
{{Tip|Define a passphrase in addition to the keyfile for backup access to encrypted volumes in the event the defined keyfile is lost or changed.}}<br />
<br />
'''Why use a keyfile?'''<br />
<br />
There are many kinds of keyfiles. Each type of keyfile used has benefits and disadvantages summarized below:<br />
<br />
=== Types of keyfiles ===<br />
<br />
==== passphrase ====<br />
<br />
This is a keyfile containing a simple passphrase. The benefit of this type of keyfile is that if the file is lost the data it contained is known and hopefully easily remembered by the owner of the encrypted volume. However the disadvantage is that this does not add any security over entering a passphrase during the initial system start.<br />
<br />
Example: {{ic|1234}}<br />
<br />
{{Note|The keyfile containing the passphrase must not have a newline in it. One option is to create it using <br />
<br />
# echo -n 'your_passphrase' > ''/path/to/keyfile''<br />
# chown root:root ''/path/to/keyfile''; chmod 400 ''/path/to/keyfile''<br />
<br />
If the file contains special characters such as a backslash, rather than escaping these, it is recommended to simply edit the key file directly entering or pasting the passphrase and then remove the trailing newline with a handy perl one-liner:<br />
<br />
# perl -pi -e 'chomp if eof' ''/path/to/keyfile''<br />
}}<br />
<br />
==== randomtext ====<br />
<br />
This is a keyfile containing a block of random characters. The benefit of this type of keyfile is that it is much more resistant to dictionary attacks than a simple passphrase. An additional strength of keyfiles can be utilized in this situation which is the length of data used. Since this is not a string meant to be memorized by a person for entry, it is trivial to create files containing thousands of random characters as the key. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase.<br />
<br />
Example: {{ic|fjqweifj830149-57 819y4my1-38t1934yt8-91m 34co3;t8y;9p3y-}}<br />
<br />
==== binary ====<br />
<br />
This is a binary file that has been defined as a keyfile. When identifying files as candidates for a keyfile, it is recommended to choose files that are relatively static such as photos, music, video clips. The benefit of these files is that they serve a dual function which can make them harder to identify as keyfiles. Instead of having a text file with a large amount of random text, the keyfile would look like a regular image file or music clip to the casual observer. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase. Additionally, there is a theoretical loss of randomness when compared to a randomly generated text file. This is due to the fact that images, videos and music have some intrinsic relationship between neighboring bits of data that does not exist for a random text file. However this is controversial and has never been exploited publicly.<br />
<br />
Example: images, text, video, ...<br />
<br />
=== Creating a keyfile with random characters ===<br />
<br />
==== Storing the keyfile on a file system ====<br />
<br />
A keyfile can be of arbitrary content and size. <br />
<br />
Here [[dd]] is used to generate a keyfile of 2048 random bytes, storing it in the file {{ic|/etc/mykeyfile}}:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/etc/mykeyfile iflag=fullblock<br />
<br />
If you are planning to store the keyfile on an external device, you can also simply change the outputfile to the corresponding directory:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/media/usbstick/mykeyfile iflag=fullblock<br />
<br />
To deny any access for other users than {{ic|root}}:<br />
<br />
# chmod 600 /etc/mykeyfile<br />
<br />
===== Securely overwriting stored keyfiles =====<br />
<br />
If you stored your temporary keyfile on a physical storage device, and want to delete it, remember to not just remove the keyfile later on, but use something like<br />
<br />
# shred --remove --zero mykeyfile<br />
<br />
to securely overwrite it. For overaged file systems like FAT or ext2 this will suffice while in the case of journaling file systems, flash memory hardware and other cases it is highly recommended to [[Securely wipe disk|wipe the entire device]].<br />
<br />
==== Storing the keyfile in ramfs ====<br />
<br />
Alternatively, you can mount a ramfs for storing the keyfile temporarily:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/myramfs<br />
# cd /root/myramfs<br />
<br />
The advantage is that it resides in RAM and not on a physical disk, therefore it can not be recovered after unmounting the ramfs. After copying the keyfile to another secure and persistent file system, unmount the ramfs again with<br />
<br />
# umount /root/myramfs<br />
<br />
=== Configuring LUKS to make use of the keyfile ===<br />
<br />
Add a keyslot for the keyfile to the LUKS header:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/sda2 /etc/mykeyfile|<br />
Enter any LUKS passphrase:<br />
key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
=== Manually unlocking a partition using a keyfile ===<br />
<br />
Use the {{ic|--key-file}} option when opening the LUKS device:<br />
<br />
# cryptsetup open /dev/sda2 ''dm_name'' --key-file /etc/mykeyfile<br />
<br />
=== Unlocking the root partition at boot ===<br />
<br />
This is simply a matter of configuring [[mkinitcpio]] to include the necessary modules or files and configuring the [[dm-crypt/System configuration#cryptkey|cryptkey]] [[kernel parameter]] to know where to find the keyfile.<br />
<br />
Two cases are covered below:<br />
<br />
# Using a keyfile stored on an external medium (e.g. a USB stick)<br />
# Using a keyfile embedded in the initramfs<br />
<br />
==== With a keyfile stored on an external media ====<br />
<br />
===== Configuring mkinitcpio =====<br />
<br />
You have to add the kernel module for the drive's [[file system]] to the [[mkinitcpio#MODULES|MODULES array]] in {{ic|/etc/mkinitcpio.conf}}. For example, add {{ic|ext4}} if the file system is [[Ext4]] or {{ic|vfat}} in case it is [[FAT]]:<br />
<br />
MODULES=(vfat)<br />
<br />
If there are messages about bad superblock and bad codepage at boot, then you need an extra codepage module to be loaded. For instance, you may need {{ic|nls_iso8859-1}} module for {{ic|iso8859-1}} codepage.<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
===== Configuring the kernel parameters =====<br />
<br />
* For a busybox-based initramfs using the [[dm-crypt/System configuration#Using encrypt hook|encrypt]] hook, see [[dm-crypt/System configuration#cryptkey]].<br />
* For a systemd based initramfs using the [[sd-encrypt]] hook, see [[dm-crypt/System configuration#rd.luks.key]].<br />
<br />
==== With a keyfile embedded in the initramfs ====<br />
<br />
{{Warning|Use an embedded keyfile '''only''' if you protect the keyfile sufficiently by:<br />
* Using some form of authentication earlier in the boot process. Otherwise auto-decryption will occur, defeating completely the purpose of block device encryption.<br />
* {{ic|/boot}} is encrypted. Otherwise root on a different installation (including the [[Installation guide#Boot the live environment|live environment]]) can extract your key from the initramfs, and unlock the device without any other authentication.}}<br />
<br />
This method allows to use a specially named keyfile that will be embedded in the [[initramfs]] and picked up by the {{ic|encrypt}} [[Mkinitcpio#HOOKS|hook]] to unlock the root file system ({{ic|cryptdevice}}) automatically. It may be useful to apply when using the [[GRUB#Encrypted /boot|GRUB early cryptodisk]] feature, in order to avoid entering two passphrases during boot.<br />
<br />
The {{ic|encrypt}} hook lets the user specify a keyfile with the {{ic|cryptkey}} kernel parameter: in the case of initramfs, the syntax is {{ic|rootfs:''/path/to/keyfile''}}. See [[dm-crypt/System configuration#cryptkey]]. Besides, this kernel parameter defaults to use {{ic|/crypto_keyfile.bin}}, and if the initramfs contains a valid key with this name, decryption will occur automatically without the need to configure the {{ic|cryptkey}} parameter.<br />
<br />
If using {{ic|sd-encrypt}} instead of {{ic|encrypt}}, specify the location of the keyfile with the {{ic|rd.luks.key}} kernel parameter: in the case of initramfs, the syntax is {{ic|''/path/to/keyfile''}}. See [[dm-crypt/System configuration#rd.luks.key]]. This kernel parameter defaults to using {{ic|/etc/cryptsetup-keys.d/''name''.key}} (where {{ic|''name''}} is the {{ic|''dm_name''}} used for decryption in [[#Encrypting devices with cryptsetup]]) and can be omitted if initramfs contains a valid key with this path.<br />
<br />
[[#Creating a keyfile with random characters|Generate the keyfile]], give it suitable permissions and [[#Adding LUKS keys|add it as a LUKS key]]:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/crypto_keyfile.bin iflag=fullblock<br />
# chmod 600 /crypto_keyfile.bin<br />
# cryptsetup luksAddKey /dev/sdX# /crypto_keyfile.bin<br />
<br />
{{Note|The initramfs is generated by mkinitcpio with {{ic|600}} [[permissions]] by default, so regular users are not able to read the keyfile via the generated initramfs.}}<br />
<br />
Include the key in [[mkinitcpio#BINARIES and FILES|mkinitcpio's FILES array]]:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/crypto_keyfile.bin)<br />
}}<br />
<br />
Finally [[regenerate the initramfs]].<br />
<br />
On the next reboot you should only have to enter your container decryption passphrase once.<br />
<br />
([https://www.pavelkogan.com/2014/05/23/luks-full-disk-encryption/#bonus-login-once source])</div>PXfhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Device_encryption&diff=746481Dm-crypt/Device encryption2022-09-16T06:24:16Z<p>PXf: /* Removing LUKS keys */ shorten synopsis</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[es:Dm-crypt (Español)/Device encryption]]<br />
[[ja:Dm-crypt/デバイスの暗号化]]<br />
[[pl:Dm-crypt (Polski)/Device encryption]]<br />
[[pt:Dm-crypt (Português)/Device encryption]]<br />
[[zh-hans:Dm-crypt (简体中文)/Device encryption]]<br />
This section covers how to manually utilize ''dm-crypt'' from the command line to encrypt a system.<br />
<br />
== Preparation ==<br />
<br />
Before using {{pkg|cryptsetup}}, always make sure the {{ic|dm_crypt}} [[kernel module]] is loaded.<br />
<br />
== Cryptsetup usage ==<br />
<br />
''Cryptsetup'' is the command line tool to interface with ''dm-crypt'' for creating, accessing and managing encrypted devices. The tool was later expanded to support different encryption types that rely on the Linux kernel '''d'''evice-'''m'''apper and the '''crypt'''ographic modules. The most notable expansion was for the Linux Unified Key Setup (LUKS) extension, which stores all of the needed setup information for dm-crypt on the disk itself and abstracts partition and key management in an attempt to improve ease of use. Devices accessed via the device-mapper are called block devices. For further information see [[Data-at-rest encryption#Block device encryption]]. <br />
<br />
The tool is used as follows: <br />
<br />
# cryptsetup ''OPTIONS'' ''action'' ''action-specific-options'' ''device'' ''dmname''<br />
<br />
It has compiled-in defaults for the options and the encryption mode, which will be used if no others are specified on the command line. Have a look at <br />
<br />
$ cryptsetup --help <br />
<br />
which lists options, actions and the default parameters for the encryption modes in that order. A full list of options can be found on the man page.<br />
Since different parameters are required or optional, depending on encryption mode and action, the following sections point out differences further. Block device encryption is fast, but speed matters a lot too. Since changing an encryption cipher of a block device after setup is difficult, it is important to check ''dm-crypt'' performance for the individual parameters in advance: <br />
<br />
$ cryptsetup benchmark <br />
<br />
can give guidance on deciding for an algorithm and key-size prior to installation. If certain AES ciphers excel with a considerable higher throughput, these are probably the ones with hardware support in the CPU.<br />
<br />
{{Tip|You may want to practise encrypting a virtual hard drive in a [[virtual machine]] when learning.}}<br />
<br />
=== Cryptsetup passphrases and keys ===<br />
<br />
An encrypted block device is protected by a key. A key is either: <br />
<br />
* a passphrase: see [[Security#Passwords]].<br />
* a keyfile, see [[#Keyfiles]].<br />
<br />
Both key types have default maximum sizes: passphrases can be up to 512 characters and keyfiles up to 8192 KiB. <br />
<br />
An important distinction of ''LUKS'' to note at this point is that the key is used to unlock the master-key of a LUKS-encrypted device and can be changed with root access. Other encryption modes do not support changing the key after setup, because they do not employ a master-key for the encryption. See [[Data-at-rest encryption#Block device encryption]] for details.<br />
<br />
== Encryption options with dm-crypt ==<br />
<br />
''Cryptsetup'' supports different encryption operating modes to use with ''dm-crypt'': <br />
<br />
* {{ic|--type luks}} for using the default LUKS format version (LUKS1 with {{Pkg|cryptsetup}} < 2.1.0, LUKS2 with {{Pkg|cryptsetup}} ≥ 2.1.0),<br />
* {{ic|--type luks1}} for using LUKS1, the most common version of LUKS,<br />
* {{ic|--type luks2}} for using LUKS2, the latest available version of LUKS that allows additional extensions,<br />
* {{ic|--type plain}} for using dm-crypt plain mode, <br />
* {{ic|--type loopaes}} for a loopaes legacy mode, <br />
* {{ic|--type tcrypt}} for a [[TrueCrypt]] compatibility mode.<br />
* {{ic|--type bitlk}} for a [[Wikipedia:BitLocker|BitLocker]] compatibility mode. See {{man|8|cryptsetup|BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL)}}.<br />
<br />
The basic cryptographic options for encryption cipher and hashes available can be used for all modes and rely on the kernel cryptographic backend features. All that are loaded and available to use as options at runtime can be viewed with:<br />
<br />
$ less /proc/crypto <br />
<br />
{{Tip|If the list is short, execute {{ic|$ cryptsetup benchmark}} which will trigger loading available modules.}}<br />
<br />
The following introduces encryption options for the {{ic|luks}}, {{ic|luks1}}, {{ic|luks2}} and {{ic|plain}} modes. Note that the tables list options used in the respective examples in this article and not all available ones.<br />
<br />
=== Encryption options for LUKS mode ===<br />
<br />
The ''cryptsetup'' action to set up a new dm-crypt device in LUKS encryption mode is {{ic|luksFormat}}. Unlike what the name implies, it does not format the device, but sets up the LUKS device header and encrypts the master-key with the desired cryptographic options. <br />
<br />
In order to create a new LUKS container with the compiled-in defaults listed by {{ic|cryptsetup --help}}, simply execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
As of cryptsetup 2.4.0, this is equivalent to: <br />
<br />
# cryptsetup --type luks2 --cipher aes-xts-plain64 --hash sha256 --iter-time 2000 --key-size 256 --pbkdf argon2id --use-urandom --verify-passphrase luksFormat ''device''<br />
<br />
Defaults are compared with a cryptographically higher specification example in the table below, with accompanying comments: <br />
<br />
{| class="wikitable"<br />
! Options !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-xts-plain64}}<br />
| {{ic|aes-xts-plain64}}<br />
| [https://www.kernel.org/pub/linux/utils/cryptsetup/v1.6/v1.6.0-ReleaseNotes Release 1.6.0] changed the defaults to an AES [[Data-at-rest encryption#Ciphers and modes of operation|cipher]] in [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS]] mode (see item 5.16 [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects of the FAQ]). It is advised against using the previous default {{ic|--cipher aes-cbc-essiv}} because of its known [[wikipedia:Disk encryption theory#Cipher-block chaining (CBC)|issues]] and practical [https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ attacks] against them.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
| {{ic|256}} ({{ic|512}} for XTS)<br />
| {{ic|512}}<br />
| By default a 512 bit key-size is used for XTS ciphers. Note however that [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS splits the supplied key in half]], so this results in AES-256 being used.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|sha256}}<br />
| {{ic|sha512}}<br />
| Hash algorithm used for [[Data-at-rest encryption#Cryptographic metadata|key derivation]]. Release 1.7.0 changed defaults from {{ic|sha1}} to {{ic|sha256}} "''not for security reasons [but] mainly to prevent compatibility problems on hardened systems where SHA1 is already [being] phased out''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. The former default of {{ic|sha1}} can still be used for compatibility with older versions of ''cryptsetup'' since it is [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects considered secure] (see item 5.20). <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --iter-time<br />
-i<br />
| {{ic|2000}}<br />
| {{ic|5000}}<br />
| Number of milliseconds to spend with PBKDF2 passphrase processing. Release 1.7.0 changed defaults from {{ic|1000}} to {{ic|2000}} to "''try to keep PBKDF2 iteration count still high enough and also still acceptable for users.''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. This option is only relevant for LUKS operations that set or change passphrases, such as {{ic|luksFormat}} or {{ic|luksAddKey}}. Specifying 0 as parameter selects the compiled-in default..<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --use-urandom<br />
| {{ic|--use-urandom}}<br />
| {{ic|--use-random}}<br />
| Selects which [[random number generator]] to use. Note that [https://lwn.net/Articles/808575/ /dev/random blocking pool has been removed]. Therefore, {{ic|--use-random}} flag is now equivalent to {{ic|--use-urandom}}.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --verify-passphrase<br />
-y<br />
| Yes<br />
| -<br />
| Enabled by default in Arch Linux for {{ic|luksFormat}} and {{ic|luksAddKey}}.<br />
|}<br />
<br />
The properties of LUKS features and options are described in the [https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification LUKS1] (pdf) and [https://gitlab.com/cryptsetup/cryptsetup/blob/master/docs/on-disk-format-luks2.pdf LUKS2] (pdf) specifications.<br />
<br />
{{Tip|The project developers' [https://mbroz.fedorapeople.org/talks/DevConf2016/devconf2016-luks2.pdf devconfcz2016] (pdf) presentation summarizes the motivation for the major specification update to LUKS2.}}<br />
<br />
==== Iteration time ====<br />
<br />
From [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#2-setup cryptsetup FAQ§2.1] and [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#3-common-problems §3.4]:<br />
<br />
:The unlock time for a key-slot [...] is calculated when setting a passphrase. By default it is 1 second (2 seconds for LUKS2). [...]<br />
:Passphrase iteration count is based on time and hence security level depends on CPU power of the system the LUKS container is created on. [...]<br />
:If you set a passphrase on a fast machine and then unlock it on a slow machine, the unlocking time can be much longer.<br />
<br />
As such, it is better to always create a container on the machine where it will be most often accessed.<br />
<br />
Read the rest of those sections for advice on how to correctly adjust the iteration count should the need arise.<br />
<br />
==== Sector size ====<br />
<br />
See [[Advanced Format#dm-crypt]].<br />
<br />
=== Encryption options for plain mode ===<br />
<br />
In dm-crypt ''plain'' mode, there is no master-key on the device, hence, there is no need to set it up. Instead the encryption options to be employed are used directly to create the mapping between an encrypted disk and a named device. The mapping can be created against a partition or a full device. In the latter case not even a partition table is needed. <br />
<br />
To create a ''plain'' mode mapping with cryptsetup's default parameters: <br />
<br />
# cryptsetup ''options'' open --type plain ''device'' ''dmname''<br />
<br />
Executing it will prompt for a password, which should have very high entropy. Below a comparison of default parameters with the example in [[dm-crypt/Encrypting an entire system#Plain dm-crypt]].<br />
<br />
{| class="wikitable"<br />
! Option !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|ripemd160}}<br />
| -<br />
| The hash is used to create the key from the passphrase; it is not used on a keyfile. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-cbc-essiv:sha256}}<br />
| {{ic|aes-xts-plain64}}<br />
| The cipher consists of three parts: cipher-chainmode-IV generator. Please see [[Data-at-rest encryption#Ciphers and modes of operation]] for an explanation of these settings, and the [https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt DMCrypt documentation] for some of the options available. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
|{{ic|256}}<br />
|{{ic|512}}<br />
|The key size (in bits). The size will depend on the cipher being used and also the chainmode in use. Xts mode requires twice the key size of cbc. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --size<br />
-b<br />
|real size of target disk<br />
|{{ic|2048}} (mapped device will be 512B×2048=1MiB)<br />
|Limit the maximum size of the device (in 512-byte sectors).<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --offset<br />
-o<br />
|{{ic|0}}<br />
|{{ic|0}}<br />
|The offset from the beginning of the target disk (in 512-byte sectors) from which to start the mapping.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --skip<br />
-p<br />
|{{ic|0}}<br />
|{{ic|2048}} (512B×2048=1MiB will be skipped)<br />
|The number of 512-byte sectors of encrypted data to skip at the beginning.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-file<br />
-d<br />
| default uses a passphrase<br />
| {{ic|/dev/sd''Z''}} (or e.g. {{ic|/boot/keyfile.enc}})<br />
|The device or file to be used as a key. See [[#Keyfiles]] for further details.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-offset<br />
| {{ic|0}}<br />
| {{ic|0}}<br />
| Offset from the beginning of the file where the key starts (in bytes). This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-size<br />
-l<br />
|{{ic|8192kB}}<br />
| - (default applies)<br />
| Limits the bytes read from the key file. This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|}<br />
<br />
Using the device {{ic|/dev/sd''X''}}, the above right column example results in:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sd''Z'' --key-size=512 open --type=plain /dev/sdX enc<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, hash and key file details. We can now check that the mapping has been made:<br />
<br />
# fdisk -l<br />
<br />
An entry should now exist for {{ic|/dev/mapper/enc}}.<br />
<br />
== Encrypting devices with cryptsetup ==<br />
<br />
This section shows how to employ the options for creating new encrypted block devices and accessing them manually. <br />
<br />
{{Warning|GRUB's support for LUKS2 is limited; see [[GRUB#Encrypted /boot]] for details. Use LUKS1 ({{ic|1=cryptsetup luksFormat --type luks1}}) for partitions that GRUB will need to unlock.}}<br />
<br />
=== Encrypting devices with LUKS mode ===<br />
<br />
==== Formatting LUKS partitions ====<br />
<br />
In order to setup a partition as an encrypted LUKS partition execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
You will then be prompted to enter a password and verify it.<br />
<br />
See [[#Encryption options for LUKS mode]] for command line options.<br />
<br />
You can check the results with:<br />
<br />
# cryptsetup luksDump ''device''<br />
<br />
You will note that the dump not only shows the cipher header information, but also the key-slots in use for the LUKS partition. <br />
<br />
The following example will create an encrypted root partition on {{ic|/dev/sda1}} using the default AES cipher in XTS mode with an effective 256-bit encryption <br />
<br />
# cryptsetup -s 512 luksFormat /dev/sda1<br />
<br />
===== Using LUKS to format partitions with a keyfile =====<br />
<br />
When creating a new LUKS encrypted partition, a keyfile may be associated with the partition on its creation using:<br />
<br />
# cryptsetup luksFormat ''device'' ''/path/to/mykeyfile''<br />
<br />
See [[#Keyfiles]] for instructions on how to generate and manage keyfiles.<br />
<br />
==== Unlocking/Mapping LUKS partitions with the device mapper ====<br />
<br />
Once the LUKS partitions have been created, they can then be unlocked.<br />
<br />
The unlocking process will map the partitions to a new device name using the device mapper. This alerts the kernel that {{ic|''device''}} is actually an encrypted device and should be addressed through LUKS using the {{ic|/dev/mapper/''dm_name''}} so as not to overwrite the encrypted data. To guard against accidental overwriting, read about the possibilities to [[#Backup and restore|backup the cryptheader]] after finishing setup.<br />
<br />
In order to open an encrypted LUKS partition execute:<br />
<br />
# cryptsetup open ''device'' ''dm_name''<br />
<br />
You will then be prompted for the password to unlock the partition. Usually the device mapped name is descriptive of the function of the partition that is mapped. For example the following unlocks a root luks partition {{ic|/dev/sda1}} and maps it to device mapper named {{ic|root}}:<br />
<br />
# cryptsetup open /dev/sda1 root <br />
<br />
Once opened, the root partition device address would be {{ic|/dev/mapper/root}} instead of the partition (e.g. {{ic|/dev/sda1}}). <br />
<br />
For setting up LVM ontop the encryption layer the device file for the decrypted volume group would be anything like {{ic|/dev/mapper/root}} instead of {{ic|/dev/sda1}}. LVM will then give additional names to all logical volumes created, e.g. {{ic|/dev/lvmpool/root}} and {{ic|/dev/lvmpool/swap}}.<br />
<br />
In order to write encrypted data into the partition it must be accessed through the device mapped name. The first step of access will typically be to [[create a file system]]. For example:<br />
<br />
# mkfs -t ext4 /dev/mapper/root<br />
<br />
The device {{ic|/dev/mapper/root}} can then be [[mount]]ed like any other partition.<br />
<br />
To close the LUKS container, unmount the partition and do:<br />
<br />
# cryptsetup close root<br />
<br />
==== Using a TPM to store keys ====<br />
<br />
See [[Trusted Platform Module#Data-at-rest encryption with LUKS]].<br />
<br />
=== Encrypting devices with plain mode ===<br />
<br />
The creation and subsequent access of a ''dm-crypt'' plain mode encryption both require not more than using the ''cryptsetup'' {{ic|open}} action with correct [[#Encryption options for plain mode|parameters]]. The following shows that with two examples of non-root devices, but adds a quirk by stacking both (i.e. the second is created inside the first). Obviously, stacking the encryption doubles overhead. The usecase here is simply to illustrate another example of the cipher option usage. <br />
<br />
A first mapper is created with ''cryptsetup's'' plain-mode defaults, as described in the table's left column above <br />
<br />
{{hc|# cryptsetup --type plain -v open /dev/sdaX plain1|<br />
Enter passphrase: <br />
Command successful.<br />
}}<br />
<br />
Now we add the second block device inside it, using different encryption parameters and with an (optional) offset, create a file system and mount it <br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
/dev/sda <br />
├─/dev/sdaX <br />
│ └─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
# mkfs -t ext2 /dev/mapper/plain2<br />
# mount -t ext2 /dev/mapper/plain2 /mnt<br />
# echo "This is stacked. one passphrase per foot to shoot." > /mnt/stacked.txt<br />
<br />
We close the stack to check access works<br />
<br />
# cryptsetup close plain2<br />
# cryptsetup close plain1<br />
<br />
First, let us try to open the file system directly: <br />
<br />
# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/sdaX plain2<br />
<br />
{{hc|# mount -t ext2 /dev/mapper/plain2 /mnt|<br />
mount: wrong fs type, bad option, bad superblock on /dev/mapper/plain2,<br />
missing codepage or helper program, or other error<br />
}}<br />
<br />
Why that did not work? Because the "plain2" starting block ({{ic|10}}) is still encrypted with the cipher from "plain1". It can only be accessed via the stacked mapper. The error is arbitrary though, trying a wrong passphrase or wrong options will yield the same. For ''dm-crypt'' plain mode, the {{ic|open}} action will not error out itself. <br />
<br />
Trying again in correct order: <br />
<br />
# cryptsetup close plain2 # dysfunctional mapper from previous try<br />
<br />
{{hc|# cryptsetup --type plain open /dev/sdaX plain1|<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# mount /dev/mapper/plain2 /mnt && cat /mnt/stacked.txt|<br />
This is stacked. one passphrase per foot to shoot.<br />
}}<br />
<br />
''dm-crypt'' will handle stacked encryption with some mixed modes too. For example LUKS mode could be stacked on the "plain1" mapper. Its header would then be encrypted inside "plain1" when that is closed.<br />
<br />
Available for plain mode only is the option {{ic|--shared}}. With it a single device can be segmented into different non-overlapping mappers. We do that in the next example, using a ''loopaes'' compatible cipher mode for "plain2" this time: <br />
<br />
{{hc|# cryptsetup --type plain --offset 0 --size 1000 open /dev/sdaX plain1|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --offset 1000 --size 1000 --shared --cipher=aes-cbc-lmk --hash=sha256 open /dev/sdaX plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
dev/sdaX <br />
├─/dev/sdaX <br />
│ ├─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
As the device tree shows both reside on the same level, i.e. are not stacked and "plain2" can be opened individually.<br />
<br />
== Cryptsetup actions specific for LUKS ==<br />
<br />
=== Key management ===<br />
<br />
It is possible to define additional keys for the LUKS partition. This enables the user to create access keys for safe backup storage In so-called key escrow, one key is used for daily usage, another kept in escrow to gain access to the partition in case the daily passphrase is forgotten or a keyfile is lost/damaged. A different key-slot could also be used to grant access to a partition to a user by issuing a second key and later revoking it again. <br />
<br />
Once an encrypted partition has been created, the initial keyslot 0 is created (if no other was specified manually). Additional keyslots are numbered from 1 to 7. Which keyslots are used can be seen by issuing <br />
<br />
# cryptsetup luksDump /dev/''device''<br />
<br />
Where {{ic|''device''}} is the block device containing the LUKS header. This and all the following commands in this section work on header backup files as well.<br />
<br />
==== Adding LUKS keys ====<br />
<br />
Adding new keyslots is accomplished with the {{ic|luksAddKey}} action. For safety it will always, even for already unlocked devices, ask for a valid existing key (a passphrase for any existing slot) before a new one may be entered:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' [''/path/to/additionalkeyfile'']|<br />
Enter any passphrase:<br />
Enter new passphrase for key slot:<br />
Verify passphrase: <br />
}}<br />
<br />
If {{ic|''/path/to/additionalkeyfile''}} is given, cryptsetup will add a new keyslot for {{ic|''additionalkeyfile''}}. Otherwise it prompts for a new passphrase. To authorize the action with an existing ''keyfile'', the {{ic|--key-file}} or {{ic|-d}} option followed by the "old" {{ic|''keyfile''}} will try to unlock all available keyfile keyslots:<br />
<br />
# cryptsetup luksAddKey /dev/''device'' [''/path/to/additionalkeyfile''] -d ''/path/to/keyfile''<br />
<br />
If it is intended to use multiple keys and change or revoke them, the {{ic|--key-slot}} or {{ic|-S}} option may be used to specify the slot: <br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' -S 6|<br />
Enter any passphrase: <br />
Enter new passphrase for key slot: <br />
Verify passphrase:<br />
}}<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: ENABLED<br />
}}<br />
<br />
To show an associated action in this example, we decide to change the key right away: <br />
<br />
{{hc|# cryptsetup luksChangeKey /dev/''device'' -S 6|<br />
Enter LUKS passphrase to be changed: <br />
Enter new LUKS passphrase:<br />
}}<br />
<br />
before continuing to remove it.<br />
<br />
==== Removing LUKS keys ====<br />
<br />
There are three different actions to remove keys from the header: <br />
<br />
* {{ic|luksRemoveKey}} removes a key by specifying its passphrase/key-file. <br />
* {{ic|luksKillSlot}} removes a key by specifying its slot (needs another valid key). Obviously, this is extremely useful if you have forgotten a passphrase, lost a key-file, or have no access to it. <br />
* {{ic|luksErase}} removes '''all''' active keys. <br />
<br />
{{warning|<br />
* All above actions can be used to irrevocably delete the last active key for an encrypted device! <br />
* The {{ic|luksErase}} command was added in version 1.6.4 to quickly nuke access to the device. This action '''will not''' prompt for a valid passphrase! It will not [[dm-crypt/Drive preparation#Wipe LUKS header|wipe the LUKS header]], but all keyslots at once and you will, therefore, not be able to regain access unless you have a valid backup of the LUKS header.<br />
}}<br />
<br />
For above warning it is good to know the key we want to '''keep''' is valid. An easy check is to unlock the device with the {{ic|-v}} option, which will specify which slot it occupies: <br />
<br />
{{hc|# cryptsetup --test-passphrase -v open /dev/''device''|<br />
Enter passphrase for /dev/''device'': <br />
Key slot 1 unlocked.<br />
Command successful.<br />
}}<br />
<br />
Now we can remove the key added in the previous subsection using its passphrase: <br />
<br />
{{hc|# cryptsetup luksRemoveKey /dev/''device''|<br />
Enter LUKS passphrase to be deleted:<br />
}}<br />
<br />
If we had used the same passphrase for two keyslots, the first slot would be wiped now. Only executing it again would remove the second one. <br />
<br />
Alternatively, we can specify the key slot: <br />
<br />
{{hc|# cryptsetup luksKillSlot /dev/''device'' 6|<br />
Enter any remaining LUKS passphrase:<br />
}}<br />
<br />
Note that in both cases, no confirmation was required.<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: DISABLED<br />
}}<br />
<br />
To re-iterate the warning above: If the same passphrase had been used for key slots 1 and 6, both would be gone now.<br />
<br />
=== Backup and restore ===<br />
<br />
If the header of a LUKS encrypted partition gets destroyed, you will not be able to decrypt your data. It is just as much of a dilemma as forgetting the passphrase or damaging a key-file used to unlock the partition. Damage may occur by your own fault while re-partitioning the disk later or by third-party programs misinterpreting the partition table. Therefore, having a backup of the header and storing it on another disk might be a good idea.<br />
<br />
{{Note|If one of the LUKS-encrypted partitions' passphrases becomes compromised, you must revoke it on ''every'' copy of the cryptheader, even those you have backed up. Otherwise, a copy of the backed-up cryptheader that uses the compromised passphrase can be used to determine the master key which in turn can be used to decrypt the associated partition (even your actual partition, not only the backed-up version). On the other hand, if the master key gets compromised, you have to reencrypt your whole partition. See [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#6-backup-and-data-recovery LUKS FAQ] for further details.}}<br />
<br />
==== Backup using cryptsetup ====<br />
<br />
Cryptsetup's {{ic|luksHeaderBackup}} action stores a binary backup of the LUKS header and keyslot area:<br />
<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file ''/mnt/backup/file.img''<br />
<br />
where {{ic|''device''}} is the partition containing the LUKS volume.<br />
<br />
You can also back up the plain text header into ramfs and encrypt it with e.g. [[GPG]] before writing it to persistent storage:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/''tmp''<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file /root/''tmp''/''file''.img<br />
# gpg2 --recipient ''User_ID'' --encrypt /root/''tmp''/''file''.img <br />
# cp /root/''tmp''/''file''.img.gpg /mnt/''backup''/<br />
# umount /root/''tmp''<br />
<br />
{{Warning|[[tmpfs]] can swap to the disk in low memory situations, so it is not recommended here.}}<br />
<br />
==== Restore using cryptsetup ====<br />
<br />
{{Warning|Restoring the wrong header or restoring to an unencrypted partition will cause data loss! The action can not perform a check whether the header is actually the ''correct'' one for that particular device.}} <br />
<br />
In order to evade restoring a wrong header, you can ensure it does work by using it as a remote {{ic|--header}} first: <br />
<br />
{{hc|# cryptsetup -v --header /mnt/''backup''/''file''.img open /dev/''device'' test|<br />
Key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
# mount /dev/mapper/test /mnt/test && ls /mnt/test <br />
# umount /mnt/test <br />
# cryptsetup close test <br />
<br />
Now that the check succeeded, the restore may be performed: <br />
<br />
# cryptsetup luksHeaderRestore /dev/''device'' --header-backup-file ./mnt/''backup''/''file''.img<br />
<br />
Now that all the keyslot areas are overwritten; only active keyslots from the backup file are available after issuing the command.<br />
<br />
==== Manual backup and restore ====<br />
<br />
The header always resides at the beginning of the device and a backup can be performed without access to ''cryptsetup'' as well. First you have to find out the payload offset of the crypted partition:<br />
<br />
{{hc|# cryptsetup luksDump /dev/''device'' {{!}} grep "Payload offset"|<br />
Payload offset: 4040<br />
}}<br />
<br />
Second check the sector size of the drive<br />
<br />
{{hc|# fdisk -l /dev/''device'' {{!}} grep "Sector size"|<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
}}<br />
<br />
Now that you know the values, you can backup the header with a simple [[dd]] command:<br />
<br />
# dd if=/dev/''device'' of=/path/to/''file''.img bs=512 count=4040<br />
<br />
and store it safely.<br />
<br />
A restore can then be performed using the same values as when backing up:<br />
<br />
# dd if=./''file''.img of=/dev/''device'' bs=512 count=4040<br />
<br />
=== Re-encrypting devices ===<br />
<br />
{{Expansion|cryptsetup 2.2 using LUKS2 (with a 16 MiB header) supports online encryption/decryption/reencryption.[https://mirrors.edge.kernel.org/pub/linux/utils/cryptsetup/v2.2/v2.2.0-ReleaseNotes]}}<br />
<br />
{{Out of date|cryptsetup-reencrypt was removed in cryptsetup 2.5.0.[https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/v2.5.0-ReleaseNotes]}}<br />
<br />
The {{Pkg|cryptsetup}} package features two options for re-encryption.<br />
<br />
; cryptsetup reencrypt: Argument to {{ic|cryptsetup}} itself: Preferred method. Currently LUKS2 devices only. Actions can be performed online. Supports multiple parallel re-encryption jobs. Resilient to system failures. See {{man|8|cryptsetup}} for more information.<br />
<br />
; cryptsetup-reencrypt: Legacy tool, supports LUKS1 in addition to LUKS2. Actions can be performed on unmounted devices only. Single process at a time. Sensitive to system failures. See {{man|8|cryptsetup-reencrypt}} for more information. <br />
<br />
Both can be used to convert an existing unencrypted file system to a LUKS encrypted one or permanently remove LUKS encryption from a device (using {{ic|--decrypt}}). As its name suggests it can also be used to re-encrypt an existing LUKS encrypted device, though, re-encryption is not possible for a detached LUKS header or other encryption modes (e.g. plain-mode). For re-encryption it is possible to change the [[#Encryption options for LUKS mode]]. <br />
<br />
One application of re-encryption may be to secure the data again after a passphrase or [[#Keyfiles|keyfile]] has been compromised ''and'' one cannot be certain that no copy of the LUKS header has been obtained. For example, if only a passphrase has been shoulder-surfed but no physical/logical access to the device happened, it would be enough to change the respective passphrase/key only ([[#Key management]]). <br />
<br />
{{Warning|Always make sure a '''reliable backup''' is available and double-check options you specify before using the tool!}}<br />
<br />
The following shows an example to encrypt an unencrypted file system partition and a re-encryption of an existing LUKS device.<br />
<br />
==== Encrypt an existing unencrypted file system ====<br />
<br />
{{Tip|If you are trying to encrypt an existing root partition, you might want to create a separate and unencrypted boot partition which will be mounted to {{ic|/boot}} (see [[Dm-crypt/Encrypting an entire system#Preparing the boot partition]]). It is not strictly necessary but has a number of advantages:<br />
<br />
* If {{ic|/boot}} is located inside an encrypted root partition, the system will ask for the passphrase twice when the machine is powered on. The first time will happen when the boot loader attempts to read the files located inside encrypted {{ic|/boot}}, the second time will be when the kernel tries to mount the encrypted partition [https://opencraft.com/blog/tutorial-encrypting-an-existing-root-partition-in-ubuntu-with-dm-crypt-and-luks/]. This might not be the desired behaviour and can be prevented by having a separate and unencryted boot partition.<br />
* Some system restore applications (e.g., {{AUR|timeshift}}) will not work if {{ic|/boot}} is located inside an encryted partition [https://github.com/teejee2008/timeshift/issues/280].<br />
<br />
In short, create a partition with the size of at least 260 MiB if needed. See [[Partitioning#/boot]].}}<br />
<br />
A LUKS encryption header is always stored at the beginning of the device. Since an existing file system will usually be allocated all partition sectors, the first step is to shrink it to make space for the LUKS header.<br />
<br />
{{Expansion|cryptsetup man pages suggest using twice the LUKS2 header size. That implies 32 MiB and using {{ic|--reduce-device-size 32M}}}}<br />
<br />
The [[#Encryption options for LUKS mode|default]] LUKS2 header requires 16 MiB. If the current file system occupies all the available space, we will have to shrink it at least that much. To shrink an existing {{ic|ext4}} file system on {{ic|/dev/sdaX}} to its current possible minimum:<br />
<br />
# umount /mnt<br />
<br />
{{hc|# e2fsck -f /dev/sdaX|<br />
e2fsck 1.43-WIP (18-May-2015)<br />
Pass 1: Checking inodes, blocks, and sizes<br />
...<br />
/dev/sda6: 12/166320 files (0.0% non-contiguous), 28783/665062 blocks<br />
}}<br />
<br />
{{hc|# resize2fs -p -M /dev/sdaX|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/sdaX to 26347 (4k) blocks.<br />
The filesystem on /dev/sdaX is now 26347 (4k) blocks long.<br />
}}<br />
<br />
{{Tip|Shrinking to the minimum size with {{ic|-M}} might take very long. You might want to calculate a size just 32 MiB smaller than the current size instead of using {{ic|-M}}.}}<br />
<br />
{{Warning|The file system should be shrunk while the underlying device (e.g., a partition) should be kept at its original size. Some graphical tools (e.g., [[GParted]]) may resize both the file system and the partition, and data loss may occur after encryption.}}<br />
<br />
Now we encrypt it, using the default cipher we do not have to specify it explicitly:<br />
<br />
{{hc|# cryptsetup reencrypt --encrypt --reduce-device-size 16M /dev/sdaX|<nowiki><br />
<br />
WARNING!<br />
<br />
========<br />
<br />
This will overwrite data on LUKS2-temp-12345678-9012-3456-7890-123456789012.new irrevocably.<br />
<br />
Are you sure? (Type 'yes' in capital letters): YES<br />
Enter passphrase for LUKS2-temp-12345678-9012-3456-7890-123456789012.new: <br />
Verify passphrase: <br />
</nowiki>}}<br />
<br />
After it finished, the whole {{ic|/dev/sdaX}} partition is encrypted, not only the space the file system was shrunk to. As a final step we extend the original {{ic|ext4}} file system to occupy all available space again, on the now encrypted partition:<br />
<br />
{{hc|# cryptsetup open /dev/sdaX recrypt|<br />
Enter passphrase for /dev/sdaX: <br />
...<br />
}}<br />
<br />
{{hc|# resize2fs /dev/mapper/recrypt|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/mapper/recrypt to 664807 (4k) blocks.<br />
The filesystem on /dev/mapper/recrypt is now 664807 (4k) blocks long.<br />
}}<br />
<br />
# mount /dev/mapper/recrypt /mnt<br />
<br />
The file system is now ready to use. You may want to add it to your [[crypttab]].<br />
<br />
{{Tip|If you have just encrypted your root partition, you might need to perform a number of post-encryption adjustments.<br />
<br />
See [[Dm-crypt/Encrypting an entire system#Configuring mkinitcpio]], [[Dm-crypt/Encrypting an entire system#Configuring the boot loader]], and [[Dm-crypt/Encrypting an entire system#Configuring GRUB]].}}<br />
<br />
==== Re-encrypting an existing LUKS partition ====<br />
<br />
In this example an existing LUKS device is re-encrypted. <br />
<br />
{{Warning|Double-check you specify encryption options for correctly and ''never'' re-encrypt without a '''reliable backup'''!}}<br />
<br />
In order to re-encrypt a device with its existing encryption options, they do not need to be specified:<br />
{{bc|# cryptsetup reencrypt /dev/sdaX}}<br />
{{Note|For LUKS1 we will need to use the legacy tool:{{bc|# cryptsetup-reencrypt /dev/sdaX}}}}<br />
<br />
Existing keys are retained when re-encrypting a device with a different cipher and/or hash. Another use case is to re-encrypt LUKS devices which have non-current encryption options. Apart from above warning on specifying options correctly, the ability to change the LUKS header may also be limited by its size. For example, if the device was initially encrypted using a CBC mode cipher and 128 bit key-size, the LUKS header will be half the size of above mentioned {{ic|4096}} sectors: <br />
<br />
{{hc|# cryptsetup luksDump /dev/sdaX {{!}} grep -e "mode" -e "Payload" -e "MK bits"|<br />
Cipher mode: cbc-essiv:sha256<br />
Payload offset: '''2048'''<br />
MK bits: 128<br />
}}<br />
<br />
While it is possible to upgrade the encryption of such a device, it is currently only feasible in two steps. First, re-encrypting with the same encryption options, but using the {{ic|--reduce-device-size}} option to make further space for the larger LUKS header. Second, re-encypt the whole device again with the desired cipher. For this reason and the fact that a backup should be created in any case, creating a new, fresh encrypted device to restore into is always the faster option.<br />
<br />
=== Conversion from LUKS1 to LUKS2 and back ===<br />
<br />
The {{Pkg|cryptsetup}} package has {{ic|convert}} option that needed for conversion between LUKS1 and LUKS2 container types. The argument {{ic|--type}} is '''required'''.<br />
<br />
Migration from LUKS1 to LUKS2:<br />
<br />
# cryptsetup convert --type luks2 /dev/sdaX<br />
<br />
{{Note|The LUKS header size will be 2 MiB instead of 16 MiB.}}<br />
<br />
Rollback to LUKS1 (for example, to boot from [[GRUB#Encrypted /boot|GRUB with encrypted /boot]]):<br />
<br />
# cryptsetup convert --type luks1 /dev/sdaX<br />
<br />
{{Note|Conversion from LUKS2 to LUKS1 is '''not''' always possible. You may get the following error:<br />
Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible.<br />
}}<br />
<br />
== Resizing encrypted devices ==<br />
<br />
{{Expansion|This section should be rewritten to introduce resizing more generically. Perhaps work on it together with [[Resizing LVM-on-LUKS]].}}<br />
<br />
If a storage device encrypted with dm-crypt is being cloned (with a tool like dd) to another larger device, the underlying dm-crypt device must be resized to use the whole space. <br />
<br />
The destination device is /dev/sdX2 in this example, the whole available space adjacent to the partition will be used:<br />
<br />
# cryptsetup luksOpen /dev/sdX2 sdX2<br />
# cryptsetup resize sdX2<br />
<br />
Then the underlying file system must be resized.<br />
<br />
=== Loopback file system ===<br />
<br />
Assume that an encrypted loopback file system is stored in a file {{ic|/bigsecret}}, looped to {{ic|/dev/loop0}}, mapped to {{ic|secret}} and mounted on {{ic|/mnt/secret}}, as in the example at [[dm-crypt/Encrypting a non-root file system#File container]].<br />
<br />
If the container file is currently mapped and/or mounted, unmount and/or close it:<br />
<br />
# umount /mnt/secret<br />
# cryptsetup close secret<br />
# losetup -d /dev/loop0<br />
<br />
Next, expand the container file with the size of the data you want to add. In this example, the file will be expanded with 1M * 1024, which is 1G.<br />
<br />
{{Warning|Make absolutely sure to use '''two''' {{ic|>}}, instead of just one, or else you will overwrite the file instead of appending to it. Making a backup before this step is strongly recommended.}}<br />
<br />
# dd if=/dev/urandom bs=1M count=1024 | cat - >> /bigsecret<br />
<br />
Now map the container to the loop device:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
# cryptsetup open /dev/loop0 secret<br />
<br />
After this, resize the encrypted part of the container to the new maximum size of the container file:<br />
<br />
# cryptsetup resize secret<br />
<br />
Finally, perform a file system check and, if it is ok, resize it (example for ext2/3/4):<br />
<br />
# e2fsck -f /dev/mapper/secret<br />
# resize2fs /dev/mapper/secret<br />
<br />
You can now mount the container again:<br />
<br />
# mount /dev/mapper/secret /mnt/secret<br />
<br />
=== Integrity protected device ===<br />
<br />
If the device was formatted with integrity support (e.g., {{ic|--integrity hmac-sha256}}) and the backing block device is shrinked, it cannot be opened with this error: {{ic|device-mapper: reload ioctl on failed: Invalid argument}}.<br />
<br />
To fix this issue without wiping the device again, it can be formatted with the previous master key (keeping the per-sector tags valid).<br />
<br />
# cryptsetup luksDump /dev/sdX2 --dump-master-key --master-key-file=/tmp/masterkey-in-tmpfs.key<br />
# cryptsetup luksFormat /dev/sdX2 --type luks2 --integrity hmac-sha256 --master-key-file=/tmp/masterkey-in-tmpfs.key --integrity-no-wipe<br />
# rm /tmp/masterkey-in-tmpfs.key<br />
<br />
== Keyfiles ==<br />
<br />
{{Note|This section describes using a plaintext keyfile. If you want to encrypt your keyfile giving you two factor authentication see [[dm-crypt/Specialties#Using GPG, LUKS, or OpenSSL Encrypted Keyfiles|Using GPG or OpenSSL Encrypted Keyfiles]] for details, but please still read this section.}}<br />
<br />
'''What is a keyfile?'''<br />
<br />
A keyfile is a file whose data is used as the passphrase to unlock an encrypted volume.<br />
That means if such a file is lost or changed, decrypting the volume may no longer be possible.<br />
<br />
{{Tip|Define a passphrase in addition to the keyfile for backup access to encrypted volumes in the event the defined keyfile is lost or changed.}}<br />
<br />
'''Why use a keyfile?'''<br />
<br />
There are many kinds of keyfiles. Each type of keyfile used has benefits and disadvantages summarized below:<br />
<br />
=== Types of keyfiles ===<br />
<br />
==== passphrase ====<br />
<br />
This is a keyfile containing a simple passphrase. The benefit of this type of keyfile is that if the file is lost the data it contained is known and hopefully easily remembered by the owner of the encrypted volume. However the disadvantage is that this does not add any security over entering a passphrase during the initial system start.<br />
<br />
Example: {{ic|1234}}<br />
<br />
{{Note|The keyfile containing the passphrase must not have a newline in it. One option is to create it using <br />
<br />
# echo -n 'your_passphrase' > ''/path/to/keyfile''<br />
# chown root:root ''/path/to/keyfile''; chmod 400 ''/path/to/keyfile''<br />
<br />
If the file contains special characters such as a backslash, rather than escaping these, it is recommended to simply edit the key file directly entering or pasting the passphrase and then remove the trailing newline with a handy perl one-liner:<br />
<br />
# perl -pi -e 'chomp if eof' ''/path/to/keyfile''<br />
}}<br />
<br />
==== randomtext ====<br />
<br />
This is a keyfile containing a block of random characters. The benefit of this type of keyfile is that it is much more resistant to dictionary attacks than a simple passphrase. An additional strength of keyfiles can be utilized in this situation which is the length of data used. Since this is not a string meant to be memorized by a person for entry, it is trivial to create files containing thousands of random characters as the key. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase.<br />
<br />
Example: {{ic|fjqweifj830149-57 819y4my1-38t1934yt8-91m 34co3;t8y;9p3y-}}<br />
<br />
==== binary ====<br />
<br />
This is a binary file that has been defined as a keyfile. When identifying files as candidates for a keyfile, it is recommended to choose files that are relatively static such as photos, music, video clips. The benefit of these files is that they serve a dual function which can make them harder to identify as keyfiles. Instead of having a text file with a large amount of random text, the keyfile would look like a regular image file or music clip to the casual observer. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase. Additionally, there is a theoretical loss of randomness when compared to a randomly generated text file. This is due to the fact that images, videos and music have some intrinsic relationship between neighboring bits of data that does not exist for a random text file. However this is controversial and has never been exploited publicly.<br />
<br />
Example: images, text, video, ...<br />
<br />
=== Creating a keyfile with random characters ===<br />
<br />
==== Storing the keyfile on a file system ====<br />
<br />
A keyfile can be of arbitrary content and size. <br />
<br />
Here [[dd]] is used to generate a keyfile of 2048 random bytes, storing it in the file {{ic|/etc/mykeyfile}}:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/etc/mykeyfile iflag=fullblock<br />
<br />
If you are planning to store the keyfile on an external device, you can also simply change the outputfile to the corresponding directory:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/media/usbstick/mykeyfile iflag=fullblock<br />
<br />
To deny any access for other users than {{ic|root}}:<br />
<br />
# chmod 600 /etc/mykeyfile<br />
<br />
===== Securely overwriting stored keyfiles =====<br />
<br />
If you stored your temporary keyfile on a physical storage device, and want to delete it, remember to not just remove the keyfile later on, but use something like<br />
<br />
# shred --remove --zero mykeyfile<br />
<br />
to securely overwrite it. For overaged file systems like FAT or ext2 this will suffice while in the case of journaling file systems, flash memory hardware and other cases it is highly recommended to [[Securely wipe disk|wipe the entire device]].<br />
<br />
==== Storing the keyfile in ramfs ====<br />
<br />
Alternatively, you can mount a ramfs for storing the keyfile temporarily:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/myramfs<br />
# cd /root/myramfs<br />
<br />
The advantage is that it resides in RAM and not on a physical disk, therefore it can not be recovered after unmounting the ramfs. After copying the keyfile to another secure and persistent file system, unmount the ramfs again with<br />
<br />
# umount /root/myramfs<br />
<br />
=== Configuring LUKS to make use of the keyfile ===<br />
<br />
Add a keyslot for the keyfile to the LUKS header:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/sda2 /etc/mykeyfile|<br />
Enter any LUKS passphrase:<br />
key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
=== Manually unlocking a partition using a keyfile ===<br />
<br />
Use the {{ic|--key-file}} option when opening the LUKS device:<br />
<br />
# cryptsetup open /dev/sda2 ''dm_name'' --key-file /etc/mykeyfile<br />
<br />
=== Unlocking the root partition at boot ===<br />
<br />
This is simply a matter of configuring [[mkinitcpio]] to include the necessary modules or files and configuring the [[dm-crypt/System configuration#cryptkey|cryptkey]] [[kernel parameter]] to know where to find the keyfile.<br />
<br />
Two cases are covered below:<br />
<br />
# Using a keyfile stored on an external medium (e.g. a USB stick)<br />
# Using a keyfile embedded in the initramfs<br />
<br />
==== With a keyfile stored on an external media ====<br />
<br />
===== Configuring mkinitcpio =====<br />
<br />
You have to add the kernel module for the drive's [[file system]] to the [[mkinitcpio#MODULES|MODULES array]] in {{ic|/etc/mkinitcpio.conf}}. For example, add {{ic|ext4}} if the file system is [[Ext4]] or {{ic|vfat}} in case it is [[FAT]]:<br />
<br />
MODULES=(vfat)<br />
<br />
If there are messages about bad superblock and bad codepage at boot, then you need an extra codepage module to be loaded. For instance, you may need {{ic|nls_iso8859-1}} module for {{ic|iso8859-1}} codepage.<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
===== Configuring the kernel parameters =====<br />
<br />
* For a busybox-based initramfs using the [[dm-crypt/System configuration#Using encrypt hook|encrypt]] hook, see [[dm-crypt/System configuration#cryptkey]].<br />
* For a systemd based initramfs using the [[sd-encrypt]] hook, see [[dm-crypt/System configuration#rd.luks.key]].<br />
<br />
==== With a keyfile embedded in the initramfs ====<br />
<br />
{{Warning|Use an embedded keyfile '''only''' if you protect the keyfile sufficiently by:<br />
* Using some form of authentication earlier in the boot process. Otherwise auto-decryption will occur, defeating completely the purpose of block device encryption.<br />
* {{ic|/boot}} is encrypted. Otherwise root on a different installation (including the [[Installation guide#Boot the live environment|live environment]]) can extract your key from the initramfs, and unlock the device without any other authentication.}}<br />
<br />
This method allows to use a specially named keyfile that will be embedded in the [[initramfs]] and picked up by the {{ic|encrypt}} [[Mkinitcpio#HOOKS|hook]] to unlock the root file system ({{ic|cryptdevice}}) automatically. It may be useful to apply when using the [[GRUB#Encrypted /boot|GRUB early cryptodisk]] feature, in order to avoid entering two passphrases during boot.<br />
<br />
The {{ic|encrypt}} hook lets the user specify a keyfile with the {{ic|cryptkey}} kernel parameter: in the case of initramfs, the syntax is {{ic|rootfs:''/path/to/keyfile''}}. See [[dm-crypt/System configuration#cryptkey]]. Besides, this kernel parameter defaults to use {{ic|/crypto_keyfile.bin}}, and if the initramfs contains a valid key with this name, decryption will occur automatically without the need to configure the {{ic|cryptkey}} parameter.<br />
<br />
If using {{ic|sd-encrypt}} instead of {{ic|encrypt}}, specify the location of the keyfile with the {{ic|rd.luks.key}} kernel parameter: in the case of initramfs, the syntax is {{ic|''/path/to/keyfile''}}. See [[dm-crypt/System configuration#rd.luks.key]]. This kernel parameter defaults to using {{ic|/etc/cryptsetup-keys.d/''name''.key}} (where {{ic|''name''}} is the {{ic|''dm_name''}} used for decryption in [[#Encrypting devices with cryptsetup]]) and can be omitted if initramfs contains a valid key with this path.<br />
<br />
[[#Creating a keyfile with random characters|Generate the keyfile]], give it suitable permissions and [[#Adding LUKS keys|add it as a LUKS key]]:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/crypto_keyfile.bin iflag=fullblock<br />
# chmod 600 /crypto_keyfile.bin<br />
# cryptsetup luksAddKey /dev/sdX# /crypto_keyfile.bin<br />
<br />
{{Note|The initramfs is generated by mkinitcpio with {{ic|600}} [[permissions]] by default, so regular users are not able to read the keyfile via the generated initramfs.}}<br />
<br />
Include the key in [[mkinitcpio#BINARIES and FILES|mkinitcpio's FILES array]]:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/crypto_keyfile.bin)<br />
}}<br />
<br />
Finally [[regenerate the initramfs]].<br />
<br />
On the next reboot you should only have to enter your container decryption passphrase once.<br />
<br />
([https://www.pavelkogan.com/2014/05/23/luks-full-disk-encryption/#bonus-login-once source])</div>PXfhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Device_encryption&diff=746480Dm-crypt/Device encryption2022-09-16T06:11:38Z<p>PXf: /* Adding LUKS keys */ try to fix words [please review!]</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[es:Dm-crypt (Español)/Device encryption]]<br />
[[ja:Dm-crypt/デバイスの暗号化]]<br />
[[pl:Dm-crypt (Polski)/Device encryption]]<br />
[[pt:Dm-crypt (Português)/Device encryption]]<br />
[[zh-hans:Dm-crypt (简体中文)/Device encryption]]<br />
This section covers how to manually utilize ''dm-crypt'' from the command line to encrypt a system.<br />
<br />
== Preparation ==<br />
<br />
Before using {{pkg|cryptsetup}}, always make sure the {{ic|dm_crypt}} [[kernel module]] is loaded.<br />
<br />
== Cryptsetup usage ==<br />
<br />
''Cryptsetup'' is the command line tool to interface with ''dm-crypt'' for creating, accessing and managing encrypted devices. The tool was later expanded to support different encryption types that rely on the Linux kernel '''d'''evice-'''m'''apper and the '''crypt'''ographic modules. The most notable expansion was for the Linux Unified Key Setup (LUKS) extension, which stores all of the needed setup information for dm-crypt on the disk itself and abstracts partition and key management in an attempt to improve ease of use. Devices accessed via the device-mapper are called block devices. For further information see [[Data-at-rest encryption#Block device encryption]]. <br />
<br />
The tool is used as follows: <br />
<br />
# cryptsetup ''OPTIONS'' ''action'' ''action-specific-options'' ''device'' ''dmname''<br />
<br />
It has compiled-in defaults for the options and the encryption mode, which will be used if no others are specified on the command line. Have a look at <br />
<br />
$ cryptsetup --help <br />
<br />
which lists options, actions and the default parameters for the encryption modes in that order. A full list of options can be found on the man page.<br />
Since different parameters are required or optional, depending on encryption mode and action, the following sections point out differences further. Block device encryption is fast, but speed matters a lot too. Since changing an encryption cipher of a block device after setup is difficult, it is important to check ''dm-crypt'' performance for the individual parameters in advance: <br />
<br />
$ cryptsetup benchmark <br />
<br />
can give guidance on deciding for an algorithm and key-size prior to installation. If certain AES ciphers excel with a considerable higher throughput, these are probably the ones with hardware support in the CPU.<br />
<br />
{{Tip|You may want to practise encrypting a virtual hard drive in a [[virtual machine]] when learning.}}<br />
<br />
=== Cryptsetup passphrases and keys ===<br />
<br />
An encrypted block device is protected by a key. A key is either: <br />
<br />
* a passphrase: see [[Security#Passwords]].<br />
* a keyfile, see [[#Keyfiles]].<br />
<br />
Both key types have default maximum sizes: passphrases can be up to 512 characters and keyfiles up to 8192 KiB. <br />
<br />
An important distinction of ''LUKS'' to note at this point is that the key is used to unlock the master-key of a LUKS-encrypted device and can be changed with root access. Other encryption modes do not support changing the key after setup, because they do not employ a master-key for the encryption. See [[Data-at-rest encryption#Block device encryption]] for details.<br />
<br />
== Encryption options with dm-crypt ==<br />
<br />
''Cryptsetup'' supports different encryption operating modes to use with ''dm-crypt'': <br />
<br />
* {{ic|--type luks}} for using the default LUKS format version (LUKS1 with {{Pkg|cryptsetup}} < 2.1.0, LUKS2 with {{Pkg|cryptsetup}} ≥ 2.1.0),<br />
* {{ic|--type luks1}} for using LUKS1, the most common version of LUKS,<br />
* {{ic|--type luks2}} for using LUKS2, the latest available version of LUKS that allows additional extensions,<br />
* {{ic|--type plain}} for using dm-crypt plain mode, <br />
* {{ic|--type loopaes}} for a loopaes legacy mode, <br />
* {{ic|--type tcrypt}} for a [[TrueCrypt]] compatibility mode.<br />
* {{ic|--type bitlk}} for a [[Wikipedia:BitLocker|BitLocker]] compatibility mode. See {{man|8|cryptsetup|BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL)}}.<br />
<br />
The basic cryptographic options for encryption cipher and hashes available can be used for all modes and rely on the kernel cryptographic backend features. All that are loaded and available to use as options at runtime can be viewed with:<br />
<br />
$ less /proc/crypto <br />
<br />
{{Tip|If the list is short, execute {{ic|$ cryptsetup benchmark}} which will trigger loading available modules.}}<br />
<br />
The following introduces encryption options for the {{ic|luks}}, {{ic|luks1}}, {{ic|luks2}} and {{ic|plain}} modes. Note that the tables list options used in the respective examples in this article and not all available ones.<br />
<br />
=== Encryption options for LUKS mode ===<br />
<br />
The ''cryptsetup'' action to set up a new dm-crypt device in LUKS encryption mode is {{ic|luksFormat}}. Unlike what the name implies, it does not format the device, but sets up the LUKS device header and encrypts the master-key with the desired cryptographic options. <br />
<br />
In order to create a new LUKS container with the compiled-in defaults listed by {{ic|cryptsetup --help}}, simply execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
As of cryptsetup 2.4.0, this is equivalent to: <br />
<br />
# cryptsetup --type luks2 --cipher aes-xts-plain64 --hash sha256 --iter-time 2000 --key-size 256 --pbkdf argon2id --use-urandom --verify-passphrase luksFormat ''device''<br />
<br />
Defaults are compared with a cryptographically higher specification example in the table below, with accompanying comments: <br />
<br />
{| class="wikitable"<br />
! Options !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-xts-plain64}}<br />
| {{ic|aes-xts-plain64}}<br />
| [https://www.kernel.org/pub/linux/utils/cryptsetup/v1.6/v1.6.0-ReleaseNotes Release 1.6.0] changed the defaults to an AES [[Data-at-rest encryption#Ciphers and modes of operation|cipher]] in [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS]] mode (see item 5.16 [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects of the FAQ]). It is advised against using the previous default {{ic|--cipher aes-cbc-essiv}} because of its known [[wikipedia:Disk encryption theory#Cipher-block chaining (CBC)|issues]] and practical [https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ attacks] against them.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
| {{ic|256}} ({{ic|512}} for XTS)<br />
| {{ic|512}}<br />
| By default a 512 bit key-size is used for XTS ciphers. Note however that [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS splits the supplied key in half]], so this results in AES-256 being used.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|sha256}}<br />
| {{ic|sha512}}<br />
| Hash algorithm used for [[Data-at-rest encryption#Cryptographic metadata|key derivation]]. Release 1.7.0 changed defaults from {{ic|sha1}} to {{ic|sha256}} "''not for security reasons [but] mainly to prevent compatibility problems on hardened systems where SHA1 is already [being] phased out''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. The former default of {{ic|sha1}} can still be used for compatibility with older versions of ''cryptsetup'' since it is [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects considered secure] (see item 5.20). <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --iter-time<br />
-i<br />
| {{ic|2000}}<br />
| {{ic|5000}}<br />
| Number of milliseconds to spend with PBKDF2 passphrase processing. Release 1.7.0 changed defaults from {{ic|1000}} to {{ic|2000}} to "''try to keep PBKDF2 iteration count still high enough and also still acceptable for users.''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. This option is only relevant for LUKS operations that set or change passphrases, such as {{ic|luksFormat}} or {{ic|luksAddKey}}. Specifying 0 as parameter selects the compiled-in default..<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --use-urandom<br />
| {{ic|--use-urandom}}<br />
| {{ic|--use-random}}<br />
| Selects which [[random number generator]] to use. Note that [https://lwn.net/Articles/808575/ /dev/random blocking pool has been removed]. Therefore, {{ic|--use-random}} flag is now equivalent to {{ic|--use-urandom}}.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --verify-passphrase<br />
-y<br />
| Yes<br />
| -<br />
| Enabled by default in Arch Linux for {{ic|luksFormat}} and {{ic|luksAddKey}}.<br />
|}<br />
<br />
The properties of LUKS features and options are described in the [https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification LUKS1] (pdf) and [https://gitlab.com/cryptsetup/cryptsetup/blob/master/docs/on-disk-format-luks2.pdf LUKS2] (pdf) specifications.<br />
<br />
{{Tip|The project developers' [https://mbroz.fedorapeople.org/talks/DevConf2016/devconf2016-luks2.pdf devconfcz2016] (pdf) presentation summarizes the motivation for the major specification update to LUKS2.}}<br />
<br />
==== Iteration time ====<br />
<br />
From [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#2-setup cryptsetup FAQ§2.1] and [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#3-common-problems §3.4]:<br />
<br />
:The unlock time for a key-slot [...] is calculated when setting a passphrase. By default it is 1 second (2 seconds for LUKS2). [...]<br />
:Passphrase iteration count is based on time and hence security level depends on CPU power of the system the LUKS container is created on. [...]<br />
:If you set a passphrase on a fast machine and then unlock it on a slow machine, the unlocking time can be much longer.<br />
<br />
As such, it is better to always create a container on the machine where it will be most often accessed.<br />
<br />
Read the rest of those sections for advice on how to correctly adjust the iteration count should the need arise.<br />
<br />
==== Sector size ====<br />
<br />
See [[Advanced Format#dm-crypt]].<br />
<br />
=== Encryption options for plain mode ===<br />
<br />
In dm-crypt ''plain'' mode, there is no master-key on the device, hence, there is no need to set it up. Instead the encryption options to be employed are used directly to create the mapping between an encrypted disk and a named device. The mapping can be created against a partition or a full device. In the latter case not even a partition table is needed. <br />
<br />
To create a ''plain'' mode mapping with cryptsetup's default parameters: <br />
<br />
# cryptsetup ''options'' open --type plain ''device'' ''dmname''<br />
<br />
Executing it will prompt for a password, which should have very high entropy. Below a comparison of default parameters with the example in [[dm-crypt/Encrypting an entire system#Plain dm-crypt]].<br />
<br />
{| class="wikitable"<br />
! Option !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|ripemd160}}<br />
| -<br />
| The hash is used to create the key from the passphrase; it is not used on a keyfile. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-cbc-essiv:sha256}}<br />
| {{ic|aes-xts-plain64}}<br />
| The cipher consists of three parts: cipher-chainmode-IV generator. Please see [[Data-at-rest encryption#Ciphers and modes of operation]] for an explanation of these settings, and the [https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt DMCrypt documentation] for some of the options available. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
|{{ic|256}}<br />
|{{ic|512}}<br />
|The key size (in bits). The size will depend on the cipher being used and also the chainmode in use. Xts mode requires twice the key size of cbc. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --size<br />
-b<br />
|real size of target disk<br />
|{{ic|2048}} (mapped device will be 512B×2048=1MiB)<br />
|Limit the maximum size of the device (in 512-byte sectors).<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --offset<br />
-o<br />
|{{ic|0}}<br />
|{{ic|0}}<br />
|The offset from the beginning of the target disk (in 512-byte sectors) from which to start the mapping.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --skip<br />
-p<br />
|{{ic|0}}<br />
|{{ic|2048}} (512B×2048=1MiB will be skipped)<br />
|The number of 512-byte sectors of encrypted data to skip at the beginning.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-file<br />
-d<br />
| default uses a passphrase<br />
| {{ic|/dev/sd''Z''}} (or e.g. {{ic|/boot/keyfile.enc}})<br />
|The device or file to be used as a key. See [[#Keyfiles]] for further details.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-offset<br />
| {{ic|0}}<br />
| {{ic|0}}<br />
| Offset from the beginning of the file where the key starts (in bytes). This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-size<br />
-l<br />
|{{ic|8192kB}}<br />
| - (default applies)<br />
| Limits the bytes read from the key file. This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|}<br />
<br />
Using the device {{ic|/dev/sd''X''}}, the above right column example results in:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sd''Z'' --key-size=512 open --type=plain /dev/sdX enc<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, hash and key file details. We can now check that the mapping has been made:<br />
<br />
# fdisk -l<br />
<br />
An entry should now exist for {{ic|/dev/mapper/enc}}.<br />
<br />
== Encrypting devices with cryptsetup ==<br />
<br />
This section shows how to employ the options for creating new encrypted block devices and accessing them manually. <br />
<br />
{{Warning|GRUB's support for LUKS2 is limited; see [[GRUB#Encrypted /boot]] for details. Use LUKS1 ({{ic|1=cryptsetup luksFormat --type luks1}}) for partitions that GRUB will need to unlock.}}<br />
<br />
=== Encrypting devices with LUKS mode ===<br />
<br />
==== Formatting LUKS partitions ====<br />
<br />
In order to setup a partition as an encrypted LUKS partition execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
You will then be prompted to enter a password and verify it.<br />
<br />
See [[#Encryption options for LUKS mode]] for command line options.<br />
<br />
You can check the results with:<br />
<br />
# cryptsetup luksDump ''device''<br />
<br />
You will note that the dump not only shows the cipher header information, but also the key-slots in use for the LUKS partition. <br />
<br />
The following example will create an encrypted root partition on {{ic|/dev/sda1}} using the default AES cipher in XTS mode with an effective 256-bit encryption <br />
<br />
# cryptsetup -s 512 luksFormat /dev/sda1<br />
<br />
===== Using LUKS to format partitions with a keyfile =====<br />
<br />
When creating a new LUKS encrypted partition, a keyfile may be associated with the partition on its creation using:<br />
<br />
# cryptsetup luksFormat ''device'' ''/path/to/mykeyfile''<br />
<br />
See [[#Keyfiles]] for instructions on how to generate and manage keyfiles.<br />
<br />
==== Unlocking/Mapping LUKS partitions with the device mapper ====<br />
<br />
Once the LUKS partitions have been created, they can then be unlocked.<br />
<br />
The unlocking process will map the partitions to a new device name using the device mapper. This alerts the kernel that {{ic|''device''}} is actually an encrypted device and should be addressed through LUKS using the {{ic|/dev/mapper/''dm_name''}} so as not to overwrite the encrypted data. To guard against accidental overwriting, read about the possibilities to [[#Backup and restore|backup the cryptheader]] after finishing setup.<br />
<br />
In order to open an encrypted LUKS partition execute:<br />
<br />
# cryptsetup open ''device'' ''dm_name''<br />
<br />
You will then be prompted for the password to unlock the partition. Usually the device mapped name is descriptive of the function of the partition that is mapped. For example the following unlocks a root luks partition {{ic|/dev/sda1}} and maps it to device mapper named {{ic|root}}:<br />
<br />
# cryptsetup open /dev/sda1 root <br />
<br />
Once opened, the root partition device address would be {{ic|/dev/mapper/root}} instead of the partition (e.g. {{ic|/dev/sda1}}). <br />
<br />
For setting up LVM ontop the encryption layer the device file for the decrypted volume group would be anything like {{ic|/dev/mapper/root}} instead of {{ic|/dev/sda1}}. LVM will then give additional names to all logical volumes created, e.g. {{ic|/dev/lvmpool/root}} and {{ic|/dev/lvmpool/swap}}.<br />
<br />
In order to write encrypted data into the partition it must be accessed through the device mapped name. The first step of access will typically be to [[create a file system]]. For example:<br />
<br />
# mkfs -t ext4 /dev/mapper/root<br />
<br />
The device {{ic|/dev/mapper/root}} can then be [[mount]]ed like any other partition.<br />
<br />
To close the LUKS container, unmount the partition and do:<br />
<br />
# cryptsetup close root<br />
<br />
==== Using a TPM to store keys ====<br />
<br />
See [[Trusted Platform Module#Data-at-rest encryption with LUKS]].<br />
<br />
=== Encrypting devices with plain mode ===<br />
<br />
The creation and subsequent access of a ''dm-crypt'' plain mode encryption both require not more than using the ''cryptsetup'' {{ic|open}} action with correct [[#Encryption options for plain mode|parameters]]. The following shows that with two examples of non-root devices, but adds a quirk by stacking both (i.e. the second is created inside the first). Obviously, stacking the encryption doubles overhead. The usecase here is simply to illustrate another example of the cipher option usage. <br />
<br />
A first mapper is created with ''cryptsetup's'' plain-mode defaults, as described in the table's left column above <br />
<br />
{{hc|# cryptsetup --type plain -v open /dev/sdaX plain1|<br />
Enter passphrase: <br />
Command successful.<br />
}}<br />
<br />
Now we add the second block device inside it, using different encryption parameters and with an (optional) offset, create a file system and mount it <br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
/dev/sda <br />
├─/dev/sdaX <br />
│ └─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
# mkfs -t ext2 /dev/mapper/plain2<br />
# mount -t ext2 /dev/mapper/plain2 /mnt<br />
# echo "This is stacked. one passphrase per foot to shoot." > /mnt/stacked.txt<br />
<br />
We close the stack to check access works<br />
<br />
# cryptsetup close plain2<br />
# cryptsetup close plain1<br />
<br />
First, let us try to open the file system directly: <br />
<br />
# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/sdaX plain2<br />
<br />
{{hc|# mount -t ext2 /dev/mapper/plain2 /mnt|<br />
mount: wrong fs type, bad option, bad superblock on /dev/mapper/plain2,<br />
missing codepage or helper program, or other error<br />
}}<br />
<br />
Why that did not work? Because the "plain2" starting block ({{ic|10}}) is still encrypted with the cipher from "plain1". It can only be accessed via the stacked mapper. The error is arbitrary though, trying a wrong passphrase or wrong options will yield the same. For ''dm-crypt'' plain mode, the {{ic|open}} action will not error out itself. <br />
<br />
Trying again in correct order: <br />
<br />
# cryptsetup close plain2 # dysfunctional mapper from previous try<br />
<br />
{{hc|# cryptsetup --type plain open /dev/sdaX plain1|<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# mount /dev/mapper/plain2 /mnt && cat /mnt/stacked.txt|<br />
This is stacked. one passphrase per foot to shoot.<br />
}}<br />
<br />
''dm-crypt'' will handle stacked encryption with some mixed modes too. For example LUKS mode could be stacked on the "plain1" mapper. Its header would then be encrypted inside "plain1" when that is closed.<br />
<br />
Available for plain mode only is the option {{ic|--shared}}. With it a single device can be segmented into different non-overlapping mappers. We do that in the next example, using a ''loopaes'' compatible cipher mode for "plain2" this time: <br />
<br />
{{hc|# cryptsetup --type plain --offset 0 --size 1000 open /dev/sdaX plain1|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --offset 1000 --size 1000 --shared --cipher=aes-cbc-lmk --hash=sha256 open /dev/sdaX plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
dev/sdaX <br />
├─/dev/sdaX <br />
│ ├─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
As the device tree shows both reside on the same level, i.e. are not stacked and "plain2" can be opened individually.<br />
<br />
== Cryptsetup actions specific for LUKS ==<br />
<br />
=== Key management ===<br />
<br />
It is possible to define additional keys for the LUKS partition. This enables the user to create access keys for safe backup storage In so-called key escrow, one key is used for daily usage, another kept in escrow to gain access to the partition in case the daily passphrase is forgotten or a keyfile is lost/damaged. A different key-slot could also be used to grant access to a partition to a user by issuing a second key and later revoking it again. <br />
<br />
Once an encrypted partition has been created, the initial keyslot 0 is created (if no other was specified manually). Additional keyslots are numbered from 1 to 7. Which keyslots are used can be seen by issuing <br />
<br />
# cryptsetup luksDump /dev/''device''<br />
<br />
Where {{ic|''device''}} is the block device containing the LUKS header. This and all the following commands in this section work on header backup files as well.<br />
<br />
==== Adding LUKS keys ====<br />
<br />
Adding new keyslots is accomplished with the {{ic|luksAddKey}} action. For safety it will always, even for already unlocked devices, ask for a valid existing key (a passphrase for any existing slot) before a new one may be entered:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' [''/path/to/additionalkeyfile'']|<br />
Enter any passphrase:<br />
Enter new passphrase for key slot:<br />
Verify passphrase: <br />
}}<br />
<br />
If {{ic|''/path/to/additionalkeyfile''}} is given, cryptsetup will add a new keyslot for {{ic|''additionalkeyfile''}}. Otherwise it prompts for a new passphrase. To authorize the action with an existing ''keyfile'', the {{ic|--key-file}} or {{ic|-d}} option followed by the "old" {{ic|''keyfile''}} will try to unlock all available keyfile keyslots:<br />
<br />
# cryptsetup luksAddKey /dev/''device'' [''/path/to/additionalkeyfile''] -d ''/path/to/keyfile''<br />
<br />
If it is intended to use multiple keys and change or revoke them, the {{ic|--key-slot}} or {{ic|-S}} option may be used to specify the slot: <br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' -S 6|<br />
Enter any passphrase: <br />
Enter new passphrase for key slot: <br />
Verify passphrase:<br />
}}<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: ENABLED<br />
}}<br />
<br />
To show an associated action in this example, we decide to change the key right away: <br />
<br />
{{hc|# cryptsetup luksChangeKey /dev/''device'' -S 6|<br />
Enter LUKS passphrase to be changed: <br />
Enter new LUKS passphrase:<br />
}}<br />
<br />
before continuing to remove it.<br />
<br />
==== Removing LUKS keys ====<br />
<br />
There are three different actions to remove keys from the header: <br />
<br />
* {{ic|luksRemoveKey}} is used to remove a key by specifying its passphrase/key-file. <br />
* {{ic|luksKillSlot}} may be used to remove a key from a specific key slot (using another key). Obviously, this is extremely useful if you have forgotten a passphrase, lost a key-file, or have no access to it. <br />
* {{ic|luksErase}} is used to quickly remove '''all''' active keys. <br />
<br />
{{warning|<br />
* All above actions can be used to irrevocably delete the last active key for an encrypted device! <br />
* The {{ic|luksErase}} command was added in version 1.6.4 to quickly nuke access to the device. This action '''will not''' prompt for a valid passphrase! It will not [[dm-crypt/Drive preparation#Wipe LUKS header|wipe the LUKS header]], but all keyslots at once and you will, therefore, not be able to regain access unless you have a valid backup of the LUKS header.<br />
}}<br />
<br />
For above warning it is good to know the key we want to '''keep''' is valid. An easy check is to unlock the device with the {{ic|-v}} option, which will specify which slot it occupies: <br />
<br />
{{hc|# cryptsetup --test-passphrase -v open /dev/''device''|<br />
Enter passphrase for /dev/''device'': <br />
Key slot 1 unlocked.<br />
Command successful.<br />
}}<br />
<br />
Now we can remove the key added in the previous subsection using its passphrase: <br />
<br />
{{hc|# cryptsetup luksRemoveKey /dev/''device''|<br />
Enter LUKS passphrase to be deleted:<br />
}}<br />
<br />
If we had used the same passphrase for two keyslots, the first slot would be wiped now. Only executing it again would remove the second one. <br />
<br />
Alternatively, we can specify the key slot: <br />
<br />
{{hc|# cryptsetup luksKillSlot /dev/''device'' 6|<br />
Enter any remaining LUKS passphrase:<br />
}}<br />
<br />
Note that in both cases, no confirmation was required.<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: DISABLED<br />
}}<br />
<br />
To re-iterate the warning above: If the same passphrase had been used for key slots 1 and 6, both would be gone now.<br />
<br />
=== Backup and restore ===<br />
<br />
If the header of a LUKS encrypted partition gets destroyed, you will not be able to decrypt your data. It is just as much of a dilemma as forgetting the passphrase or damaging a key-file used to unlock the partition. Damage may occur by your own fault while re-partitioning the disk later or by third-party programs misinterpreting the partition table. Therefore, having a backup of the header and storing it on another disk might be a good idea.<br />
<br />
{{Note|If one of the LUKS-encrypted partitions' passphrases becomes compromised, you must revoke it on ''every'' copy of the cryptheader, even those you have backed up. Otherwise, a copy of the backed-up cryptheader that uses the compromised passphrase can be used to determine the master key which in turn can be used to decrypt the associated partition (even your actual partition, not only the backed-up version). On the other hand, if the master key gets compromised, you have to reencrypt your whole partition. See [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#6-backup-and-data-recovery LUKS FAQ] for further details.}}<br />
<br />
==== Backup using cryptsetup ====<br />
<br />
Cryptsetup's {{ic|luksHeaderBackup}} action stores a binary backup of the LUKS header and keyslot area:<br />
<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file ''/mnt/backup/file.img''<br />
<br />
where {{ic|''device''}} is the partition containing the LUKS volume.<br />
<br />
You can also back up the plain text header into ramfs and encrypt it with e.g. [[GPG]] before writing it to persistent storage:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/''tmp''<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file /root/''tmp''/''file''.img<br />
# gpg2 --recipient ''User_ID'' --encrypt /root/''tmp''/''file''.img <br />
# cp /root/''tmp''/''file''.img.gpg /mnt/''backup''/<br />
# umount /root/''tmp''<br />
<br />
{{Warning|[[tmpfs]] can swap to the disk in low memory situations, so it is not recommended here.}}<br />
<br />
==== Restore using cryptsetup ====<br />
<br />
{{Warning|Restoring the wrong header or restoring to an unencrypted partition will cause data loss! The action can not perform a check whether the header is actually the ''correct'' one for that particular device.}} <br />
<br />
In order to evade restoring a wrong header, you can ensure it does work by using it as a remote {{ic|--header}} first: <br />
<br />
{{hc|# cryptsetup -v --header /mnt/''backup''/''file''.img open /dev/''device'' test|<br />
Key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
# mount /dev/mapper/test /mnt/test && ls /mnt/test <br />
# umount /mnt/test <br />
# cryptsetup close test <br />
<br />
Now that the check succeeded, the restore may be performed: <br />
<br />
# cryptsetup luksHeaderRestore /dev/''device'' --header-backup-file ./mnt/''backup''/''file''.img<br />
<br />
Now that all the keyslot areas are overwritten; only active keyslots from the backup file are available after issuing the command.<br />
<br />
==== Manual backup and restore ====<br />
<br />
The header always resides at the beginning of the device and a backup can be performed without access to ''cryptsetup'' as well. First you have to find out the payload offset of the crypted partition:<br />
<br />
{{hc|# cryptsetup luksDump /dev/''device'' {{!}} grep "Payload offset"|<br />
Payload offset: 4040<br />
}}<br />
<br />
Second check the sector size of the drive<br />
<br />
{{hc|# fdisk -l /dev/''device'' {{!}} grep "Sector size"|<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
}}<br />
<br />
Now that you know the values, you can backup the header with a simple [[dd]] command:<br />
<br />
# dd if=/dev/''device'' of=/path/to/''file''.img bs=512 count=4040<br />
<br />
and store it safely.<br />
<br />
A restore can then be performed using the same values as when backing up:<br />
<br />
# dd if=./''file''.img of=/dev/''device'' bs=512 count=4040<br />
<br />
=== Re-encrypting devices ===<br />
<br />
{{Expansion|cryptsetup 2.2 using LUKS2 (with a 16 MiB header) supports online encryption/decryption/reencryption.[https://mirrors.edge.kernel.org/pub/linux/utils/cryptsetup/v2.2/v2.2.0-ReleaseNotes]}}<br />
<br />
{{Out of date|cryptsetup-reencrypt was removed in cryptsetup 2.5.0.[https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/v2.5.0-ReleaseNotes]}}<br />
<br />
The {{Pkg|cryptsetup}} package features two options for re-encryption.<br />
<br />
; cryptsetup reencrypt: Argument to {{ic|cryptsetup}} itself: Preferred method. Currently LUKS2 devices only. Actions can be performed online. Supports multiple parallel re-encryption jobs. Resilient to system failures. See {{man|8|cryptsetup}} for more information.<br />
<br />
; cryptsetup-reencrypt: Legacy tool, supports LUKS1 in addition to LUKS2. Actions can be performed on unmounted devices only. Single process at a time. Sensitive to system failures. See {{man|8|cryptsetup-reencrypt}} for more information. <br />
<br />
Both can be used to convert an existing unencrypted file system to a LUKS encrypted one or permanently remove LUKS encryption from a device (using {{ic|--decrypt}}). As its name suggests it can also be used to re-encrypt an existing LUKS encrypted device, though, re-encryption is not possible for a detached LUKS header or other encryption modes (e.g. plain-mode). For re-encryption it is possible to change the [[#Encryption options for LUKS mode]]. <br />
<br />
One application of re-encryption may be to secure the data again after a passphrase or [[#Keyfiles|keyfile]] has been compromised ''and'' one cannot be certain that no copy of the LUKS header has been obtained. For example, if only a passphrase has been shoulder-surfed but no physical/logical access to the device happened, it would be enough to change the respective passphrase/key only ([[#Key management]]). <br />
<br />
{{Warning|Always make sure a '''reliable backup''' is available and double-check options you specify before using the tool!}}<br />
<br />
The following shows an example to encrypt an unencrypted file system partition and a re-encryption of an existing LUKS device.<br />
<br />
==== Encrypt an existing unencrypted file system ====<br />
<br />
{{Tip|If you are trying to encrypt an existing root partition, you might want to create a separate and unencrypted boot partition which will be mounted to {{ic|/boot}} (see [[Dm-crypt/Encrypting an entire system#Preparing the boot partition]]). It is not strictly necessary but has a number of advantages:<br />
<br />
* If {{ic|/boot}} is located inside an encrypted root partition, the system will ask for the passphrase twice when the machine is powered on. The first time will happen when the boot loader attempts to read the files located inside encrypted {{ic|/boot}}, the second time will be when the kernel tries to mount the encrypted partition [https://opencraft.com/blog/tutorial-encrypting-an-existing-root-partition-in-ubuntu-with-dm-crypt-and-luks/]. This might not be the desired behaviour and can be prevented by having a separate and unencryted boot partition.<br />
* Some system restore applications (e.g., {{AUR|timeshift}}) will not work if {{ic|/boot}} is located inside an encryted partition [https://github.com/teejee2008/timeshift/issues/280].<br />
<br />
In short, create a partition with the size of at least 260 MiB if needed. See [[Partitioning#/boot]].}}<br />
<br />
A LUKS encryption header is always stored at the beginning of the device. Since an existing file system will usually be allocated all partition sectors, the first step is to shrink it to make space for the LUKS header.<br />
<br />
{{Expansion|cryptsetup man pages suggest using twice the LUKS2 header size. That implies 32 MiB and using {{ic|--reduce-device-size 32M}}}}<br />
<br />
The [[#Encryption options for LUKS mode|default]] LUKS2 header requires 16 MiB. If the current file system occupies all the available space, we will have to shrink it at least that much. To shrink an existing {{ic|ext4}} file system on {{ic|/dev/sdaX}} to its current possible minimum:<br />
<br />
# umount /mnt<br />
<br />
{{hc|# e2fsck -f /dev/sdaX|<br />
e2fsck 1.43-WIP (18-May-2015)<br />
Pass 1: Checking inodes, blocks, and sizes<br />
...<br />
/dev/sda6: 12/166320 files (0.0% non-contiguous), 28783/665062 blocks<br />
}}<br />
<br />
{{hc|# resize2fs -p -M /dev/sdaX|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/sdaX to 26347 (4k) blocks.<br />
The filesystem on /dev/sdaX is now 26347 (4k) blocks long.<br />
}}<br />
<br />
{{Tip|Shrinking to the minimum size with {{ic|-M}} might take very long. You might want to calculate a size just 32 MiB smaller than the current size instead of using {{ic|-M}}.}}<br />
<br />
{{Warning|The file system should be shrunk while the underlying device (e.g., a partition) should be kept at its original size. Some graphical tools (e.g., [[GParted]]) may resize both the file system and the partition, and data loss may occur after encryption.}}<br />
<br />
Now we encrypt it, using the default cipher we do not have to specify it explicitly:<br />
<br />
{{hc|# cryptsetup reencrypt --encrypt --reduce-device-size 16M /dev/sdaX|<nowiki><br />
<br />
WARNING!<br />
<br />
========<br />
<br />
This will overwrite data on LUKS2-temp-12345678-9012-3456-7890-123456789012.new irrevocably.<br />
<br />
Are you sure? (Type 'yes' in capital letters): YES<br />
Enter passphrase for LUKS2-temp-12345678-9012-3456-7890-123456789012.new: <br />
Verify passphrase: <br />
</nowiki>}}<br />
<br />
After it finished, the whole {{ic|/dev/sdaX}} partition is encrypted, not only the space the file system was shrunk to. As a final step we extend the original {{ic|ext4}} file system to occupy all available space again, on the now encrypted partition:<br />
<br />
{{hc|# cryptsetup open /dev/sdaX recrypt|<br />
Enter passphrase for /dev/sdaX: <br />
...<br />
}}<br />
<br />
{{hc|# resize2fs /dev/mapper/recrypt|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/mapper/recrypt to 664807 (4k) blocks.<br />
The filesystem on /dev/mapper/recrypt is now 664807 (4k) blocks long.<br />
}}<br />
<br />
# mount /dev/mapper/recrypt /mnt<br />
<br />
The file system is now ready to use. You may want to add it to your [[crypttab]].<br />
<br />
{{Tip|If you have just encrypted your root partition, you might need to perform a number of post-encryption adjustments.<br />
<br />
See [[Dm-crypt/Encrypting an entire system#Configuring mkinitcpio]], [[Dm-crypt/Encrypting an entire system#Configuring the boot loader]], and [[Dm-crypt/Encrypting an entire system#Configuring GRUB]].}}<br />
<br />
==== Re-encrypting an existing LUKS partition ====<br />
<br />
In this example an existing LUKS device is re-encrypted. <br />
<br />
{{Warning|Double-check you specify encryption options for correctly and ''never'' re-encrypt without a '''reliable backup'''!}}<br />
<br />
In order to re-encrypt a device with its existing encryption options, they do not need to be specified:<br />
{{bc|# cryptsetup reencrypt /dev/sdaX}}<br />
{{Note|For LUKS1 we will need to use the legacy tool:{{bc|# cryptsetup-reencrypt /dev/sdaX}}}}<br />
<br />
Existing keys are retained when re-encrypting a device with a different cipher and/or hash. Another use case is to re-encrypt LUKS devices which have non-current encryption options. Apart from above warning on specifying options correctly, the ability to change the LUKS header may also be limited by its size. For example, if the device was initially encrypted using a CBC mode cipher and 128 bit key-size, the LUKS header will be half the size of above mentioned {{ic|4096}} sectors: <br />
<br />
{{hc|# cryptsetup luksDump /dev/sdaX {{!}} grep -e "mode" -e "Payload" -e "MK bits"|<br />
Cipher mode: cbc-essiv:sha256<br />
Payload offset: '''2048'''<br />
MK bits: 128<br />
}}<br />
<br />
While it is possible to upgrade the encryption of such a device, it is currently only feasible in two steps. First, re-encrypting with the same encryption options, but using the {{ic|--reduce-device-size}} option to make further space for the larger LUKS header. Second, re-encypt the whole device again with the desired cipher. For this reason and the fact that a backup should be created in any case, creating a new, fresh encrypted device to restore into is always the faster option.<br />
<br />
=== Conversion from LUKS1 to LUKS2 and back ===<br />
<br />
The {{Pkg|cryptsetup}} package has {{ic|convert}} option that needed for conversion between LUKS1 and LUKS2 container types. The argument {{ic|--type}} is '''required'''.<br />
<br />
Migration from LUKS1 to LUKS2:<br />
<br />
# cryptsetup convert --type luks2 /dev/sdaX<br />
<br />
{{Note|The LUKS header size will be 2 MiB instead of 16 MiB.}}<br />
<br />
Rollback to LUKS1 (for example, to boot from [[GRUB#Encrypted /boot|GRUB with encrypted /boot]]):<br />
<br />
# cryptsetup convert --type luks1 /dev/sdaX<br />
<br />
{{Note|Conversion from LUKS2 to LUKS1 is '''not''' always possible. You may get the following error:<br />
Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible.<br />
}}<br />
<br />
== Resizing encrypted devices ==<br />
<br />
{{Expansion|This section should be rewritten to introduce resizing more generically. Perhaps work on it together with [[Resizing LVM-on-LUKS]].}}<br />
<br />
If a storage device encrypted with dm-crypt is being cloned (with a tool like dd) to another larger device, the underlying dm-crypt device must be resized to use the whole space. <br />
<br />
The destination device is /dev/sdX2 in this example, the whole available space adjacent to the partition will be used:<br />
<br />
# cryptsetup luksOpen /dev/sdX2 sdX2<br />
# cryptsetup resize sdX2<br />
<br />
Then the underlying file system must be resized.<br />
<br />
=== Loopback file system ===<br />
<br />
Assume that an encrypted loopback file system is stored in a file {{ic|/bigsecret}}, looped to {{ic|/dev/loop0}}, mapped to {{ic|secret}} and mounted on {{ic|/mnt/secret}}, as in the example at [[dm-crypt/Encrypting a non-root file system#File container]].<br />
<br />
If the container file is currently mapped and/or mounted, unmount and/or close it:<br />
<br />
# umount /mnt/secret<br />
# cryptsetup close secret<br />
# losetup -d /dev/loop0<br />
<br />
Next, expand the container file with the size of the data you want to add. In this example, the file will be expanded with 1M * 1024, which is 1G.<br />
<br />
{{Warning|Make absolutely sure to use '''two''' {{ic|>}}, instead of just one, or else you will overwrite the file instead of appending to it. Making a backup before this step is strongly recommended.}}<br />
<br />
# dd if=/dev/urandom bs=1M count=1024 | cat - >> /bigsecret<br />
<br />
Now map the container to the loop device:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
# cryptsetup open /dev/loop0 secret<br />
<br />
After this, resize the encrypted part of the container to the new maximum size of the container file:<br />
<br />
# cryptsetup resize secret<br />
<br />
Finally, perform a file system check and, if it is ok, resize it (example for ext2/3/4):<br />
<br />
# e2fsck -f /dev/mapper/secret<br />
# resize2fs /dev/mapper/secret<br />
<br />
You can now mount the container again:<br />
<br />
# mount /dev/mapper/secret /mnt/secret<br />
<br />
=== Integrity protected device ===<br />
<br />
If the device was formatted with integrity support (e.g., {{ic|--integrity hmac-sha256}}) and the backing block device is shrinked, it cannot be opened with this error: {{ic|device-mapper: reload ioctl on failed: Invalid argument}}.<br />
<br />
To fix this issue without wiping the device again, it can be formatted with the previous master key (keeping the per-sector tags valid).<br />
<br />
# cryptsetup luksDump /dev/sdX2 --dump-master-key --master-key-file=/tmp/masterkey-in-tmpfs.key<br />
# cryptsetup luksFormat /dev/sdX2 --type luks2 --integrity hmac-sha256 --master-key-file=/tmp/masterkey-in-tmpfs.key --integrity-no-wipe<br />
# rm /tmp/masterkey-in-tmpfs.key<br />
<br />
== Keyfiles ==<br />
<br />
{{Note|This section describes using a plaintext keyfile. If you want to encrypt your keyfile giving you two factor authentication see [[dm-crypt/Specialties#Using GPG, LUKS, or OpenSSL Encrypted Keyfiles|Using GPG or OpenSSL Encrypted Keyfiles]] for details, but please still read this section.}}<br />
<br />
'''What is a keyfile?'''<br />
<br />
A keyfile is a file whose data is used as the passphrase to unlock an encrypted volume.<br />
That means if such a file is lost or changed, decrypting the volume may no longer be possible.<br />
<br />
{{Tip|Define a passphrase in addition to the keyfile for backup access to encrypted volumes in the event the defined keyfile is lost or changed.}}<br />
<br />
'''Why use a keyfile?'''<br />
<br />
There are many kinds of keyfiles. Each type of keyfile used has benefits and disadvantages summarized below:<br />
<br />
=== Types of keyfiles ===<br />
<br />
==== passphrase ====<br />
<br />
This is a keyfile containing a simple passphrase. The benefit of this type of keyfile is that if the file is lost the data it contained is known and hopefully easily remembered by the owner of the encrypted volume. However the disadvantage is that this does not add any security over entering a passphrase during the initial system start.<br />
<br />
Example: {{ic|1234}}<br />
<br />
{{Note|The keyfile containing the passphrase must not have a newline in it. One option is to create it using <br />
<br />
# echo -n 'your_passphrase' > ''/path/to/keyfile''<br />
# chown root:root ''/path/to/keyfile''; chmod 400 ''/path/to/keyfile''<br />
<br />
If the file contains special characters such as a backslash, rather than escaping these, it is recommended to simply edit the key file directly entering or pasting the passphrase and then remove the trailing newline with a handy perl one-liner:<br />
<br />
# perl -pi -e 'chomp if eof' ''/path/to/keyfile''<br />
}}<br />
<br />
==== randomtext ====<br />
<br />
This is a keyfile containing a block of random characters. The benefit of this type of keyfile is that it is much more resistant to dictionary attacks than a simple passphrase. An additional strength of keyfiles can be utilized in this situation which is the length of data used. Since this is not a string meant to be memorized by a person for entry, it is trivial to create files containing thousands of random characters as the key. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase.<br />
<br />
Example: {{ic|fjqweifj830149-57 819y4my1-38t1934yt8-91m 34co3;t8y;9p3y-}}<br />
<br />
==== binary ====<br />
<br />
This is a binary file that has been defined as a keyfile. When identifying files as candidates for a keyfile, it is recommended to choose files that are relatively static such as photos, music, video clips. The benefit of these files is that they serve a dual function which can make them harder to identify as keyfiles. Instead of having a text file with a large amount of random text, the keyfile would look like a regular image file or music clip to the casual observer. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase. Additionally, there is a theoretical loss of randomness when compared to a randomly generated text file. This is due to the fact that images, videos and music have some intrinsic relationship between neighboring bits of data that does not exist for a random text file. However this is controversial and has never been exploited publicly.<br />
<br />
Example: images, text, video, ...<br />
<br />
=== Creating a keyfile with random characters ===<br />
<br />
==== Storing the keyfile on a file system ====<br />
<br />
A keyfile can be of arbitrary content and size. <br />
<br />
Here [[dd]] is used to generate a keyfile of 2048 random bytes, storing it in the file {{ic|/etc/mykeyfile}}:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/etc/mykeyfile iflag=fullblock<br />
<br />
If you are planning to store the keyfile on an external device, you can also simply change the outputfile to the corresponding directory:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/media/usbstick/mykeyfile iflag=fullblock<br />
<br />
To deny any access for other users than {{ic|root}}:<br />
<br />
# chmod 600 /etc/mykeyfile<br />
<br />
===== Securely overwriting stored keyfiles =====<br />
<br />
If you stored your temporary keyfile on a physical storage device, and want to delete it, remember to not just remove the keyfile later on, but use something like<br />
<br />
# shred --remove --zero mykeyfile<br />
<br />
to securely overwrite it. For overaged file systems like FAT or ext2 this will suffice while in the case of journaling file systems, flash memory hardware and other cases it is highly recommended to [[Securely wipe disk|wipe the entire device]].<br />
<br />
==== Storing the keyfile in ramfs ====<br />
<br />
Alternatively, you can mount a ramfs for storing the keyfile temporarily:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/myramfs<br />
# cd /root/myramfs<br />
<br />
The advantage is that it resides in RAM and not on a physical disk, therefore it can not be recovered after unmounting the ramfs. After copying the keyfile to another secure and persistent file system, unmount the ramfs again with<br />
<br />
# umount /root/myramfs<br />
<br />
=== Configuring LUKS to make use of the keyfile ===<br />
<br />
Add a keyslot for the keyfile to the LUKS header:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/sda2 /etc/mykeyfile|<br />
Enter any LUKS passphrase:<br />
key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
=== Manually unlocking a partition using a keyfile ===<br />
<br />
Use the {{ic|--key-file}} option when opening the LUKS device:<br />
<br />
# cryptsetup open /dev/sda2 ''dm_name'' --key-file /etc/mykeyfile<br />
<br />
=== Unlocking the root partition at boot ===<br />
<br />
This is simply a matter of configuring [[mkinitcpio]] to include the necessary modules or files and configuring the [[dm-crypt/System configuration#cryptkey|cryptkey]] [[kernel parameter]] to know where to find the keyfile.<br />
<br />
Two cases are covered below:<br />
<br />
# Using a keyfile stored on an external medium (e.g. a USB stick)<br />
# Using a keyfile embedded in the initramfs<br />
<br />
==== With a keyfile stored on an external media ====<br />
<br />
===== Configuring mkinitcpio =====<br />
<br />
You have to add the kernel module for the drive's [[file system]] to the [[mkinitcpio#MODULES|MODULES array]] in {{ic|/etc/mkinitcpio.conf}}. For example, add {{ic|ext4}} if the file system is [[Ext4]] or {{ic|vfat}} in case it is [[FAT]]:<br />
<br />
MODULES=(vfat)<br />
<br />
If there are messages about bad superblock and bad codepage at boot, then you need an extra codepage module to be loaded. For instance, you may need {{ic|nls_iso8859-1}} module for {{ic|iso8859-1}} codepage.<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
===== Configuring the kernel parameters =====<br />
<br />
* For a busybox-based initramfs using the [[dm-crypt/System configuration#Using encrypt hook|encrypt]] hook, see [[dm-crypt/System configuration#cryptkey]].<br />
* For a systemd based initramfs using the [[sd-encrypt]] hook, see [[dm-crypt/System configuration#rd.luks.key]].<br />
<br />
==== With a keyfile embedded in the initramfs ====<br />
<br />
{{Warning|Use an embedded keyfile '''only''' if you protect the keyfile sufficiently by:<br />
* Using some form of authentication earlier in the boot process. Otherwise auto-decryption will occur, defeating completely the purpose of block device encryption.<br />
* {{ic|/boot}} is encrypted. Otherwise root on a different installation (including the [[Installation guide#Boot the live environment|live environment]]) can extract your key from the initramfs, and unlock the device without any other authentication.}}<br />
<br />
This method allows to use a specially named keyfile that will be embedded in the [[initramfs]] and picked up by the {{ic|encrypt}} [[Mkinitcpio#HOOKS|hook]] to unlock the root file system ({{ic|cryptdevice}}) automatically. It may be useful to apply when using the [[GRUB#Encrypted /boot|GRUB early cryptodisk]] feature, in order to avoid entering two passphrases during boot.<br />
<br />
The {{ic|encrypt}} hook lets the user specify a keyfile with the {{ic|cryptkey}} kernel parameter: in the case of initramfs, the syntax is {{ic|rootfs:''/path/to/keyfile''}}. See [[dm-crypt/System configuration#cryptkey]]. Besides, this kernel parameter defaults to use {{ic|/crypto_keyfile.bin}}, and if the initramfs contains a valid key with this name, decryption will occur automatically without the need to configure the {{ic|cryptkey}} parameter.<br />
<br />
If using {{ic|sd-encrypt}} instead of {{ic|encrypt}}, specify the location of the keyfile with the {{ic|rd.luks.key}} kernel parameter: in the case of initramfs, the syntax is {{ic|''/path/to/keyfile''}}. See [[dm-crypt/System configuration#rd.luks.key]]. This kernel parameter defaults to using {{ic|/etc/cryptsetup-keys.d/''name''.key}} (where {{ic|''name''}} is the {{ic|''dm_name''}} used for decryption in [[#Encrypting devices with cryptsetup]]) and can be omitted if initramfs contains a valid key with this path.<br />
<br />
[[#Creating a keyfile with random characters|Generate the keyfile]], give it suitable permissions and [[#Adding LUKS keys|add it as a LUKS key]]:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/crypto_keyfile.bin iflag=fullblock<br />
# chmod 600 /crypto_keyfile.bin<br />
# cryptsetup luksAddKey /dev/sdX# /crypto_keyfile.bin<br />
<br />
{{Note|The initramfs is generated by mkinitcpio with {{ic|600}} [[permissions]] by default, so regular users are not able to read the keyfile via the generated initramfs.}}<br />
<br />
Include the key in [[mkinitcpio#BINARIES and FILES|mkinitcpio's FILES array]]:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/crypto_keyfile.bin)<br />
}}<br />
<br />
Finally [[regenerate the initramfs]].<br />
<br />
On the next reboot you should only have to enter your container decryption passphrase once.<br />
<br />
([https://www.pavelkogan.com/2014/05/23/luks-full-disk-encryption/#bonus-login-once source])</div>PXfhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Device_encryption&diff=746478Dm-crypt/Device encryption2022-09-16T06:03:40Z<p>PXf: /* Key management */ typo addition -> additional</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data-at-rest encryption]]<br />
[[es:Dm-crypt (Español)/Device encryption]]<br />
[[ja:Dm-crypt/デバイスの暗号化]]<br />
[[pl:Dm-crypt (Polski)/Device encryption]]<br />
[[pt:Dm-crypt (Português)/Device encryption]]<br />
[[zh-hans:Dm-crypt (简体中文)/Device encryption]]<br />
This section covers how to manually utilize ''dm-crypt'' from the command line to encrypt a system.<br />
<br />
== Preparation ==<br />
<br />
Before using {{pkg|cryptsetup}}, always make sure the {{ic|dm_crypt}} [[kernel module]] is loaded.<br />
<br />
== Cryptsetup usage ==<br />
<br />
''Cryptsetup'' is the command line tool to interface with ''dm-crypt'' for creating, accessing and managing encrypted devices. The tool was later expanded to support different encryption types that rely on the Linux kernel '''d'''evice-'''m'''apper and the '''crypt'''ographic modules. The most notable expansion was for the Linux Unified Key Setup (LUKS) extension, which stores all of the needed setup information for dm-crypt on the disk itself and abstracts partition and key management in an attempt to improve ease of use. Devices accessed via the device-mapper are called block devices. For further information see [[Data-at-rest encryption#Block device encryption]]. <br />
<br />
The tool is used as follows: <br />
<br />
# cryptsetup ''OPTIONS'' ''action'' ''action-specific-options'' ''device'' ''dmname''<br />
<br />
It has compiled-in defaults for the options and the encryption mode, which will be used if no others are specified on the command line. Have a look at <br />
<br />
$ cryptsetup --help <br />
<br />
which lists options, actions and the default parameters for the encryption modes in that order. A full list of options can be found on the man page.<br />
Since different parameters are required or optional, depending on encryption mode and action, the following sections point out differences further. Block device encryption is fast, but speed matters a lot too. Since changing an encryption cipher of a block device after setup is difficult, it is important to check ''dm-crypt'' performance for the individual parameters in advance: <br />
<br />
$ cryptsetup benchmark <br />
<br />
can give guidance on deciding for an algorithm and key-size prior to installation. If certain AES ciphers excel with a considerable higher throughput, these are probably the ones with hardware support in the CPU.<br />
<br />
{{Tip|You may want to practise encrypting a virtual hard drive in a [[virtual machine]] when learning.}}<br />
<br />
=== Cryptsetup passphrases and keys ===<br />
<br />
An encrypted block device is protected by a key. A key is either: <br />
<br />
* a passphrase: see [[Security#Passwords]].<br />
* a keyfile, see [[#Keyfiles]].<br />
<br />
Both key types have default maximum sizes: passphrases can be up to 512 characters and keyfiles up to 8192 KiB. <br />
<br />
An important distinction of ''LUKS'' to note at this point is that the key is used to unlock the master-key of a LUKS-encrypted device and can be changed with root access. Other encryption modes do not support changing the key after setup, because they do not employ a master-key for the encryption. See [[Data-at-rest encryption#Block device encryption]] for details.<br />
<br />
== Encryption options with dm-crypt ==<br />
<br />
''Cryptsetup'' supports different encryption operating modes to use with ''dm-crypt'': <br />
<br />
* {{ic|--type luks}} for using the default LUKS format version (LUKS1 with {{Pkg|cryptsetup}} < 2.1.0, LUKS2 with {{Pkg|cryptsetup}} ≥ 2.1.0),<br />
* {{ic|--type luks1}} for using LUKS1, the most common version of LUKS,<br />
* {{ic|--type luks2}} for using LUKS2, the latest available version of LUKS that allows additional extensions,<br />
* {{ic|--type plain}} for using dm-crypt plain mode, <br />
* {{ic|--type loopaes}} for a loopaes legacy mode, <br />
* {{ic|--type tcrypt}} for a [[TrueCrypt]] compatibility mode.<br />
* {{ic|--type bitlk}} for a [[Wikipedia:BitLocker|BitLocker]] compatibility mode. See {{man|8|cryptsetup|BITLK (Windows BitLocker-compatible) EXTENSION (EXPERIMENTAL)}}.<br />
<br />
The basic cryptographic options for encryption cipher and hashes available can be used for all modes and rely on the kernel cryptographic backend features. All that are loaded and available to use as options at runtime can be viewed with:<br />
<br />
$ less /proc/crypto <br />
<br />
{{Tip|If the list is short, execute {{ic|$ cryptsetup benchmark}} which will trigger loading available modules.}}<br />
<br />
The following introduces encryption options for the {{ic|luks}}, {{ic|luks1}}, {{ic|luks2}} and {{ic|plain}} modes. Note that the tables list options used in the respective examples in this article and not all available ones.<br />
<br />
=== Encryption options for LUKS mode ===<br />
<br />
The ''cryptsetup'' action to set up a new dm-crypt device in LUKS encryption mode is {{ic|luksFormat}}. Unlike what the name implies, it does not format the device, but sets up the LUKS device header and encrypts the master-key with the desired cryptographic options. <br />
<br />
In order to create a new LUKS container with the compiled-in defaults listed by {{ic|cryptsetup --help}}, simply execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
As of cryptsetup 2.4.0, this is equivalent to: <br />
<br />
# cryptsetup --type luks2 --cipher aes-xts-plain64 --hash sha256 --iter-time 2000 --key-size 256 --pbkdf argon2id --use-urandom --verify-passphrase luksFormat ''device''<br />
<br />
Defaults are compared with a cryptographically higher specification example in the table below, with accompanying comments: <br />
<br />
{| class="wikitable"<br />
! Options !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-xts-plain64}}<br />
| {{ic|aes-xts-plain64}}<br />
| [https://www.kernel.org/pub/linux/utils/cryptsetup/v1.6/v1.6.0-ReleaseNotes Release 1.6.0] changed the defaults to an AES [[Data-at-rest encryption#Ciphers and modes of operation|cipher]] in [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS]] mode (see item 5.16 [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects of the FAQ]). It is advised against using the previous default {{ic|--cipher aes-cbc-essiv}} because of its known [[wikipedia:Disk encryption theory#Cipher-block chaining (CBC)|issues]] and practical [https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ attacks] against them.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
| {{ic|256}} ({{ic|512}} for XTS)<br />
| {{ic|512}}<br />
| By default a 512 bit key-size is used for XTS ciphers. Note however that [[wikipedia:Disk encryption theory#XEX-based tweaked-codebook mode with ciphertext stealing (XTS)|XTS splits the supplied key in half]], so this results in AES-256 being used.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|sha256}}<br />
| {{ic|sha512}}<br />
| Hash algorithm used for [[Data-at-rest encryption#Cryptographic metadata|key derivation]]. Release 1.7.0 changed defaults from {{ic|sha1}} to {{ic|sha256}} "''not for security reasons [but] mainly to prevent compatibility problems on hardened systems where SHA1 is already [being] phased out''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. The former default of {{ic|sha1}} can still be used for compatibility with older versions of ''cryptsetup'' since it is [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects considered secure] (see item 5.20). <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --iter-time<br />
-i<br />
| {{ic|2000}}<br />
| {{ic|5000}}<br />
| Number of milliseconds to spend with PBKDF2 passphrase processing. Release 1.7.0 changed defaults from {{ic|1000}} to {{ic|2000}} to "''try to keep PBKDF2 iteration count still high enough and also still acceptable for users.''"[https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.0-ReleaseNotes]. This option is only relevant for LUKS operations that set or change passphrases, such as {{ic|luksFormat}} or {{ic|luksAddKey}}. Specifying 0 as parameter selects the compiled-in default..<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --use-urandom<br />
| {{ic|--use-urandom}}<br />
| {{ic|--use-random}}<br />
| Selects which [[random number generator]] to use. Note that [https://lwn.net/Articles/808575/ /dev/random blocking pool has been removed]. Therefore, {{ic|--use-random}} flag is now equivalent to {{ic|--use-urandom}}.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --verify-passphrase<br />
-y<br />
| Yes<br />
| -<br />
| Enabled by default in Arch Linux for {{ic|luksFormat}} and {{ic|luksAddKey}}.<br />
|}<br />
<br />
The properties of LUKS features and options are described in the [https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification LUKS1] (pdf) and [https://gitlab.com/cryptsetup/cryptsetup/blob/master/docs/on-disk-format-luks2.pdf LUKS2] (pdf) specifications.<br />
<br />
{{Tip|The project developers' [https://mbroz.fedorapeople.org/talks/DevConf2016/devconf2016-luks2.pdf devconfcz2016] (pdf) presentation summarizes the motivation for the major specification update to LUKS2.}}<br />
<br />
==== Iteration time ====<br />
<br />
From [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#2-setup cryptsetup FAQ§2.1] and [https://gitlab.com/cryptsetup/cryptsetup/-/wikis/FrequentlyAskedQuestions#3-common-problems §3.4]:<br />
<br />
:The unlock time for a key-slot [...] is calculated when setting a passphrase. By default it is 1 second (2 seconds for LUKS2). [...]<br />
:Passphrase iteration count is based on time and hence security level depends on CPU power of the system the LUKS container is created on. [...]<br />
:If you set a passphrase on a fast machine and then unlock it on a slow machine, the unlocking time can be much longer.<br />
<br />
As such, it is better to always create a container on the machine where it will be most often accessed.<br />
<br />
Read the rest of those sections for advice on how to correctly adjust the iteration count should the need arise.<br />
<br />
==== Sector size ====<br />
<br />
See [[Advanced Format#dm-crypt]].<br />
<br />
=== Encryption options for plain mode ===<br />
<br />
In dm-crypt ''plain'' mode, there is no master-key on the device, hence, there is no need to set it up. Instead the encryption options to be employed are used directly to create the mapping between an encrypted disk and a named device. The mapping can be created against a partition or a full device. In the latter case not even a partition table is needed. <br />
<br />
To create a ''plain'' mode mapping with cryptsetup's default parameters: <br />
<br />
# cryptsetup ''options'' open --type plain ''device'' ''dmname''<br />
<br />
Executing it will prompt for a password, which should have very high entropy. Below a comparison of default parameters with the example in [[dm-crypt/Encrypting an entire system#Plain dm-crypt]].<br />
<br />
{| class="wikitable"<br />
! Option !! Cryptsetup 2.1.0 defaults !! Example !! Comment<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --hash<br />
-h<br />
| {{ic|ripemd160}}<br />
| -<br />
| The hash is used to create the key from the passphrase; it is not used on a keyfile. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --cipher<br />
-c<br />
| {{ic|aes-cbc-essiv:sha256}}<br />
| {{ic|aes-xts-plain64}}<br />
| The cipher consists of three parts: cipher-chainmode-IV generator. Please see [[Data-at-rest encryption#Ciphers and modes of operation]] for an explanation of these settings, and the [https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt DMCrypt documentation] for some of the options available. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-size<br />
-s<br />
|{{ic|256}}<br />
|{{ic|512}}<br />
|The key size (in bits). The size will depend on the cipher being used and also the chainmode in use. Xts mode requires twice the key size of cbc. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --size<br />
-b<br />
|real size of target disk<br />
|{{ic|2048}} (mapped device will be 512B×2048=1MiB)<br />
|Limit the maximum size of the device (in 512-byte sectors).<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --offset<br />
-o<br />
|{{ic|0}}<br />
|{{ic|0}}<br />
|The offset from the beginning of the target disk (in 512-byte sectors) from which to start the mapping.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --skip<br />
-p<br />
|{{ic|0}}<br />
|{{ic|2048}} (512B×2048=1MiB will be skipped)<br />
|The number of 512-byte sectors of encrypted data to skip at the beginning.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --key-file<br />
-d<br />
| default uses a passphrase<br />
| {{ic|/dev/sd''Z''}} (or e.g. {{ic|/boot/keyfile.enc}})<br />
|The device or file to be used as a key. See [[#Keyfiles]] for further details.<br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-offset<br />
| {{ic|0}}<br />
| {{ic|0}}<br />
| Offset from the beginning of the file where the key starts (in bytes). This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|-<br />
! style="text-align:right;white-space:nowrap;" | --keyfile-size<br />
-l<br />
|{{ic|8192kB}}<br />
| - (default applies)<br />
| Limits the bytes read from the key file. This option is supported from ''cryptsetup'' 1.6.7 onwards. <br />
|}<br />
<br />
Using the device {{ic|/dev/sd''X''}}, the above right column example results in:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sd''Z'' --key-size=512 open --type=plain /dev/sdX enc<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, hash and key file details. We can now check that the mapping has been made:<br />
<br />
# fdisk -l<br />
<br />
An entry should now exist for {{ic|/dev/mapper/enc}}.<br />
<br />
== Encrypting devices with cryptsetup ==<br />
<br />
This section shows how to employ the options for creating new encrypted block devices and accessing them manually. <br />
<br />
{{Warning|GRUB's support for LUKS2 is limited; see [[GRUB#Encrypted /boot]] for details. Use LUKS1 ({{ic|1=cryptsetup luksFormat --type luks1}}) for partitions that GRUB will need to unlock.}}<br />
<br />
=== Encrypting devices with LUKS mode ===<br />
<br />
==== Formatting LUKS partitions ====<br />
<br />
In order to setup a partition as an encrypted LUKS partition execute:<br />
<br />
# cryptsetup luksFormat ''device''<br />
<br />
You will then be prompted to enter a password and verify it.<br />
<br />
See [[#Encryption options for LUKS mode]] for command line options.<br />
<br />
You can check the results with:<br />
<br />
# cryptsetup luksDump ''device''<br />
<br />
You will note that the dump not only shows the cipher header information, but also the key-slots in use for the LUKS partition. <br />
<br />
The following example will create an encrypted root partition on {{ic|/dev/sda1}} using the default AES cipher in XTS mode with an effective 256-bit encryption <br />
<br />
# cryptsetup -s 512 luksFormat /dev/sda1<br />
<br />
===== Using LUKS to format partitions with a keyfile =====<br />
<br />
When creating a new LUKS encrypted partition, a keyfile may be associated with the partition on its creation using:<br />
<br />
# cryptsetup luksFormat ''device'' ''/path/to/mykeyfile''<br />
<br />
See [[#Keyfiles]] for instructions on how to generate and manage keyfiles.<br />
<br />
==== Unlocking/Mapping LUKS partitions with the device mapper ====<br />
<br />
Once the LUKS partitions have been created, they can then be unlocked.<br />
<br />
The unlocking process will map the partitions to a new device name using the device mapper. This alerts the kernel that {{ic|''device''}} is actually an encrypted device and should be addressed through LUKS using the {{ic|/dev/mapper/''dm_name''}} so as not to overwrite the encrypted data. To guard against accidental overwriting, read about the possibilities to [[#Backup and restore|backup the cryptheader]] after finishing setup.<br />
<br />
In order to open an encrypted LUKS partition execute:<br />
<br />
# cryptsetup open ''device'' ''dm_name''<br />
<br />
You will then be prompted for the password to unlock the partition. Usually the device mapped name is descriptive of the function of the partition that is mapped. For example the following unlocks a root luks partition {{ic|/dev/sda1}} and maps it to device mapper named {{ic|root}}:<br />
<br />
# cryptsetup open /dev/sda1 root <br />
<br />
Once opened, the root partition device address would be {{ic|/dev/mapper/root}} instead of the partition (e.g. {{ic|/dev/sda1}}). <br />
<br />
For setting up LVM ontop the encryption layer the device file for the decrypted volume group would be anything like {{ic|/dev/mapper/root}} instead of {{ic|/dev/sda1}}. LVM will then give additional names to all logical volumes created, e.g. {{ic|/dev/lvmpool/root}} and {{ic|/dev/lvmpool/swap}}.<br />
<br />
In order to write encrypted data into the partition it must be accessed through the device mapped name. The first step of access will typically be to [[create a file system]]. For example:<br />
<br />
# mkfs -t ext4 /dev/mapper/root<br />
<br />
The device {{ic|/dev/mapper/root}} can then be [[mount]]ed like any other partition.<br />
<br />
To close the LUKS container, unmount the partition and do:<br />
<br />
# cryptsetup close root<br />
<br />
==== Using a TPM to store keys ====<br />
<br />
See [[Trusted Platform Module#Data-at-rest encryption with LUKS]].<br />
<br />
=== Encrypting devices with plain mode ===<br />
<br />
The creation and subsequent access of a ''dm-crypt'' plain mode encryption both require not more than using the ''cryptsetup'' {{ic|open}} action with correct [[#Encryption options for plain mode|parameters]]. The following shows that with two examples of non-root devices, but adds a quirk by stacking both (i.e. the second is created inside the first). Obviously, stacking the encryption doubles overhead. The usecase here is simply to illustrate another example of the cipher option usage. <br />
<br />
A first mapper is created with ''cryptsetup's'' plain-mode defaults, as described in the table's left column above <br />
<br />
{{hc|# cryptsetup --type plain -v open /dev/sdaX plain1|<br />
Enter passphrase: <br />
Command successful.<br />
}}<br />
<br />
Now we add the second block device inside it, using different encryption parameters and with an (optional) offset, create a file system and mount it <br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
/dev/sda <br />
├─/dev/sdaX <br />
│ └─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
# mkfs -t ext2 /dev/mapper/plain2<br />
# mount -t ext2 /dev/mapper/plain2 /mnt<br />
# echo "This is stacked. one passphrase per foot to shoot." > /mnt/stacked.txt<br />
<br />
We close the stack to check access works<br />
<br />
# cryptsetup close plain2<br />
# cryptsetup close plain1<br />
<br />
First, let us try to open the file system directly: <br />
<br />
# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/sdaX plain2<br />
<br />
{{hc|# mount -t ext2 /dev/mapper/plain2 /mnt|<br />
mount: wrong fs type, bad option, bad superblock on /dev/mapper/plain2,<br />
missing codepage or helper program, or other error<br />
}}<br />
<br />
Why that did not work? Because the "plain2" starting block ({{ic|10}}) is still encrypted with the cipher from "plain1". It can only be accessed via the stacked mapper. The error is arbitrary though, trying a wrong passphrase or wrong options will yield the same. For ''dm-crypt'' plain mode, the {{ic|open}} action will not error out itself. <br />
<br />
Trying again in correct order: <br />
<br />
# cryptsetup close plain2 # dysfunctional mapper from previous try<br />
<br />
{{hc|# cryptsetup --type plain open /dev/sdaX plain1|<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --cipher=serpent-xts-plain64 --hash=sha256 --key-size=256 --offset=10 open /dev/mapper/plain1 plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# mount /dev/mapper/plain2 /mnt && cat /mnt/stacked.txt|<br />
This is stacked. one passphrase per foot to shoot.<br />
}}<br />
<br />
''dm-crypt'' will handle stacked encryption with some mixed modes too. For example LUKS mode could be stacked on the "plain1" mapper. Its header would then be encrypted inside "plain1" when that is closed.<br />
<br />
Available for plain mode only is the option {{ic|--shared}}. With it a single device can be segmented into different non-overlapping mappers. We do that in the next example, using a ''loopaes'' compatible cipher mode for "plain2" this time: <br />
<br />
{{hc|# cryptsetup --type plain --offset 0 --size 1000 open /dev/sdaX plain1|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|1=# cryptsetup --type plain --offset 1000 --size 1000 --shared --cipher=aes-cbc-lmk --hash=sha256 open /dev/sdaX plain2|2=<br />
Enter passphrase:<br />
}}<br />
<br />
{{hc|# lsblk -p|<br />
NAME <br />
dev/sdaX <br />
├─/dev/sdaX <br />
│ ├─/dev/mapper/plain1 <br />
│ └─/dev/mapper/plain2 <br />
...<br />
}}<br />
<br />
As the device tree shows both reside on the same level, i.e. are not stacked and "plain2" can be opened individually.<br />
<br />
== Cryptsetup actions specific for LUKS ==<br />
<br />
=== Key management ===<br />
<br />
It is possible to define additional keys for the LUKS partition. This enables the user to create access keys for safe backup storage In so-called key escrow, one key is used for daily usage, another kept in escrow to gain access to the partition in case the daily passphrase is forgotten or a keyfile is lost/damaged. A different key-slot could also be used to grant access to a partition to a user by issuing a second key and later revoking it again. <br />
<br />
Once an encrypted partition has been created, the initial keyslot 0 is created (if no other was specified manually). Additional keyslots are numbered from 1 to 7. Which keyslots are used can be seen by issuing <br />
<br />
# cryptsetup luksDump /dev/''device''<br />
<br />
Where {{ic|''device''}} is the block device containing the LUKS header. This and all the following commands in this section work on header backup files as well.<br />
<br />
==== Adding LUKS keys ====<br />
<br />
Adding new keyslots is accomplished using cryptsetup with the {{ic|luksAddKey}} action. For safety it will always, i.e. also for already unlocked devices, ask for a valid existing key ("any passphrase") before a new one may be entered:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' (''/path/to/''additionalkeyfile'')|<br />
Enter any passphrase:<br />
Enter new passphrase for key slot:<br />
Verify passphrase: <br />
}}<br />
<br />
If {{ic|''/path/to/additionalkeyfile''}} is given, cryptsetup will add a new keyslot for {{ic|''additionalkeyfile''}}. Otherwise a new passphrase will be prompted for twice. For using an existing ''keyfile'' to authorize the action, the {{ic|--key-file}} or {{ic|-d}} option followed by the "old" {{ic|''keyfile''}} will try to unlock all available keyfile keyslots:<br />
<br />
# cryptsetup luksAddKey /dev/''device'' (''/path/to/additionalkeyfile'') -d ''/path/to/keyfile''<br />
<br />
If it is intended to use multiple keys and change or revoke them, the {{ic|--key-slot}} or {{ic|-S}} option may be used to specify the slot: <br />
<br />
{{hc|# cryptsetup luksAddKey /dev/''device'' -S 6|<br />
Enter any passphrase: <br />
Enter new passphrase for key slot: <br />
Verify passphrase:<br />
}}<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: ENABLED<br />
}}<br />
<br />
To show an associated action in this example, we decide to change the key right away: <br />
<br />
{{hc|# cryptsetup luksChangeKey /dev/''device'' -S 6|<br />
Enter LUKS passphrase to be changed: <br />
Enter new LUKS passphrase:<br />
}}<br />
<br />
before continuing to remove it.<br />
<br />
==== Removing LUKS keys ====<br />
<br />
There are three different actions to remove keys from the header: <br />
<br />
* {{ic|luksRemoveKey}} is used to remove a key by specifying its passphrase/key-file. <br />
* {{ic|luksKillSlot}} may be used to remove a key from a specific key slot (using another key). Obviously, this is extremely useful if you have forgotten a passphrase, lost a key-file, or have no access to it. <br />
* {{ic|luksErase}} is used to quickly remove '''all''' active keys. <br />
<br />
{{warning|<br />
* All above actions can be used to irrevocably delete the last active key for an encrypted device! <br />
* The {{ic|luksErase}} command was added in version 1.6.4 to quickly nuke access to the device. This action '''will not''' prompt for a valid passphrase! It will not [[dm-crypt/Drive preparation#Wipe LUKS header|wipe the LUKS header]], but all keyslots at once and you will, therefore, not be able to regain access unless you have a valid backup of the LUKS header.<br />
}}<br />
<br />
For above warning it is good to know the key we want to '''keep''' is valid. An easy check is to unlock the device with the {{ic|-v}} option, which will specify which slot it occupies: <br />
<br />
{{hc|# cryptsetup --test-passphrase -v open /dev/''device''|<br />
Enter passphrase for /dev/''device'': <br />
Key slot 1 unlocked.<br />
Command successful.<br />
}}<br />
<br />
Now we can remove the key added in the previous subsection using its passphrase: <br />
<br />
{{hc|# cryptsetup luksRemoveKey /dev/''device''|<br />
Enter LUKS passphrase to be deleted:<br />
}}<br />
<br />
If we had used the same passphrase for two keyslots, the first slot would be wiped now. Only executing it again would remove the second one. <br />
<br />
Alternatively, we can specify the key slot: <br />
<br />
{{hc|# cryptsetup luksKillSlot /dev/''device'' 6|<br />
Enter any remaining LUKS passphrase:<br />
}}<br />
<br />
Note that in both cases, no confirmation was required.<br />
<br />
{{hc|# cryptsetup luksDump /dev/sda8 {{!}} grep 'Slot 6'|<br />
Key Slot 6: DISABLED<br />
}}<br />
<br />
To re-iterate the warning above: If the same passphrase had been used for key slots 1 and 6, both would be gone now.<br />
<br />
=== Backup and restore ===<br />
<br />
If the header of a LUKS encrypted partition gets destroyed, you will not be able to decrypt your data. It is just as much of a dilemma as forgetting the passphrase or damaging a key-file used to unlock the partition. Damage may occur by your own fault while re-partitioning the disk later or by third-party programs misinterpreting the partition table. Therefore, having a backup of the header and storing it on another disk might be a good idea.<br />
<br />
{{Note|If one of the LUKS-encrypted partitions' passphrases becomes compromised, you must revoke it on ''every'' copy of the cryptheader, even those you have backed up. Otherwise, a copy of the backed-up cryptheader that uses the compromised passphrase can be used to determine the master key which in turn can be used to decrypt the associated partition (even your actual partition, not only the backed-up version). On the other hand, if the master key gets compromised, you have to reencrypt your whole partition. See [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#6-backup-and-data-recovery LUKS FAQ] for further details.}}<br />
<br />
==== Backup using cryptsetup ====<br />
<br />
Cryptsetup's {{ic|luksHeaderBackup}} action stores a binary backup of the LUKS header and keyslot area:<br />
<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file ''/mnt/backup/file.img''<br />
<br />
where {{ic|''device''}} is the partition containing the LUKS volume.<br />
<br />
You can also back up the plain text header into ramfs and encrypt it with e.g. [[GPG]] before writing it to persistent storage:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/''tmp''<br />
# cryptsetup luksHeaderBackup /dev/''device'' --header-backup-file /root/''tmp''/''file''.img<br />
# gpg2 --recipient ''User_ID'' --encrypt /root/''tmp''/''file''.img <br />
# cp /root/''tmp''/''file''.img.gpg /mnt/''backup''/<br />
# umount /root/''tmp''<br />
<br />
{{Warning|[[tmpfs]] can swap to the disk in low memory situations, so it is not recommended here.}}<br />
<br />
==== Restore using cryptsetup ====<br />
<br />
{{Warning|Restoring the wrong header or restoring to an unencrypted partition will cause data loss! The action can not perform a check whether the header is actually the ''correct'' one for that particular device.}} <br />
<br />
In order to evade restoring a wrong header, you can ensure it does work by using it as a remote {{ic|--header}} first: <br />
<br />
{{hc|# cryptsetup -v --header /mnt/''backup''/''file''.img open /dev/''device'' test|<br />
Key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
# mount /dev/mapper/test /mnt/test && ls /mnt/test <br />
# umount /mnt/test <br />
# cryptsetup close test <br />
<br />
Now that the check succeeded, the restore may be performed: <br />
<br />
# cryptsetup luksHeaderRestore /dev/''device'' --header-backup-file ./mnt/''backup''/''file''.img<br />
<br />
Now that all the keyslot areas are overwritten; only active keyslots from the backup file are available after issuing the command.<br />
<br />
==== Manual backup and restore ====<br />
<br />
The header always resides at the beginning of the device and a backup can be performed without access to ''cryptsetup'' as well. First you have to find out the payload offset of the crypted partition:<br />
<br />
{{hc|# cryptsetup luksDump /dev/''device'' {{!}} grep "Payload offset"|<br />
Payload offset: 4040<br />
}}<br />
<br />
Second check the sector size of the drive<br />
<br />
{{hc|# fdisk -l /dev/''device'' {{!}} grep "Sector size"|<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
}}<br />
<br />
Now that you know the values, you can backup the header with a simple [[dd]] command:<br />
<br />
# dd if=/dev/''device'' of=/path/to/''file''.img bs=512 count=4040<br />
<br />
and store it safely.<br />
<br />
A restore can then be performed using the same values as when backing up:<br />
<br />
# dd if=./''file''.img of=/dev/''device'' bs=512 count=4040<br />
<br />
=== Re-encrypting devices ===<br />
<br />
{{Expansion|cryptsetup 2.2 using LUKS2 (with a 16 MiB header) supports online encryption/decryption/reencryption.[https://mirrors.edge.kernel.org/pub/linux/utils/cryptsetup/v2.2/v2.2.0-ReleaseNotes]}}<br />
<br />
{{Out of date|cryptsetup-reencrypt was removed in cryptsetup 2.5.0.[https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/v2.5.0-ReleaseNotes]}}<br />
<br />
The {{Pkg|cryptsetup}} package features two options for re-encryption.<br />
<br />
; cryptsetup reencrypt: Argument to {{ic|cryptsetup}} itself: Preferred method. Currently LUKS2 devices only. Actions can be performed online. Supports multiple parallel re-encryption jobs. Resilient to system failures. See {{man|8|cryptsetup}} for more information.<br />
<br />
; cryptsetup-reencrypt: Legacy tool, supports LUKS1 in addition to LUKS2. Actions can be performed on unmounted devices only. Single process at a time. Sensitive to system failures. See {{man|8|cryptsetup-reencrypt}} for more information. <br />
<br />
Both can be used to convert an existing unencrypted file system to a LUKS encrypted one or permanently remove LUKS encryption from a device (using {{ic|--decrypt}}). As its name suggests it can also be used to re-encrypt an existing LUKS encrypted device, though, re-encryption is not possible for a detached LUKS header or other encryption modes (e.g. plain-mode). For re-encryption it is possible to change the [[#Encryption options for LUKS mode]]. <br />
<br />
One application of re-encryption may be to secure the data again after a passphrase or [[#Keyfiles|keyfile]] has been compromised ''and'' one cannot be certain that no copy of the LUKS header has been obtained. For example, if only a passphrase has been shoulder-surfed but no physical/logical access to the device happened, it would be enough to change the respective passphrase/key only ([[#Key management]]). <br />
<br />
{{Warning|Always make sure a '''reliable backup''' is available and double-check options you specify before using the tool!}}<br />
<br />
The following shows an example to encrypt an unencrypted file system partition and a re-encryption of an existing LUKS device.<br />
<br />
==== Encrypt an existing unencrypted file system ====<br />
<br />
{{Tip|If you are trying to encrypt an existing root partition, you might want to create a separate and unencrypted boot partition which will be mounted to {{ic|/boot}} (see [[Dm-crypt/Encrypting an entire system#Preparing the boot partition]]). It is not strictly necessary but has a number of advantages:<br />
<br />
* If {{ic|/boot}} is located inside an encrypted root partition, the system will ask for the passphrase twice when the machine is powered on. The first time will happen when the boot loader attempts to read the files located inside encrypted {{ic|/boot}}, the second time will be when the kernel tries to mount the encrypted partition [https://opencraft.com/blog/tutorial-encrypting-an-existing-root-partition-in-ubuntu-with-dm-crypt-and-luks/]. This might not be the desired behaviour and can be prevented by having a separate and unencryted boot partition.<br />
* Some system restore applications (e.g., {{AUR|timeshift}}) will not work if {{ic|/boot}} is located inside an encryted partition [https://github.com/teejee2008/timeshift/issues/280].<br />
<br />
In short, create a partition with the size of at least 260 MiB if needed. See [[Partitioning#/boot]].}}<br />
<br />
A LUKS encryption header is always stored at the beginning of the device. Since an existing file system will usually be allocated all partition sectors, the first step is to shrink it to make space for the LUKS header.<br />
<br />
{{Expansion|cryptsetup man pages suggest using twice the LUKS2 header size. That implies 32 MiB and using {{ic|--reduce-device-size 32M}}}}<br />
<br />
The [[#Encryption options for LUKS mode|default]] LUKS2 header requires 16 MiB. If the current file system occupies all the available space, we will have to shrink it at least that much. To shrink an existing {{ic|ext4}} file system on {{ic|/dev/sdaX}} to its current possible minimum:<br />
<br />
# umount /mnt<br />
<br />
{{hc|# e2fsck -f /dev/sdaX|<br />
e2fsck 1.43-WIP (18-May-2015)<br />
Pass 1: Checking inodes, blocks, and sizes<br />
...<br />
/dev/sda6: 12/166320 files (0.0% non-contiguous), 28783/665062 blocks<br />
}}<br />
<br />
{{hc|# resize2fs -p -M /dev/sdaX|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/sdaX to 26347 (4k) blocks.<br />
The filesystem on /dev/sdaX is now 26347 (4k) blocks long.<br />
}}<br />
<br />
{{Tip|Shrinking to the minimum size with {{ic|-M}} might take very long. You might want to calculate a size just 32 MiB smaller than the current size instead of using {{ic|-M}}.}}<br />
<br />
{{Warning|The file system should be shrunk while the underlying device (e.g., a partition) should be kept at its original size. Some graphical tools (e.g., [[GParted]]) may resize both the file system and the partition, and data loss may occur after encryption.}}<br />
<br />
Now we encrypt it, using the default cipher we do not have to specify it explicitly:<br />
<br />
{{hc|# cryptsetup reencrypt --encrypt --reduce-device-size 16M /dev/sdaX|<nowiki><br />
<br />
WARNING!<br />
<br />
========<br />
<br />
This will overwrite data on LUKS2-temp-12345678-9012-3456-7890-123456789012.new irrevocably.<br />
<br />
Are you sure? (Type 'yes' in capital letters): YES<br />
Enter passphrase for LUKS2-temp-12345678-9012-3456-7890-123456789012.new: <br />
Verify passphrase: <br />
</nowiki>}}<br />
<br />
After it finished, the whole {{ic|/dev/sdaX}} partition is encrypted, not only the space the file system was shrunk to. As a final step we extend the original {{ic|ext4}} file system to occupy all available space again, on the now encrypted partition:<br />
<br />
{{hc|# cryptsetup open /dev/sdaX recrypt|<br />
Enter passphrase for /dev/sdaX: <br />
...<br />
}}<br />
<br />
{{hc|# resize2fs /dev/mapper/recrypt|<br />
resize2fs 1.43-WIP (18-May-2015)<br />
Resizing the filesystem on /dev/mapper/recrypt to 664807 (4k) blocks.<br />
The filesystem on /dev/mapper/recrypt is now 664807 (4k) blocks long.<br />
}}<br />
<br />
# mount /dev/mapper/recrypt /mnt<br />
<br />
The file system is now ready to use. You may want to add it to your [[crypttab]].<br />
<br />
{{Tip|If you have just encrypted your root partition, you might need to perform a number of post-encryption adjustments.<br />
<br />
See [[Dm-crypt/Encrypting an entire system#Configuring mkinitcpio]], [[Dm-crypt/Encrypting an entire system#Configuring the boot loader]], and [[Dm-crypt/Encrypting an entire system#Configuring GRUB]].}}<br />
<br />
==== Re-encrypting an existing LUKS partition ====<br />
<br />
In this example an existing LUKS device is re-encrypted. <br />
<br />
{{Warning|Double-check you specify encryption options for correctly and ''never'' re-encrypt without a '''reliable backup'''!}}<br />
<br />
In order to re-encrypt a device with its existing encryption options, they do not need to be specified:<br />
{{bc|# cryptsetup reencrypt /dev/sdaX}}<br />
{{Note|For LUKS1 we will need to use the legacy tool:{{bc|# cryptsetup-reencrypt /dev/sdaX}}}}<br />
<br />
Existing keys are retained when re-encrypting a device with a different cipher and/or hash. Another use case is to re-encrypt LUKS devices which have non-current encryption options. Apart from above warning on specifying options correctly, the ability to change the LUKS header may also be limited by its size. For example, if the device was initially encrypted using a CBC mode cipher and 128 bit key-size, the LUKS header will be half the size of above mentioned {{ic|4096}} sectors: <br />
<br />
{{hc|# cryptsetup luksDump /dev/sdaX {{!}} grep -e "mode" -e "Payload" -e "MK bits"|<br />
Cipher mode: cbc-essiv:sha256<br />
Payload offset: '''2048'''<br />
MK bits: 128<br />
}}<br />
<br />
While it is possible to upgrade the encryption of such a device, it is currently only feasible in two steps. First, re-encrypting with the same encryption options, but using the {{ic|--reduce-device-size}} option to make further space for the larger LUKS header. Second, re-encypt the whole device again with the desired cipher. For this reason and the fact that a backup should be created in any case, creating a new, fresh encrypted device to restore into is always the faster option.<br />
<br />
=== Conversion from LUKS1 to LUKS2 and back ===<br />
<br />
The {{Pkg|cryptsetup}} package has {{ic|convert}} option that needed for conversion between LUKS1 and LUKS2 container types. The argument {{ic|--type}} is '''required'''.<br />
<br />
Migration from LUKS1 to LUKS2:<br />
<br />
# cryptsetup convert --type luks2 /dev/sdaX<br />
<br />
{{Note|The LUKS header size will be 2 MiB instead of 16 MiB.}}<br />
<br />
Rollback to LUKS1 (for example, to boot from [[GRUB#Encrypted /boot|GRUB with encrypted /boot]]):<br />
<br />
# cryptsetup convert --type luks1 /dev/sdaX<br />
<br />
{{Note|Conversion from LUKS2 to LUKS1 is '''not''' always possible. You may get the following error:<br />
Cannot convert to LUKS1 format - keyslot 0 is not LUKS1 compatible.<br />
}}<br />
<br />
== Resizing encrypted devices ==<br />
<br />
{{Expansion|This section should be rewritten to introduce resizing more generically. Perhaps work on it together with [[Resizing LVM-on-LUKS]].}}<br />
<br />
If a storage device encrypted with dm-crypt is being cloned (with a tool like dd) to another larger device, the underlying dm-crypt device must be resized to use the whole space. <br />
<br />
The destination device is /dev/sdX2 in this example, the whole available space adjacent to the partition will be used:<br />
<br />
# cryptsetup luksOpen /dev/sdX2 sdX2<br />
# cryptsetup resize sdX2<br />
<br />
Then the underlying file system must be resized.<br />
<br />
=== Loopback file system ===<br />
<br />
Assume that an encrypted loopback file system is stored in a file {{ic|/bigsecret}}, looped to {{ic|/dev/loop0}}, mapped to {{ic|secret}} and mounted on {{ic|/mnt/secret}}, as in the example at [[dm-crypt/Encrypting a non-root file system#File container]].<br />
<br />
If the container file is currently mapped and/or mounted, unmount and/or close it:<br />
<br />
# umount /mnt/secret<br />
# cryptsetup close secret<br />
# losetup -d /dev/loop0<br />
<br />
Next, expand the container file with the size of the data you want to add. In this example, the file will be expanded with 1M * 1024, which is 1G.<br />
<br />
{{Warning|Make absolutely sure to use '''two''' {{ic|>}}, instead of just one, or else you will overwrite the file instead of appending to it. Making a backup before this step is strongly recommended.}}<br />
<br />
# dd if=/dev/urandom bs=1M count=1024 | cat - >> /bigsecret<br />
<br />
Now map the container to the loop device:<br />
<br />
# losetup /dev/loop0 /bigsecret<br />
# cryptsetup open /dev/loop0 secret<br />
<br />
After this, resize the encrypted part of the container to the new maximum size of the container file:<br />
<br />
# cryptsetup resize secret<br />
<br />
Finally, perform a file system check and, if it is ok, resize it (example for ext2/3/4):<br />
<br />
# e2fsck -f /dev/mapper/secret<br />
# resize2fs /dev/mapper/secret<br />
<br />
You can now mount the container again:<br />
<br />
# mount /dev/mapper/secret /mnt/secret<br />
<br />
=== Integrity protected device ===<br />
<br />
If the device was formatted with integrity support (e.g., {{ic|--integrity hmac-sha256}}) and the backing block device is shrinked, it cannot be opened with this error: {{ic|device-mapper: reload ioctl on failed: Invalid argument}}.<br />
<br />
To fix this issue without wiping the device again, it can be formatted with the previous master key (keeping the per-sector tags valid).<br />
<br />
# cryptsetup luksDump /dev/sdX2 --dump-master-key --master-key-file=/tmp/masterkey-in-tmpfs.key<br />
# cryptsetup luksFormat /dev/sdX2 --type luks2 --integrity hmac-sha256 --master-key-file=/tmp/masterkey-in-tmpfs.key --integrity-no-wipe<br />
# rm /tmp/masterkey-in-tmpfs.key<br />
<br />
== Keyfiles ==<br />
<br />
{{Note|This section describes using a plaintext keyfile. If you want to encrypt your keyfile giving you two factor authentication see [[dm-crypt/Specialties#Using GPG, LUKS, or OpenSSL Encrypted Keyfiles|Using GPG or OpenSSL Encrypted Keyfiles]] for details, but please still read this section.}}<br />
<br />
'''What is a keyfile?'''<br />
<br />
A keyfile is a file whose data is used as the passphrase to unlock an encrypted volume.<br />
That means if such a file is lost or changed, decrypting the volume may no longer be possible.<br />
<br />
{{Tip|Define a passphrase in addition to the keyfile for backup access to encrypted volumes in the event the defined keyfile is lost or changed.}}<br />
<br />
'''Why use a keyfile?'''<br />
<br />
There are many kinds of keyfiles. Each type of keyfile used has benefits and disadvantages summarized below:<br />
<br />
=== Types of keyfiles ===<br />
<br />
==== passphrase ====<br />
<br />
This is a keyfile containing a simple passphrase. The benefit of this type of keyfile is that if the file is lost the data it contained is known and hopefully easily remembered by the owner of the encrypted volume. However the disadvantage is that this does not add any security over entering a passphrase during the initial system start.<br />
<br />
Example: {{ic|1234}}<br />
<br />
{{Note|The keyfile containing the passphrase must not have a newline in it. One option is to create it using <br />
<br />
# echo -n 'your_passphrase' > ''/path/to/keyfile''<br />
# chown root:root ''/path/to/keyfile''; chmod 400 ''/path/to/keyfile''<br />
<br />
If the file contains special characters such as a backslash, rather than escaping these, it is recommended to simply edit the key file directly entering or pasting the passphrase and then remove the trailing newline with a handy perl one-liner:<br />
<br />
# perl -pi -e 'chomp if eof' ''/path/to/keyfile''<br />
}}<br />
<br />
==== randomtext ====<br />
<br />
This is a keyfile containing a block of random characters. The benefit of this type of keyfile is that it is much more resistant to dictionary attacks than a simple passphrase. An additional strength of keyfiles can be utilized in this situation which is the length of data used. Since this is not a string meant to be memorized by a person for entry, it is trivial to create files containing thousands of random characters as the key. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase.<br />
<br />
Example: {{ic|fjqweifj830149-57 819y4my1-38t1934yt8-91m 34co3;t8y;9p3y-}}<br />
<br />
==== binary ====<br />
<br />
This is a binary file that has been defined as a keyfile. When identifying files as candidates for a keyfile, it is recommended to choose files that are relatively static such as photos, music, video clips. The benefit of these files is that they serve a dual function which can make them harder to identify as keyfiles. Instead of having a text file with a large amount of random text, the keyfile would look like a regular image file or music clip to the casual observer. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase. Additionally, there is a theoretical loss of randomness when compared to a randomly generated text file. This is due to the fact that images, videos and music have some intrinsic relationship between neighboring bits of data that does not exist for a random text file. However this is controversial and has never been exploited publicly.<br />
<br />
Example: images, text, video, ...<br />
<br />
=== Creating a keyfile with random characters ===<br />
<br />
==== Storing the keyfile on a file system ====<br />
<br />
A keyfile can be of arbitrary content and size. <br />
<br />
Here [[dd]] is used to generate a keyfile of 2048 random bytes, storing it in the file {{ic|/etc/mykeyfile}}:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/etc/mykeyfile iflag=fullblock<br />
<br />
If you are planning to store the keyfile on an external device, you can also simply change the outputfile to the corresponding directory:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/media/usbstick/mykeyfile iflag=fullblock<br />
<br />
To deny any access for other users than {{ic|root}}:<br />
<br />
# chmod 600 /etc/mykeyfile<br />
<br />
===== Securely overwriting stored keyfiles =====<br />
<br />
If you stored your temporary keyfile on a physical storage device, and want to delete it, remember to not just remove the keyfile later on, but use something like<br />
<br />
# shred --remove --zero mykeyfile<br />
<br />
to securely overwrite it. For overaged file systems like FAT or ext2 this will suffice while in the case of journaling file systems, flash memory hardware and other cases it is highly recommended to [[Securely wipe disk|wipe the entire device]].<br />
<br />
==== Storing the keyfile in ramfs ====<br />
<br />
Alternatively, you can mount a ramfs for storing the keyfile temporarily:<br />
<br />
# mount --mkdir -t ramfs ramfs /root/myramfs<br />
# cd /root/myramfs<br />
<br />
The advantage is that it resides in RAM and not on a physical disk, therefore it can not be recovered after unmounting the ramfs. After copying the keyfile to another secure and persistent file system, unmount the ramfs again with<br />
<br />
# umount /root/myramfs<br />
<br />
=== Configuring LUKS to make use of the keyfile ===<br />
<br />
Add a keyslot for the keyfile to the LUKS header:<br />
<br />
{{hc|# cryptsetup luksAddKey /dev/sda2 /etc/mykeyfile|<br />
Enter any LUKS passphrase:<br />
key slot 0 unlocked.<br />
Command successful.<br />
}}<br />
<br />
=== Manually unlocking a partition using a keyfile ===<br />
<br />
Use the {{ic|--key-file}} option when opening the LUKS device:<br />
<br />
# cryptsetup open /dev/sda2 ''dm_name'' --key-file /etc/mykeyfile<br />
<br />
=== Unlocking the root partition at boot ===<br />
<br />
This is simply a matter of configuring [[mkinitcpio]] to include the necessary modules or files and configuring the [[dm-crypt/System configuration#cryptkey|cryptkey]] [[kernel parameter]] to know where to find the keyfile.<br />
<br />
Two cases are covered below:<br />
<br />
# Using a keyfile stored on an external medium (e.g. a USB stick)<br />
# Using a keyfile embedded in the initramfs<br />
<br />
==== With a keyfile stored on an external media ====<br />
<br />
===== Configuring mkinitcpio =====<br />
<br />
You have to add the kernel module for the drive's [[file system]] to the [[mkinitcpio#MODULES|MODULES array]] in {{ic|/etc/mkinitcpio.conf}}. For example, add {{ic|ext4}} if the file system is [[Ext4]] or {{ic|vfat}} in case it is [[FAT]]:<br />
<br />
MODULES=(vfat)<br />
<br />
If there are messages about bad superblock and bad codepage at boot, then you need an extra codepage module to be loaded. For instance, you may need {{ic|nls_iso8859-1}} module for {{ic|iso8859-1}} codepage.<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
===== Configuring the kernel parameters =====<br />
<br />
* For a busybox-based initramfs using the [[dm-crypt/System configuration#Using encrypt hook|encrypt]] hook, see [[dm-crypt/System configuration#cryptkey]].<br />
* For a systemd based initramfs using the [[sd-encrypt]] hook, see [[dm-crypt/System configuration#rd.luks.key]].<br />
<br />
==== With a keyfile embedded in the initramfs ====<br />
<br />
{{Warning|Use an embedded keyfile '''only''' if you protect the keyfile sufficiently by:<br />
* Using some form of authentication earlier in the boot process. Otherwise auto-decryption will occur, defeating completely the purpose of block device encryption.<br />
* {{ic|/boot}} is encrypted. Otherwise root on a different installation (including the [[Installation guide#Boot the live environment|live environment]]) can extract your key from the initramfs, and unlock the device without any other authentication.}}<br />
<br />
This method allows to use a specially named keyfile that will be embedded in the [[initramfs]] and picked up by the {{ic|encrypt}} [[Mkinitcpio#HOOKS|hook]] to unlock the root file system ({{ic|cryptdevice}}) automatically. It may be useful to apply when using the [[GRUB#Encrypted /boot|GRUB early cryptodisk]] feature, in order to avoid entering two passphrases during boot.<br />
<br />
The {{ic|encrypt}} hook lets the user specify a keyfile with the {{ic|cryptkey}} kernel parameter: in the case of initramfs, the syntax is {{ic|rootfs:''/path/to/keyfile''}}. See [[dm-crypt/System configuration#cryptkey]]. Besides, this kernel parameter defaults to use {{ic|/crypto_keyfile.bin}}, and if the initramfs contains a valid key with this name, decryption will occur automatically without the need to configure the {{ic|cryptkey}} parameter.<br />
<br />
If using {{ic|sd-encrypt}} instead of {{ic|encrypt}}, specify the location of the keyfile with the {{ic|rd.luks.key}} kernel parameter: in the case of initramfs, the syntax is {{ic|''/path/to/keyfile''}}. See [[dm-crypt/System configuration#rd.luks.key]]. This kernel parameter defaults to using {{ic|/etc/cryptsetup-keys.d/''name''.key}} (where {{ic|''name''}} is the {{ic|''dm_name''}} used for decryption in [[#Encrypting devices with cryptsetup]]) and can be omitted if initramfs contains a valid key with this path.<br />
<br />
[[#Creating a keyfile with random characters|Generate the keyfile]], give it suitable permissions and [[#Adding LUKS keys|add it as a LUKS key]]:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/crypto_keyfile.bin iflag=fullblock<br />
# chmod 600 /crypto_keyfile.bin<br />
# cryptsetup luksAddKey /dev/sdX# /crypto_keyfile.bin<br />
<br />
{{Note|The initramfs is generated by mkinitcpio with {{ic|600}} [[permissions]] by default, so regular users are not able to read the keyfile via the generated initramfs.}}<br />
<br />
Include the key in [[mkinitcpio#BINARIES and FILES|mkinitcpio's FILES array]]:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/crypto_keyfile.bin)<br />
}}<br />
<br />
Finally [[regenerate the initramfs]].<br />
<br />
On the next reboot you should only have to enter your container decryption passphrase once.<br />
<br />
([https://www.pavelkogan.com/2014/05/23/luks-full-disk-encryption/#bonus-login-once source])</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:QEMU&diff=745260Talk:QEMU2022-09-08T10:04:29Z<p>PXf: /* qemu-user-static and binfmt-qemu-static no longer exist */ qemu-user-static moved from AUR to extra</p>
<hr />
<div>== Linear RAID ==<br />
<br />
When I was updating the article yesterday, I had tried to fit the section about linear raid (boot a VM from a partition by prepending a MBR to it) into the article better. But I'm not sure the technique described is the right one at all. It looks like it works, but wouldn't it be easier to install a bootloader directly to the partition (e.g. syslinux)? Then the VM could be booted directly from the partition simply by using it as its virtual disk.<br />
--[[User:Synchronicity|Synchronicity]] ([[User talk:Synchronicity|talk]]) 19:23, 9 May 2012 (UTC)<br />
<br />
:What about Windows installations then? [[User:Nesk|Nesk]] ([[User talk:Nesk|talk]]) 09:18, 4 October 2016 (UTC)<br />
<br />
== Creating bridge manually ==<br />
<br />
I really don't know what to do with this section. I'd say it has been superseded by [[QEMU#Creating bridge using qemu-bridge-helper]] (available since qemu-1.1, we now have qemu-1.5) - or is someone still using this method? Perhaps link to https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces or http://wiki.qemu.org/Documentation/Networking/NAT is sufficient. What do you think? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:42, 22 July 2013 (UTC)<br />
<br />
:Actually, I've become a happy user of this method. I've written some scripts to easily create bridge interface, TAP interface, and combined with Xyne's [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html excellent scripts] to set up NAT and launch DHCP server, I have complete solution to easily manage multiple VMs on one (or even more) bridge.<br />
:My scripts are available on github: [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-launcher.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-tap-helper.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-mac-hasher.py] but I won't probably integrate them into the wiki, I'l just leave a note when I do some more testing.<br />
:The thing is, what to do with the current content? Personally I think that links to [https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces], [http://wiki.qemu.org/Documentation/Networking/NAT] and my scripts are sufficient (of course others are welcome). I'd also leave the note at the end to ''disable the firewall on the bridge'', I find it extremely useful.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:24, 5 September 2013 (UTC)<br />
<br />
:I would not remove something that works still heh.--[[User:Webdawg|Webdawg]] ([[User talk:Webdawg|talk]]) 07:31, 17 July 2016 (UTC)<br />
<br />
People may be coming to this article for a very simple example, not using opinionated dependencies or assumptions about setup like firewalls. The method used in Lahwaacz script is perfect (although the link in this discussion is out of date).<br />
It can be boiled down to about 6 {{ic|ip}} commands:<br />
Create the bridge {{ic|bridge0}} and bring it UP<br />
# ip link add name bridge0 type bridge<br />
# ip link set bridge0 up<br />
Create the tap {{ic|tap0}} and bring it UP<br />
# ip tuntap add dev tap0 mode tap<br />
# ip link set tap0 up promisc on<br />
Add your network interface (it must be UP), and tap to the bridge<br />
# ip link set enp2s0f0 master bridge0<br />
# ip link set tap0 master bridge0<br />
-- [[User:Razzintown|Razzintown]] ([[User talk:Razzintown|talk]]) 23:54, 15 November 2020 (UTC)<br />
<br />
<code>qemu-bridge-helper</code> adds and removes [[Network_tap|tap]], but does not construct a <code>bridge</code>, with an IP for the host, and containing the physical nic.<br />
I modified <code>run-qemu</code> to construct a bridge, such that network is available on host and guest.<br />
The previous <code>run-qemu</code> probably assumed that the main host network access had been moved to <code>bridge</code> before. [[User:Roland Puntaier|Roland Puntaier]] ([[User talk:Roland Puntaier|talk]]) 16:05, 24 June 2022 (UTC)<br />
<br />
== Kexec Hackery When Using a Real Partition ==<br />
<br />
After banging my head against a wall long enough and figuring out what {{ic|-kernel}} and {{ic|-initrd}} were really calling, I put a note above the appropriate section and mentioned two ways to use the guest's images. (Otherwise, you'll have to worry if the host and guest images match.) The first -- mount the partition(s) -- is more appropriate for "low-volume-handling" of VMs. The second -- using kexec -- becomes more useful when you're juggling more than a few VMs.<br />
<br />
I'm only mentioning this hack because (as of now) [[Kexec]] only mentions use for rebooting into another kernel, not switching out the kernel before the system is even up. This hack comes from from https://digitalocean.uservoice.com/forums/136585-digitalocean/suggestions/2814988-give-option-to-use-the-droplet-s-own-bootloader- which has two suggestions. The most recent, using systemd units by jkuan, doesn't work because jkuan tried to copy a {{ic|.target}} file into a {{ic|.service}} file and systemd wants {{ic|ExecStart}} in a {{ic|.service}} file. The second one, replacing {{ic|/usr/bin/init}} by andrew_sparks, works for me on my Arch instance at DigitalOcean.<br />
<br />
Adaptation from said post:<br />
<br />
# pacman -S kexec-tools<br />
# pacman -R systemd-sysvcompat<br />
<br />
{{hc|1=/tmp/init|2=<br />
#!/bin/sh<br />
<br />
kexec --load /boot/vmlinuz-linux --initrd=/boot/initramfs-linux.img --append="root=/dev/sda init=/usr/lib/systemd/systemd" &&<br />
mount -o ro,remount / && kexec -e<br />
exec /usr/lib/systemd/systemd<br />
}}<br />
<br />
# cd [/path/to/vm]/usr/bin<br />
# mv init init.dist<br />
# cp /tmp/init ./<br />
# chmod 755 init<br />
<br />
I'm leaving this on the Talk page as I haven't even tried it out in QEMU myself. Also, my eyes are about ready to pop out of my head, so I'm barring myself from figuring out the appropriate way to edit this in for the time being. [[User:BrainwreckedTech|BrainwreckedTech]] ([[User talk:BrainwreckedTech|talk]]) 21:23, 14 January 2014 (UTC)<br />
<br />
== Replace -net with -netdev ==<br />
<br />
The {{ic|-net}} option is deprecated and replaced by {{ic|-netdev}}. I think this article should be modified to reflect that.<br />
http://en.wikibooks.org/wiki/QEMU/Networking#cite_ref-1<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 18:12, 1 July 2014 (UTC)<br />
<br />
:Yes {{ic|-net}} is the old syntax as stated in [https://wiki.gentoo.org/wiki/QEMU/Options#Pass-through Gentoo's Wiki] where we should use {{ic|1=-netdev user,id=vmnic -device virtio-net,netdev=vmnic}} [[User:Pickfire|Pickfire]] ([[User talk:Pickfire|talk]]) 04:11, 31 March 2017 (UTC)<br />
<br />
== I'm rewriting the network section ==<br />
<br />
https://wiki.archlinux.org/index.php/User:Axper/sandbox/qemu_network<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 20:07, 2 July 2014 (UTC)<br />
<br />
::I think a lot of networking topics could be moved outside of the QEMU page. Many virtualization applications share the same basic principles with regards to networking, such as tun/tap creating, bridges, VDE, etc. There are a few networking schemes that are QEMU-specific, for example multicast sockets and {{ic|-net socket,...}}, and these could be mentioned on the QEMU page, although these are less reliable and rarely used in comparison to tap devices. We should also of course note the QEMU-specific command line options in the QEMU page, but for general concepts and commands independent of the virtualization applications, they could go on pages dedicated to the task. The best example is VDE, which is in no way limited to QEMU, yet it still doesn't have its own page on the Arch wiki.<br />
<br />
::Incidentally, I'm planning on rewriting [[User Mode Linux]] (yes, I promise I will get around to it), which happens to share the "tap with bridge" and VDE concepts with QEMU. It would be nice if I could link to pages dedicated to those topics and only write UML-specific commands in the page, instead of duplicating a bunch of general information. I'm not familiar very familiar with Xen or LXC or Docker or the like, but I would suspect that they also share some networking infrastructure. We could possibly even create a category just for these types of pages, for example "Virtual Networking" or "Advanced Networking". [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 13:32, 19 February 2015 (UTC)<br />
<br />
== -enable-kvm vs -machine type=pc,accel=kvm ==<br />
<br />
The section [[QEMU#Enabling_KVM]] recommends {{ic|-enable-kvm}}, while [[QEMU#Virtual_machine_runs_too_slowly]] recommends {{ic|1=-machine type=pc,accel=kvm}}. Is there any difference between the two? Is one preferred over the other? Should we just link to the former section from the latter (and possibly move both command line switches to the same section)? [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 17:23, 18 January 2015 (UTC)<br />
<br />
:2.5 years later... Has anyone found an answer to the question of `-enable-kvm` VS `-machine type=pc,accel=kvm`? -[[User:Physicist1616|Physicist1616]] ([[User talk:Physicist1616|talk]]) 19:32, 3 August 2017 (UTC)<br />
<br />
::Yes. They're equivalent. [https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg00132.html Discussion on the QEMU mailing list] about marking {{ic|-enable-kvm}} deprecated didn't result in that; {{ic|-enable-hax}} did get deprecated. Confusing, especially when checking whether e.g. libvirt has actually started the machine with KVM enabled. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 16:24, 4 December 2018 (UTC)<br />
<br />
== virtio-gpu ==<br />
<br />
Any tutorial on using the new virtio-gpu which is introduced in qemu-2.4 and kernel 4.2? [[User:Adam900710|Adam900710]] ([[User talk:Adam900710|talk]]) 02:44, 19 August 2015 (UTC)<br />
<br />
:Should be "plug and play" with recent kernel and other packages: [https://www.kraxel.org/blog/2016/09/using-virtio-gpu-with-libvirt-and-spice/ article]. The article is about libvirt, but I've run Arch guest on Arch host successfully with qemu script. [[User:Nesk|Nesk]] ([[User talk:Nesk|talk]]) 09:24, 4 October 2016 (UTC)<br />
<br />
== host only networking ==<br />
<br />
I added a quick and easy method but it was deleted. I found errors in what is here. Is it worth my time to correct them or will they be deleted? {{unsigned|16:39, 4 January 2016|Netskink}}<br />
<br />
:You are welcome to make any corrections. Nobody can tell you if they will be kept or reverted beforehand, but if you're afraid to waste your time feel free to just point them out using an [[Help:Template|Article status templates|article status template]] (should be less time consuming). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:28, 21 February 2016 (UTC)<br />
<br />
== Windows 7 specific issues ==<br />
<br />
I have noticed that for me, any attempts at installing Windows 7 using qemu with virt-manager as a frontend stalls on "Starting Windows." This is immediately after booting the computer for the first time. In Virt-manager, I am able to change the Display from QXL to Cirrus to fix the issue. I'm not sure if this applies to this page in particular, but if so, might be worth adding to the "Troubleshooting" section -- [[User:Ephreal|Ephreal]] ([[User talk:Ephreal|talk]]) 14:25, 10 August 2016 (UTC)<br />
<br />
== Using existing partition on GPT disk (with linear RAID or otherwise) ==<br />
<br />
[https://wiki.archlinux.org/index.php/QEMU#Simulate_virtual_disk_with_MBR_using_linear_RAID Section on using existing partition] is pretty awesome, but it is MBR-specific. Can someone with enough knowledge create a similar section about GPT disk please?<br />
<br />
== Could not access KVM kernel module: Permission denied ==<br />
<br />
Simply changing {{ic|1=group = "78"}} to {{ic|1=group = "kvm"}} in {{ic|/etc/libvirt/qemu.conf}} was not enough for me to fix this issue. Indeed, some files were still installed with gid 78, which you can confirm with:<br />
<br />
find / -gid 78<br />
<br />
So in the end, I still had to change the group id of kvm to workaround this issue:<br />
<br />
groupmod -g 78 kvm<br />
<br />
{{unsigned|17:15, 1 September 2017|Nivata}}<br />
<br />
== Starting QEMU virtual machines with systemd in 2018 ==<br />
<br />
The custom service script uses KillMethod=none to avoid the virtual machine being killed before shutdown. Here is an example to avoid this logic using {{Pkg|socat}}:<br />
<br />
ExecStart=/usr/bin/env qemu-system-x86_64 -name %i … -monitor unix:/var/run/qemu-%i.monitor,server,nowait<br />
ExecStop=/bin/sh -c 'echo system_powerdown | socat stdio,ignoreeof /var/run/qemu-%i.monitor'<br />
<br />
In this way, the stop command will exit when the QEMU monitor closes the socket. Other options, e.g. PIDFile or KillMode are not necessary.<br />
<br />
While a unix socket is used for this example, it works as well with telnet/tcp-connect.<br />
[[User:Ypnos|Ypnos]] ([[User talk:Ypnos|talk]]) 18:29, 30 January 2018 (UTC)<br />
<br />
I've tested using {{Pkg|openbsd-netcat}}, and that variant seems to keep the connection open after issuing the command as well. So there are a couple options to avoid using the KillMethod, which I agree is not a good idea.<br />
[[User:Djmoch|Djmoch]] ([[User talk:Djmoch|talk]]) 13:21, 2 March 2019 (UTC)<br />
<br />
== e1000e: waiting for carrier... timed out ==<br />
<br />
my physical host is an ArchLinux with 4.14.40-1-lts kernel and Qemu 2.12.0.<br />
<br />
in my first virtualisation case, my guest is an ArchLinux with 4.9.36-1-lts kernel (e1000e ver. 3.2.6-k) : everything works normally when I request the assignment of a network address with dhcpcd (after a few seconds, my guest gets the 10.0.2.15 intended address).<br />
<br />
in my second virtualisation case, my guest is an ArchLinux with 4.14.40-1-lts kernel (e1000e ver. 3.2.6-k) : no carrier is detected and therefore no address is assigned to the enp0s2 network card.<br />
<br />
I think the problem would rather come from the virtualized 4.14.40-1-lts kernel side because I do not meet it on my physical host which also uses the e1000e module...<br />
<br />
does anyone have an idea or a lead ?<br />
<br />
(this problem does not appear if I add in both cases the parameter "-machine pc" which forces the use of the module e1000/ens3 instead of the module e1000e/enp0s2).<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 16:09, 28 May 2018 (UTC)<br />
<br />
== Options for fstab with 9p ==<br />
https://wiki.archlinux.org/index.php?title=QEMU&diff=next&oldid=573709<br />
<br />
Maybe the options are not very hard to deduce, but they are not obvious, and having them written down is very useful as a "cheat sheet".<br />
<br />
[[User:Marmistrz|Marmistrz]] ([[User talk:Marmistrz|talk]]) 15:19, 15 June 2019 (UTC)<br />
<br />
:The options (and more) are written on the page which is linked from the section: https://wiki.qemu.org/Documentation/9psetup -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:23, 15 June 2019 (UTC)<br />
<br />
: +1 to keep the options. I suggest also to mention <tt>msize=512000</tt> option necessary to achieve satisfactory performance, this is something qemu docs fail to mention [[User:Ivank|Ivank]] ([[User talk:Ivank|talk]]) 17:39, 15 June 2019 (UTC)<br />
<br />
::{{ic|msize}} is also mentioned on the linked page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:13, 15 June 2019 (UTC)<br />
<br />
::: Yes, in a totally useless way, just that msize exists and 8192 is the default. msize=512000 (max) vs msize=8192 (default) is 10x throughput difference in my testing, that's not mentioned and I'd argue is a much more important and helpful fact to know for a user. [[User:Ivank|Ivank]] ([[User talk:Ivank|talk]]) 18:40, 15 June 2019 (UTC)<br />
<br />
== VDE ==<br />
<br />
can you tell me if you are also having trouble running VDE with QEMU ? for my part, I encounter a very random functioning with the set below:<br />
<br />
vde_switch<br />
<br />
slirpvde -n 192.168.0.0.0 -L 2222:192.168.0.102:22<br />
Starting slirpvde: virtual_host=192.168.0.2/24<br />
DNS =192.168.0.3<br />
vde switch =*DEFAULT*<br />
redir TCP =2222:192.168.0.102:22<br />
<br />
qemu -m 512 -nic vde,mac=52:54:00:12:34:56 -hda samba.disk # 192.168.0.101<br />
<br />
qemu -m 512 -nic vde,mac=52:54:00:12:34:57 -hda linux.disk # 192.168.0.102<br />
<br />
qemu -m 1024 -nic vde,mac=52:54:00:12:34:58 -hda windows.disk # 192.168.0.103<br />
<br />
dysfunctions are for example no answer when I execute the {{ic|ssh -p 2222 root@localhost}} command from another console or the loss of connection (freeze) with my Linux VM when it finally established.<br />
I checked several times the network configuration of my three virtual machines.<br />
the logs do not report any particular errors.<br />
<br />
I use the trio {{ic|vde_switch}}, {{ic|slirpvde}} and {{ic|nic vde}} because it does not require any privileges.<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 12:49, 23 September 2019 (UTC)<br />
<br />
== Systemd service starting qemu as root ==<br />
<br />
The systemd unit suggested at [[QEMU#With_systemd_service]] runs qemu as root, unless it is started as a [[Systemd/User|user service]]. Running qemu as root is explicitly discouraged from at [[QEMU#Running_virtualized_system]]. I suggest adding {{ic|-runas some_user}} to {{ic|1=ExecStart=}}, or {{ic|1=User=some_user}} and {{ic|1=Group=some_group}}. I prefer the former, because it allows to access block devices owned by root, in particular LVM logical volumes.<br />
<br />
[[User:Respiranto|Respiranto]] ([[User talk:Respiranto|talk]]) 19:45, 28 November 2020 (UTC)<br />
<br />
== UEFI with vanilla QEMU? ==<br />
<br />
I'm not exactly sure if this is possible, however /usr/share/qemu seems to have support for many different UEFI implementations and the -bios option seems to be the one that specifies which one to use, however I have seen little to no documentation on the subject (probably because it is usually abstracted away by libvirt).<br />
<br />
[[User:BTDMaster|BTDMaster]] ([[User talk:BTDMaster|talk]]) 10:54, 2 April 2021 (UTC)<br />
<br />
: You haven't used your google powers, there are enough examples online. I'm just dropping here some code from my now-archived vm startup script (libvirt is much nicer).<br />
{{bc|1=<br />
# cp /usr/share/edk2-ovmf/x64/OVMF_VARS.fd /tmp/my_vars.bin<br />
if [ "$OVMF" = "yes" ]; then<br />
QEMU_ARG="$QEMU_ARG \<br />
-drive if=pflash,format=raw,readonly,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd \<br />
-drive if=pflash,format=raw,file=$DRV_BASE/${DRV_IMG}.fd"<br />
else<br />
QEMU_ARG="$QEMU_ARG \<br />
-bios /usr/share/qemu/bios.bin"<br />
fi<br />
}}<br />
: [[User:Tinywrkb|Tinywrkb]] ([[User talk:Tinywrkb|talk]]) 12:08, 2 April 2021 (UTC)<br />
<br />
:: Thank you! I've seen OVMF mentioned, but I thought the binaries provided by QEMU would be enough. (Saving less than 15 MB, I know.)<br />
:: [[User:BTDMaster|BTDMaster]] ([[User talk:BTDMaster|talk]]) 20:52, 2 April 2021 (UTC)<br />
<br />
== Fix short-form boolean options ==<br />
<br />
[https://www.mail-archive.com/qemu-devel@nongnu.org/msg775793.html QEMU has deprecated short-form boolean options]. I have fixed the one instance of this that I was warned about in my own script ("-spice"), but I am sure there are more instances of this in this page that have to be fixed.<br />
<br />
[[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 03:08, 19 July 2021 (UTC)<br />
<br />
== UEFI instructions ==<br />
<br />
I found two different places with almost identical instructions how to boot QEMU with UEFI:<br />
<br />
* [[PCI passthrough via OVMF#Plain QEMU without libvirt]]<br />
* [[Unified Extensible Firmware Interface#OVMF for virtual machines]]<br />
<br />
But the [[QEMU]] article does not mention UEFI at all! I find this situation a bit absurd.<br />
<br />
I think it would be better to create a new section named, for example, '''"Booting a virtual machine in UEFI mode"''' (probably as a "Tips and tricks" subsection) and redirect to that section from other articles to prevent duplication of instructions.<br />
<br />
(I can do it myself if there are no objections.)<br />
<br />
[[User:Andreymal|andreymal]] ([[User talk:Andreymal|talk]]) 16:54, 6 February 2022 (UTC)<br />
<br />
:Sounds good to me. Though, I don't think [[QEMU#Tips and tricks|Tips and tricks]] would be the ideal place. Maybe in [[QEMU#Running virtualized system]] or as a separate top-level section. This page is overdue for a large overhaul anyway... -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 11:15, 7 February 2022 (UTC)<br />
<br />
:Created: [[QEMU#Booting in UEFI mode]]. I was testing UEFI support by running Windows 11 as a guest OS, so I accidentally created another section: [[QEMU#Trusted Platform Module emulation]].<br />
:I am not sure they are good enough, so feel free to edit or even shorten them if they are too long.<br />
:I did not mention Secure Boot because I did not find an easy way to install all the necessary keys (I just copied {{ic|/usr/share/OVMF/OVMF_VARS.ms.fd}} from [https://packages.ubuntu.com/jammy/ovmf ubuntu/ovmf] which is stupid). I think it would be nice if someone would add an additional subsection about Secure Boot.<br />
:[[User:Andreymal|andreymal]] ([[User talk:Andreymal|talk]]) 17:36, 6 August 2022 (UTC)<br />
::Copying from ubuntu/debian [https://bbs.archlinux.org/viewtopic.php?pid=2032619#p2032619 does not sound like a bad idea]. Although the preferred way should be either hard-coding Microsoft's keys during compilation (is that achievable?), or [https://projectacrn.github.io/latest/tutorials/waag-secure-boot.html#use-qemu-to-inject-secure-boot-keys-into-ovmf injecting them manually in UEFI settings] the same way you load custom keys to a physical machine.<br />
::In the aforementioned guide, replace {{ic|1=-hda fat:hda-contents}} with [https://en.wikibooks.org/wiki/QEMU/Devices/Storage VVFAT] arg {{ic|1=-drive file=fat:rw:hda-contents,format=raw}}.<br />
::These cost me tons of googling. Consider giving some hints on this wiki page.<br />
::[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 09:59, 8 September 2022 (UTC)<br />
<br />
== qemu-user-static and binfmt-qemu-static no longer exist ==<br />
<br />
Wiki still mentions them, but they have been deleted from the AUR.<br />
:That is sad. But the good news is that you [https://archlinux.org/packages/extra/x86_64/qemu-user-static/ don't need to build it on your machine] anymore :)<br />
:[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 10:04, 8 September 2022 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:QEMU&diff=745259Talk:QEMU2022-09-08T09:59:34Z<p>PXf: /* UEFI instructions */ how to load secure boot keys the "proper" way</p>
<hr />
<div>== Linear RAID ==<br />
<br />
When I was updating the article yesterday, I had tried to fit the section about linear raid (boot a VM from a partition by prepending a MBR to it) into the article better. But I'm not sure the technique described is the right one at all. It looks like it works, but wouldn't it be easier to install a bootloader directly to the partition (e.g. syslinux)? Then the VM could be booted directly from the partition simply by using it as its virtual disk.<br />
--[[User:Synchronicity|Synchronicity]] ([[User talk:Synchronicity|talk]]) 19:23, 9 May 2012 (UTC)<br />
<br />
:What about Windows installations then? [[User:Nesk|Nesk]] ([[User talk:Nesk|talk]]) 09:18, 4 October 2016 (UTC)<br />
<br />
== Creating bridge manually ==<br />
<br />
I really don't know what to do with this section. I'd say it has been superseded by [[QEMU#Creating bridge using qemu-bridge-helper]] (available since qemu-1.1, we now have qemu-1.5) - or is someone still using this method? Perhaps link to https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces or http://wiki.qemu.org/Documentation/Networking/NAT is sufficient. What do you think? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:42, 22 July 2013 (UTC)<br />
<br />
:Actually, I've become a happy user of this method. I've written some scripts to easily create bridge interface, TAP interface, and combined with Xyne's [http://xyne.archlinux.ca/notes/network/dhcp_with_dns.html excellent scripts] to set up NAT and launch DHCP server, I have complete solution to easily manage multiple VMs on one (or even more) bridge.<br />
:My scripts are available on github: [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-launcher.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-tap-helper.sh], [https://github.com/lahwaacz/archlinux-dotfiles/blob/master/Scripts/qemu-mac-hasher.py] but I won't probably integrate them into the wiki, I'l just leave a note when I do some more testing.<br />
:The thing is, what to do with the current content? Personally I think that links to [https://en.wikibooks.org/wiki/QEMU/Networking#TAP_interfaces], [http://wiki.qemu.org/Documentation/Networking/NAT] and my scripts are sufficient (of course others are welcome). I'd also leave the note at the end to ''disable the firewall on the bridge'', I find it extremely useful.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:24, 5 September 2013 (UTC)<br />
<br />
:I would not remove something that works still heh.--[[User:Webdawg|Webdawg]] ([[User talk:Webdawg|talk]]) 07:31, 17 July 2016 (UTC)<br />
<br />
People may be coming to this article for a very simple example, not using opinionated dependencies or assumptions about setup like firewalls. The method used in Lahwaacz script is perfect (although the link in this discussion is out of date).<br />
It can be boiled down to about 6 {{ic|ip}} commands:<br />
Create the bridge {{ic|bridge0}} and bring it UP<br />
# ip link add name bridge0 type bridge<br />
# ip link set bridge0 up<br />
Create the tap {{ic|tap0}} and bring it UP<br />
# ip tuntap add dev tap0 mode tap<br />
# ip link set tap0 up promisc on<br />
Add your network interface (it must be UP), and tap to the bridge<br />
# ip link set enp2s0f0 master bridge0<br />
# ip link set tap0 master bridge0<br />
-- [[User:Razzintown|Razzintown]] ([[User talk:Razzintown|talk]]) 23:54, 15 November 2020 (UTC)<br />
<br />
<code>qemu-bridge-helper</code> adds and removes [[Network_tap|tap]], but does not construct a <code>bridge</code>, with an IP for the host, and containing the physical nic.<br />
I modified <code>run-qemu</code> to construct a bridge, such that network is available on host and guest.<br />
The previous <code>run-qemu</code> probably assumed that the main host network access had been moved to <code>bridge</code> before. [[User:Roland Puntaier|Roland Puntaier]] ([[User talk:Roland Puntaier|talk]]) 16:05, 24 June 2022 (UTC)<br />
<br />
== Kexec Hackery When Using a Real Partition ==<br />
<br />
After banging my head against a wall long enough and figuring out what {{ic|-kernel}} and {{ic|-initrd}} were really calling, I put a note above the appropriate section and mentioned two ways to use the guest's images. (Otherwise, you'll have to worry if the host and guest images match.) The first -- mount the partition(s) -- is more appropriate for "low-volume-handling" of VMs. The second -- using kexec -- becomes more useful when you're juggling more than a few VMs.<br />
<br />
I'm only mentioning this hack because (as of now) [[Kexec]] only mentions use for rebooting into another kernel, not switching out the kernel before the system is even up. This hack comes from from https://digitalocean.uservoice.com/forums/136585-digitalocean/suggestions/2814988-give-option-to-use-the-droplet-s-own-bootloader- which has two suggestions. The most recent, using systemd units by jkuan, doesn't work because jkuan tried to copy a {{ic|.target}} file into a {{ic|.service}} file and systemd wants {{ic|ExecStart}} in a {{ic|.service}} file. The second one, replacing {{ic|/usr/bin/init}} by andrew_sparks, works for me on my Arch instance at DigitalOcean.<br />
<br />
Adaptation from said post:<br />
<br />
# pacman -S kexec-tools<br />
# pacman -R systemd-sysvcompat<br />
<br />
{{hc|1=/tmp/init|2=<br />
#!/bin/sh<br />
<br />
kexec --load /boot/vmlinuz-linux --initrd=/boot/initramfs-linux.img --append="root=/dev/sda init=/usr/lib/systemd/systemd" &&<br />
mount -o ro,remount / && kexec -e<br />
exec /usr/lib/systemd/systemd<br />
}}<br />
<br />
# cd [/path/to/vm]/usr/bin<br />
# mv init init.dist<br />
# cp /tmp/init ./<br />
# chmod 755 init<br />
<br />
I'm leaving this on the Talk page as I haven't even tried it out in QEMU myself. Also, my eyes are about ready to pop out of my head, so I'm barring myself from figuring out the appropriate way to edit this in for the time being. [[User:BrainwreckedTech|BrainwreckedTech]] ([[User talk:BrainwreckedTech|talk]]) 21:23, 14 January 2014 (UTC)<br />
<br />
== Replace -net with -netdev ==<br />
<br />
The {{ic|-net}} option is deprecated and replaced by {{ic|-netdev}}. I think this article should be modified to reflect that.<br />
http://en.wikibooks.org/wiki/QEMU/Networking#cite_ref-1<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 18:12, 1 July 2014 (UTC)<br />
<br />
:Yes {{ic|-net}} is the old syntax as stated in [https://wiki.gentoo.org/wiki/QEMU/Options#Pass-through Gentoo's Wiki] where we should use {{ic|1=-netdev user,id=vmnic -device virtio-net,netdev=vmnic}} [[User:Pickfire|Pickfire]] ([[User talk:Pickfire|talk]]) 04:11, 31 March 2017 (UTC)<br />
<br />
== I'm rewriting the network section ==<br />
<br />
https://wiki.archlinux.org/index.php/User:Axper/sandbox/qemu_network<br />
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 20:07, 2 July 2014 (UTC)<br />
<br />
::I think a lot of networking topics could be moved outside of the QEMU page. Many virtualization applications share the same basic principles with regards to networking, such as tun/tap creating, bridges, VDE, etc. There are a few networking schemes that are QEMU-specific, for example multicast sockets and {{ic|-net socket,...}}, and these could be mentioned on the QEMU page, although these are less reliable and rarely used in comparison to tap devices. We should also of course note the QEMU-specific command line options in the QEMU page, but for general concepts and commands independent of the virtualization applications, they could go on pages dedicated to the task. The best example is VDE, which is in no way limited to QEMU, yet it still doesn't have its own page on the Arch wiki.<br />
<br />
::Incidentally, I'm planning on rewriting [[User Mode Linux]] (yes, I promise I will get around to it), which happens to share the "tap with bridge" and VDE concepts with QEMU. It would be nice if I could link to pages dedicated to those topics and only write UML-specific commands in the page, instead of duplicating a bunch of general information. I'm not familiar very familiar with Xen or LXC or Docker or the like, but I would suspect that they also share some networking infrastructure. We could possibly even create a category just for these types of pages, for example "Virtual Networking" or "Advanced Networking". [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 13:32, 19 February 2015 (UTC)<br />
<br />
== -enable-kvm vs -machine type=pc,accel=kvm ==<br />
<br />
The section [[QEMU#Enabling_KVM]] recommends {{ic|-enable-kvm}}, while [[QEMU#Virtual_machine_runs_too_slowly]] recommends {{ic|1=-machine type=pc,accel=kvm}}. Is there any difference between the two? Is one preferred over the other? Should we just link to the former section from the latter (and possibly move both command line switches to the same section)? [[User:EscapedNull|EscapedNull]] ([[User talk:EscapedNull|talk]]) 17:23, 18 January 2015 (UTC)<br />
<br />
:2.5 years later... Has anyone found an answer to the question of `-enable-kvm` VS `-machine type=pc,accel=kvm`? -[[User:Physicist1616|Physicist1616]] ([[User talk:Physicist1616|talk]]) 19:32, 3 August 2017 (UTC)<br />
<br />
::Yes. They're equivalent. [https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg00132.html Discussion on the QEMU mailing list] about marking {{ic|-enable-kvm}} deprecated didn't result in that; {{ic|-enable-hax}} did get deprecated. Confusing, especially when checking whether e.g. libvirt has actually started the machine with KVM enabled. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 16:24, 4 December 2018 (UTC)<br />
<br />
== virtio-gpu ==<br />
<br />
Any tutorial on using the new virtio-gpu which is introduced in qemu-2.4 and kernel 4.2? [[User:Adam900710|Adam900710]] ([[User talk:Adam900710|talk]]) 02:44, 19 August 2015 (UTC)<br />
<br />
:Should be "plug and play" with recent kernel and other packages: [https://www.kraxel.org/blog/2016/09/using-virtio-gpu-with-libvirt-and-spice/ article]. The article is about libvirt, but I've run Arch guest on Arch host successfully with qemu script. [[User:Nesk|Nesk]] ([[User talk:Nesk|talk]]) 09:24, 4 October 2016 (UTC)<br />
<br />
== host only networking ==<br />
<br />
I added a quick and easy method but it was deleted. I found errors in what is here. Is it worth my time to correct them or will they be deleted? {{unsigned|16:39, 4 January 2016|Netskink}}<br />
<br />
:You are welcome to make any corrections. Nobody can tell you if they will be kept or reverted beforehand, but if you're afraid to waste your time feel free to just point them out using an [[Help:Template|Article status templates|article status template]] (should be less time consuming). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:28, 21 February 2016 (UTC)<br />
<br />
== Windows 7 specific issues ==<br />
<br />
I have noticed that for me, any attempts at installing Windows 7 using qemu with virt-manager as a frontend stalls on "Starting Windows." This is immediately after booting the computer for the first time. In Virt-manager, I am able to change the Display from QXL to Cirrus to fix the issue. I'm not sure if this applies to this page in particular, but if so, might be worth adding to the "Troubleshooting" section -- [[User:Ephreal|Ephreal]] ([[User talk:Ephreal|talk]]) 14:25, 10 August 2016 (UTC)<br />
<br />
== Using existing partition on GPT disk (with linear RAID or otherwise) ==<br />
<br />
[https://wiki.archlinux.org/index.php/QEMU#Simulate_virtual_disk_with_MBR_using_linear_RAID Section on using existing partition] is pretty awesome, but it is MBR-specific. Can someone with enough knowledge create a similar section about GPT disk please?<br />
<br />
== Could not access KVM kernel module: Permission denied ==<br />
<br />
Simply changing {{ic|1=group = "78"}} to {{ic|1=group = "kvm"}} in {{ic|/etc/libvirt/qemu.conf}} was not enough for me to fix this issue. Indeed, some files were still installed with gid 78, which you can confirm with:<br />
<br />
find / -gid 78<br />
<br />
So in the end, I still had to change the group id of kvm to workaround this issue:<br />
<br />
groupmod -g 78 kvm<br />
<br />
{{unsigned|17:15, 1 September 2017|Nivata}}<br />
<br />
== Starting QEMU virtual machines with systemd in 2018 ==<br />
<br />
The custom service script uses KillMethod=none to avoid the virtual machine being killed before shutdown. Here is an example to avoid this logic using {{Pkg|socat}}:<br />
<br />
ExecStart=/usr/bin/env qemu-system-x86_64 -name %i … -monitor unix:/var/run/qemu-%i.monitor,server,nowait<br />
ExecStop=/bin/sh -c 'echo system_powerdown | socat stdio,ignoreeof /var/run/qemu-%i.monitor'<br />
<br />
In this way, the stop command will exit when the QEMU monitor closes the socket. Other options, e.g. PIDFile or KillMode are not necessary.<br />
<br />
While a unix socket is used for this example, it works as well with telnet/tcp-connect.<br />
[[User:Ypnos|Ypnos]] ([[User talk:Ypnos|talk]]) 18:29, 30 January 2018 (UTC)<br />
<br />
I've tested using {{Pkg|openbsd-netcat}}, and that variant seems to keep the connection open after issuing the command as well. So there are a couple options to avoid using the KillMethod, which I agree is not a good idea.<br />
[[User:Djmoch|Djmoch]] ([[User talk:Djmoch|talk]]) 13:21, 2 March 2019 (UTC)<br />
<br />
== e1000e: waiting for carrier... timed out ==<br />
<br />
my physical host is an ArchLinux with 4.14.40-1-lts kernel and Qemu 2.12.0.<br />
<br />
in my first virtualisation case, my guest is an ArchLinux with 4.9.36-1-lts kernel (e1000e ver. 3.2.6-k) : everything works normally when I request the assignment of a network address with dhcpcd (after a few seconds, my guest gets the 10.0.2.15 intended address).<br />
<br />
in my second virtualisation case, my guest is an ArchLinux with 4.14.40-1-lts kernel (e1000e ver. 3.2.6-k) : no carrier is detected and therefore no address is assigned to the enp0s2 network card.<br />
<br />
I think the problem would rather come from the virtualized 4.14.40-1-lts kernel side because I do not meet it on my physical host which also uses the e1000e module...<br />
<br />
does anyone have an idea or a lead ?<br />
<br />
(this problem does not appear if I add in both cases the parameter "-machine pc" which forces the use of the module e1000/ens3 instead of the module e1000e/enp0s2).<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 16:09, 28 May 2018 (UTC)<br />
<br />
== Options for fstab with 9p ==<br />
https://wiki.archlinux.org/index.php?title=QEMU&diff=next&oldid=573709<br />
<br />
Maybe the options are not very hard to deduce, but they are not obvious, and having them written down is very useful as a "cheat sheet".<br />
<br />
[[User:Marmistrz|Marmistrz]] ([[User talk:Marmistrz|talk]]) 15:19, 15 June 2019 (UTC)<br />
<br />
:The options (and more) are written on the page which is linked from the section: https://wiki.qemu.org/Documentation/9psetup -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:23, 15 June 2019 (UTC)<br />
<br />
: +1 to keep the options. I suggest also to mention <tt>msize=512000</tt> option necessary to achieve satisfactory performance, this is something qemu docs fail to mention [[User:Ivank|Ivank]] ([[User talk:Ivank|talk]]) 17:39, 15 June 2019 (UTC)<br />
<br />
::{{ic|msize}} is also mentioned on the linked page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:13, 15 June 2019 (UTC)<br />
<br />
::: Yes, in a totally useless way, just that msize exists and 8192 is the default. msize=512000 (max) vs msize=8192 (default) is 10x throughput difference in my testing, that's not mentioned and I'd argue is a much more important and helpful fact to know for a user. [[User:Ivank|Ivank]] ([[User talk:Ivank|talk]]) 18:40, 15 June 2019 (UTC)<br />
<br />
== VDE ==<br />
<br />
can you tell me if you are also having trouble running VDE with QEMU ? for my part, I encounter a very random functioning with the set below:<br />
<br />
vde_switch<br />
<br />
slirpvde -n 192.168.0.0.0 -L 2222:192.168.0.102:22<br />
Starting slirpvde: virtual_host=192.168.0.2/24<br />
DNS =192.168.0.3<br />
vde switch =*DEFAULT*<br />
redir TCP =2222:192.168.0.102:22<br />
<br />
qemu -m 512 -nic vde,mac=52:54:00:12:34:56 -hda samba.disk # 192.168.0.101<br />
<br />
qemu -m 512 -nic vde,mac=52:54:00:12:34:57 -hda linux.disk # 192.168.0.102<br />
<br />
qemu -m 1024 -nic vde,mac=52:54:00:12:34:58 -hda windows.disk # 192.168.0.103<br />
<br />
dysfunctions are for example no answer when I execute the {{ic|ssh -p 2222 root@localhost}} command from another console or the loss of connection (freeze) with my Linux VM when it finally established.<br />
I checked several times the network configuration of my three virtual machines.<br />
the logs do not report any particular errors.<br />
<br />
I use the trio {{ic|vde_switch}}, {{ic|slirpvde}} and {{ic|nic vde}} because it does not require any privileges.<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 12:49, 23 September 2019 (UTC)<br />
<br />
== Systemd service starting qemu as root ==<br />
<br />
The systemd unit suggested at [[QEMU#With_systemd_service]] runs qemu as root, unless it is started as a [[Systemd/User|user service]]. Running qemu as root is explicitly discouraged from at [[QEMU#Running_virtualized_system]]. I suggest adding {{ic|-runas some_user}} to {{ic|1=ExecStart=}}, or {{ic|1=User=some_user}} and {{ic|1=Group=some_group}}. I prefer the former, because it allows to access block devices owned by root, in particular LVM logical volumes.<br />
<br />
[[User:Respiranto|Respiranto]] ([[User talk:Respiranto|talk]]) 19:45, 28 November 2020 (UTC)<br />
<br />
== UEFI with vanilla QEMU? ==<br />
<br />
I'm not exactly sure if this is possible, however /usr/share/qemu seems to have support for many different UEFI implementations and the -bios option seems to be the one that specifies which one to use, however I have seen little to no documentation on the subject (probably because it is usually abstracted away by libvirt).<br />
<br />
[[User:BTDMaster|BTDMaster]] ([[User talk:BTDMaster|talk]]) 10:54, 2 April 2021 (UTC)<br />
<br />
: You haven't used your google powers, there are enough examples online. I'm just dropping here some code from my now-archived vm startup script (libvirt is much nicer).<br />
{{bc|1=<br />
# cp /usr/share/edk2-ovmf/x64/OVMF_VARS.fd /tmp/my_vars.bin<br />
if [ "$OVMF" = "yes" ]; then<br />
QEMU_ARG="$QEMU_ARG \<br />
-drive if=pflash,format=raw,readonly,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd \<br />
-drive if=pflash,format=raw,file=$DRV_BASE/${DRV_IMG}.fd"<br />
else<br />
QEMU_ARG="$QEMU_ARG \<br />
-bios /usr/share/qemu/bios.bin"<br />
fi<br />
}}<br />
: [[User:Tinywrkb|Tinywrkb]] ([[User talk:Tinywrkb|talk]]) 12:08, 2 April 2021 (UTC)<br />
<br />
:: Thank you! I've seen OVMF mentioned, but I thought the binaries provided by QEMU would be enough. (Saving less than 15 MB, I know.)<br />
:: [[User:BTDMaster|BTDMaster]] ([[User talk:BTDMaster|talk]]) 20:52, 2 April 2021 (UTC)<br />
<br />
== Fix short-form boolean options ==<br />
<br />
[https://www.mail-archive.com/qemu-devel@nongnu.org/msg775793.html QEMU has deprecated short-form boolean options]. I have fixed the one instance of this that I was warned about in my own script ("-spice"), but I am sure there are more instances of this in this page that have to be fixed.<br />
<br />
[[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 03:08, 19 July 2021 (UTC)<br />
<br />
== UEFI instructions ==<br />
<br />
I found two different places with almost identical instructions how to boot QEMU with UEFI:<br />
<br />
* [[PCI passthrough via OVMF#Plain QEMU without libvirt]]<br />
* [[Unified Extensible Firmware Interface#OVMF for virtual machines]]<br />
<br />
But the [[QEMU]] article does not mention UEFI at all! I find this situation a bit absurd.<br />
<br />
I think it would be better to create a new section named, for example, '''"Booting a virtual machine in UEFI mode"''' (probably as a "Tips and tricks" subsection) and redirect to that section from other articles to prevent duplication of instructions.<br />
<br />
(I can do it myself if there are no objections.)<br />
<br />
[[User:Andreymal|andreymal]] ([[User talk:Andreymal|talk]]) 16:54, 6 February 2022 (UTC)<br />
<br />
:Sounds good to me. Though, I don't think [[QEMU#Tips and tricks|Tips and tricks]] would be the ideal place. Maybe in [[QEMU#Running virtualized system]] or as a separate top-level section. This page is overdue for a large overhaul anyway... -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 11:15, 7 February 2022 (UTC)<br />
<br />
:Created: [[QEMU#Booting in UEFI mode]]. I was testing UEFI support by running Windows 11 as a guest OS, so I accidentally created another section: [[QEMU#Trusted Platform Module emulation]].<br />
:I am not sure they are good enough, so feel free to edit or even shorten them if they are too long.<br />
:I did not mention Secure Boot because I did not find an easy way to install all the necessary keys (I just copied {{ic|/usr/share/OVMF/OVMF_VARS.ms.fd}} from [https://packages.ubuntu.com/jammy/ovmf ubuntu/ovmf] which is stupid). I think it would be nice if someone would add an additional subsection about Secure Boot.<br />
:[[User:Andreymal|andreymal]] ([[User talk:Andreymal|talk]]) 17:36, 6 August 2022 (UTC)<br />
::Copying from ubuntu/debian [https://bbs.archlinux.org/viewtopic.php?pid=2032619#p2032619 does not sound like a bad idea]. Although the preferred way should be either hard-coding Microsoft's keys during compilation (is that achievable?), or [https://projectacrn.github.io/latest/tutorials/waag-secure-boot.html#use-qemu-to-inject-secure-boot-keys-into-ovmf injecting them manually in UEFI settings] the same way you load custom keys to a physical machine.<br />
::In the aforementioned guide, replace {{ic|1=-hda fat:hda-contents}} with [https://en.wikibooks.org/wiki/QEMU/Devices/Storage VVFAT] arg {{ic|1=-drive file=fat:rw:hda-contents,format=raw}}.<br />
::These cost me tons of googling. Consider giving some hints on this wiki page.<br />
::[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 09:59, 8 September 2022 (UTC)<br />
<br />
== qemu-user-static and binfmt-qemu-static no longer exist ==<br />
<br />
Wiki still mentions them, but they have been deleted from the AUR.</div>PXfhttps://wiki.archlinux.org/index.php?title=QEMU&diff=745225QEMU2022-09-08T02:41:47Z<p>PXf: /* Enabling KVM */ we aren't likely to start them at the same time</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Hypervisors]]<br />
[[de:QEMU]]<br />
[[es:QEMU]]<br />
[[fr:QEMU]]<br />
[[it:QEMU]]<br />
[[ja:QEMU]]<br />
[[zh-hans:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related|QEMU/Guest graphics acceleration}}<br />
{{Related|PCI passthrough via OVMF}}<br />
{{Related articles end}}<br />
<br />
According to the [https://wiki.qemu.org/Main_Page QEMU about page], "QEMU is a generic and open source machine emulator and virtualizer."<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|qemu-full}} package (or {{Pkg|qemu-base}} for the version without GUI) and below optional packages for your needs:<br />
<br />
* {{Pkg|qemu-block-gluster}} - [[Glusterfs]] block support<br />
* {{Pkg|qemu-block-iscsi}} - [[iSCSI]] block support<br />
* {{Pkg|qemu-block-rbd}} - [https://docs.ceph.com/en/quincy/rbd/index.html RBD] block support <br />
* {{Pkg|samba}} - [[Samba|SMB/CIFS]] server support<br />
<br />
Alternatively, {{AUR|qemu-user-static}} exists as a usermode and static variant.<br />
<br />
=== QEMU variants ===<br />
<br />
QEMU is offered in several variants suited for different use cases.<br />
<br />
As a first classification, QEMU is offered in full-system and usermode emulation modes:<br />
<br />
; Full-system emulation<br />
: In this mode, QEMU emulates a full system, including one or several processors and various peripherals. It is more accurate but slower, and does not require the emulated OS to be Linux.<br />
: QEMU commands for full-system emulation are named {{ic|qemu-system-''target_architecture''}}, e.g. {{ic|qemu-system-x86_64}} for emulating intel 64-bit CPUs, {{ic|qemu-system-i386}} for intel 32 bits CPUs, {{ic|qemu-system-arm}} for ARM (32 bits), {{ic|qemu-system-aarch64}} for ARM64, etc.<br />
: If the target architecture matches the host CPU, this mode may still benefit from a significant speedup by using a hypervisor like [[#Enabling KVM|KVM]] or Xen.<br />
; [https://www.qemu.org/docs/master/user/main.html Usermode emulation]: In this mode, QEMU is able to invoke a Linux executable compiled for a (potentially) different architecture by leveraging the host system resources. There may be compatibility issues, e.g. some features may not be implemented, dynamically linked executables will not work out of the box (see [[#Chrooting into arm/arm64 environment from x86_64]] to address this) and only Linux is supported (although [https://wiki.winehq.org/Emulation Wine may be used] for running Windows executables).<br />
: QEMU commands for usermode emulation are named {{ic|qemu-''target_architecture''}}, e.g. {{ic|qemu-x86_64}} for emulating intel 64-bit CPUs.<br />
<br />
QEMU is offered in dynamically-linked and statically-linked variants:<br />
<br />
; Dynamically-linked (default): {{ic|qemu-*}} commands depend on the host OS libraries, so executables are smaller.<br />
; Statically-linked: {{ic|qemu-*}} commands can be copied to any Linux system with the same architecture.<br />
<br />
In the case of Arch Linux, full-system emulation is offered as:<br />
<br />
; Non-headless (default): This variant enables GUI features that require additional dependencies (like SDL or GTK).<br />
; Headless: This is a slimmer variant that does not require GUI (this is suitable e.g. for servers).<br />
<br />
Note that headless and non-headless versions install commands with the same name (e.g. {{ic|qemu-system-x86_64}}) and thus cannot be both installed at the same time.<br />
<br />
=== Details on packages available in Arch Linux ===<br />
<br />
* The {{Pkg|qemu-desktop}} package provides the {{ic|x86_64}} architecture emulators for full-system emulation ({{ic|qemu-system-x86_64}}). The {{Pkg|qemu-emulators-full}} package provides the {{ic|x86_64}} usermode variant ({{ic|qemu-x86_64}}) and also for the rest of supported architectures it includes both full-system and usermode variants (e.g. {{ic|qemu-system-arm}} and {{ic|qemu-arm}}).<br />
* The headless versions of these packages (only applicable to full-system emulation) are {{Pkg|qemu-base}} ({{ic|x86_64}}-only) and {{Pkg|qemu-emulators-full}} (rest of architectures).<br />
* Full-system emulation can be expanded with some QEMU modules present in separate packages: {{Pkg|qemu-block-gluster}}, {{Pkg|qemu-block-iscsi}}, {{Pkg|qemu-block-rbd}} and {{Pkg|qemu-guest-agent}}.<br />
* The unofficial AUR package {{AUR|qemu-user-static}} provides a usermode and static variant for all target architectures supported by QEMU. A precompiled version of this package exists: {{AUR|qemu-user-static-bin}}. The installed QEMU commands are named {{ic|qemu-''target_architecture''-static}}, for example, {{ic|qemu-x86_64-static}} for intel 64-bit CPUs.<br />
* The unofficial AUR package {{AUR|qemu-loongarch64-git}} (along with {{AUR|qemu-system-loongarch64-git}} and {{AUR|qemu-loongarch64-static-git}}) provide QEMU for the LoongArch architecture, officially supported since [https://wiki.qemu.org/ChangeLog/7.1#LoongArch version 7.1].<br />
<br />
{{Note|At present, Arch does not offer a full-system mode and statically linked variant (neither officially nor via AUR), as this is usually not needed.}}<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s).<br />
<br />
[[Libvirt]] provides a convenient way to manage QEMU virtual machines. See [[Libvirt#Client|list of libvirt clients]] for available front-ends.<br />
<br />
Other GUI front-ends for QEMU:<br />
<br />
* {{App|AQEMU|QEMU GUI written in Qt5.|https://github.com/tobimensch/aqemu|{{AUR|aqemu}}}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Accuracy|If I get the man page right the raw format only allocates the full size if the filesystem does not support "holes" or it is <br />
explicitly told to preallocate. See {{man|1|qemu-img|NOTES}}.}} <br />
<br />
{{Tip|See [[Wikibooks:QEMU/Images]] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. This image format also supports QEMU snapshotting functionality (see [[#Creating and managing snapshots via the monitor console]] for details). However, using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GiB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-on-Write (CoW)|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-x86_64 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. It is recommended to create a backup first.}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GiB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss! For a Windows guest, open the "create and format hard disk partitions" control panel.<br />
<br />
==== Converting an image ====<br />
<br />
You can convert an image to other formats using {{ic|qemu-img convert}}. This example shows how to convert a ''raw'' image to ''qcow2'':<br />
<br />
$ qemu-img convert -f raw -O qcow2 ''input''.img ''output''.qcow2<br />
<br />
This will not remove the original input file.<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso'' bs=4k}}}}<br />
<br />
=== Installing the operating system ===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM and a raw disk image:<br />
<br />
$ qemu-system-x86_64 -cdrom ''iso_image'' -boot order=d -drive file=''disk_image'',format=raw<br />
<br />
See {{man|1|qemu}} for more information about loading other media types (such as floppy, disk images or physical drives) and [[#Running virtualized system]] for other useful options.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Note|By default only 128 MiB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.}}<br />
<br />
{{Tip|<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* When running QEMU in headless mode, it starts a local VNC server on port 5900 per default. You can use [[TigerVNC]] to connect to the guest OS: {{ic|vncviewer :5900}}<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.<br />
}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-x86_64 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{man|1|qemu}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt+g}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM (''Kernel-based Virtual Machine'') full virtualization must be supported by your Linux kernel and your hardware, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-accel kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the [[#QEMU monitor]] and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* The argument {{ic|1=accel=kvm}} of the {{ic|-machine}} option is equivalent to the {{ic|-enable-kvm}} or the {{ic|-accel kvm}} option.<br />
* CPU model {{ic|host}} requires KVM<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 or Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
=== Enabling IOMMU (Intel VT-d/AMD-Vi) support ===<br />
<br />
First enable IOMMU, see [[PCI passthrough via OVMF#Setting up IOMMU]].<br />
<br />
Add {{ic|-device intel-iommu}} to create the IOMMU device:<br />
<br />
$ qemu-system-x86_64 '''-enable-kvm -machine q35 -device intel-iommu''' -cpu host ..<br />
<br />
{{Note|<br />
On Intel CPU based systems creating an IOMMU device in a QEMU guest with {{ic|-device intel-iommu}} will disable PCI passthrough with an error like: {{bc|Device at bus pcie.0 addr 09.0 requires iommu notifier which is currently not supported by intel-iommu emulation}} While adding the kernel parameter {{ic|1=intel_iommu=on}} is still needed for remapping IO (e.g. [[PCI passthrough via OVMF#Isolating the GPU|PCI passthrough with vfio-pci]]), {{ic|-device intel-iommu}} should not be set if PCI passthrough is required.<br />
}}<br />
<br />
=== Booting in UEFI mode ===<br />
<br />
The default firmware used by QEMU is [https://www.coreboot.org/SeaBIOS SeaBIOS], which is a Legacy BIOS implementation. QEMU uses {{ic|/usr/share/qemu/bios-256k.bin}} (provided by the {{Pkg|seabios}} package) as a default read-only (ROM) image. You can use the {{ic|-bios}} argument to select another firmware file. However, UEFI requires writable memory to work properly, so you need to emulate [https://wiki.qemu.org/Features/PC_System_Flash PC System Flash] instead.<br />
<br />
[https://github.com/tianocore/tianocore.github.io/wiki/OVMF OVMF] is a TianoCore project to enable UEFI support for Virtual Machines. It can be [[install]]ed with the {{Pkg|edk2-ovmf}} package.<br />
<br />
There are two ways to use OVMF as a firmware. The first is to copy {{ic|/usr/share/edk2-ovmf/x64/OVMF.fd}}, make it writable and use as a pflash drive:<br />
<br />
-drive if=pflash,format=raw,file=''/copy/of/OVMF.fd''<br />
<br />
All changes to the UEFI settings will be saved directly to this file.<br />
<br />
Another and more preferable way is to split OVMF into two files. The first one will be read-only and store the firmware executable, and the second one will be used as a writable variable store. The advantage is that you can use the firmware file directly without copying, so it will be updated automatically by [[pacman]].<br />
<br />
Use {{ic|/usr/share/edk2-ovmf/x64/OVMF_CODE.fd}} as a first read-only pflash drive. Copy {{ic|/usr/share/edk2-ovmf/x64/OVMF_VARS.fd}}, make it writable and use as a second writable pflash drive:<br />
<br />
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd \<br />
-drive if=pflash,format=raw,file=''/copy/of/OVMF_VARS.fd''<br />
<br />
=== Trusted Platform Module emulation ===<br />
<br />
QEMU can emulate [[Trusted Platform Module]], which is required by some systems such as Windows 11.<br />
<br />
[[Install]] the {{Pkg|swtpm}} package, which provides a software TPM implementation. Create some directory for storing TPM data ({{ic|''/path/to/mytpm''}} will be used as an example). Run this command to start the emulator:<br />
<br />
$ swtpm socket --tpm2 --tpmstate dir=''/path/to/mytpm'' --ctrl type=unixio,path=''/path/to/mytpm/swtpm-sock''<br />
<br />
{{ic|''/path/to/mytpm/swtpm-sock''}} will be created by ''swtpm'': this is a UNIX socket to which QEMU will connect. You can put it in any directory.<br />
<br />
By default, ''swtpm'' starts a TPM version 1.2 emulator. The {{ic|--tpm2}} option enables TPM 2.0 emulation.<br />
<br />
Finally, add the following options to QEMU:<br />
<br />
-chardev socket,id=chrtpm,path=''/path/to/mytpm/swtpm-sock'' \<br />
-tpmdev emulator,id=tpm0,chardev=chrtpm \<br />
-device tpm-tis,tpmdev=tpm0<br />
<br />
and TPM will be available inside the VM. After shutting down the VM, ''swtpm'' will be automatically terminated.<br />
<br />
See [https://qemu-project.gitlab.io/qemu/specs/tpm.html the QEMU documentation] for more information.<br />
<br />
== Sharing data between host and guest ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network block device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's port forwarding ===<br />
<br />
{{Note|QEMU's port forwarding is IPv4-only. IPv6 port forwarding is not implemented and the last patches were proposed in 2018.[https://lore.kernel.org/qemu-devel/1540512223-21199-1-git-send-email-max7255@yandex-team.ru/T/#u]}}<br />
<br />
QEMU can forward ports from the host to the guest to enable e.g. connecting from the host to an SSH server running on the guest.<br />
<br />
For example, to bind port 60022 on the host with port 22 (SSH) on the guest, start QEMU with a command like:<br />
<br />
$ qemu-system-x86_64 ''disk_image'' -nic user,hostfwd=tcp::60022-:22<br />
<br />
Make sure the sshd is running on the guest and connect with:<br />
<br />
$ ssh ''guest-user''@127.0.0.1 -p 60022<br />
<br />
You can use [[SSHFS]] to mount the guest's file system at the host for shared read and write access.<br />
<br />
To forward several ports, you just repeat the {{ic|hostfwd}} in the {{ic|-nic}} argument, e.g. for VNC's port:<br />
<br />
$ qemu-system-x86_64 ''disk_image'' -nic user,hostfwd=tcp::60022-:22,hostfwd=tcp::5900-:5900<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] on the host with an automatically generated {{ic|smb.conf}} file located in {{ic|/tmp/qemu-smb.''random_string''}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and is useful when you do not want to start the normal [[Samba]] service on the host, which the guest can also access if you have set up shares on it.<br />
<br />
Only a single directory can be set as shared with the option {{ic|1=smb=}}, but adding more directories (even while the virtual machine is running) could be as easy as creating symbolic links in the shared directory if QEMU configured SMB to follow symbolic links. It does not do so, but the configuration of the running SMB server can be changed as described below.<br />
<br />
''Samba'' must be installed on the host. To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-x86_64 -nic user,id=nic0,smb=''shared_dir_path'' ''disk_image''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [https://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
* If you cannot access the shared folder and the guest system is Windows 10 Enterprise or Education or Windows Server 2016, [https://support.microsoft.com/en-us/help/4046019 enable guest access].<br />
* If you use [[#Tap networking with QEMU]], use {{ic|1=-device virtio-net,netdev=vmnic -netdev user,id=vmnic,smb=''shared_dir_path''}} to get SMB.<br />
}}<br />
<br />
One way to share multiple directories and to add or remove them while the virtual machine is running, is to share an empty directory and create/remove symbolic links to the directories in the shared directory. For this to work, the configuration of the running SMB server can be changed with the following script, which also allows the execution of files on the guest that are not set executable on the host:<br />
<br />
#!/bin/sh<br />
eval $(ps h -C smbd -o pid,args | grep /tmp/qemu-smb | gawk '{print "pid="$1";conf="$6}')<br />
echo "[global]<br />
allow insecure wide links = yes<br />
[qemu]<br />
follow symlinks = yes<br />
wide links = yes<br />
acl allow execute always = yes" >> "$conf"<br />
# in case the change is not detected automatically:<br />
smbcontrol --configfile="$conf" "$pid" reload-config<br />
<br />
This can be applied to the running server started by qemu only after the guest has connected to the network drive the first time. An alternative to this method is to add additional shares to the configuration file like so:<br />
<br />
echo "[''myshare'']<br />
path=''another_path''<br />
read only=no<br />
guest ok=yes<br />
force user=''username''" >> $conf<br />
<br />
This share will be available on the guest as {{ic|\\10.0.2.4\''myshare''}}.<br />
<br />
=== Using filesystem passthrough and VirtFS ===<br />
<br />
See the [https://wiki.qemu.org/Documentation/9psetup QEMU documentation].<br />
<br />
=== Host file sharing with virtiofsd ===<br />
<br />
{{Style|See [[Help:Style/Formatting and punctuation]].}}<br />
<br />
virtiofsd is shipped with QEMU package. Documentation is available [https://qemu-stsquad.readthedocs.io/en/docs-next/tools/virtiofsd.html online] or {{ic|/usr/share/doc/qemu/tools/virtiofsd.html}} on local file system with QEMU installed.<br />
<br />
Add user that runs qemu to 'kvm' group, because it needs to access virtiofsd socket. You might have to logout for change to take effect.<br />
<br />
{{Accuracy|Running services as root is not secure. Also the process should be wrapped in a systemd service.}}<br />
<br />
Start as virtiofsd as root:<br />
<br />
# /usr/lib/qemu/virtiofsd --socket-path=/var/run/qemu-vm-001.sock -o source=/tmp/vm-001 -o cache=always<br />
<br />
where<br />
<br />
* {{ic|/var/run/qemu-vm-001.sock}} is a socket file,<br />
* {{ic|/tmp/vm-001}} is a shared directory between host and guest vm.<br />
<br />
The created socket file has root only access permission. Give group kvm access to it with:<br />
<br />
# chgrp kvm qemu-vm-001.sock; chmod g+rxw qemu-vm-001.sock<br />
<br />
Add the following configuration options when starting VM:<br />
<br />
-object memory-backend-memfd,id=mem,size=4G,share=on \<br />
-numa node,memdev=mem \<br />
-chardev socket,id=char0,path=/var/run/qemu-vm-001.sock \<br />
-device vhost-user-fs-pci,chardev=char0,tag=myfs<br />
<br />
where<br />
<br />
{{Expansion|Explain the remaining options (or remove them if they are not necessary).}}<br />
<br />
* {{ic|1=size=4G}} shall match size specified with {{ic|-m 4G}} option,<br />
* {{ic|/var/run/qemu-vm-001.sock}} points to socket file started earlier,<br />
<br />
{{Style|The section should not be specific to Windows.}}<br />
<br />
Remember, that guest must be configured to enable sharing. For windows there are [https://virtio-fs.gitlab.io/howto-windows.html instructions]. Once configured, windows will have Z: drive mapped automatically with shared directory content. <br />
<br />
Your Windows 10 guest system is properly configured if it has:<br />
<br />
* VirtioFSSService windows service,<br />
* WinFsp.Launcher windows service,<br />
* VirtIO FS Device driver under "System devices" in Windows "Device Manager".<br />
<br />
If the above installed and {{ic|Z:}} drive is still not listed, try repairing "Virtio-win-guest-tools" in Windows add/remove programs.<br />
<br />
=== Mounting a partition of the guest on the host ===<br />
<br />
It can be useful to mount a drive image under the host system, it can be a way to transfer files in and out of the guest. This should be done when the virtual machine is not running.<br />
<br />
The procedure to mount the drive on the host depends on the type of qemu image, ''raw'' or ''qcow2''. We detail thereafter the steps to mount a drive in the two formats in [[#Mounting a partition from a raw image]] and [[#Mounting a partition from a qcow2 image]]. For the full documentation see [[Wikibooks:QEMU/Images#Mounting an image on the host]].<br />
<br />
{{Warning|You must unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== Mounting a partition from a raw image ====<br />
<br />
It is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices.<br />
<br />
===== With manually specifying byte offset =====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
===== With loop module autodetecting partitions =====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel modules#Manual module handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
To mount the disk image with ''udisksctl'', see [[Udisks#Mount loop devices]].<br />
<br />
===== With kpartx =====<br />
<br />
''kpartx'' from the {{Pkg|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
==== Mounting a partition from a qcow2 image ====<br />
<br />
We will use {{ic|qemu-nbd}}, which lets use the NBD (''network block device'') protocol to share the disk image.<br />
<br />
First, we need the ''nbd'' module loaded:<br />
<br />
# modprobe nbd max_part=16<br />
<br />
Then, we can share the disk and create the device entries:<br />
<br />
# qemu-nbd -c /dev/nbd0 ''/path/to/image.qcow2''<br />
<br />
Discover the partitions:<br />
<br />
# partprobe /dev/nbd0<br />
<br />
''fdisk'' can be used to get information regarding the different partitions in {{ic|''nbd0''}}:<br />
<br />
{{hc|# fdisk -l /dev/nbd0|2=<br />
Disk /dev/nbd0: 25.2 GiB, 27074281472 bytes, 52879456 sectors<br />
Units: sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disklabel type: dos<br />
Disk identifier: 0xa6a4d542<br />
<br />
Device Boot Start End Sectors Size Id Type<br />
/dev/nbd0p1 * 2048 1026047 1024000 500M 7 HPFS/NTFS/exFAT<br />
/dev/nbd0p2 1026048 52877311 51851264 24.7G 7 HPFS/NTFS/exFAT}}<br />
<br />
Then mount any partition of the drive image, for example the partition 2:<br />
<br />
# mount /dev/nbd0'''p2''' ''mountpoint''<br />
<br />
After the usage, it is important to unmount the image and reverse previous steps, i.e. unmount the partition and disconnect the nbd device:<br />
<br />
# umount ''mountpoint''<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you must either change the owner of the partition's device file to that user, add that user to the ''disk'' group, or use [[ACL]] for more fine-grained access control.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with an MBR. Such a virtual machine can be booted either by: [[#Specifying kernel and initrd manually]], [[#Simulating a virtual disk with MBR]], [[#Using the device-mapper]], [[#Using a linear RAID]] or [[#Using a Network Block Device]].<br />
<br />
==== Specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-x86_64 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulating a virtual disk with MBR ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate an MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
For the following, suppose you have a plain, unmounted {{ic|/dev/hda''N''}} partition with some file system on it you wish to make part of a QEMU disk image. The trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image. More generally, the partition can be any part of a larger simulated disk, in particular a block device that simulates the original physical disk but only exposes {{ic|/dev/hda''N''}} to the virtual machine.<br />
<br />
A virtual disk of this type can be represented by a VMDK file that contains references to (a copy of) the MBR and the partition, but QEMU does not support this VMDK format. For instance, a virtual disk [https://www.virtualbox.org/manual/ch09.html#rawdisk created by]<br />
<br />
$ VBoxManage internalcommands createrawvmdk -filename ''/path/to/file.vmdk'' -rawdisk /dev/hda<br />
<br />
will be rejected by QEMU with the error message<br />
<br />
Unsupported image type 'partitionedDevice'<br />
<br />
Note that {{ic|VBoxManage}} creates two files, {{ic|''file.vmdk''}} and {{ic|''file-pt.vmdk''}}, the latter being a copy of the MBR, to which the text file {{ic|file.vmdk}} points. Read operations outside the target partition or the MBR would give zeros, while written data would be discarded.<br />
<br />
===== Using the device-mapper =====<br />
<br />
A method that is similar to the use of a VMDK descriptor file uses the [https://docs.kernel.org/admin-guide/device-mapper/index.html device-mapper] to prepend a loop device attached to the MBR file to the target partition. In case we do not need our virtual disk to have the same size as the original, we first create a file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=2048<br />
<br />
Here, a 1 MiB (2048 * 512 bytes) file is created in accordance with partition alignment policies used by modern disk partitioning tools. For compatibility with older partitioning software, 63 sectors instead of 2048 might be required. The MBR only needs a single 512 bytes block, the additional free space can be used for a BIOS boot partition and, in the case of a hybrid partitioning scheme, for a GUID Partition Table. Then, we attach a loop device to the MBR file:<br />
<br />
# losetup --show -f ''/path/to/mbr''<br />
/dev/loop0<br />
<br />
In this example, the resulting device is {{ic|/dev/loop0}}. The device mapper is now used to join the MBR and the partition:<br />
<br />
# echo "0 2048 linear /dev/loop0 0<br />
2048 `blockdev --getsz /dev/hda''N''` linear /dev/hda''N'' 0" | dmsetup create qemu<br />
<br />
The resulting {{ic|/dev/mapper/qemu}} is what we will use as a QEMU raw disk image. Additional steps are required to create a partition table (see the section that describes the use of a linear RAID for an example) and boot loader code on the virtual disk (which will be stored in {{ic|''/path/to/mbr''}}).<br />
<br />
The following setup is an example where the position of {{ic|/dev/hda''N''}} on the virtual disk is to be the same as on the physical disk and the rest of the disk is hidden, except for the MBR, which is provided as a copy:<br />
<br />
# dd if=/dev/hda count=1 of=''/path/to/mbr''<br />
# loop=`losetup --show -f ''/path/to/mbr''`<br />
# start=`blockdev --report /dev/hda''N'' | tail -1 | awk '{print $5}'`<br />
# size=`blockdev --getsz /dev/hda''N''`<br />
# disksize=`blockdev --getsz /dev/hda`<br />
# echo "0 1 linear $loop 0<br />
1 $((start-1)) zero<br />
$start $size linear /dev/hda''N'' 0<br />
$((start+size)) $((disksize-start-size)) zero" | dmsetup create qemu<br />
<br />
The table provided as standard input to {{ic|dmsetup}} has a similar format as the table in a VDMK descriptor file produced by {{ic|VBoxManage}} and can alternatively be loaded from a file with {{ic|dmsetup create qemu --table ''table_file''}}. To the virtual machine, only {{ic|/dev/hda''N''}} is accessible, while the rest of the hard disk reads as zeros and discards written data, except for the first sector. We can print the table for {{ic|/dev/mapper/qemu}} with {{ic|dmsetup table qemu}} (use {{ic|udevadm info -rq name /sys/dev/block/''major'':''minor''}} to translate {{ic|''major'':''minor''}} to the corresponding {{ic|/dev/''blockdevice''}} name). Use {{ic|dmsetup remove qemu}} and {{ic|losetup -d $loop}} to delete the created devices.<br />
<br />
A situation where this example would be useful is an existing Windows XP installation in a multi-boot configuration and maybe a hybrid partitioning scheme (on the physical hardware, Windows XP could be the only operating system that uses the MBR partition table, while more modern operating systems installed on the same computer could use the GUID Partition Table). Windows XP supports hardware profiles, so that that the same installation can be used with different hardware configurations alternatingly (in this case bare metal vs. virtual) with Windows needing to install drivers for newly detected hardware only once for every profile. Note that in this example the boot loader code in the copied MBR needs to be updated to directly load Windows XP from {{ic|/dev/hda''N''}} instead of trying to start the multi-boot capable boot loader (like GRUB) present in the original system. Alternatively, a copy of the boot partition containing the boot loader installation can be included in the virtual disk the same way as the MBR.<br />
<br />
===== Using a linear RAID =====<br />
<br />
You can also do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: <br />
<br />
First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KiB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hda''N''}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kibibyte-roundable offsets (such as 31.5 KiB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-x86_64 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
===== Using a Network Block Device =====<br />
<br />
With [https://docs.kernel.org/admin-guide/blockdev/nbd.html Network Block Device], Linux can use a remote server as one of its block device. You may use {{ic|nbd-server}} (from the {{pkg|nbd}} package) to create an MBR wrapper for QEMU.<br />
<br />
Assuming you have already set up your MBR wrapper file like above, rename it to {{ic|wrapper.img.0}}. Then create a symbolic link named {{ic|wrapper.img.1}} in the same directory, pointing to your partition. Then put the following script in the same directory:<br />
<br />
#!/bin/sh<br />
dir="$(realpath "$(dirname "$0")")"<br />
cat >wrapper.conf <<EOF<br />
[generic]<br />
allowlist = true<br />
listenaddr = 127.713705<br />
port = 10809<br />
<br />
[wrap]<br />
exportname = $dir/wrapper.img<br />
multifile = true<br />
EOF<br />
<br />
nbd-server \<br />
-C wrapper.conf \<br />
-p wrapper.pid \<br />
"$@"<br />
<br />
The {{ic|.0}} and {{ic|.1}} suffixes are essential; the rest can be changed. After running the above script (which you may need to do as root to make sure nbd-server is able to access the partition), you can launch QEMU with:<br />
<br />
qemu-system-x86_64 -drive file=nbd:127.713705:10809:exportname=wrap ''[...]''<br />
<br />
=== Using an entire physical disk device inside the VM ===<br />
<br />
{{Style|Duplicates [[#Using any real partition as the single primary partition of a hard disk image]], libvirt instructions do not belong to this page.}}<br />
<br />
You may have a second hdd/ssd with a different OS (like Windows) on it and may want to gain the ability to also boot it inside a VM.<br />
Since the disk access is raw, the disk will perform quite well inside the VM.<br />
<br />
==== windows VM boot prerequisites ====<br />
<br />
Be sure to install the [https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-virtio/ virtio drivers] inside the OS on that disk before trying to boot it in the VM.<br />
For Win 7 use version [https://askubuntu.com/questions/1310440/using-virtio-win-drivers-with-win7-sp1-x64 0.1.173-4].<br />
Some singular drivers from newer virtio builds may be used on Win 7 but you will have to install them manually via device manager.<br />
For Win 10 you can use the latest virtio build.<br />
<br />
===== set up the windows disk interface drivers =====<br />
<br />
You may get a {{ic|0x0000007B}} bluescreen when trying to boot the VM. This means Windows can not access the drive during the early boot stage because the disk interface driver it would need for that is not loaded / is set to start manually.<br />
<br />
The solution is to [https://superuser.com/a/1032769 enable these drivers to start at boot].<br />
<br />
In {{ic|HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services}}, find the folders {{ic|aliide, amdide, atapi, cmdide, iastor (may not exist), iastorV, intelide, LSI_SAS, msahci, pciide and viaide}}.<br />
Inside each of those, set all their "start" values to 0 in order to enable them at boot.<br />
If your drive is a PCIe NVMe drive, also enable that driver (should it exist).<br />
<br />
==== find the unique path of your disk ====<br />
<br />
Run {{ic|ls /dev/disk/by-id/}}<br />
There you pick out the ID of the drive you want to insert into the VM, my disk ID is {{ic|ata-TS512GMTS930L_C199211383}}<br />
Now add that ID to {{ic|/dev/disk/by-id/}} so you get {{ic|/dev/disk/by-id/ata-TS512GMTS930L_C199211383}} .<br />
That is the unique path to that disk.<br />
<br />
==== add the disk in QEMU CLI ====<br />
<br />
In QEMU CLI that would probably be:<br />
<br />
{{ic|1=-drive file=/dev/disk/by-id/ata-TS512GMTS930L_C199211383,format=raw,media=disk}}<br />
<br />
Just modify "file=" to be the unique path of your drive.<br />
<br />
==== add the disk in libvirt ====<br />
<br />
In libvirt xml that translates to<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<disk type="block" device="disk"><br />
<driver name="qemu" type="raw" cache="none" io="native"/><br />
<source dev="/dev/disk/by-id/ata-TS512GMTS930L_C199211383"/><br />
<target dev="sda" bus="sata"/><br />
<address type="drive" controller="0" bus="0" target="0" unit="0"/><br />
</disk><br />
...<br />
</nowiki>}}<br />
<br />
Just modify "source dev" to be the unique path of your drive.<br />
<br />
==== add the disk in virt-manager ====<br />
<br />
When creating a VM, select "import existing drive" and just paste that unique path.<br />
If you already have the VM, add a device, storage, then select or create custom storage.<br />
Now paste the unique path.<br />
<br />
== Networking ==<br />
<br />
{{Style|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [https://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-x86_64 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
* Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
* Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-x86_64 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
* Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|2=<br />
#!/usr/bin/env python<br />
# usage: qemu-mac-hasher.py <VMName><br />
<br />
import sys<br />
import zlib<br />
<br />
crc = str(hex(zlib.crc32(sys.argv[1].encode("utf-8")))).replace("x", "")[-8:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-x86_64 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{Note|ICMPv6 will not work, as support for it is not implemented: {{ic|Slirp: external icmpv6 not supported yet}}. [[Ping]]ing an IPv6 address will not work.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
{{Note|If the host system uses [[systemd-networkd]], make sure to symlink the {{ic|/etc/resolv.conf}} file as described in [[systemd-networkd#Required services and setup]], otherwise the DNS lookup in the guest system will not work.}}<br />
<br />
{{Tip|To use the virtio driver with user-mode networking, the option is: {{ic|1=-nic user,model=virtio-net-pci}}.}}<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-device virtio-net,netdev=network0 -netdev tap,id=network0,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-device virtio-net,netdev=network0 -netdev tap,id=network0,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See [https://web.archive.org/web/20160222161955/http://www.linux-kvm.com:80/content/how-maximize-virtio-net-performance-vhost-net] for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* See [[Network bridge]] for information on creating bridge.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
<br />
{{bc|1=<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.20.0.2,172.20.255.254<br />
}}<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|<br />
* See [[Network bridge]] for information on creating bridge.<br />
* See https://wiki.qemu.org/Features/HelperNetworking for more information on QEMU's network helper.<br />
}}<br />
<br />
First, create a configuration file containing the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''br0''<br />
allow ''br1''<br />
...}}<br />
<br />
Make sure {{ic|/etc/qemu/}} has {{ic|755}} [[permissions]]. [https://gitlab.com/qemu-project/qemu/-/issues/515 QEMU issues] and [https://www.gns3.com/community/discussions/gns3-cannot-work-with-qemu GNS3 issues] may arise if this is not the case.<br />
<br />
Now start the VM; the most basic usage to run QEMU with the default network helper and default bridge {{ic|br0}}:<br />
<br />
$ qemu-system-x86_64 -nic bridge ''[...]''<br />
<br />
Using the bridge {{ic|br1}} and the virtio driver:<br />
<br />
$ qemu-system-x86_64 -nic bridge,br=''br1'',model=virtio-net-pci ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Style|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [https://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Optionally create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name. In the {{ic|run-qemu}} script below, {{ic|br0}} is set up if not listed, as it is assumed that by default the host is not accessing network via the bridge.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
: '<br />
e.g. with img created via:<br />
qemu-img create -f qcow2 example.img 90G<br />
run-qemu -cdrom archlinux-x86_64.iso -boot order=d -drive file=example.img,format=qcow2 -m 4G -enable-kvm -cpu host -smp 4<br />
run-qemu -drive file=example.img,format=qcow2 -m 4G -enable-kvm -cpu host -smp 4<br />
'<br />
<br />
nicbr0() {<br />
sudo ip link set dev $1 promisc on up &> /dev/null<br />
sudo ip addr flush dev $1 scope host &>/dev/null<br />
sudo ip addr flush dev $1 scope site &>/dev/null<br />
sudo ip addr flush dev $1 scope global &>/dev/null<br />
sudo ip link set dev $1 master br0 &> /dev/null<br />
}<br />
_nicbr0() {<br />
sudo ip link set $1 promisc off down &> /dev/null<br />
sudo ip link set dev $1 nomaster &> /dev/null<br />
}<br />
<br />
HASBR0="$( ip link show | grep br0 )"<br />
if [ -z $HASBR0 ] ; then<br />
ROUTER="192.168.1.1"<br />
SUBNET="192.168.1."<br />
NIC=$(ip link show | grep enp | grep 'state UP' | head -n 1 | cut -d":" -f 2 | xargs)<br />
IPADDR=$(ip addr show | grep -o "inet $SUBNET\([0-9]*\)" | cut -d ' ' -f2)<br />
sudo ip link add name br0 type bridge &> /dev/null<br />
sudo ip link set dev br0 up<br />
sudo ip addr add $IPADDR/24 brd + dev br0<br />
sudo ip route del default &> /dev/null<br />
sudo ip route add default via $ROUTER dev br0 onlink<br />
nicbr0 $NIC<br />
sudo iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
fi<br />
<br />
USERID=$(whoami)<br />
precreationg=$(ip tuntap list | cut -d: -f1 | sort)<br />
sudo ip tuntap add user $USERID mode tap<br />
postcreation=$(ip tuntap list | cut -d: -f1 | sort)<br />
TAP=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
nicbr0 $TAP<br />
<br />
printf -v MACADDR "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-x86_64 -net nic,macaddr=$MACADDR,model=virtio \<br />
-net tap,ifname=$TAP,script=no,downscript=no,vhost=on \<br />
$@<br />
<br />
_nicbr0 $TAP<br />
sudo ip link set dev $TAP down &> /dev/null<br />
sudo ip tuntap del $TAP mode tap<br />
<br />
if [ -z $HASBR0 ] ; then<br />
_nicbr0 $NIC<br />
sudo ip addr del dev br0 $IPADDR/24 &> /dev/null<br />
sudo ip link set dev br0 down<br />
sudo ip link delete br0 type bridge &> /dev/null<br />
sudo ip route del default &> /dev/null<br />
sudo ip link set dev $NIC up<br />
sudo ip route add default via $ROUTER dev $NIC onlink &> /dev/null<br />
fi<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
<br />
$ run-qemu -hda ''myvm.img'' -m 512<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [https://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Automatic module loading with systemd]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it is easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See [[Network bridge#Wireless interface on a bridge]] as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See [[Internet sharing]] as a reference.<br />
<br />
There you can find what is needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside {{ic|/etc/sysctl.d}}:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge does not include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Style|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [https://wiki.virtualsquare.org/ the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[install]]ed via the {{Pkg|vde2}} package.<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-x86_64 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be [[executable]]. <br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
==== Alternative method ====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-x86_64 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [https://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|2=<br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for users in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|2=<br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
=== Shorthand configuration ===<br />
<br />
If you are using QEMU with various networking options a lot, you probably have created a lot of {{ic|-netdev}} and {{ic|-device}} argument pairs, which gets quite repetitive. You can instead use the {{ic|-nic}} argument to combine {{ic|-netdev}} and {{ic|-device}} together, so that, for example, these arguments:<br />
<br />
-netdev tap,id=network0,ifname=tap0,script=no,downscript=no,vhost=on -device virtio-net-pci,netdev=network0<br />
<br />
become:<br />
<br />
-nic tap,script=no,downscript=no,vhost=on,model=virtio-net-pci<br />
<br />
Notice the lack of network IDs, and that the device was created with {{ic|1=model=}}. The first half of the {{ic|-nic}} parameters are {{ic|-netdev}} parameters, whereas the second half (after {{ic|1=model=}}) are related with the device. The same parameters (for example, {{ic|1=smb=}}) are used. To completely disable the networking use {{ic|-nic none}}.<br />
<br />
See [https://qemu.weilnetz.de/doc/6.0/system/net.html QEMU networking documentation] for more information on parameters you can use.<br />
<br />
== Graphic card ==<br />
<br />
QEMU can emulate a standard graphic card text mode using {{ic|-curses}} command line option. This allows to type text and see text output directly inside a text terminal. Alternatively, {{ic|-nographic}} serves a similar purpose.<br />
<br />
QEMU can emulate several types of VGA card. The card type is passed in the {{ic|-vga ''type''}} command line option and can be {{ic|std}}, {{ic|qxl}}, {{ic|vmware}}, {{ic|virtio}}, {{ic|cirrus}} or {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels without requiring guest drivers. This is the default since QEMU 2.2.<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest. You may want to use [[#SPICE]] for improved graphical performance when using QXL.<br />
<br />
On Linux guests, the {{ic|qxl}} and {{ic|bochs_drm}} kernel modules must be loaded in order to gain a decent performance.<br />
<br />
Default VGA memory size for QXL devices is 16M which is sufficient to drive resolutions approximately up to QHD (2560x1440). To enable higher resolutions, [[#Multi-monitor support|increase vga_memmb]].<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. Install the VMware drivers {{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests.<br />
<br />
=== virtio ===<br />
<br />
{{ic|virtio-vga}} / {{ic|virtio-gpu}} is a paravirtual 3D graphics driver based on [https://virgil3d.github.io/ virgl]. Currently a work in progress, supporting only very recent (>= 4.4) Linux guests with {{Pkg|mesa}} (>=11.2) compiled with the option {{ic|1=gallium-drivers=virgl}}.<br />
<br />
To enable 3D acceleration on the guest system select this vga with {{ic|-device virtio-vga-gl}} and enable the opengl context in the display device with {{ic|1=-display sdl,gl=on}} or {{ic|1=-display gtk,gl=on}} for the sdl and gtk display output respectively. Successful configuration can be confirmed looking at the kernel log in the guest:<br />
<br />
{{hc|# dmesg {{!}} grep drm |<br />
[drm] pci: virtio-vga detected<br />
[drm] virgl 3d acceleration enabled<br />
}}<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [https://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
== SPICE ==<br />
<br />
The [https://www.spice-space.org/ SPICE project] aims to provide a complete open source solution for remote access to virtual machines in a seamless way.<br />
<br />
=== Enabling SPICE support on the host ===<br />
<br />
The following is an example of booting with SPICE as the remote desktop protocol, including the support for copy and paste from host:<br />
<br />
$ qemu-system-x86_64 -vga qxl -device virtio-serial-pci -spice port=5930,disable-ticketing=on -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The parameters have the following meaning:<br />
<br />
# {{ic|-device virtio-serial-pci}} adds a virtio-serial device<br />
# {{ic|1=-spice port=5930,disable-ticketing=on}} set TCP port {{ic|5930}} for spice channels listening and allow client to connect without authentication{{Tip|Using [[wikipedia:Unix_socket|Unix sockets]] instead of TCP ports does not involve using network stack on the host system. It does not imply that packets are encapsulated and decapsulated to use the network and the related protocol. The sockets are identified solely by the inodes on the hard drive. It is therefore considered better for performance. Use instead {{ic|1=-spice unix=on,addr=/tmp/vm_spice.socket,disable-ticketing=on}}.}}<br />
# {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in the virtio-serial device,<br />
# {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port. It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Connecting to the guest with a SPICE client ===<br />
<br />
A SPICE client is necessary to connect to the guest. In Arch, the following clients are available:<br />
<br />
{{App|virt-viewer|SPICE client recommended by the protocol developers, a subset of the virt-manager project.|https://virt-manager.org/|{{Pkg|virt-viewer}}}}<br />
<br />
{{App|spice-gtk|SPICE GTK client, a subset of the SPICE project. Embedded into other applications as a widget.|https://www.spice-space.org/|{{Pkg|spice-gtk}}}}<br />
<br />
For clients that run on smartphone or on other platforms, refer to the ''Other clients'' section in [https://www.spice-space.org/download.html spice-space download].<br />
<br />
==== Manually running a SPICE client ====<br />
<br />
One way of connecting to a guest listening on Unix socket {{ic|/tmp/vm_spice.socket}} is to manually run the SPICE client using {{ic|$ remote-viewer spice+unix:///tmp/vm_spice.socket}} or {{ic|1=$ spicy --uri="spice+unix:///tmp/vm_spice.socket"}}, depending on the desired client. Since QEMU in SPICE mode acts similarly to a remote desktop server, it may be more convenient to run QEMU in daemon mode with the {{ic|-daemonize}} parameter.<br />
<br />
{{Tip|To connect to the guest through SSH tunelling, the following type of command can be used: {{bc|$ ssh -fL 5999:localhost:5930 ''my.domain.org'' sleep 10; spicy -h 127.0.0.1 -p 5999}}<br />
This example connects ''spicy'' to the local port {{ic|5999}} which is forwarded through SSH to the guest's SPICE server located at the address ''my.domain.org'', port {{ic|5930}}.<br />
Note the {{ic|-f}} option that requests ssh to execute the command {{ic|sleep 10}} in the background. This way, the ssh session runs while the client is active and auto-closes once the client ends.<br />
}}<br />
<br />
==== Running a SPICE client with QEMU ====<br />
<br />
QEMU can automatically start a SPICE client with an appropriate socket, if the display is set to SPICE with the {{ic|-display spice-app}} parameter. This will use the system's default SPICE client as the viewer, determined by your [[XDG MIME Applications#mimeapps.list|mimeapps.list]] files.<br />
<br />
=== Enabling SPICE support on the guest ===<br />
<br />
For '''Arch Linux guests''', for improved support for multiple monitors or clipboard sharing, the following packages should be installed:<br />
* {{Pkg|spice-vdagent}}: Spice agent xorg client that enables copy and paste between client and X-session and more.<br />
* {{Pkg|xf86-video-qxl}}: Xorg X11 qxl video driver<br />
For guests under '''other operating systems''', refer to the ''Guest'' section in [https://www.spice-space.org/download.html spice-space download].<br />
<br />
=== Password authentication with SPICE ===<br />
<br />
If you want to enable password authentication with SPICE you need to remove {{ic|disable-ticketing}} from the {{ic|-spice}} argument and instead add {{ic|1=password=''yourpassword''}}. For example:<br />
<br />
$ qemu-system-x86_64 -vga qxl -spice port=5900,password=''yourpassword'' -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
Your SPICE client should now ask for the password to be able to connect to the SPICE server.<br />
<br />
=== TLS encrypted communication with SPICE ===<br />
<br />
You can also configure TLS encryption for communicating with the SPICE server. First, you need to have a directory which contains the following files (the names must be exactly as indicated):<br />
<br />
* {{ic|ca-cert.pem}}: the CA master certificate.<br />
* {{ic|server-cert.pem}}: the server certificate signed with {{ic|ca-cert.pem}}.<br />
* {{ic|server-key.pem}}: the server private key.<br />
<br />
An example of generation of self-signed certificates with your own generated CA for your server is shown in the [https://www.spice-space.org/spice-user-manual.html#_generating_self_signed_certificates Spice User Manual].<br />
<br />
Afterwards, you can run QEMU with SPICE as explained above but using the following {{ic|-spice}} argument: {{ic|1=-spice tls-port=5901,password=''yourpassword'',x509-dir=''/path/to/pki_certs''}}, where {{ic|''/path/to/pki_certs''}} is the directory path that contains the three needed files shown earlier.<br />
<br />
It is now possible to connect to the server using {{pkg|virt-viewer}}:<br />
<br />
$ remote-viewer spice://''hostname''?tls-port=5901 --spice-ca-file=''/path/to/ca-cert.pem'' --spice-host-subject="C=''XX'',L=''city'',O=''organization'',CN=''hostname''" --spice-secure-channels=all<br />
<br />
Keep in mind that the {{ic|--spice-host-subject}} parameter needs to be set according to your {{ic|server-cert.pem}} subject. You also need to copy {{ic|ca-cert.pem}} to every client to verify the server certificate.<br />
<br />
{{Tip|You can get the subject line of the server certificate in the correct format for {{ic|--spice-host-subject}} (with entries separated by commas) using the following command: {{bc|<nowiki>$ openssl x509 -noout -subject -in server-cert.pem | cut -d' ' -f2- | sed 's/\///' | sed 's/\//,/g'</nowiki>}}<br />
}}<br />
<br />
The equivalent {{Pkg|spice-gtk}} command is:<br />
<br />
$ spicy -h ''hostname'' -s 5901 --spice-ca-file=ca-cert.pem --spice-host-subject="C=''XX'',L=''city'',O=''organization'',CN=''hostname''" --spice-secure-channels=all<br />
<br />
== VNC ==<br />
<br />
One can add the {{ic|-vnc :''X''}} option to have QEMU redirect the VGA display to the VNC session. Substitute {{ic|''X''}} for the number of the display (0 will then listen on 5900, 1 on 5901...).<br />
<br />
$ qemu-system-x86_64 -vnc :0<br />
<br />
An example is also provided in the [[#Starting QEMU virtual machines on boot]] section.<br />
{{Warning|The default VNC server setup does not use any form of authentication. Any user can connect from any host.}}<br />
<br />
=== Basic password authentication ===<br />
<br />
An access password can be setup easily by using the {{ic|password}} option. The password must be indicated in the QEMU monitor and connection is only possible once the password is provided.<br />
<br />
$ qemu-system-x86_64 -vnc :0,password -monitor stdio<br />
<br />
In the QEMU monitor, password is set using the command {{ic|change vnc password}} and then indicating the password.<br />
<br />
The following command line directly runs vnc with a password:<br />
<br />
$ printf "change vnc password\n%s\n" MYPASSWORD | qemu-system-x86_64 -vnc :0,password -monitor stdio<br />
<br />
{{Note|The password is limited to 8 characters and can be guessed through brute force attack. More elaborated protection is strongly recommended for public network.}}<br />
<br />
== Audio ==<br />
<br />
=== Creating an audio backend ===<br />
<br />
The {{ic|-audiodev}} flag sets the audio backend driver on the host and its options. The list of available audio backend drivers and their optional settings is detailed in the {{man|1|qemu}} man page.<br />
<br />
At the bare minimum, one need to choose an audio backend and set an id, for [[PulseAudio]] for example:<br />
<br />
-audiodev pa,id=snd0<br />
<br />
=== Using the audio backend ===<br />
<br />
==== Intel HD Audio ====<br />
<br />
For Intel HD Audio emulation, add both controller and codec devices. To list the available Intel HDA Audio devices:<br />
<br />
$ qemu-system-x86_64 -device help | grep hda<br />
<br />
Add the audio controller:<br />
<br />
-device ich9-intel-hda<br />
<br />
Also add the audio codec and map it to a host audio backend id:<br />
<br />
-device hda-output,audiodev=snd0<br />
<br />
==== Intel 82801AA AC97 ====<br />
<br />
For AC97 emulation just add the audio card device and map it to a host audio backend id<br />
<br />
-device AC97,audiodev=snd0<br />
<br />
{{Note|<br />
* If the audiodev backend is not provided, QEMU looks up for it and adds it automatically, this only works for a single audiodev. For example {{ic|-device intel-hda -device hda-duplex}} will emulate {{ic|intel-hda}} on the guest using the default audiodev backend.<br />
* Video graphic card emulated drivers for the guest machine may also cause a problem with the sound quality. Test one by one to make it work. You can list possible options with {{ic|<nowiki>qemu-system-x86_64 -h | grep vga</nowiki>}}.}}<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [https://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} for passing a disk image, with parameter {{Ic|1=if=virtio}}:<br />
$ qemu-system-x86_64 -drive file=''disk_image'',if='''virtio'''<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-x86_64 -nic user,model='''virtio-net-pci'''<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an Arch Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=(virtio virtio_blk virtio_pci virtio_net)}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [https://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
You might also want to install {{Pkg|qemu-guest-agent}} to implement support for QMP commands that will enhance the hypervisor management capabilities. After installing the package you can enable and start the {{ic|qemu-guest-agent.service}}.<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
==== Virtio drivers for Windows ====<br />
<br />
Windows does not come with the virtio drivers. The latest and stable versions of the drivers are regularly built by Fedora, details on downloading the drivers are given on [https://github.com/virtio-win/virtio-win-pkg-scripts/blob/master/README.md virtio-win on GitHub]. In the following sections we will mostly use the stable ISO file provided here: [https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso virtio-win.iso]. Alternatively, use {{AUR|virtio-win}}.<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
The drivers need to be loaded during installation, the procedure is to load the ISO image with the virtio drivers in a cdrom device along with the primary disk device and the Windows ISO install media:<br />
<br />
$ qemu-system-x86_64 ... \<br />
-drive file=''disk_image'',index=0,media=disk,if=virtio \<br />
-drive file=''windows.iso'',index=2,media=cdrom \<br />
-drive file=''virtio-win.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, at some stage, the Windows installer will ask "Where do you want to install Windows?", it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option ''Load Drivers''.<br />
* Uncheck the box for ''Hide drivers that are not compatible with this computer's hardware''.<br />
* Click the browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and confirm.<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change existing Windows VM to use virtio =====<br />
<br />
Modifying an existing Windows guest for booting from virtio disk requires that the virtio driver is loaded by the guest at boot time.<br />
We will therefore need to teach Windows to load the virtio driver at boot time before being able to boot a disk image in virtio mode.<br />
<br />
To achieve that, first create a new disk image that will be attached in virtio mode and trigger the search for the driver:<br />
<br />
$ qemu-img create -f qcow2 ''dummy.qcow2'' 1G<br />
<br />
Run the original Windows guest with the boot disk still in IDE mode, the fake disk in virtio mode and the driver ISO image.<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''disk_image'',if=ide -drive file=''dummy.qcow2'',if=virtio -cdrom virtio-win.iso<br />
<br />
Windows will detect the fake disk and look for a suitable driver. If it fails, go to ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not navigate to the driver folder within the CD-ROM, simply select the CD-ROM drive and Windows will find the appropriate driver automatically (tested for Windows 7 SP1).<br />
<br />
Request Windows to boot in safe mode next time it starts up. This can be done using the ''msconfig.exe'' tool in Windows. In safe mode all the drivers will be loaded at boot time including the new virtio driver. Once Windows knows that the virtio driver is required at boot it will memorize it for future boot.<br />
<br />
Once instructed to boot in safe mode, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''disk_image'',if=virtio<br />
<br />
You should boot in safe mode with virtio driver loaded, you can now return to ''msconfig.exe'' disable safe mode boot and restart Windows.<br />
<br />
{{Note|If you encounter the blue screen of death using the {{ic|1=if=virtio}} parameter, it probably means the virtio disk driver is not installed or not loaded at boot time, reboot in safe mode and check your driver configuration.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-nic}} argument.<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''windows_disk_image'',if=virtio -nic user,model=virtio-net-pci -cdrom virtio-win.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
==== Balloon driver ====<br />
<br />
If you want to track you guest memory state (for example via {{ic|virsh}} command {{ic|dommemstat}}) or change guest's memory size in runtime (you still will not be able to change memory size, but can limit memory usage via inflating balloon driver) you will need to install guest balloon driver.<br />
<br />
For this you will need to go to ''Device Manager'', locate ''PCI standard RAM Controller'' in ''System devices'' (or unrecognized PCI controller from ''Other devices'') and choose ''Update driver''. In opened window you will need to choose ''Browse my computer...'' and select the CD-ROM (and do not forget the ''Include subdirectories'' checkbox). Reboot after installation. This will install the driver and you will be able to inflate the balloon (for example via hmp command {{ic|balloon ''memory_size''}}, which will cause balloon to take as much memory as possible in order to shrink the guest's available memory size to ''memory_size''). However, you still will not be able to track guest memory state. In order to do this you will need to install ''Balloon'' service properly. For that open command line as administrator, go to the CD-ROM, ''Balloon'' directory and deeper, depending on your system and architecture. Once you are in ''amd64'' (''x86'') directory, run {{ic|blnsrv.exe -i}} which will do the installation. After that {{ic|virsh}} command {{ic|dommemstat}} should be outputting all supported values.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|1=<br />
virtio_load="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
# sed -ibak "s/ada/vtbd/g" /etc/fstab<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== QEMU monitor ==<br />
<br />
While QEMU is running, a monitor console is provided in order to provide several ways to interact with the virtual machine running. The QEMU monitor offers interesting capabilities such as obtaining information about the current virtual machine, hotplugging devices, creating snapshots of the current state of the virtual machine, etc. To see the list of all commands, run {{ic|help}} or {{ic|?}} in the QEMU monitor console or review the relevant section of the [https://www.qemu.org/docs/master/system/monitor.html official QEMU documentation].<br />
<br />
=== Accessing the monitor console ===<br />
<br />
==== Graphical view ====<br />
<br />
When using the {{ic|std}} default graphics option, one can access the QEMU monitor by pressing {{ic|Ctrl+Alt+2}} or by clicking ''View > compatmonitor0'' in the QEMU window. To return to the virtual machine graphical view either press {{ic|Ctrl+Alt+1}} or click ''View > VGA''.<br />
<br />
However, the standard method of accessing the monitor is not always convenient and does not work in all graphic outputs QEMU supports.<br />
<br />
==== Telnet ====<br />
<br />
To enable [[telnet]], run QEMU with the {{ic|-monitor telnet:127.0.0.1:''port'',server,nowait}} parameter. When the virtual machine is started you will be able to access the monitor via telnet:<br />
<br />
$ telnet 127.0.0.1 ''port''<br />
<br />
{{Note|If {{ic|127.0.0.1}} is specified as the IP to listen it will be only possible to connect to the monitor from the same host QEMU is running on. If connecting from remote hosts is desired, QEMU must be told to listen {{ic|0.0.0.0}} as follows: {{ic|-monitor telnet:0.0.0.0:''port'',server,nowait}}. Keep in mind that it is recommended to have a [[firewall]] configured in this case or make sure your local network is completely trustworthy since this connection is completely unauthenticated and unencrypted.}}<br />
<br />
==== UNIX socket ====<br />
<br />
Run QEMU with the {{ic|-monitor unix:''socketfile'',server,nowait}} parameter. Then you can connect with either {{pkg|socat}}, {{pkg|nmap}} or {{pkg|openbsd-netcat}}.<br />
<br />
For example, if QEMU is run via:<br />
<br />
$ qemu-system-x86_64 -monitor unix:/tmp/monitor.sock,server,nowait ''[...]''<br />
<br />
It is possible to connect to the monitor with:<br />
<br />
$ socat - UNIX-CONNECT:/tmp/monitor.sock<br />
<br />
Or with:<br />
<br />
$ nc -U /tmp/monitor.sock<br />
<br />
Alternatively with {{pkg|nmap}}:<br />
<br />
$ ncat -U /tmp/monitor.sock<br />
<br />
==== TCP ====<br />
<br />
You can expose the monitor over TCP with the argument {{ic|-monitor tcp:127.0.0.1:''port'',server,nowait}}. Then connect with netcat, either {{pkg|openbsd-netcat}} or {{pkg|gnu-netcat}} by running:<br />
<br />
$ nc 127.0.0.1 ''port''<br />
<br />
{{Note|In order to be able to connect to the tcp socket from other devices other than the same host QEMU is being run on you need to listen to {{ic|0.0.0.0}} like explained in the telnet case. The same security warnings apply in this case as well.}}<br />
<br />
==== Standard I/O ====<br />
<br />
It is possible to access the monitor automatically from the same terminal QEMU is being run by running it with the argument {{ic|-monitor stdio}}.<br />
<br />
=== Sending keyboard presses to the virtual machine using the monitor console ===<br />
<br />
Some combinations of keys may be difficult to perform on virtual machines due to the host intercepting them instead in some configurations (a notable example is the {{ic|Ctrl+Alt+F*}} key combinations, which change the active tty). To avoid this problem, the problematic combination of keys may be sent via the monitor console instead. Switch to the monitor and use the {{ic|sendkey}} command to forward the necessary keypresses to the virtual machine. For example:<br />
<br />
(qemu) sendkey ctrl-alt-f2<br />
<br />
=== Creating and managing snapshots via the monitor console ===<br />
<br />
{{Note|This feature will '''only''' work when the virtual machine disk image is in ''qcow2'' format. It will not work with ''raw'' images.}}<br />
<br />
It is sometimes desirable to save the current state of a virtual machine and having the possibility of reverting the state of the virtual machine to that of a previously saved snapshot at any time. The QEMU monitor console provides the user with the necessary utilities to create snapshots, manage them, and revert the machine state to a saved snapshot.<br />
<br />
* Use {{ic|savevm ''name''}} in order to create a snapshot with the tag ''name''.<br />
* Use {{ic|loadvm ''name''}} to revert the virtual machine to the state of the snapshot ''name''.<br />
* Use {{ic|delvm ''name''}} to delete the snapshot tagged as ''name''.<br />
* Use {{ic|info snapshots}} to see a list of saved snapshots. Snapshots are identified by both an auto-incremented ID number and a text tag (set by the user on snapshot creation).<br />
<br />
=== Running the virtual machine in immutable mode ===<br />
<br />
It is possible to run a virtual machine in a frozen state so that all changes will be discarded when the virtual machine is powered off just by running QEMU with the {{ic|-snapshot}} parameter. When the disk image is written by the guest, changes will be saved in a temporary file in {{ic|/tmp}} and will be discarded when QEMU halts.<br />
<br />
However, if a machine is running in frozen mode it is still possible to save the changes to the disk image if it is afterwards desired by using the monitor console and running the following command:<br />
<br />
(qemu) commit all<br />
<br />
If snapshots are created when running in frozen mode they will be discarded as soon as QEMU is exited unless changes are explicitly commited to disk, as well.<br />
<br />
=== Pause and power options via the monitor console ===<br />
<br />
Some operations of a physical machine can be emulated by QEMU using some monitor commands:<br />
<br />
* {{ic|system_powerdown}} will send an ACPI shutdown request to the virtual machine. This effect is similar to the power button in a physical machine.<br />
* {{ic|system_reset}} will reset the virtual machine similarly to a reset button in a physical machine. This operation can cause data loss and file system corruption since the virtual machine is not cleanly restarted.<br />
* {{ic|stop}} will pause the virtual machine.<br />
* {{ic|cont}} will resume a virtual machine previously paused.<br />
<br />
=== Taking screenshots of the virtual machine ===<br />
<br />
Screenshots of the virtual machine graphic display can be obtained in the PPM format by running the following command in the monitor console:<br />
<br />
(qemu) screendump ''file.ppm''<br />
<br />
== QEMU machine protocol ==<br />
<br />
The QEMU machine protocol (QMP) is a JSON-based protocol which allows applications to control a QEMU instance. Similarly to the [[#QEMU monitor]] it offers ways to interact with a running machine and the JSON protocol allows to do it programmatically. The description of all the QMP commands can be found in [https://raw.githubusercontent.com/coreos/qemu/master/qmp-commands.hx qmp-commands].<br />
<br />
=== Start QMP ===<br />
<br />
The usual way to control the guest using the QMP protocol, is to open a TCP socket when launching the machine using the {{ic|-qmp}} option. Here it is using for example the TCP port 4444:<br />
<br />
$ qemu-system-x86_64 ''[...]'' -qmp tcp:localhost:4444,server,nowait<br />
<br />
Then one way to communicate with the QMP agent is to use [[netcat]]:<br />
<br />
{{hc|nc localhost 4444|{"QMP": {"version": {"qemu": {"micro": 0, "minor": 1, "major": 3}, "package": ""}, "capabilities": []} } }}<br />
<br />
At this stage, the only command that can be recognized is {{ic|qmp_capabilities}}, so that QMP enters into command mode. Type:<br />
<br />
{"execute": "qmp_capabilities"}<br />
<br />
Now, QMP is ready to receive commands, to retrieve the list of recognized commands, use:<br />
<br />
{"execute": "query-commands"}<br />
<br />
=== Live merging of child image into parent image ===<br />
<br />
It is possible to merge a running snapshot into its parent by issuing a {{ic|block-commit}} command. In its simplest form the following line will commit the child into its parent:<br />
<br />
{"execute": "block-commit", "arguments": {"device": "''devicename''"}}<br />
<br />
Upon reception of this command, the handler looks for the base image and converts it from read only to read write mode and then runs the commit job.<br />
<br />
Once the ''block-commit'' operation has completed, the event {{ic|BLOCK_JOB_READY}} will be emitted, signalling that the synchronization has finished. The job can then be gracefully completed by issuing the command {{ic|block-job-complete}}:<br />
<br />
{"execute": "block-job-complete", "arguments": {"device": "''devicename''"}}<br />
<br />
Until such a command is issued, the ''commit'' operation remains active.<br />
After successful completion, the base image remains in read write mode and becomes the new active layer. On the other hand, the child image becomes invalid and it is the responsibility of the user to clean it up.<br />
<br />
{{Tip|The list of device and their names can be retrieved by executing the command {{ic|query-block}} and parsing the results. The device name is in the {{ic|device}} field, for example {{ic|ide0-hd0}} for the hard disk in this example: {{hc|{"execute": "query-block"}|{"return": [{"io-status": "ok", "device": "'''ide0-hd0'''", "locked": false, "removable": false, "inserted": {"iops_rd": 0, "detect_zeroes": "off", "image": {"backing-image": {"virtual-size": 27074281472, "filename": "parent.qcow2", ... } }} }}<br />
<br />
=== Live creation of a new snapshot ===<br />
<br />
To create a new snapshot out of a running image, run the command:<br />
<br />
{"execute": "blockdev-snapshot-sync", "arguments": {"device": "''devicename''","snapshot-file": "''new_snapshot_name''.qcow2"}}<br />
<br />
This creates an overlay file named {{ic|''new_snapshot_name''.qcow2}} which then becomes the new active layer.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Improve virtual machine performance ===<br />
<br />
There are a number of techniques that you can use to improve the performance of the virtual machine. For example:<br />
<br />
* Apply [[#Enabling KVM]] for full virtualization.<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU rather than a more generic CPU.<br />
* Especially for Windows guests, enable [https://blog.wikichoon.com/2014/07/enabling-hyper-v-enlightenments-with-kvm.html Hyper-V enlightenments]: {{ic|1=-cpu host,hv_relaxed,hv_spinlocks=0x1fff,hv_vapic,hv_time}}.<br />
* If the host machine has multiple cores, assign the guest more cores using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* If supported by drivers in the guest operating system, use virtio for network and/or block devices, see [[#Installing virtio drivers]].<br />
* Use TAP devices instead of user-mode networking, see [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, you may want to disable the cache:{{bc|1=$ qemu-system-x86_64 -drive file=''disk_image'',if=virtio,'''cache=none'''}}<br />
* Use the native Linux AIO: {{bc|1=$ qemu-system-x86_64 -drive file=''disk_image'',if=virtio''',aio=native,cache.direct=on'''}}<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]. See [[#Enabling KSM]].<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU using {{ic|-device virtio-balloon}}.<br />
* It is possible to use a emulation layer for an ICH-9 AHCI controller (although it may be unstable). The AHCI emulation supports [[Wikipedia:Native_Command_Queuing|NCQ]], so multiple read or write requests can be outstanding at the same time: {{bc|1=$ qemu-system-x86_64 -drive id=disk,file=''disk_image'',if=none -device ich9-ahci,id=ahci -device ide-drive,drive=disk,bus=ahci.0}}<br />
<br />
See https://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured with {{ic|virsh autostart}} or through the ''virt-manager'' GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== With systemd service ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|2=<br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/qemu-system-x86_64 -name %i -enable-kvm -m 512 -nographic $args<br />
ExecStop=/usr/bin/bash -c ${haltcmd}<br />
ExecStop=/usr/bin/bash -c 'while nc localhost 7100; do sleep 1; done'<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Note|This service will wait for the console port to be released, which means that the VM has been shutdown, to graciously end.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the variables {{ic|args}} and {{ic|haltcmd}} set. Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|2=<br />
args="-hda /dev/vg0/vm1 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' {{!}} nc localhost 7100" # or netcat/ncat}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|2=<br />
args="-hda /srv/kvm/vm2 -serial telnet:localhost:7001,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="ssh powermanager@vm2 sudo poweroff"}}<br />
<br />
The description of the variables is the following:<br />
<br />
* {{ic|args}} - QEMU command line arguments to be used.<br />
* {{ic|haltcmd}} - Command to shut down a VM safely. In the first example, the QEMU monitor is exposed via telnet using {{ic|-monitor telnet:..}} and the VMs are powered off via ACPI by sending {{ic|system_powerdown}} to monitor with the {{ic|nc}} command. In the other example, SSH is used.<br />
<br />
To set which virtual machines will start on boot-up, [[enable]] the {{ic|qemu@''vm_name''.service}} systemd unit.<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the options {{ic|-usb -device usb-tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-x86_64 -hda ''disk_image'' -m 512 -usb -device usb-tablet<br />
<br />
If that does not work, try using {{ic|-vga qxl}} parameter, also look at the instructions [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
It is possible to access the physical device connected to a USB port of the host from the guest. The first step is to identify where the device is connected, this can be found running the {{ic|lsusb}} command. For example:<br />
<br />
{{hc|$ lsusb|<br />
...<br />
Bus '''003''' Device '''007''': ID '''0781''':'''5406''' SanDisk Corp. Cruzer Micro U3<br />
}}<br />
<br />
The outputs in bold above will be useful to identify respectively the ''host_bus'' and ''host_addr'' or the ''vendor_id'' and ''product_id''.<br />
<br />
In qemu, the idea is to emulate an EHCI (USB 2) or XHCI (USB 1.1 USB 2 USB 3) controller with the option {{ic|1=-device usb-ehci,id=ehci}} or {{ic|1=-device qemu-xhci,id=xhci}} respectively and then attach the physical device to it with the option {{ic|1=-device usb-host,..}}. We will consider that ''controller_id'' is either {{ic|ehci}} or {{ic|xhci}} for the rest of this section.<br />
<br />
Then, there are two ways to connect to the USB of the host with qemu:<br />
<br />
# Identify the device and connect to it on any bus and address it is attached to on the host, the generic syntax is: {{bc|1=-device usb-host,bus=''controller_id''.0,vendorid=0x''vendor_id'',productid=0x''product_id''}}Applied to the device used in the example above, it becomes:{{bc|1=-device usb-ehci,id=ehci -device usb-host,bus=ehci.0,vendorid=0x'''0781''',productid=0x'''5406'''}}One can also add the {{ic|1=...,port=''port_number''}} setting to the previous option to specify in which physical port of the virtual controller the device should be attached, useful in the case one wants to add multiple usb devices to the VM. Another option is to use the new {{ic|hostdevice}} property of {{ic|usb-host}} which is available since QEMU 5.1.0, the syntax is: {{bc|1=-device qemu-xhci,id=xhci -device usb-host,hostdevice=/dev/bus/usb/003/007}}<br />
# Attach whatever is connected to a given USB bus and address, the syntax is:{{bc|1=-device usb-host,bus=''controller_id''.0,hostbus=''host_bus'',host_addr=''host_addr''}}Applied to the bus and the address in the example above, it becomes:{{bc|1=-device usb-ehci,id=ehci -device usb-host,bus=ehci.0,hostbus='''3''',hostaddr='''7'''}}<br />
See [https://www.qemu.org/docs/master/system/devices/usb.html QEMU/USB emulation] for more information.<br />
{{Note|If you encounter permission errors when running QEMU, see [[udev#About udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== USB redirection with SPICE ===<br />
<br />
When using [[#SPICE]] it is possible to redirect USB devices from the client to the virtual machine without needing to specify them in the QEMU command. It is possible to configure the number of USB slots available for redirected devices (the number of slots will determine the maximum number of devices which can be redirected simultaneously). The main advantages of using SPICE for redirection compared to the previously-mentioned {{ic|-usbdevice}} method is the possibility of hot-swapping USB devices after the virtual machine has started, without needing to halt it in order to remove USB devices from the redirection or adding new ones. This method of USB redirection also allows us to redirect USB devices over the network, from the client to the server. In summary, it is the most flexible method of using USB devices in a QEMU virtual machine.<br />
<br />
We need to add one EHCI/UHCI controller per available USB redirection slot desired as well as one SPICE redirection channel per slot. For example, adding the following arguments to the QEMU command you use for starting the virtual machine in SPICE mode will start the virtual machine with three available USB slots for redirection:<br />
<br />
{{bc|1=<br />
-device ich9-usb-ehci1,id=usb \<br />
-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \<br />
-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \<br />
-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev1 -device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev2 -device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev3 -device usb-redir,chardev=usbredirchardev3,id=usbredirdev3<br />
}}<br />
<br />
See [https://www.spice-space.org/usbredir.html SPICE/usbredir] for more information.<br />
<br />
Both {{ic|spicy}} from {{Pkg|spice-gtk}} (''Input > Select USB Devices for redirection'') and {{ic|remote-viewer}} from {{pkg|virt-viewer}} (''File > USB device selection'') support this feature. Please make sure that you have installed the necessary SPICE Guest Tools on the virtual machine for this functionality to work as expected (see the [[#SPICE]] section for more information).<br />
<br />
{{Warning|Keep in mind that when a USB device is redirected from the client, it will not be usable from the client operating system itself until the redirection is stopped. It is specially important to never redirect the input devices (namely mouse and keyboard), since it will be then difficult to access the SPICE client menus to revert the situation, because the client will not respond to the input devices after being redirected to the virtual machine.}}<br />
<br />
==== Automatic USB forwarding with udev ====<br />
<br />
Normally, forwarded devices must be available at VM boot time to be forwarded. If that device is disconnected, it will not be forwarded anymore.<br />
<br />
You can use [[udev rule]]s to automatically attach a device when it comes online. Create a {{ic|hostdev}} entry somewhere on disk. [[chown]] it to root to prevent other users modifying it.<br />
<br />
{{hc|/usr/local/hostdev-mydevice.xml|2=<br />
<hostdev mode='subsystem' type='usb'><br />
<source><br />
<vendor id='0x03f0'/><br />
<product id='0x4217'/><br />
</source><br />
</hostdev><br />
}}<br />
<br />
Then create a ''udev'' rule which will attach/detach the device:<br />
<br />
{{hc|/usr/lib/udev/rules.d/90-libvirt-mydevice|2=<br />
ACTION=="add", \<br />
SUBSYSTEM=="usb", \<br />
ENV{ID_VENDOR_ID}=="03f0", \<br />
ENV{ID_MODEL_ID}=="4217", \<br />
RUN+="/usr/bin/virsh attach-device GUESTNAME /usr/local/hostdev-mydevice.xml"<br />
ACTION=="remove", \<br />
SUBSYSTEM=="usb", \<br />
ENV{ID_VENDOR_ID}=="03f0", \<br />
ENV{ID_MODEL_ID}=="4217", \<br />
RUN+="/usr/bin/virsh detach-device GUESTNAME /usr/local/hostdev-mydevice.xml"<br />
}}<br />
<br />
[https://rolandtapken.de/blog/2011-04/how-auto-hotplug-usb-devices-libvirt-vms-update-1 Source and further reading].<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
{{Note|Although KSM may reduce memory usage, it may increase CPU usage. Also note some security issues may occur, see [[Wikipedia:Kernel same-page merging]].}}<br />
<br />
To enable KSM:<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, use [[systemd#systemd-tmpfiles - temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://docs.kernel.org/admin-guide/mm/ksm.html for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory:<br />
<br />
$ grep -r . /sys/kernel/mm/ksm/<br />
<br />
}}<br />
<br />
=== Multi-monitor support ===<br />
<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Custom display resolution ===<br />
<br />
A custom display resolution can be set with {{ic|1=-device VGA,edid=on,xres=1280,yres=720}} (see [[wikipedia:Extended_Display_Identification_Data|EDID]] and [[wikipedia:Display_resolution|display resolution]]).<br />
<br />
=== Copy and paste ===<br />
<br />
One way to share the clipboard between the host and the guest is to enable the SPICE remote desktop protocol and access the client with a SPICE client.<br />
One needs to follow the steps described in [[#SPICE]]. A guest run this way will support copy paste with the host.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 11.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Fast startup ====<br />
<br />
{{Note|An administrator account is required to change power settings.}}<br />
<br />
For Windows 8 (or later) guests it is better to disable "Turn on fast startup (recommended)" from the Power Options of the Control Panel as explained in the following [https://www.tenforums.com/tutorials/4189-turn-off-fast-startup-windows-10-a.html forum page], as it causes the guest to hang during every other boot.<br />
<br />
Fast Startup may also need to be disabled for changes to the {{ic|-smp}} option to be properly applied.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-x86_64 -nographic -nic user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either {{Pkg|rdesktop}} or {{Pkg|freerdp}} to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
=== Clone Linux system installed on physical equipment ===<br />
<br />
Linux system installed on physical equipment can be cloned for running on QEMU vm. See [https://coffeebirthday.wordpress.com/2018/09/14/clone-linux-system-for-qemu-virtual-machine/ Clone Linux system from hardware for QEMU virtual machine]<br />
<br />
=== Chrooting into arm/arm64 environment from x86_64 ===<br />
<br />
Sometimes it is easier to work directly on a disk image instead of the real ARM based device. This can be achieved by mounting an SD card/storage containing the ''root'' partition and chrooting into it.<br />
<br />
Another use case for an ARM chroot is building ARM packages on an x86_64 machine - {{AUR|armutils-git}} can be used for that. Here, the chroot environment can be created from an image tarball from [https://archlinuxarm.org Arch Linux ARM] - see [https://nerdstuff.org/posts/2020/2020-003_simplest_way_to_create_an_arm_chroot/] for a detailed description of this approach.<br />
<br />
Either way, from the chroot it should be possible to run ''pacman'' and install more packages, compile large libraries etc. Since the executables are for the ARM architecture, the translation to x86 needs to be performed by [[QEMU]].<br />
<br />
Install {{AUR|binfmt-qemu-static}} and {{AUR|qemu-user-static}} from the [[AUR]] on the x86_64 machine/host. ''binfmt-qemu-static'' will take care of registering the qemu binaries to binfmt service.<br />
<br />
[[Restart]] {{ic|systemd-binfmt.service}}<br />
<br />
{{AUR|qemu-user-static}} is needed to allow the execution of compiled programs from other architectures. This is similar to what is provided by {{Pkg|qemu-emulators-full}}, but the "static" variant is required for chroot. Examples:<br />
<br />
qemu-arm-static path_to_sdcard/usr/bin/ls<br />
qemu-aarch64-static path_to_sdcard/usr/bin/ls<br />
<br />
These two lines execute the {{ic|ls}} command compiled for 32-bit ARM and 64-bit ARM respectively. Note that this will not work without chrooting, because it will look for libraries not present in the host system.<br />
<br />
{{AUR|qemu-user-static}} allows automatically prefixing the ARM exectuable with {{ic|qemu-arm-static}} or {{ic|qemu-aarch64-static}}.<br />
<br />
Make sure that the ARM executable support is active:<br />
<br />
{{hc|$ ls /proc/sys/fs/binfmt_misc|<br />
qemu-aarch64 qemu-arm qemu-cris qemu-microblaze qemu-mipsel qemu-ppc64 qemu-riscv64 qemu-sh4 qemu-sparc qemu-sparc64 status<br />
qemu-alpha qemu-armeb qemu-m68k qemu-mips qemu-ppc qemu-ppc64abi32 qemu-s390x qemu-sh4eb qemu-sparc32plus register<br />
}}<br />
<br />
Each executable must be listed.<br />
<br />
If it is not active, [[reinstall]] {{AUR|binfmt-qemu-static}} and [[restart]] {{ic|systemd-binfmt.service}}.<br />
<br />
Mount the SD card to {{ic|/mnt/sdcard}} (the device name may be different).<br />
<br />
# mkdir -p /mnt/sdcard<br />
# mount /dev/mmcblk0p2 /mnt/sdcard<br />
<br />
Mount boot partition if needed (again, use the suitable device name):<br />
<br />
# mount /dev/mmcblk0p1 /mnt/sdcard/boot<br />
<br />
Finally ''chroot'' into the SD card root as described in [[Change root#Using chroot]]:<br />
<br />
# chroot /mnt/sdcard /bin/bash<br />
<br />
Alternatively, you can use ''arch-chroot'' from {{Pkg|arch-install-scripts}}, as it will provide an easier way to get network support:<br />
<br />
# arch-chroot /mnt/sdcard /bin/bash<br />
<br />
You can also use [[systemd-nspawn]] to chroot into the ARM environment:<br />
<br />
# systemd-nspawn -D /mnt/sdcard -M myARMMachine --bind-ro=/etc/resolv.conf<br />
<br />
{{ic|1=--bind-ro=/etc/resolv.conf}} is optional and gives a working network DNS inside the chroot<br />
<br />
=== Not grabbing mouse input ===<br />
<br />
{{Style|It is not explained what the option actually does. Is it causing or avoiding the side effect?}}<br />
<br />
Tablet mode has side effect of not grabbing mouse input in QEMU window:<br />
<br />
-usb -device usb-tablet<br />
<br />
It works with several {{ic|-vga}} backends one of which is virtio.<br />
<br />
== Troubleshooting ==<br />
<br />
{{Merge|QEMU/Troubleshooting|This section is long enough to be split into a dedicated subpage.}}<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|1=-display default,show-cursor=on}} to QEMU's options to see a mouse cursor.<br />
<br />
If that still does not work, make sure you have set your display device appropriately, for example: {{ic|-vga qxl}}.<br />
<br />
Another option to try is {{ic|-usb -device usb-tablet}} as mentioned in [[#Mouse integration]]. This overrides the default PS/2 mouse emulation and synchronizes pointer location between host and guest as an added bonus.<br />
<br />
=== Two different mouse cursors are visible ===<br />
<br />
Apply the tip [[#Mouse integration]].<br />
<br />
=== Keyboard issues when using VNC ===<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [https://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps/}}.<br />
<br />
$ qemu-system-x86_64 -k ''keymap'' ''disk_image''<br />
<br />
=== Could not read keymap file ===<br />
<br />
qemu-system-x86_64: -display vnc=0.0.0.0:0: could not read keymap file: 'en'<br />
<br />
is caused by an invalid ''keymap'' passed to the {{ic|-k}} argument. For example, {{ic|en}} is invalid, but {{ic|en-us}} is valid - see {{ic|/usr/share/qemu/keymaps/}}.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
[[Install]] {{pkg|glusterfs}} or ignore the error message as GlusterFS is a optional dependency.<br />
<br />
=== Kernel panic on LIVE-environments ===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. cannot unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
=== Windows 7 guest suffers low-quality sound ===<br />
<br />
Using the {{ic|hda}} audio driver for Windows 7 guest may result in low-quality sound. Changing the audio driver to {{ic|ac97}} by passing the {{ic|-soundhw ac97}} arguments to QEMU and installing the AC97 driver from [https://www.realtek.com/en/component/zoo/category/pc-audio-codecs-ac-97-audio-codecs-software Realtek AC'97 Audio Codecs] in the guest may solve the problem. See [https://bugzilla.redhat.com/show_bug.cgi?id=1176761#c16 Red Hat Bugzilla – Bug 1176761] for more information.<br />
<br />
=== Could not access KVM kernel module: Permission denied ===<br />
<br />
If you encounter the following error:<br />
<br />
libvirtError: internal error: process exited while connecting to monitor: Could not access KVM kernel module: Permission denied failed to initialize KVM: Permission denied<br />
<br />
Systemd 234 assigns a dynamic ID for the {{ic|kvm}} group (see {{Bug|54943}}). To avoid this error, you need edit the file {{ic|/etc/libvirt/qemu.conf}} and change the line with {{ic|1=group = "78"}} to {{ic|1=group = "kvm"}}.<br />
<br />
=== "System Thread Exception Not Handled" when booting a Windows VM ===<br />
<br />
Windows 8 or Windows 10 guests may raise a generic compatibility exception at boot, namely "System Thread Exception Not Handled", which tends to be caused by legacy drivers acting strangely on real machines. On KVM machines this issue can generally be solved by setting the CPU model to {{ic|core2duo}}.<br />
<br />
=== Certain Windows games/applications crashing/causing a bluescreen ===<br />
<br />
Occasionally, applications running in the VM may crash unexpectedly, whereas they would run normally on a physical machine. If, while running {{ic|dmesg -wH}} as root, you encounter an error mentioning {{ic|MSR}}, the reason for those crashes is that KVM injects a [[wikipedia:General protection fault|General protection fault]] (GPF) when the guest tries to access unsupported [[wikipedia:Model-specific register|Model-specific registers]] (MSRs) - this often results in guest applications/OS crashing. A number of those issues can be solved by passing the {{ic|1=ignore_msrs=1}} option to the KVM module, which will ignore unimplemented MSRs.<br />
<br />
{{hc|/etc/modprobe.d/kvm.conf|2=<br />
...<br />
options kvm ignore_msrs=1<br />
...<br />
}}<br />
<br />
Cases where adding this option might help:<br />
<br />
* GeForce Experience complaining about an unsupported CPU being present.<br />
* StarCraft 2 and L.A. Noire reliably blue-screening Windows 10 with {{ic|KMODE_EXCEPTION_NOT_HANDLED}}. The blue screen information does not identify a driver file in these cases.<br />
<br />
{{Warning|While this is normally safe and some applications might not work without this, silently ignoring unknown MSR accesses could potentially break other software within the VM or other VMs.}}<br />
<br />
=== Applications in the VM experience long delays or take a long time to start ===<br />
<br />
This may be caused by insufficient available entropy in the VM. Consider allowing the guest to access the hosts's entropy pool by adding a [https://wiki.qemu.org/Features/VirtIORNG VirtIO RNG device] to the VM, or by installing an entropy generating daemon such as [[Haveged]].<br />
<br />
Anecdotally, OpenSSH takes a while to start accepting connections under insufficient entropy, without the logs revealing why.<br />
<br />
=== High interrupt latency and microstuttering ===<br />
<br />
This problem manifests itself as small pauses (stutters) and is particularly noticeable in graphics-intensive applications, such as games.<br />
<br />
* One of the causes is CPU power saving features, which are controlled by [[CPU frequency scaling]]. Change this to {{ic|performance}} for all processor cores. <br />
* Another possible cause is PS/2 inputs. Switch from PS/2 to Virtio inputs, see [[PCI passthrough via OVMF#Passing keyboard/mouse via Evdev]].<br />
<br />
=== QXL video causes low resolution ===<br />
<br />
QEMU 4.1.0 introduced a regression where QXL video can fall back to low resolutions, when being displayed through spice. [https://bugs.launchpad.net/qemu/+bug/1843151] For example, when KMS starts, text resolution may become as low as 4x10 characters. When trying to increase GUI resolution, it may go to the lowest supported resolution.<br />
<br />
As a workaround, create your device in this form:<br />
<br />
-device qxl-vga,max_outputs=1...<br />
<br />
=== VM does not boot when using a Secure Boot enabled OVMF ===<br />
<br />
{{ic|/usr/share/edk2-ovmf/x64/OVMF_CODE.secboot.fd}} from {{Pkg|edk2-ovmf}} is built with [[Wikipedia:System Management Mode|SMM]] support. If S3 support is not disabled in the VM, then the VM might not boot at all.<br />
<br />
Add the {{ic|1=-global ICH9-LPC.disable_s3=1}} option to the ''qemu'' command.<br />
<br />
See {{Bug|59465}} and https://github.com/tianocore/edk2/blob/master/OvmfPkg/README for more details and the required options to use Secure Boot in QEMU.<br />
<br />
=== VM does not boot into Arch ISO ===<br />
<br />
When trying to boot VM for the first time from Arch ISO image the boot process hangs. Adding {{ic|1=console=ttyS0}} to kernel boot options by pressing {{ic|e}} in the boot menu you will get more boot messages and the following error:<br />
<br />
:: Mounting '/dev/disk/by-label/ARCH_202204' to '/run/archiso/bootmnt'<br />
Waiting 30 seconds for device /dev/disk/by-label/ARCH_202204 ...<br />
ERROR: '/dev/disk/by-label/ARCH_202204' device did not show up after 30 seconds...<br />
Falling back to interactive prompt<br />
You can try to fix the problem manually, log out when you are finished<br />
sh: can't access tty; job control turned off<br />
<br />
The error message does not give a good clue as to what the real issue is. The problem is with the default 128MB of RAM that QEMU allocates to the VM. Increasing the limit to 1024MB with {{ic|-m 1024}} solves the issue and lets system boot. You can continue installing Arch Linux as per usual after that. Once installation is complete the memory allocation for the VM can be decreased. The need for 1024MB is due to RAM disk requirements and size of installation media. See [https://lists.archlinux.org/archives/list/arch-releng@lists.archlinux.org/message/D5HSGOFTPGYI6IZUEB3ZNAX4D3F3ID37/ this message on the arch-releng mailing list] and [https://bbs.archlinux.org/viewtopic.php?id=204023 this forum thread].<br />
<br />
=== Guest CPU interrupts are not firing ===<br />
<br />
If you are writing your own operating system by following the [https://wiki.osdev.org/ OSDev wiki], or are simply getting stepping through the guest architecture assembly code using QEMU's {{ic|gdb}} interface using the {{ic|-s}} flag, it is useful to know that many emulators, QEMU included, usually implement some CPU interrupts leaving many hardware interrupts unimplemented. One way to know if your code if firing an interrupt, is by using:<br />
<br />
-d int<br />
<br />
to enable showing interrupts/exceptions on stdout.<br />
<br />
To see what other guest debugging features QEMU has to offer, see:<br />
<br />
qemu-system-x86_64 -d help<br />
<br />
or replace {{ic|x86_64}} for your chosen guest architecture.<br />
<br />
== See also ==<br />
<br />
* [https://qemu.org Official QEMU website]<br />
* [https://www.linux-kvm.org Official KVM website]<br />
* [https://qemu.weilnetz.de/doc/6.0/ QEMU Emulator User Documentation]<br />
* [[Wikibooks:QEMU|QEMU Wikibook]]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [https://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [https://qemu.weilnetz.de/ QEMU on Windows]<br />
* [[wikipedia:Qemu|Wikipedia]]<br />
* [[debian:QEMU|Debian Wiki - QEMU]]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]<br />
* [https://wiki.mikejung.biz/KVM_/_Xen KVM/QEMU Virtio Tuning and SSD VM Optimization Guide]<br />
* [https://doc.opensuse.org/documentation/leap/virtualization/html/book-virt/part-virt-qemu.html Managing Virtual Machines with QEMU - openSUSE documentation]<br />
* [https://www.ibm.com/support/knowledgecenter/en/linuxonibm/liaat/liaatkvm.htm KVM on IBM Knowledge Center]</div>PXfhttps://wiki.archlinux.org/index.php?title=QEMU&diff=745148QEMU2022-09-07T02:12:22Z<p>PXf: /* Installation */ add external link to ceph rbd page</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Hypervisors]]<br />
[[de:QEMU]]<br />
[[es:QEMU]]<br />
[[fr:QEMU]]<br />
[[it:QEMU]]<br />
[[ja:QEMU]]<br />
[[zh-hans:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related|QEMU/Guest graphics acceleration}}<br />
{{Related|PCI passthrough via OVMF}}<br />
{{Related articles end}}<br />
<br />
According to the [https://wiki.qemu.org/Main_Page QEMU about page], "QEMU is a generic and open source machine emulator and virtualizer."<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|qemu-full}} package (or {{Pkg|qemu-base}} for the version without GUI) and below optional packages for your needs:<br />
<br />
* {{Pkg|qemu-block-gluster}} - [[Glusterfs]] block support<br />
* {{Pkg|qemu-block-iscsi}} - [[iSCSI]] block support<br />
* {{Pkg|qemu-block-rbd}} - [https://docs.ceph.com/en/quincy/rbd/index.html RBD] block support <br />
* {{Pkg|samba}} - [[Samba|SMB/CIFS]] server support<br />
<br />
Alternatively, {{AUR|qemu-user-static}} exists as a usermode and static variant.<br />
<br />
=== QEMU variants ===<br />
<br />
QEMU is offered in several variants suited for different use cases.<br />
<br />
As a first classification, QEMU is offered in full-system and usermode emulation modes:<br />
<br />
; Full-system emulation<br />
: In this mode, QEMU emulates a full system, including one or several processors and various peripherals. It is more accurate but slower, and does not require the emulated OS to be Linux.<br />
: QEMU commands for full-system emulation are named {{ic|qemu-system-''target_architecture''}}, e.g. {{ic|qemu-system-x86_64}} for emulating intel 64-bit CPUs, {{ic|qemu-system-i386}} for intel 32 bits CPUs, {{ic|qemu-system-arm}} for ARM (32 bits), {{ic|qemu-system-aarch64}} for ARM64, etc.<br />
: If the target architecture matches the host CPU, this mode may still benefit from a significant speedup by using a hypervisor like [[#Enabling KVM|KVM]] or Xen.<br />
; [https://www.qemu.org/docs/master/user/main.html Usermode emulation]: In this mode, QEMU is able to invoke a Linux executable compiled for a (potentially) different architecture by leveraging the host system resources. There may be compatibility issues, e.g. some features may not be implemented, dynamically linked executables will not work out of the box (see [[#Chrooting into arm/arm64 environment from x86_64]] to address this) and only Linux is supported (although [https://wiki.winehq.org/Emulation Wine may be used] for running Windows executables).<br />
: QEMU commands for usermode emulation are named {{ic|qemu-''target_architecture''}}, e.g. {{ic|qemu-x86_64}} for emulating intel 64-bit CPUs.<br />
<br />
QEMU is offered in dynamically-linked and statically-linked variants:<br />
<br />
; Dynamically-linked (default): {{ic|qemu-*}} commands depend on the host OS libraries, so executables are smaller.<br />
; Statically-linked: {{ic|qemu-*}} commands can be copied to any Linux system with the same architecture.<br />
<br />
In the case of Arch Linux, full-system emulation is offered as:<br />
<br />
; Non-headless (default): This variant enables GUI features that require additional dependencies (like SDL or GTK).<br />
; Headless: This is a slimmer variant that does not require GUI (this is suitable e.g. for servers).<br />
<br />
Note that headless and non-headless versions install commands with the same name (e.g. {{ic|qemu-system-x86_64}}) and thus cannot be both installed at the same time.<br />
<br />
=== Details on packages available in Arch Linux ===<br />
<br />
* The {{Pkg|qemu-desktop}} package provides the {{ic|x86_64}} architecture emulators for full-system emulation ({{ic|qemu-system-x86_64}}). The {{Pkg|qemu-emulators-full}} package provides the {{ic|x86_64}} usermode variant ({{ic|qemu-x86_64}}) and also for the rest of supported architectures it includes both full-system and usermode variants (e.g. {{ic|qemu-system-arm}} and {{ic|qemu-arm}}).<br />
* The headless versions of these packages (only applicable to full-system emulation) are {{Pkg|qemu-base}} ({{ic|x86_64}}-only) and {{Pkg|qemu-emulators-full}} (rest of architectures).<br />
* Full-system emulation can be expanded with some QEMU modules present in separate packages: {{Pkg|qemu-block-gluster}}, {{Pkg|qemu-block-iscsi}}, {{Pkg|qemu-block-rbd}} and {{Pkg|qemu-guest-agent}}.<br />
* The unofficial AUR package {{AUR|qemu-user-static}} provides a usermode and static variant for all target architectures supported by QEMU. A precompiled version of this package exists: {{AUR|qemu-user-static-bin}}. The installed QEMU commands are named {{ic|qemu-''target_architecture''-static}}, for example, {{ic|qemu-x86_64-static}} for intel 64-bit CPUs.<br />
* The unofficial AUR package {{AUR|qemu-loongarch64-git}} (along with {{AUR|qemu-system-loongarch64-git}} and {{AUR|qemu-loongarch64-static-git}}) provide QEMU for the LoongArch architecture, officially supported since [https://wiki.qemu.org/ChangeLog/7.1#LoongArch version 7.1].<br />
<br />
{{Note|At present, Arch does not offer a full-system mode and statically linked variant (neither officially nor via AUR), as this is usually not needed.}}<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s).<br />
<br />
[[Libvirt]] provides a convenient way to manage QEMU virtual machines. See [[Libvirt#Client|list of libvirt clients]] for available front-ends.<br />
<br />
Other GUI front-ends for QEMU:<br />
<br />
* {{App|AQEMU|QEMU GUI written in Qt5.|https://github.com/tobimensch/aqemu|{{AUR|aqemu}}}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Accuracy|If I get the man page right the raw format only allocates the full size if the filesystem does not support "holes" or it is <br />
explicitly told to preallocate. See {{man|1|qemu-img|NOTES}}.}} <br />
<br />
{{Tip|See [[Wikibooks:QEMU/Images]] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. This image format also supports QEMU snapshotting functionality (see [[#Creating and managing snapshots via the monitor console]] for details). However, using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GiB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-on-Write (CoW)|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-x86_64 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. It is recommended to create a backup first.}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GiB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss! For a Windows guest, open the "create and format hard disk partitions" control panel.<br />
<br />
==== Converting an image ====<br />
<br />
You can convert an image to other formats using {{ic|qemu-img convert}}. This example shows how to convert a ''raw'' image to ''qcow2'':<br />
<br />
$ qemu-img convert -f raw -O qcow2 ''input''.img ''output''.qcow2<br />
<br />
This will not remove the original input file.<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso'' bs=4k}}}}<br />
<br />
=== Installing the operating system ===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM and a raw disk image:<br />
<br />
$ qemu-system-x86_64 -cdrom ''iso_image'' -boot order=d -drive file=''disk_image'',format=raw<br />
<br />
See {{man|1|qemu}} for more information about loading other media types (such as floppy, disk images or physical drives) and [[#Running virtualized system]] for other useful options.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Note|By default only 128 MiB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.}}<br />
<br />
{{Tip|<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* When running QEMU in headless mode, it starts a local VNC server on port 5900 per default. You can use [[TigerVNC]] to connect to the guest OS: {{ic|vncviewer :5900}}<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.<br />
}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-x86_64 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{man|1|qemu}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt+g}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM (''Kernel-based Virtual Machine'') full virtualization must be supported by your Linux kernel and your hardware, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-accel kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the [[#QEMU monitor]] and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* The argument {{ic|1=accel=kvm}} of the {{ic|-machine}} option is equivalent to the {{ic|-enable-kvm}} or the {{ic|-accel kvm}} option.<br />
* CPU model {{ic|host}} requires KVM<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
=== Enabling IOMMU (Intel VT-d/AMD-Vi) support ===<br />
<br />
First enable IOMMU, see [[PCI passthrough via OVMF#Setting up IOMMU]].<br />
<br />
Add {{ic|-device intel-iommu}} to create the IOMMU device:<br />
<br />
$ qemu-system-x86_64 '''-enable-kvm -machine q35 -device intel-iommu''' -cpu host ..<br />
<br />
{{Note|<br />
On Intel CPU based systems creating an IOMMU device in a QEMU guest with {{ic|-device intel-iommu}} will disable PCI passthrough with an error like: {{bc|Device at bus pcie.0 addr 09.0 requires iommu notifier which is currently not supported by intel-iommu emulation}} While adding the kernel parameter {{ic|1=intel_iommu=on}} is still needed for remapping IO (e.g. [[PCI passthrough via OVMF#Isolating the GPU|PCI passthrough with vfio-pci]]), {{ic|-device intel-iommu}} should not be set if PCI passthrough is required.<br />
}}<br />
<br />
=== Booting in UEFI mode ===<br />
<br />
The default firmware used by QEMU is [https://www.coreboot.org/SeaBIOS SeaBIOS], which is a Legacy BIOS implementation. QEMU uses {{ic|/usr/share/qemu/bios-256k.bin}} (provided by the {{Pkg|seabios}} package) as a default read-only (ROM) image. You can use the {{ic|-bios}} argument to select another firmware file. However, UEFI requires writable memory to work properly, so you need to emulate [https://wiki.qemu.org/Features/PC_System_Flash PC System Flash] instead.<br />
<br />
[https://github.com/tianocore/tianocore.github.io/wiki/OVMF OVMF] is a TianoCore project to enable UEFI support for Virtual Machines. It can be [[install]]ed with the {{Pkg|edk2-ovmf}} package.<br />
<br />
There are two ways to use OVMF as a firmware. The first is to copy {{ic|/usr/share/edk2-ovmf/x64/OVMF.fd}}, make it writable and use as a pflash drive:<br />
<br />
-drive if=pflash,format=raw,file=''/copy/of/OVMF.fd''<br />
<br />
All changes to the UEFI settings will be saved directly to this file.<br />
<br />
Another and more preferable way is to split OVMF into two files. The first one will be read-only and store the firmware executable, and the second one will be used as a writable variable store. The advantage is that you can use the firmware file directly without copying, so it will be updated automatically by [[pacman]].<br />
<br />
Use {{ic|/usr/share/edk2-ovmf/x64/OVMF_CODE.fd}} as a first read-only pflash drive. Copy {{ic|/usr/share/edk2-ovmf/x64/OVMF_VARS.fd}}, make it writable and use as a second writable pflash drive:<br />
<br />
-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd \<br />
-drive if=pflash,format=raw,file=''/copy/of/OVMF_VARS.fd''<br />
<br />
=== Trusted Platform Module emulation ===<br />
<br />
QEMU can emulate [[Trusted Platform Module]], which is required by some systems such as Windows 11.<br />
<br />
[[Install]] the {{Pkg|swtpm}} package, which provides a software TPM implementation. Create some directory for storing TPM data ({{ic|''/path/to/mytpm''}} will be used as an example). Run this command to start the emulator:<br />
<br />
$ swtpm socket --tpm2 --tpmstate dir=''/path/to/mytpm'' --ctrl type=unixio,path=''/path/to/mytpm/swtpm-sock''<br />
<br />
{{ic|''/path/to/mytpm/swtpm-sock''}} will be created by ''swtpm'': this is a UNIX socket to which QEMU will connect. You can put it in any directory.<br />
<br />
By default, ''swtpm'' starts a TPM version 1.2 emulator. The {{ic|--tpm2}} option enables TPM 2.0 emulation.<br />
<br />
Finally, add the following options to QEMU:<br />
<br />
-chardev socket,id=chrtpm,path=''/path/to/mytpm/swtpm-sock'' \<br />
-tpmdev emulator,id=tpm0,chardev=chrtpm \<br />
-device tpm-tis,tpmdev=tpm0<br />
<br />
and TPM will be available inside the VM. After shutting down the VM, ''swtpm'' will be automatically terminated.<br />
<br />
See [https://qemu-project.gitlab.io/qemu/specs/tpm.html the QEMU documentation] for more information.<br />
<br />
== Sharing data between host and guest ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network block device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's port forwarding ===<br />
<br />
{{Note|QEMU's port forwarding is IPv4-only. IPv6 port forwarding is not implemented and the last patches were proposed in 2018.[https://lore.kernel.org/qemu-devel/1540512223-21199-1-git-send-email-max7255@yandex-team.ru/T/#u]}}<br />
<br />
QEMU can forward ports from the host to the guest to enable e.g. connecting from the host to an SSH server running on the guest.<br />
<br />
For example, to bind port 60022 on the host with port 22 (SSH) on the guest, start QEMU with a command like:<br />
<br />
$ qemu-system-x86_64 ''disk_image'' -nic user,hostfwd=tcp::60022-:22<br />
<br />
Make sure the sshd is running on the guest and connect with:<br />
<br />
$ ssh ''guest-user''@127.0.0.1 -p 60022<br />
<br />
You can use [[SSHFS]] to mount the guest's file system at the host for shared read and write access.<br />
<br />
To forward several ports, you just repeat the {{ic|hostfwd}} in the {{ic|-nic}} argument, e.g. for VNC's port:<br />
<br />
$ qemu-system-x86_64 ''disk_image'' -nic user,hostfwd=tcp::60022-:22,hostfwd=tcp::5900-:5900<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] on the host with an automatically generated {{ic|smb.conf}} file located in {{ic|/tmp/qemu-smb.''random_string''}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and is useful when you do not want to start the normal [[Samba]] service on the host, which the guest can also access if you have set up shares on it.<br />
<br />
Only a single directory can be set as shared with the option {{ic|1=smb=}}, but adding more directories (even while the virtual machine is running) could be as easy as creating symbolic links in the shared directory if QEMU configured SMB to follow symbolic links. It does not do so, but the configuration of the running SMB server can be changed as described below.<br />
<br />
''Samba'' must be installed on the host. To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-x86_64 -nic user,id=nic0,smb=''shared_dir_path'' ''disk_image''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [https://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
* If you cannot access the shared folder and the guest system is Windows 10 Enterprise or Education or Windows Server 2016, [https://support.microsoft.com/en-us/help/4046019 enable guest access].<br />
* If you use [[#Tap networking with QEMU]], use {{ic|1=-device virtio-net,netdev=vmnic -netdev user,id=vmnic,smb=''shared_dir_path''}} to get SMB.<br />
}}<br />
<br />
One way to share multiple directories and to add or remove them while the virtual machine is running, is to share an empty directory and create/remove symbolic links to the directories in the shared directory. For this to work, the configuration of the running SMB server can be changed with the following script, which also allows the execution of files on the guest that are not set executable on the host:<br />
<br />
#!/bin/sh<br />
eval $(ps h -C smbd -o pid,args | grep /tmp/qemu-smb | gawk '{print "pid="$1";conf="$6}')<br />
echo "[global]<br />
allow insecure wide links = yes<br />
[qemu]<br />
follow symlinks = yes<br />
wide links = yes<br />
acl allow execute always = yes" >> "$conf"<br />
# in case the change is not detected automatically:<br />
smbcontrol --configfile="$conf" "$pid" reload-config<br />
<br />
This can be applied to the running server started by qemu only after the guest has connected to the network drive the first time. An alternative to this method is to add additional shares to the configuration file like so:<br />
<br />
echo "[''myshare'']<br />
path=''another_path''<br />
read only=no<br />
guest ok=yes<br />
force user=''username''" >> $conf<br />
<br />
This share will be available on the guest as {{ic|\\10.0.2.4\''myshare''}}.<br />
<br />
=== Using filesystem passthrough and VirtFS ===<br />
<br />
See the [https://wiki.qemu.org/Documentation/9psetup QEMU documentation].<br />
<br />
=== Host file sharing with virtiofsd ===<br />
<br />
{{Style|See [[Help:Style/Formatting and punctuation]].}}<br />
<br />
virtiofsd is shipped with QEMU package. Documentation is available [https://qemu-stsquad.readthedocs.io/en/docs-next/tools/virtiofsd.html online] or {{ic|/usr/share/doc/qemu/tools/virtiofsd.html}} on local file system with QEMU installed.<br />
<br />
Add user that runs qemu to 'kvm' group, because it needs to access virtiofsd socket. You might have to logout for change to take effect.<br />
<br />
{{Accuracy|Running services as root is not secure. Also the process should be wrapped in a systemd service.}}<br />
<br />
Start as virtiofsd as root:<br />
<br />
# /usr/lib/qemu/virtiofsd --socket-path=/var/run/qemu-vm-001.sock -o source=/tmp/vm-001 -o cache=always<br />
<br />
where<br />
<br />
* {{ic|/var/run/qemu-vm-001.sock}} is a socket file,<br />
* {{ic|/tmp/vm-001}} is a shared directory between host and guest vm.<br />
<br />
The created socket file has root only access permission. Give group kvm access to it with:<br />
<br />
# chgrp kvm qemu-vm-001.sock; chmod g+rxw qemu-vm-001.sock<br />
<br />
Add the following configuration options when starting VM:<br />
<br />
-object memory-backend-memfd,id=mem,size=4G,share=on \<br />
-numa node,memdev=mem \<br />
-chardev socket,id=char0,path=/var/run/qemu-vm-001.sock \<br />
-device vhost-user-fs-pci,chardev=char0,tag=myfs<br />
<br />
where<br />
<br />
{{Expansion|Explain the remaining options (or remove them if they are not necessary).}}<br />
<br />
* {{ic|1=size=4G}} shall match size specified with {{ic|-m 4G}} option,<br />
* {{ic|/var/run/qemu-vm-001.sock}} points to socket file started earlier,<br />
<br />
{{Style|The section should not be specific to Windows.}}<br />
<br />
Remember, that guest must be configured to enable sharing. For windows there are [https://virtio-fs.gitlab.io/howto-windows.html instructions]. Once configured, windows will have Z: drive mapped automatically with shared directory content. <br />
<br />
Your Windows 10 guest system is properly configured if it has:<br />
<br />
* VirtioFSSService windows service,<br />
* WinFsp.Launcher windows service,<br />
* VirtIO FS Device driver under "System devices" in Windows "Device Manager".<br />
<br />
If the above installed and {{ic|Z:}} drive is still not listed, try repairing "Virtio-win-guest-tools" in Windows add/remove programs.<br />
<br />
=== Mounting a partition of the guest on the host ===<br />
<br />
It can be useful to mount a drive image under the host system, it can be a way to transfer files in and out of the guest. This should be done when the virtual machine is not running.<br />
<br />
The procedure to mount the drive on the host depends on the type of qemu image, ''raw'' or ''qcow2''. We detail thereafter the steps to mount a drive in the two formats in [[#Mounting a partition from a raw image]] and [[#Mounting a partition from a qcow2 image]]. For the full documentation see [[Wikibooks:QEMU/Images#Mounting an image on the host]].<br />
<br />
{{Warning|You must unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== Mounting a partition from a raw image ====<br />
<br />
It is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices.<br />
<br />
===== With manually specifying byte offset =====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
===== With loop module autodetecting partitions =====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel modules#Manual module handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
To mount the disk image with ''udisksctl'', see [[Udisks#Mount loop devices]].<br />
<br />
===== With kpartx =====<br />
<br />
''kpartx'' from the {{Pkg|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
==== Mounting a partition from a qcow2 image ====<br />
<br />
We will use {{ic|qemu-nbd}}, which lets use the NBD (''network block device'') protocol to share the disk image.<br />
<br />
First, we need the ''nbd'' module loaded:<br />
<br />
# modprobe nbd max_part=16<br />
<br />
Then, we can share the disk and create the device entries:<br />
<br />
# qemu-nbd -c /dev/nbd0 ''/path/to/image.qcow2''<br />
<br />
Discover the partitions:<br />
<br />
# partprobe /dev/nbd0<br />
<br />
''fdisk'' can be used to get information regarding the different partitions in {{ic|''nbd0''}}:<br />
<br />
{{hc|# fdisk -l /dev/nbd0|2=<br />
Disk /dev/nbd0: 25.2 GiB, 27074281472 bytes, 52879456 sectors<br />
Units: sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disklabel type: dos<br />
Disk identifier: 0xa6a4d542<br />
<br />
Device Boot Start End Sectors Size Id Type<br />
/dev/nbd0p1 * 2048 1026047 1024000 500M 7 HPFS/NTFS/exFAT<br />
/dev/nbd0p2 1026048 52877311 51851264 24.7G 7 HPFS/NTFS/exFAT}}<br />
<br />
Then mount any partition of the drive image, for example the partition 2:<br />
<br />
# mount /dev/nbd0'''p2''' ''mountpoint''<br />
<br />
After the usage, it is important to unmount the image and reverse previous steps, i.e. unmount the partition and disconnect the nbd device:<br />
<br />
# umount ''mountpoint''<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you must either change the owner of the partition's device file to that user, add that user to the ''disk'' group, or use [[ACL]] for more fine-grained access control.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with an MBR. Such a virtual machine can be booted either by: [[#Specifying kernel and initrd manually]], [[#Simulating a virtual disk with MBR]], [[#Using the device-mapper]], [[#Using a linear RAID]] or [[#Using a Network Block Device]].<br />
<br />
==== Specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-x86_64 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulating a virtual disk with MBR ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate an MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
For the following, suppose you have a plain, unmounted {{ic|/dev/hda''N''}} partition with some file system on it you wish to make part of a QEMU disk image. The trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image. More generally, the partition can be any part of a larger simulated disk, in particular a block device that simulates the original physical disk but only exposes {{ic|/dev/hda''N''}} to the virtual machine.<br />
<br />
A virtual disk of this type can be represented by a VMDK file that contains references to (a copy of) the MBR and the partition, but QEMU does not support this VMDK format. For instance, a virtual disk [https://www.virtualbox.org/manual/ch09.html#rawdisk created by]<br />
<br />
$ VBoxManage internalcommands createrawvmdk -filename ''/path/to/file.vmdk'' -rawdisk /dev/hda<br />
<br />
will be rejected by QEMU with the error message<br />
<br />
Unsupported image type 'partitionedDevice'<br />
<br />
Note that {{ic|VBoxManage}} creates two files, {{ic|''file.vmdk''}} and {{ic|''file-pt.vmdk''}}, the latter being a copy of the MBR, to which the text file {{ic|file.vmdk}} points. Read operations outside the target partition or the MBR would give zeros, while written data would be discarded.<br />
<br />
===== Using the device-mapper =====<br />
<br />
A method that is similar to the use of a VMDK descriptor file uses the [https://docs.kernel.org/admin-guide/device-mapper/index.html device-mapper] to prepend a loop device attached to the MBR file to the target partition. In case we do not need our virtual disk to have the same size as the original, we first create a file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=2048<br />
<br />
Here, a 1 MiB (2048 * 512 bytes) file is created in accordance with partition alignment policies used by modern disk partitioning tools. For compatibility with older partitioning software, 63 sectors instead of 2048 might be required. The MBR only needs a single 512 bytes block, the additional free space can be used for a BIOS boot partition and, in the case of a hybrid partitioning scheme, for a GUID Partition Table. Then, we attach a loop device to the MBR file:<br />
<br />
# losetup --show -f ''/path/to/mbr''<br />
/dev/loop0<br />
<br />
In this example, the resulting device is {{ic|/dev/loop0}}. The device mapper is now used to join the MBR and the partition:<br />
<br />
# echo "0 2048 linear /dev/loop0 0<br />
2048 `blockdev --getsz /dev/hda''N''` linear /dev/hda''N'' 0" | dmsetup create qemu<br />
<br />
The resulting {{ic|/dev/mapper/qemu}} is what we will use as a QEMU raw disk image. Additional steps are required to create a partition table (see the section that describes the use of a linear RAID for an example) and boot loader code on the virtual disk (which will be stored in {{ic|''/path/to/mbr''}}).<br />
<br />
The following setup is an example where the position of {{ic|/dev/hda''N''}} on the virtual disk is to be the same as on the physical disk and the rest of the disk is hidden, except for the MBR, which is provided as a copy:<br />
<br />
# dd if=/dev/hda count=1 of=''/path/to/mbr''<br />
# loop=`losetup --show -f ''/path/to/mbr''`<br />
# start=`blockdev --report /dev/hda''N'' | tail -1 | awk '{print $5}'`<br />
# size=`blockdev --getsz /dev/hda''N''`<br />
# disksize=`blockdev --getsz /dev/hda`<br />
# echo "0 1 linear $loop 0<br />
1 $((start-1)) zero<br />
$start $size linear /dev/hda''N'' 0<br />
$((start+size)) $((disksize-start-size)) zero" | dmsetup create qemu<br />
<br />
The table provided as standard input to {{ic|dmsetup}} has a similar format as the table in a VDMK descriptor file produced by {{ic|VBoxManage}} and can alternatively be loaded from a file with {{ic|dmsetup create qemu --table ''table_file''}}. To the virtual machine, only {{ic|/dev/hda''N''}} is accessible, while the rest of the hard disk reads as zeros and discards written data, except for the first sector. We can print the table for {{ic|/dev/mapper/qemu}} with {{ic|dmsetup table qemu}} (use {{ic|udevadm info -rq name /sys/dev/block/''major'':''minor''}} to translate {{ic|''major'':''minor''}} to the corresponding {{ic|/dev/''blockdevice''}} name). Use {{ic|dmsetup remove qemu}} and {{ic|losetup -d $loop}} to delete the created devices.<br />
<br />
A situation where this example would be useful is an existing Windows XP installation in a multi-boot configuration and maybe a hybrid partitioning scheme (on the physical hardware, Windows XP could be the only operating system that uses the MBR partition table, while more modern operating systems installed on the same computer could use the GUID Partition Table). Windows XP supports hardware profiles, so that that the same installation can be used with different hardware configurations alternatingly (in this case bare metal vs. virtual) with Windows needing to install drivers for newly detected hardware only once for every profile. Note that in this example the boot loader code in the copied MBR needs to be updated to directly load Windows XP from {{ic|/dev/hda''N''}} instead of trying to start the multi-boot capable boot loader (like GRUB) present in the original system. Alternatively, a copy of the boot partition containing the boot loader installation can be included in the virtual disk the same way as the MBR.<br />
<br />
===== Using a linear RAID =====<br />
<br />
You can also do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: <br />
<br />
First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KiB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hda''N''}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kibibyte-roundable offsets (such as 31.5 KiB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-x86_64 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
===== Using a Network Block Device =====<br />
<br />
With [https://docs.kernel.org/admin-guide/blockdev/nbd.html Network Block Device], Linux can use a remote server as one of its block device. You may use {{ic|nbd-server}} (from the {{pkg|nbd}} package) to create an MBR wrapper for QEMU.<br />
<br />
Assuming you have already set up your MBR wrapper file like above, rename it to {{ic|wrapper.img.0}}. Then create a symbolic link named {{ic|wrapper.img.1}} in the same directory, pointing to your partition. Then put the following script in the same directory:<br />
<br />
#!/bin/sh<br />
dir="$(realpath "$(dirname "$0")")"<br />
cat >wrapper.conf <<EOF<br />
[generic]<br />
allowlist = true<br />
listenaddr = 127.713705<br />
port = 10809<br />
<br />
[wrap]<br />
exportname = $dir/wrapper.img<br />
multifile = true<br />
EOF<br />
<br />
nbd-server \<br />
-C wrapper.conf \<br />
-p wrapper.pid \<br />
"$@"<br />
<br />
The {{ic|.0}} and {{ic|.1}} suffixes are essential; the rest can be changed. After running the above script (which you may need to do as root to make sure nbd-server is able to access the partition), you can launch QEMU with:<br />
<br />
qemu-system-x86_64 -drive file=nbd:127.713705:10809:exportname=wrap ''[...]''<br />
<br />
=== Using an entire physical disk device inside the VM ===<br />
<br />
{{Style|Duplicates [[#Using any real partition as the single primary partition of a hard disk image]], libvirt instructions do not belong to this page.}}<br />
<br />
You may have a second hdd/ssd with a different OS (like Windows) on it and may want to gain the ability to also boot it inside a VM.<br />
Since the disk access is raw, the disk will perform quite well inside the VM.<br />
<br />
==== windows VM boot prerequisites ====<br />
<br />
Be sure to install the [https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-virtio/ virtio drivers] inside the OS on that disk before trying to boot it in the VM.<br />
For Win 7 use version [https://askubuntu.com/questions/1310440/using-virtio-win-drivers-with-win7-sp1-x64 0.1.173-4].<br />
Some singular drivers from newer virtio builds may be used on Win 7 but you will have to install them manually via device manager.<br />
For Win 10 you can use the latest virtio build.<br />
<br />
===== set up the windows disk interface drivers =====<br />
<br />
You may get a {{ic|0x0000007B}} bluescreen when trying to boot the VM. This means Windows can not access the drive during the early boot stage because the disk interface driver it would need for that is not loaded / is set to start manually.<br />
<br />
The solution is to [https://superuser.com/a/1032769 enable these drivers to start at boot].<br />
<br />
In {{ic|HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services}}, find the folders {{ic|aliide, amdide, atapi, cmdide, iastor (may not exist), iastorV, intelide, LSI_SAS, msahci, pciide and viaide}}.<br />
Inside each of those, set all their "start" values to 0 in order to enable them at boot.<br />
If your drive is a PCIe NVMe drive, also enable that driver (should it exist).<br />
<br />
==== find the unique path of your disk ====<br />
<br />
Run {{ic|ls /dev/disk/by-id/}}<br />
There you pick out the ID of the drive you want to insert into the VM, my disk ID is {{ic|ata-TS512GMTS930L_C199211383}}<br />
Now add that ID to {{ic|/dev/disk/by-id/}} so you get {{ic|/dev/disk/by-id/ata-TS512GMTS930L_C199211383}} .<br />
That is the unique path to that disk.<br />
<br />
==== add the disk in QEMU CLI ====<br />
<br />
In QEMU CLI that would probably be:<br />
<br />
{{ic|1=-drive file=/dev/disk/by-id/ata-TS512GMTS930L_C199211383,format=raw,media=disk}}<br />
<br />
Just modify "file=" to be the unique path of your drive.<br />
<br />
==== add the disk in libvirt ====<br />
<br />
In libvirt xml that translates to<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<disk type="block" device="disk"><br />
<driver name="qemu" type="raw" cache="none" io="native"/><br />
<source dev="/dev/disk/by-id/ata-TS512GMTS930L_C199211383"/><br />
<target dev="sda" bus="sata"/><br />
<address type="drive" controller="0" bus="0" target="0" unit="0"/><br />
</disk><br />
...<br />
</nowiki>}}<br />
<br />
Just modify "source dev" to be the unique path of your drive.<br />
<br />
==== add the disk in virt-manager ====<br />
<br />
When creating a VM, select "import existing drive" and just paste that unique path.<br />
If you already have the VM, add a device, storage, then select or create custom storage.<br />
Now paste the unique path.<br />
<br />
== Networking ==<br />
<br />
{{Style|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [https://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-x86_64 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
* Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
* Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-x86_64 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
* Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|2=<br />
#!/usr/bin/env python<br />
# usage: qemu-mac-hasher.py <VMName><br />
<br />
import sys<br />
import zlib<br />
<br />
crc = str(hex(zlib.crc32(sys.argv[1].encode("utf-8")))).replace("x", "")[-8:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-x86_64 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{Note|ICMPv6 will not work, as support for it is not implemented: {{ic|Slirp: external icmpv6 not supported yet}}. [[Ping]]ing an IPv6 address will not work.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
{{Note|If the host system uses [[systemd-networkd]], make sure to symlink the {{ic|/etc/resolv.conf}} file as described in [[systemd-networkd#Required services and setup]], otherwise the DNS lookup in the guest system will not work.}}<br />
<br />
{{Tip|To use the virtio driver with user-mode networking, the option is: {{ic|1=-nic user,model=virtio-net-pci}}.}}<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-device virtio-net,netdev=network0 -netdev tap,id=network0,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-device virtio-net,netdev=network0 -netdev tap,id=network0,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See [https://web.archive.org/web/20160222161955/http://www.linux-kvm.com:80/content/how-maximize-virtio-net-performance-vhost-net] for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* See [[Network bridge]] for information on creating bridge.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
<br />
{{bc|1=<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.20.0.2,172.20.255.254<br />
}}<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|<br />
* See [[Network bridge]] for information on creating bridge.<br />
* See https://wiki.qemu.org/Features/HelperNetworking for more information on QEMU's network helper.<br />
}}<br />
<br />
First, create a configuration file containing the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''br0''<br />
allow ''br1''<br />
...}}<br />
<br />
Make sure {{ic|/etc/qemu/}} has {{ic|755}} [[permissions]]. [https://gitlab.com/qemu-project/qemu/-/issues/515 QEMU issues] and [https://www.gns3.com/community/discussions/gns3-cannot-work-with-qemu GNS3 issues] may arise if this is not the case.<br />
<br />
Now start the VM; the most basic usage to run QEMU with the default network helper and default bridge {{ic|br0}}:<br />
<br />
$ qemu-system-x86_64 -nic bridge ''[...]''<br />
<br />
Using the bridge {{ic|br1}} and the virtio driver:<br />
<br />
$ qemu-system-x86_64 -nic bridge,br=''br1'',model=virtio-net-pci ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Style|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [https://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Optionally create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name. In the {{ic|run-qemu}} script below, {{ic|br0}} is set up if not listed, as it is assumed that by default the host is not accessing network via the bridge.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
: '<br />
e.g. with img created via:<br />
qemu-img create -f qcow2 example.img 90G<br />
run-qemu -cdrom archlinux-x86_64.iso -boot order=d -drive file=example.img,format=qcow2 -m 4G -enable-kvm -cpu host -smp 4<br />
run-qemu -drive file=example.img,format=qcow2 -m 4G -enable-kvm -cpu host -smp 4<br />
'<br />
<br />
nicbr0() {<br />
sudo ip link set dev $1 promisc on up &> /dev/null<br />
sudo ip addr flush dev $1 scope host &>/dev/null<br />
sudo ip addr flush dev $1 scope site &>/dev/null<br />
sudo ip addr flush dev $1 scope global &>/dev/null<br />
sudo ip link set dev $1 master br0 &> /dev/null<br />
}<br />
_nicbr0() {<br />
sudo ip link set $1 promisc off down &> /dev/null<br />
sudo ip link set dev $1 nomaster &> /dev/null<br />
}<br />
<br />
HASBR0="$( ip link show | grep br0 )"<br />
if [ -z $HASBR0 ] ; then<br />
ROUTER="192.168.1.1"<br />
SUBNET="192.168.1."<br />
NIC=$(ip link show | grep enp | grep 'state UP' | head -n 1 | cut -d":" -f 2 | xargs)<br />
IPADDR=$(ip addr show | grep -o "inet $SUBNET\([0-9]*\)" | cut -d ' ' -f2)<br />
sudo ip link add name br0 type bridge &> /dev/null<br />
sudo ip link set dev br0 up<br />
sudo ip addr add $IPADDR/24 brd + dev br0<br />
sudo ip route del default &> /dev/null<br />
sudo ip route add default via $ROUTER dev br0 onlink<br />
nicbr0 $NIC<br />
sudo iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
fi<br />
<br />
USERID=$(whoami)<br />
precreationg=$(ip tuntap list | cut -d: -f1 | sort)<br />
sudo ip tuntap add user $USERID mode tap<br />
postcreation=$(ip tuntap list | cut -d: -f1 | sort)<br />
TAP=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
nicbr0 $TAP<br />
<br />
printf -v MACADDR "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-x86_64 -net nic,macaddr=$MACADDR,model=virtio \<br />
-net tap,ifname=$TAP,script=no,downscript=no,vhost=on \<br />
$@<br />
<br />
_nicbr0 $TAP<br />
sudo ip link set dev $TAP down &> /dev/null<br />
sudo ip tuntap del $TAP mode tap<br />
<br />
if [ -z $HASBR0 ] ; then<br />
_nicbr0 $NIC<br />
sudo ip addr del dev br0 $IPADDR/24 &> /dev/null<br />
sudo ip link set dev br0 down<br />
sudo ip link delete br0 type bridge &> /dev/null<br />
sudo ip route del default &> /dev/null<br />
sudo ip link set dev $NIC up<br />
sudo ip route add default via $ROUTER dev $NIC onlink &> /dev/null<br />
fi<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
<br />
$ run-qemu -hda ''myvm.img'' -m 512<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [https://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Automatic module loading with systemd]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it is easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See [[Network bridge#Wireless interface on a bridge]] as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See [[Internet sharing]] as a reference.<br />
<br />
There you can find what is needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside {{ic|/etc/sysctl.d}}:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge does not include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Style|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [https://wiki.virtualsquare.org/ the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[install]]ed via the {{Pkg|vde2}} package.<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-x86_64 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be [[executable]]. <br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
==== Alternative method ====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-x86_64 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [https://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|2=<br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for users in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|2=<br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
=== Shorthand configuration ===<br />
<br />
If you are using QEMU with various networking options a lot, you probably have created a lot of {{ic|-netdev}} and {{ic|-device}} argument pairs, which gets quite repetitive. You can instead use the {{ic|-nic}} argument to combine {{ic|-netdev}} and {{ic|-device}} together, so that, for example, these arguments:<br />
<br />
-netdev tap,id=network0,ifname=tap0,script=no,downscript=no,vhost=on -device virtio-net-pci,netdev=network0<br />
<br />
become:<br />
<br />
-nic tap,script=no,downscript=no,vhost=on,model=virtio-net-pci<br />
<br />
Notice the lack of network IDs, and that the device was created with {{ic|1=model=}}. The first half of the {{ic|-nic}} parameters are {{ic|-netdev}} parameters, whereas the second half (after {{ic|1=model=}}) are related with the device. The same parameters (for example, {{ic|1=smb=}}) are used. To completely disable the networking use {{ic|-nic none}}.<br />
<br />
See [https://qemu.weilnetz.de/doc/6.0/system/net.html QEMU networking documentation] for more information on parameters you can use.<br />
<br />
== Graphic card ==<br />
<br />
QEMU can emulate a standard graphic card text mode using {{ic|-curses}} command line option. This allows to type text and see text output directly inside a text terminal. Alternatively, {{ic|-nographic}} serves a similar purpose.<br />
<br />
QEMU can emulate several types of VGA card. The card type is passed in the {{ic|-vga ''type''}} command line option and can be {{ic|std}}, {{ic|qxl}}, {{ic|vmware}}, {{ic|virtio}}, {{ic|cirrus}} or {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels without requiring guest drivers. This is the default since QEMU 2.2.<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest. You may want to use [[#SPICE]] for improved graphical performance when using QXL.<br />
<br />
On Linux guests, the {{ic|qxl}} and {{ic|bochs_drm}} kernel modules must be loaded in order to gain a decent performance.<br />
<br />
Default VGA memory size for QXL devices is 16M which is sufficient to drive resolutions approximately up to QHD (2560x1440). To enable higher resolutions, [[#Multi-monitor support|increase vga_memmb]].<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. Install the VMware drivers {{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests.<br />
<br />
=== virtio ===<br />
<br />
{{ic|virtio-vga}} / {{ic|virtio-gpu}} is a paravirtual 3D graphics driver based on [https://virgil3d.github.io/ virgl]. Currently a work in progress, supporting only very recent (>= 4.4) Linux guests with {{Pkg|mesa}} (>=11.2) compiled with the option {{ic|1=gallium-drivers=virgl}}.<br />
<br />
To enable 3D acceleration on the guest system select this vga with {{ic|-device virtio-vga-gl}} and enable the opengl context in the display device with {{ic|1=-display sdl,gl=on}} or {{ic|1=-display gtk,gl=on}} for the sdl and gtk display output respectively. Successful configuration can be confirmed looking at the kernel log in the guest:<br />
<br />
{{hc|# dmesg {{!}} grep drm |<br />
[drm] pci: virtio-vga detected<br />
[drm] virgl 3d acceleration enabled<br />
}}<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [https://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
== SPICE ==<br />
<br />
The [https://www.spice-space.org/ SPICE project] aims to provide a complete open source solution for remote access to virtual machines in a seamless way.<br />
<br />
=== Enabling SPICE support on the host ===<br />
<br />
The following is an example of booting with SPICE as the remote desktop protocol, including the support for copy and paste from host:<br />
<br />
$ qemu-system-x86_64 -vga qxl -device virtio-serial-pci -spice port=5930,disable-ticketing=on -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The parameters have the following meaning:<br />
<br />
# {{ic|-device virtio-serial-pci}} adds a virtio-serial device<br />
# {{ic|1=-spice port=5930,disable-ticketing=on}} set TCP port {{ic|5930}} for spice channels listening and allow client to connect without authentication{{Tip|Using [[wikipedia:Unix_socket|Unix sockets]] instead of TCP ports does not involve using network stack on the host system. It does not imply that packets are encapsulated and decapsulated to use the network and the related protocol. The sockets are identified solely by the inodes on the hard drive. It is therefore considered better for performance. Use instead {{ic|1=-spice unix=on,addr=/tmp/vm_spice.socket,disable-ticketing=on}}.}}<br />
# {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in the virtio-serial device,<br />
# {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port. It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Connecting to the guest with a SPICE client ===<br />
<br />
A SPICE client is necessary to connect to the guest. In Arch, the following clients are available:<br />
<br />
{{App|virt-viewer|SPICE client recommended by the protocol developers, a subset of the virt-manager project.|https://virt-manager.org/|{{Pkg|virt-viewer}}}}<br />
<br />
{{App|spice-gtk|SPICE GTK client, a subset of the SPICE project. Embedded into other applications as a widget.|https://www.spice-space.org/|{{Pkg|spice-gtk}}}}<br />
<br />
For clients that run on smartphone or on other platforms, refer to the ''Other clients'' section in [https://www.spice-space.org/download.html spice-space download].<br />
<br />
==== Manually running a SPICE client ====<br />
<br />
One way of connecting to a guest listening on Unix socket {{ic|/tmp/vm_spice.socket}} is to manually run the SPICE client using {{ic|$ remote-viewer spice+unix:///tmp/vm_spice.socket}} or {{ic|1=$ spicy --uri="spice+unix:///tmp/vm_spice.socket"}}, depending on the desired client. Since QEMU in SPICE mode acts similarly to a remote desktop server, it may be more convenient to run QEMU in daemon mode with the {{ic|-daemonize}} parameter.<br />
<br />
{{Tip|To connect to the guest through SSH tunelling, the following type of command can be used: {{bc|$ ssh -fL 5999:localhost:5930 ''my.domain.org'' sleep 10; spicy -h 127.0.0.1 -p 5999}}<br />
This example connects ''spicy'' to the local port {{ic|5999}} which is forwarded through SSH to the guest's SPICE server located at the address ''my.domain.org'', port {{ic|5930}}.<br />
Note the {{ic|-f}} option that requests ssh to execute the command {{ic|sleep 10}} in the background. This way, the ssh session runs while the client is active and auto-closes once the client ends.<br />
}}<br />
<br />
==== Running a SPICE client with QEMU ====<br />
<br />
QEMU can automatically start a SPICE client with an appropriate socket, if the display is set to SPICE with the {{ic|-display spice-app}} parameter. This will use the system's default SPICE client as the viewer, determined by your [[XDG MIME Applications#mimeapps.list|mimeapps.list]] files.<br />
<br />
=== Enabling SPICE support on the guest ===<br />
<br />
For '''Arch Linux guests''', for improved support for multiple monitors or clipboard sharing, the following packages should be installed:<br />
* {{Pkg|spice-vdagent}}: Spice agent xorg client that enables copy and paste between client and X-session and more.<br />
* {{Pkg|xf86-video-qxl}}: Xorg X11 qxl video driver<br />
For guests under '''other operating systems''', refer to the ''Guest'' section in [https://www.spice-space.org/download.html spice-space download].<br />
<br />
=== Password authentication with SPICE ===<br />
<br />
If you want to enable password authentication with SPICE you need to remove {{ic|disable-ticketing}} from the {{ic|-spice}} argument and instead add {{ic|1=password=''yourpassword''}}. For example:<br />
<br />
$ qemu-system-x86_64 -vga qxl -spice port=5900,password=''yourpassword'' -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
Your SPICE client should now ask for the password to be able to connect to the SPICE server.<br />
<br />
=== TLS encrypted communication with SPICE ===<br />
<br />
You can also configure TLS encryption for communicating with the SPICE server. First, you need to have a directory which contains the following files (the names must be exactly as indicated):<br />
<br />
* {{ic|ca-cert.pem}}: the CA master certificate.<br />
* {{ic|server-cert.pem}}: the server certificate signed with {{ic|ca-cert.pem}}.<br />
* {{ic|server-key.pem}}: the server private key.<br />
<br />
An example of generation of self-signed certificates with your own generated CA for your server is shown in the [https://www.spice-space.org/spice-user-manual.html#_generating_self_signed_certificates Spice User Manual].<br />
<br />
Afterwards, you can run QEMU with SPICE as explained above but using the following {{ic|-spice}} argument: {{ic|1=-spice tls-port=5901,password=''yourpassword'',x509-dir=''/path/to/pki_certs''}}, where {{ic|''/path/to/pki_certs''}} is the directory path that contains the three needed files shown earlier.<br />
<br />
It is now possible to connect to the server using {{pkg|virt-viewer}}:<br />
<br />
$ remote-viewer spice://''hostname''?tls-port=5901 --spice-ca-file=''/path/to/ca-cert.pem'' --spice-host-subject="C=''XX'',L=''city'',O=''organization'',CN=''hostname''" --spice-secure-channels=all<br />
<br />
Keep in mind that the {{ic|--spice-host-subject}} parameter needs to be set according to your {{ic|server-cert.pem}} subject. You also need to copy {{ic|ca-cert.pem}} to every client to verify the server certificate.<br />
<br />
{{Tip|You can get the subject line of the server certificate in the correct format for {{ic|--spice-host-subject}} (with entries separated by commas) using the following command: {{bc|<nowiki>$ openssl x509 -noout -subject -in server-cert.pem | cut -d' ' -f2- | sed 's/\///' | sed 's/\//,/g'</nowiki>}}<br />
}}<br />
<br />
The equivalent {{Pkg|spice-gtk}} command is:<br />
<br />
$ spicy -h ''hostname'' -s 5901 --spice-ca-file=ca-cert.pem --spice-host-subject="C=''XX'',L=''city'',O=''organization'',CN=''hostname''" --spice-secure-channels=all<br />
<br />
== VNC ==<br />
<br />
One can add the {{ic|-vnc :''X''}} option to have QEMU redirect the VGA display to the VNC session. Substitute {{ic|''X''}} for the number of the display (0 will then listen on 5900, 1 on 5901...).<br />
<br />
$ qemu-system-x86_64 -vnc :0<br />
<br />
An example is also provided in the [[#Starting QEMU virtual machines on boot]] section.<br />
{{Warning|The default VNC server setup does not use any form of authentication. Any user can connect from any host.}}<br />
<br />
=== Basic password authentication ===<br />
<br />
An access password can be setup easily by using the {{ic|password}} option. The password must be indicated in the QEMU monitor and connection is only possible once the password is provided.<br />
<br />
$ qemu-system-x86_64 -vnc :0,password -monitor stdio<br />
<br />
In the QEMU monitor, password is set using the command {{ic|change vnc password}} and then indicating the password.<br />
<br />
The following command line directly runs vnc with a password:<br />
<br />
$ printf "change vnc password\n%s\n" MYPASSWORD | qemu-system-x86_64 -vnc :0,password -monitor stdio<br />
<br />
{{Note|The password is limited to 8 characters and can be guessed through brute force attack. More elaborated protection is strongly recommended for public network.}}<br />
<br />
== Audio ==<br />
<br />
=== Creating an audio backend ===<br />
<br />
The {{ic|-audiodev}} flag sets the audio backend driver on the host and its options. The list of available audio backend drivers and their optional settings is detailed in the {{man|1|qemu}} man page.<br />
<br />
At the bare minimum, one need to choose an audio backend and set an id, for [[PulseAudio]] for example:<br />
<br />
-audiodev pa,id=snd0<br />
<br />
=== Using the audio backend ===<br />
<br />
==== Intel HD Audio ====<br />
<br />
For Intel HD Audio emulation, add both controller and codec devices. To list the available Intel HDA Audio devices:<br />
<br />
$ qemu-system-x86_64 -device help | grep hda<br />
<br />
Add the audio controller:<br />
<br />
-device ich9-intel-hda<br />
<br />
Also add the audio codec and map it to a host audio backend id:<br />
<br />
-device hda-output,audiodev=snd0<br />
<br />
==== Intel 82801AA AC97 ====<br />
<br />
For AC97 emulation just add the audio card device and map it to a host audio backend id<br />
<br />
-device AC97,audiodev=snd0<br />
<br />
{{Note|<br />
* If the audiodev backend is not provided, QEMU looks up for it and adds it automatically, this only works for a single audiodev. For example {{ic|-device intel-hda -device hda-duplex}} will emulate {{ic|intel-hda}} on the guest using the default audiodev backend.<br />
* Video graphic card emulated drivers for the guest machine may also cause a problem with the sound quality. Test one by one to make it work. You can list possible options with {{ic|<nowiki>qemu-system-x86_64 -h | grep vga</nowiki>}}.}}<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [https://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} for passing a disk image, with parameter {{Ic|1=if=virtio}}:<br />
$ qemu-system-x86_64 -drive file=''disk_image'',if='''virtio'''<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-x86_64 -nic user,model='''virtio-net-pci'''<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an Arch Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=(virtio virtio_blk virtio_pci virtio_net)}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [https://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
You might also want to install {{Pkg|qemu-guest-agent}} to implement support for QMP commands that will enhance the hypervisor management capabilities. After installing the package you can enable and start the {{ic|qemu-guest-agent.service}}.<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
==== Virtio drivers for Windows ====<br />
<br />
Windows does not come with the virtio drivers. The latest and stable versions of the drivers are regularly built by Fedora, details on downloading the drivers are given on [https://github.com/virtio-win/virtio-win-pkg-scripts/blob/master/README.md virtio-win on GitHub]. In the following sections we will mostly use the stable ISO file provided here: [https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso virtio-win.iso]. Alternatively, use {{AUR|virtio-win}}.<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
The drivers need to be loaded during installation, the procedure is to load the ISO image with the virtio drivers in a cdrom device along with the primary disk device and the Windows ISO install media:<br />
<br />
$ qemu-system-x86_64 ... \<br />
-drive file=''disk_image'',index=0,media=disk,if=virtio \<br />
-drive file=''windows.iso'',index=2,media=cdrom \<br />
-drive file=''virtio-win.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, at some stage, the Windows installer will ask "Where do you want to install Windows?", it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option ''Load Drivers''.<br />
* Uncheck the box for ''Hide drivers that are not compatible with this computer's hardware''.<br />
* Click the browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and confirm.<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change existing Windows VM to use virtio =====<br />
<br />
Modifying an existing Windows guest for booting from virtio disk requires that the virtio driver is loaded by the guest at boot time.<br />
We will therefore need to teach Windows to load the virtio driver at boot time before being able to boot a disk image in virtio mode.<br />
<br />
To achieve that, first create a new disk image that will be attached in virtio mode and trigger the search for the driver:<br />
<br />
$ qemu-img create -f qcow2 ''dummy.qcow2'' 1G<br />
<br />
Run the original Windows guest with the boot disk still in IDE mode, the fake disk in virtio mode and the driver ISO image.<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''disk_image'',if=ide -drive file=''dummy.qcow2'',if=virtio -cdrom virtio-win.iso<br />
<br />
Windows will detect the fake disk and look for a suitable driver. If it fails, go to ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not navigate to the driver folder within the CD-ROM, simply select the CD-ROM drive and Windows will find the appropriate driver automatically (tested for Windows 7 SP1).<br />
<br />
Request Windows to boot in safe mode next time it starts up. This can be done using the ''msconfig.exe'' tool in Windows. In safe mode all the drivers will be loaded at boot time including the new virtio driver. Once Windows knows that the virtio driver is required at boot it will memorize it for future boot.<br />
<br />
Once instructed to boot in safe mode, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''disk_image'',if=virtio<br />
<br />
You should boot in safe mode with virtio driver loaded, you can now return to ''msconfig.exe'' disable safe mode boot and restart Windows.<br />
<br />
{{Note|If you encounter the blue screen of death using the {{ic|1=if=virtio}} parameter, it probably means the virtio disk driver is not installed or not loaded at boot time, reboot in safe mode and check your driver configuration.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-nic}} argument.<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''windows_disk_image'',if=virtio -nic user,model=virtio-net-pci -cdrom virtio-win.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
==== Balloon driver ====<br />
<br />
If you want to track you guest memory state (for example via {{ic|virsh}} command {{ic|dommemstat}}) or change guest's memory size in runtime (you still will not be able to change memory size, but can limit memory usage via inflating balloon driver) you will need to install guest balloon driver.<br />
<br />
For this you will need to go to ''Device Manager'', locate ''PCI standard RAM Controller'' in ''System devices'' (or unrecognized PCI controller from ''Other devices'') and choose ''Update driver''. In opened window you will need to choose ''Browse my computer...'' and select the CD-ROM (and do not forget the ''Include subdirectories'' checkbox). Reboot after installation. This will install the driver and you will be able to inflate the balloon (for example via hmp command {{ic|balloon ''memory_size''}}, which will cause balloon to take as much memory as possible in order to shrink the guest's available memory size to ''memory_size''). However, you still will not be able to track guest memory state. In order to do this you will need to install ''Balloon'' service properly. For that open command line as administrator, go to the CD-ROM, ''Balloon'' directory and deeper, depending on your system and architecture. Once you are in ''amd64'' (''x86'') directory, run {{ic|blnsrv.exe -i}} which will do the installation. After that {{ic|virsh}} command {{ic|dommemstat}} should be outputting all supported values.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|1=<br />
virtio_load="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
# sed -ibak "s/ada/vtbd/g" /etc/fstab<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== QEMU monitor ==<br />
<br />
While QEMU is running, a monitor console is provided in order to provide several ways to interact with the virtual machine running. The QEMU monitor offers interesting capabilities such as obtaining information about the current virtual machine, hotplugging devices, creating snapshots of the current state of the virtual machine, etc. To see the list of all commands, run {{ic|help}} or {{ic|?}} in the QEMU monitor console or review the relevant section of the [https://www.qemu.org/docs/master/system/monitor.html official QEMU documentation].<br />
<br />
=== Accessing the monitor console ===<br />
<br />
==== Graphical view ====<br />
<br />
When using the {{ic|std}} default graphics option, one can access the QEMU monitor by pressing {{ic|Ctrl+Alt+2}} or by clicking ''View > compatmonitor0'' in the QEMU window. To return to the virtual machine graphical view either press {{ic|Ctrl+Alt+1}} or click ''View > VGA''.<br />
<br />
However, the standard method of accessing the monitor is not always convenient and does not work in all graphic outputs QEMU supports.<br />
<br />
==== Telnet ====<br />
<br />
To enable [[telnet]], run QEMU with the {{ic|-monitor telnet:127.0.0.1:''port'',server,nowait}} parameter. When the virtual machine is started you will be able to access the monitor via telnet:<br />
<br />
$ telnet 127.0.0.1 ''port''<br />
<br />
{{Note|If {{ic|127.0.0.1}} is specified as the IP to listen it will be only possible to connect to the monitor from the same host QEMU is running on. If connecting from remote hosts is desired, QEMU must be told to listen {{ic|0.0.0.0}} as follows: {{ic|-monitor telnet:0.0.0.0:''port'',server,nowait}}. Keep in mind that it is recommended to have a [[firewall]] configured in this case or make sure your local network is completely trustworthy since this connection is completely unauthenticated and unencrypted.}}<br />
<br />
==== UNIX socket ====<br />
<br />
Run QEMU with the {{ic|-monitor unix:''socketfile'',server,nowait}} parameter. Then you can connect with either {{pkg|socat}}, {{pkg|nmap}} or {{pkg|openbsd-netcat}}.<br />
<br />
For example, if QEMU is run via:<br />
<br />
$ qemu-system-x86_64 -monitor unix:/tmp/monitor.sock,server,nowait ''[...]''<br />
<br />
It is possible to connect to the monitor with:<br />
<br />
$ socat - UNIX-CONNECT:/tmp/monitor.sock<br />
<br />
Or with:<br />
<br />
$ nc -U /tmp/monitor.sock<br />
<br />
Alternatively with {{pkg|nmap}}:<br />
<br />
$ ncat -U /tmp/monitor.sock<br />
<br />
==== TCP ====<br />
<br />
You can expose the monitor over TCP with the argument {{ic|-monitor tcp:127.0.0.1:''port'',server,nowait}}. Then connect with netcat, either {{pkg|openbsd-netcat}} or {{pkg|gnu-netcat}} by running:<br />
<br />
$ nc 127.0.0.1 ''port''<br />
<br />
{{Note|In order to be able to connect to the tcp socket from other devices other than the same host QEMU is being run on you need to listen to {{ic|0.0.0.0}} like explained in the telnet case. The same security warnings apply in this case as well.}}<br />
<br />
==== Standard I/O ====<br />
<br />
It is possible to access the monitor automatically from the same terminal QEMU is being run by running it with the argument {{ic|-monitor stdio}}.<br />
<br />
=== Sending keyboard presses to the virtual machine using the monitor console ===<br />
<br />
Some combinations of keys may be difficult to perform on virtual machines due to the host intercepting them instead in some configurations (a notable example is the {{ic|Ctrl+Alt+F*}} key combinations, which change the active tty). To avoid this problem, the problematic combination of keys may be sent via the monitor console instead. Switch to the monitor and use the {{ic|sendkey}} command to forward the necessary keypresses to the virtual machine. For example:<br />
<br />
(qemu) sendkey ctrl-alt-f2<br />
<br />
=== Creating and managing snapshots via the monitor console ===<br />
<br />
{{Note|This feature will '''only''' work when the virtual machine disk image is in ''qcow2'' format. It will not work with ''raw'' images.}}<br />
<br />
It is sometimes desirable to save the current state of a virtual machine and having the possibility of reverting the state of the virtual machine to that of a previously saved snapshot at any time. The QEMU monitor console provides the user with the necessary utilities to create snapshots, manage them, and revert the machine state to a saved snapshot.<br />
<br />
* Use {{ic|savevm ''name''}} in order to create a snapshot with the tag ''name''.<br />
* Use {{ic|loadvm ''name''}} to revert the virtual machine to the state of the snapshot ''name''.<br />
* Use {{ic|delvm ''name''}} to delete the snapshot tagged as ''name''.<br />
* Use {{ic|info snapshots}} to see a list of saved snapshots. Snapshots are identified by both an auto-incremented ID number and a text tag (set by the user on snapshot creation).<br />
<br />
=== Running the virtual machine in immutable mode ===<br />
<br />
It is possible to run a virtual machine in a frozen state so that all changes will be discarded when the virtual machine is powered off just by running QEMU with the {{ic|-snapshot}} parameter. When the disk image is written by the guest, changes will be saved in a temporary file in {{ic|/tmp}} and will be discarded when QEMU halts.<br />
<br />
However, if a machine is running in frozen mode it is still possible to save the changes to the disk image if it is afterwards desired by using the monitor console and running the following command:<br />
<br />
(qemu) commit all<br />
<br />
If snapshots are created when running in frozen mode they will be discarded as soon as QEMU is exited unless changes are explicitly commited to disk, as well.<br />
<br />
=== Pause and power options via the monitor console ===<br />
<br />
Some operations of a physical machine can be emulated by QEMU using some monitor commands:<br />
<br />
* {{ic|system_powerdown}} will send an ACPI shutdown request to the virtual machine. This effect is similar to the power button in a physical machine.<br />
* {{ic|system_reset}} will reset the virtual machine similarly to a reset button in a physical machine. This operation can cause data loss and file system corruption since the virtual machine is not cleanly restarted.<br />
* {{ic|stop}} will pause the virtual machine.<br />
* {{ic|cont}} will resume a virtual machine previously paused.<br />
<br />
=== Taking screenshots of the virtual machine ===<br />
<br />
Screenshots of the virtual machine graphic display can be obtained in the PPM format by running the following command in the monitor console:<br />
<br />
(qemu) screendump ''file.ppm''<br />
<br />
== QEMU machine protocol ==<br />
<br />
The QEMU machine protocol (QMP) is a JSON-based protocol which allows applications to control a QEMU instance. Similarly to the [[#QEMU monitor]] it offers ways to interact with a running machine and the JSON protocol allows to do it programmatically. The description of all the QMP commands can be found in [https://raw.githubusercontent.com/coreos/qemu/master/qmp-commands.hx qmp-commands].<br />
<br />
=== Start QMP ===<br />
<br />
The usual way to control the guest using the QMP protocol, is to open a TCP socket when launching the machine using the {{ic|-qmp}} option. Here it is using for example the TCP port 4444:<br />
<br />
$ qemu-system-x86_64 ''[...]'' -qmp tcp:localhost:4444,server,nowait<br />
<br />
Then one way to communicate with the QMP agent is to use [[netcat]]:<br />
<br />
{{hc|nc localhost 4444|{"QMP": {"version": {"qemu": {"micro": 0, "minor": 1, "major": 3}, "package": ""}, "capabilities": []} } }}<br />
<br />
At this stage, the only command that can be recognized is {{ic|qmp_capabilities}}, so that QMP enters into command mode. Type:<br />
<br />
{"execute": "qmp_capabilities"}<br />
<br />
Now, QMP is ready to receive commands, to retrieve the list of recognized commands, use:<br />
<br />
{"execute": "query-commands"}<br />
<br />
=== Live merging of child image into parent image ===<br />
<br />
It is possible to merge a running snapshot into its parent by issuing a {{ic|block-commit}} command. In its simplest form the following line will commit the child into its parent:<br />
<br />
{"execute": "block-commit", "arguments": {"device": "''devicename''"}}<br />
<br />
Upon reception of this command, the handler looks for the base image and converts it from read only to read write mode and then runs the commit job.<br />
<br />
Once the ''block-commit'' operation has completed, the event {{ic|BLOCK_JOB_READY}} will be emitted, signalling that the synchronization has finished. The job can then be gracefully completed by issuing the command {{ic|block-job-complete}}:<br />
<br />
{"execute": "block-job-complete", "arguments": {"device": "''devicename''"}}<br />
<br />
Until such a command is issued, the ''commit'' operation remains active.<br />
After successful completion, the base image remains in read write mode and becomes the new active layer. On the other hand, the child image becomes invalid and it is the responsibility of the user to clean it up.<br />
<br />
{{Tip|The list of device and their names can be retrieved by executing the command {{ic|query-block}} and parsing the results. The device name is in the {{ic|device}} field, for example {{ic|ide0-hd0}} for the hard disk in this example: {{hc|{"execute": "query-block"}|{"return": [{"io-status": "ok", "device": "'''ide0-hd0'''", "locked": false, "removable": false, "inserted": {"iops_rd": 0, "detect_zeroes": "off", "image": {"backing-image": {"virtual-size": 27074281472, "filename": "parent.qcow2", ... } }} }}<br />
<br />
=== Live creation of a new snapshot ===<br />
<br />
To create a new snapshot out of a running image, run the command:<br />
<br />
{"execute": "blockdev-snapshot-sync", "arguments": {"device": "''devicename''","snapshot-file": "''new_snapshot_name''.qcow2"}}<br />
<br />
This creates an overlay file named {{ic|''new_snapshot_name''.qcow2}} which then becomes the new active layer.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Improve virtual machine performance ===<br />
<br />
There are a number of techniques that you can use to improve the performance of the virtual machine. For example:<br />
<br />
* Apply [[#Enabling KVM]] for full virtualization.<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU rather than a more generic CPU.<br />
* Especially for Windows guests, enable [https://blog.wikichoon.com/2014/07/enabling-hyper-v-enlightenments-with-kvm.html Hyper-V enlightenments]: {{ic|1=-cpu host,hv_relaxed,hv_spinlocks=0x1fff,hv_vapic,hv_time}}.<br />
* If the host machine has multiple cores, assign the guest more cores using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* If supported by drivers in the guest operating system, use virtio for network and/or block devices, see [[#Installing virtio drivers]].<br />
* Use TAP devices instead of user-mode networking, see [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, you may want to disable the cache:{{bc|1=$ qemu-system-x86_64 -drive file=''disk_image'',if=virtio,'''cache=none'''}}<br />
* Use the native Linux AIO: {{bc|1=$ qemu-system-x86_64 -drive file=''disk_image'',if=virtio''',aio=native,cache.direct=on'''}}<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]. See [[#Enabling KSM]].<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU using {{ic|-device virtio-balloon}}.<br />
* It is possible to use a emulation layer for an ICH-9 AHCI controller (although it may be unstable). The AHCI emulation supports [[Wikipedia:Native_Command_Queuing|NCQ]], so multiple read or write requests can be outstanding at the same time: {{bc|1=$ qemu-system-x86_64 -drive id=disk,file=''disk_image'',if=none -device ich9-ahci,id=ahci -device ide-drive,drive=disk,bus=ahci.0}}<br />
<br />
See https://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured with {{ic|virsh autostart}} or through the ''virt-manager'' GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== With systemd service ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|2=<br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/qemu-system-x86_64 -name %i -enable-kvm -m 512 -nographic $args<br />
ExecStop=/usr/bin/bash -c ${haltcmd}<br />
ExecStop=/usr/bin/bash -c 'while nc localhost 7100; do sleep 1; done'<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Note|This service will wait for the console port to be released, which means that the VM has been shutdown, to graciously end.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the variables {{ic|args}} and {{ic|haltcmd}} set. Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|2=<br />
args="-hda /dev/vg0/vm1 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' {{!}} nc localhost 7100" # or netcat/ncat}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|2=<br />
args="-hda /srv/kvm/vm2 -serial telnet:localhost:7001,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="ssh powermanager@vm2 sudo poweroff"}}<br />
<br />
The description of the variables is the following:<br />
<br />
* {{ic|args}} - QEMU command line arguments to be used.<br />
* {{ic|haltcmd}} - Command to shut down a VM safely. In the first example, the QEMU monitor is exposed via telnet using {{ic|-monitor telnet:..}} and the VMs are powered off via ACPI by sending {{ic|system_powerdown}} to monitor with the {{ic|nc}} command. In the other example, SSH is used.<br />
<br />
To set which virtual machines will start on boot-up, [[enable]] the {{ic|qemu@''vm_name''.service}} systemd unit.<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the options {{ic|-usb -device usb-tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-x86_64 -hda ''disk_image'' -m 512 -usb -device usb-tablet<br />
<br />
If that does not work, try using {{ic|-vga qxl}} parameter, also look at the instructions [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
It is possible to access the physical device connected to a USB port of the host from the guest. The first step is to identify where the device is connected, this can be found running the {{ic|lsusb}} command. For example:<br />
<br />
{{hc|$ lsusb|<br />
...<br />
Bus '''003''' Device '''007''': ID '''0781''':'''5406''' SanDisk Corp. Cruzer Micro U3<br />
}}<br />
<br />
The outputs in bold above will be useful to identify respectively the ''host_bus'' and ''host_addr'' or the ''vendor_id'' and ''product_id''.<br />
<br />
In qemu, the idea is to emulate an EHCI (USB 2) or XHCI (USB 1.1 USB 2 USB 3) controller with the option {{ic|1=-device usb-ehci,id=ehci}} or {{ic|1=-device qemu-xhci,id=xhci}} respectively and then attach the physical device to it with the option {{ic|1=-device usb-host,..}}. We will consider that ''controller_id'' is either {{ic|ehci}} or {{ic|xhci}} for the rest of this section.<br />
<br />
Then, there are two ways to connect to the USB of the host with qemu:<br />
<br />
# Identify the device and connect to it on any bus and address it is attached to on the host, the generic syntax is: {{bc|1=-device usb-host,bus=''controller_id''.0,vendorid=0x''vendor_id'',productid=0x''product_id''}}Applied to the device used in the example above, it becomes:{{bc|1=-device usb-ehci,id=ehci -device usb-host,bus=ehci.0,vendorid=0x'''0781''',productid=0x'''5406'''}}One can also add the {{ic|1=...,port=''port_number''}} setting to the previous option to specify in which physical port of the virtual controller the device should be attached, useful in the case one wants to add multiple usb devices to the VM. Another option is to use the new {{ic|hostdevice}} property of {{ic|usb-host}} which is available since QEMU 5.1.0, the syntax is: {{bc|1=-device qemu-xhci,id=xhci -device usb-host,hostdevice=/dev/bus/usb/003/007}}<br />
# Attach whatever is connected to a given USB bus and address, the syntax is:{{bc|1=-device usb-host,bus=''controller_id''.0,hostbus=''host_bus'',host_addr=''host_addr''}}Applied to the bus and the address in the example above, it becomes:{{bc|1=-device usb-ehci,id=ehci -device usb-host,bus=ehci.0,hostbus='''3''',hostaddr='''7'''}}<br />
See [https://www.qemu.org/docs/master/system/devices/usb.html QEMU/USB emulation] for more information.<br />
{{Note|If you encounter permission errors when running QEMU, see [[udev#About udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== USB redirection with SPICE ===<br />
<br />
When using [[#SPICE]] it is possible to redirect USB devices from the client to the virtual machine without needing to specify them in the QEMU command. It is possible to configure the number of USB slots available for redirected devices (the number of slots will determine the maximum number of devices which can be redirected simultaneously). The main advantages of using SPICE for redirection compared to the previously-mentioned {{ic|-usbdevice}} method is the possibility of hot-swapping USB devices after the virtual machine has started, without needing to halt it in order to remove USB devices from the redirection or adding new ones. This method of USB redirection also allows us to redirect USB devices over the network, from the client to the server. In summary, it is the most flexible method of using USB devices in a QEMU virtual machine.<br />
<br />
We need to add one EHCI/UHCI controller per available USB redirection slot desired as well as one SPICE redirection channel per slot. For example, adding the following arguments to the QEMU command you use for starting the virtual machine in SPICE mode will start the virtual machine with three available USB slots for redirection:<br />
<br />
{{bc|1=<br />
-device ich9-usb-ehci1,id=usb \<br />
-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \<br />
-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \<br />
-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev1 -device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev2 -device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev3 -device usb-redir,chardev=usbredirchardev3,id=usbredirdev3<br />
}}<br />
<br />
See [https://www.spice-space.org/usbredir.html SPICE/usbredir] for more information.<br />
<br />
Both {{ic|spicy}} from {{Pkg|spice-gtk}} (''Input > Select USB Devices for redirection'') and {{ic|remote-viewer}} from {{pkg|virt-viewer}} (''File > USB device selection'') support this feature. Please make sure that you have installed the necessary SPICE Guest Tools on the virtual machine for this functionality to work as expected (see the [[#SPICE]] section for more information).<br />
<br />
{{Warning|Keep in mind that when a USB device is redirected from the client, it will not be usable from the client operating system itself until the redirection is stopped. It is specially important to never redirect the input devices (namely mouse and keyboard), since it will be then difficult to access the SPICE client menus to revert the situation, because the client will not respond to the input devices after being redirected to the virtual machine.}}<br />
<br />
==== Automatic USB forwarding with udev ====<br />
<br />
Normally, forwarded devices must be available at VM boot time to be forwarded. If that device is disconnected, it will not be forwarded anymore.<br />
<br />
You can use [[udev rule]]s to automatically attach a device when it comes online. Create a {{ic|hostdev}} entry somewhere on disk. [[chown]] it to root to prevent other users modifying it.<br />
<br />
{{hc|/usr/local/hostdev-mydevice.xml|2=<br />
<hostdev mode='subsystem' type='usb'><br />
<source><br />
<vendor id='0x03f0'/><br />
<product id='0x4217'/><br />
</source><br />
</hostdev><br />
}}<br />
<br />
Then create a ''udev'' rule which will attach/detach the device:<br />
<br />
{{hc|/usr/lib/udev/rules.d/90-libvirt-mydevice|2=<br />
ACTION=="add", \<br />
SUBSYSTEM=="usb", \<br />
ENV{ID_VENDOR_ID}=="03f0", \<br />
ENV{ID_MODEL_ID}=="4217", \<br />
RUN+="/usr/bin/virsh attach-device GUESTNAME /usr/local/hostdev-mydevice.xml"<br />
ACTION=="remove", \<br />
SUBSYSTEM=="usb", \<br />
ENV{ID_VENDOR_ID}=="03f0", \<br />
ENV{ID_MODEL_ID}=="4217", \<br />
RUN+="/usr/bin/virsh detach-device GUESTNAME /usr/local/hostdev-mydevice.xml"<br />
}}<br />
<br />
[https://rolandtapken.de/blog/2011-04/how-auto-hotplug-usb-devices-libvirt-vms-update-1 Source and further reading].<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
{{Note|Although KSM may reduce memory usage, it may increase CPU usage. Also note some security issues may occur, see [[Wikipedia:Kernel same-page merging]].}}<br />
<br />
To enable KSM:<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, use [[systemd#systemd-tmpfiles - temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://docs.kernel.org/admin-guide/mm/ksm.html for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory:<br />
<br />
$ grep -r . /sys/kernel/mm/ksm/<br />
<br />
}}<br />
<br />
=== Multi-monitor support ===<br />
<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Custom display resolution ===<br />
<br />
A custom display resolution can be set with {{ic|1=-device VGA,edid=on,xres=1280,yres=720}} (see [[wikipedia:Extended_Display_Identification_Data|EDID]] and [[wikipedia:Display_resolution|display resolution]]).<br />
<br />
=== Copy and paste ===<br />
<br />
One way to share the clipboard between the host and the guest is to enable the SPICE remote desktop protocol and access the client with a SPICE client.<br />
One needs to follow the steps described in [[#SPICE]]. A guest run this way will support copy paste with the host.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 11.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Fast startup ====<br />
<br />
{{Note|An administrator account is required to change power settings.}}<br />
<br />
For Windows 8 (or later) guests it is better to disable "Turn on fast startup (recommended)" from the Power Options of the Control Panel as explained in the following [https://www.tenforums.com/tutorials/4189-turn-off-fast-startup-windows-10-a.html forum page], as it causes the guest to hang during every other boot.<br />
<br />
Fast Startup may also need to be disabled for changes to the {{ic|-smp}} option to be properly applied.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-x86_64 -nographic -nic user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either {{Pkg|rdesktop}} or {{Pkg|freerdp}} to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
=== Clone Linux system installed on physical equipment ===<br />
<br />
Linux system installed on physical equipment can be cloned for running on QEMU vm. See [https://coffeebirthday.wordpress.com/2018/09/14/clone-linux-system-for-qemu-virtual-machine/ Clone Linux system from hardware for QEMU virtual machine]<br />
<br />
=== Chrooting into arm/arm64 environment from x86_64 ===<br />
<br />
Sometimes it is easier to work directly on a disk image instead of the real ARM based device. This can be achieved by mounting an SD card/storage containing the ''root'' partition and chrooting into it.<br />
<br />
Another use case for an ARM chroot is building ARM packages on an x86_64 machine - {{AUR|armutils-git}} can be used for that. Here, the chroot environment can be created from an image tarball from [https://archlinuxarm.org Arch Linux ARM] - see [https://nerdstuff.org/posts/2020/2020-003_simplest_way_to_create_an_arm_chroot/] for a detailed description of this approach.<br />
<br />
Either way, from the chroot it should be possible to run ''pacman'' and install more packages, compile large libraries etc. Since the executables are for the ARM architecture, the translation to x86 needs to be performed by [[QEMU]].<br />
<br />
Install {{AUR|binfmt-qemu-static}} and {{AUR|qemu-user-static}} from the [[AUR]] on the x86_64 machine/host. ''binfmt-qemu-static'' will take care of registering the qemu binaries to binfmt service.<br />
<br />
[[Restart]] {{ic|systemd-binfmt.service}}<br />
<br />
{{AUR|qemu-user-static}} is needed to allow the execution of compiled programs from other architectures. This is similar to what is provided by {{Pkg|qemu-emulators-full}}, but the "static" variant is required for chroot. Examples:<br />
<br />
qemu-arm-static path_to_sdcard/usr/bin/ls<br />
qemu-aarch64-static path_to_sdcard/usr/bin/ls<br />
<br />
These two lines execute the {{ic|ls}} command compiled for 32-bit ARM and 64-bit ARM respectively. Note that this will not work without chrooting, because it will look for libraries not present in the host system.<br />
<br />
{{AUR|qemu-user-static}} allows automatically prefixing the ARM exectuable with {{ic|qemu-arm-static}} or {{ic|qemu-aarch64-static}}.<br />
<br />
Make sure that the ARM executable support is active:<br />
<br />
{{hc|$ ls /proc/sys/fs/binfmt_misc|<br />
qemu-aarch64 qemu-arm qemu-cris qemu-microblaze qemu-mipsel qemu-ppc64 qemu-riscv64 qemu-sh4 qemu-sparc qemu-sparc64 status<br />
qemu-alpha qemu-armeb qemu-m68k qemu-mips qemu-ppc qemu-ppc64abi32 qemu-s390x qemu-sh4eb qemu-sparc32plus register<br />
}}<br />
<br />
Each executable must be listed.<br />
<br />
If it is not active, [[reinstall]] {{AUR|binfmt-qemu-static}} and [[restart]] {{ic|systemd-binfmt.service}}.<br />
<br />
Mount the SD card to {{ic|/mnt/sdcard}} (the device name may be different).<br />
<br />
# mkdir -p /mnt/sdcard<br />
# mount /dev/mmcblk0p2 /mnt/sdcard<br />
<br />
Mount boot partition if needed (again, use the suitable device name):<br />
<br />
# mount /dev/mmcblk0p1 /mnt/sdcard/boot<br />
<br />
Finally ''chroot'' into the SD card root as described in [[Change root#Using chroot]]:<br />
<br />
# chroot /mnt/sdcard /bin/bash<br />
<br />
Alternatively, you can use ''arch-chroot'' from {{Pkg|arch-install-scripts}}, as it will provide an easier way to get network support:<br />
<br />
# arch-chroot /mnt/sdcard /bin/bash<br />
<br />
You can also use [[systemd-nspawn]] to chroot into the ARM environment:<br />
<br />
# systemd-nspawn -D /mnt/sdcard -M myARMMachine --bind-ro=/etc/resolv.conf<br />
<br />
{{ic|1=--bind-ro=/etc/resolv.conf}} is optional and gives a working network DNS inside the chroot<br />
<br />
=== Not grabbing mouse input ===<br />
<br />
{{Style|It is not explained what the option actually does. Is it causing or avoiding the side effect?}}<br />
<br />
Tablet mode has side effect of not grabbing mouse input in QEMU window:<br />
<br />
-usb -device usb-tablet<br />
<br />
It works with several {{ic|-vga}} backends one of which is virtio.<br />
<br />
== Troubleshooting ==<br />
<br />
{{Merge|QEMU/Troubleshooting|This section is long enough to be split into a dedicated subpage.}}<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|1=-display default,show-cursor=on}} to QEMU's options to see a mouse cursor.<br />
<br />
If that still does not work, make sure you have set your display device appropriately, for example: {{ic|-vga qxl}}.<br />
<br />
Another option to try is {{ic|-usb -device usb-tablet}} as mentioned in [[#Mouse integration]]. This overrides the default PS/2 mouse emulation and synchronizes pointer location between host and guest as an added bonus.<br />
<br />
=== Two different mouse cursors are visible ===<br />
<br />
Apply the tip [[#Mouse integration]].<br />
<br />
=== Keyboard issues when using VNC ===<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [https://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps/}}.<br />
<br />
$ qemu-system-x86_64 -k ''keymap'' ''disk_image''<br />
<br />
=== Could not read keymap file ===<br />
<br />
qemu-system-x86_64: -display vnc=0.0.0.0:0: could not read keymap file: 'en'<br />
<br />
is caused by an invalid ''keymap'' passed to the {{ic|-k}} argument. For example, {{ic|en}} is invalid, but {{ic|en-us}} is valid - see {{ic|/usr/share/qemu/keymaps/}}.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
[[Install]] {{pkg|glusterfs}} or ignore the error message as GlusterFS is a optional dependency.<br />
<br />
=== Kernel panic on LIVE-environments ===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. cannot unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
=== Windows 7 guest suffers low-quality sound ===<br />
<br />
Using the {{ic|hda}} audio driver for Windows 7 guest may result in low-quality sound. Changing the audio driver to {{ic|ac97}} by passing the {{ic|-soundhw ac97}} arguments to QEMU and installing the AC97 driver from [https://www.realtek.com/en/component/zoo/category/pc-audio-codecs-ac-97-audio-codecs-software Realtek AC'97 Audio Codecs] in the guest may solve the problem. See [https://bugzilla.redhat.com/show_bug.cgi?id=1176761#c16 Red Hat Bugzilla – Bug 1176761] for more information.<br />
<br />
=== Could not access KVM kernel module: Permission denied ===<br />
<br />
If you encounter the following error:<br />
<br />
libvirtError: internal error: process exited while connecting to monitor: Could not access KVM kernel module: Permission denied failed to initialize KVM: Permission denied<br />
<br />
Systemd 234 assigns a dynamic ID for the {{ic|kvm}} group (see {{Bug|54943}}). To avoid this error, you need edit the file {{ic|/etc/libvirt/qemu.conf}} and change the line with {{ic|1=group = "78"}} to {{ic|1=group = "kvm"}}.<br />
<br />
=== "System Thread Exception Not Handled" when booting a Windows VM ===<br />
<br />
Windows 8 or Windows 10 guests may raise a generic compatibility exception at boot, namely "System Thread Exception Not Handled", which tends to be caused by legacy drivers acting strangely on real machines. On KVM machines this issue can generally be solved by setting the CPU model to {{ic|core2duo}}.<br />
<br />
=== Certain Windows games/applications crashing/causing a bluescreen ===<br />
<br />
Occasionally, applications running in the VM may crash unexpectedly, whereas they would run normally on a physical machine. If, while running {{ic|dmesg -wH}} as root, you encounter an error mentioning {{ic|MSR}}, the reason for those crashes is that KVM injects a [[wikipedia:General protection fault|General protection fault]] (GPF) when the guest tries to access unsupported [[wikipedia:Model-specific register|Model-specific registers]] (MSRs) - this often results in guest applications/OS crashing. A number of those issues can be solved by passing the {{ic|1=ignore_msrs=1}} option to the KVM module, which will ignore unimplemented MSRs.<br />
<br />
{{hc|/etc/modprobe.d/kvm.conf|2=<br />
...<br />
options kvm ignore_msrs=1<br />
...<br />
}}<br />
<br />
Cases where adding this option might help:<br />
<br />
* GeForce Experience complaining about an unsupported CPU being present.<br />
* StarCraft 2 and L.A. Noire reliably blue-screening Windows 10 with {{ic|KMODE_EXCEPTION_NOT_HANDLED}}. The blue screen information does not identify a driver file in these cases.<br />
<br />
{{Warning|While this is normally safe and some applications might not work without this, silently ignoring unknown MSR accesses could potentially break other software within the VM or other VMs.}}<br />
<br />
=== Applications in the VM experience long delays or take a long time to start ===<br />
<br />
This may be caused by insufficient available entropy in the VM. Consider allowing the guest to access the hosts's entropy pool by adding a [https://wiki.qemu.org/Features/VirtIORNG VirtIO RNG device] to the VM, or by installing an entropy generating daemon such as [[Haveged]].<br />
<br />
Anecdotally, OpenSSH takes a while to start accepting connections under insufficient entropy, without the logs revealing why.<br />
<br />
=== High interrupt latency and microstuttering ===<br />
<br />
This problem manifests itself as small pauses (stutters) and is particularly noticeable in graphics-intensive applications, such as games.<br />
<br />
* One of the causes is CPU power saving features, which are controlled by [[CPU frequency scaling]]. Change this to {{ic|performance}} for all processor cores. <br />
* Another possible cause is PS/2 inputs. Switch from PS/2 to Virtio inputs, see [[PCI passthrough via OVMF#Passing keyboard/mouse via Evdev]].<br />
<br />
=== QXL video causes low resolution ===<br />
<br />
QEMU 4.1.0 introduced a regression where QXL video can fall back to low resolutions, when being displayed through spice. [https://bugs.launchpad.net/qemu/+bug/1843151] For example, when KMS starts, text resolution may become as low as 4x10 characters. When trying to increase GUI resolution, it may go to the lowest supported resolution.<br />
<br />
As a workaround, create your device in this form:<br />
<br />
-device qxl-vga,max_outputs=1...<br />
<br />
=== VM does not boot when using a Secure Boot enabled OVMF ===<br />
<br />
{{ic|/usr/share/edk2-ovmf/x64/OVMF_CODE.secboot.fd}} from {{Pkg|edk2-ovmf}} is built with [[Wikipedia:System Management Mode|SMM]] support. If S3 support is not disabled in the VM, then the VM might not boot at all.<br />
<br />
Add the {{ic|1=-global ICH9-LPC.disable_s3=1}} option to the ''qemu'' command.<br />
<br />
See {{Bug|59465}} and https://github.com/tianocore/edk2/blob/master/OvmfPkg/README for more details and the required options to use Secure Boot in QEMU.<br />
<br />
=== VM does not boot into Arch ISO ===<br />
<br />
When trying to boot VM for the first time from Arch ISO image the boot process hangs. Adding {{ic|1=console=ttyS0}} to kernel boot options by pressing {{ic|e}} in the boot menu you will get more boot messages and the following error:<br />
<br />
:: Mounting '/dev/disk/by-label/ARCH_202204' to '/run/archiso/bootmnt'<br />
Waiting 30 seconds for device /dev/disk/by-label/ARCH_202204 ...<br />
ERROR: '/dev/disk/by-label/ARCH_202204' device did not show up after 30 seconds...<br />
Falling back to interactive prompt<br />
You can try to fix the problem manually, log out when you are finished<br />
sh: can't access tty; job control turned off<br />
<br />
The error message does not give a good clue as to what the real issue is. The problem is with the default 128MB of RAM that QEMU allocates to the VM. Increasing the limit to 1024MB with {{ic|-m 1024}} solves the issue and lets system boot. You can continue installing Arch Linux as per usual after that. Once installation is complete the memory allocation for the VM can be decreased. The need for 1024MB is due to RAM disk requirements and size of installation media. See [https://lists.archlinux.org/archives/list/arch-releng@lists.archlinux.org/message/D5HSGOFTPGYI6IZUEB3ZNAX4D3F3ID37/ this message on the arch-releng mailing list] and [https://bbs.archlinux.org/viewtopic.php?id=204023 this forum thread].<br />
<br />
=== Guest CPU interrupts are not firing ===<br />
<br />
If you are writing your own operating system by following the [https://wiki.osdev.org/ OSDev wiki], or are simply getting stepping through the guest architecture assembly code using QEMU's {{ic|gdb}} interface using the {{ic|-s}} flag, it is useful to know that many emulators, QEMU included, usually implement some CPU interrupts leaving many hardware interrupts unimplemented. One way to know if your code if firing an interrupt, is by using:<br />
<br />
-d int<br />
<br />
to enable showing interrupts/exceptions on stdout.<br />
<br />
To see what other guest debugging features QEMU has to offer, see:<br />
<br />
qemu-system-x86_64 -d help<br />
<br />
or replace {{ic|x86_64}} for your chosen guest architecture.<br />
<br />
== See also ==<br />
<br />
* [https://qemu.org Official QEMU website]<br />
* [https://www.linux-kvm.org Official KVM website]<br />
* [https://qemu.weilnetz.de/doc/6.0/ QEMU Emulator User Documentation]<br />
* [[Wikibooks:QEMU|QEMU Wikibook]]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [https://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [https://qemu.weilnetz.de/ QEMU on Windows]<br />
* [[wikipedia:Qemu|Wikipedia]]<br />
* [[debian:QEMU|Debian Wiki - QEMU]]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]<br />
* [https://wiki.mikejung.biz/KVM_/_Xen KVM/QEMU Virtio Tuning and SSD VM Optimization Guide]<br />
* [https://doc.opensuse.org/documentation/leap/virtualization/html/book-virt/part-virt-qemu.html Managing Virtual Machines with QEMU - openSUSE documentation]<br />
* [https://www.ibm.com/support/knowledgecenter/en/linuxonibm/liaat/liaatkvm.htm KVM on IBM Knowledge Center]</div>PXfhttps://wiki.archlinux.org/index.php?title=User_talk:Erus_Iluvatar&diff=731393User talk:Erus Iluvatar2022-06-03T02:45:16Z<p>PXf: /* Topic inappropriate? */ new section</p>
<hr />
<div>== Thank you ==<br />
<br />
Thank you for your recent edit on [[Pipewire]]. I am new to ArchWiki and missed the correct formatting. Thanks for fixing it. Cheers! [[User:Darksaber|Darksaber]] ([[User talk:Darksaber|talk]])<br />
<br />
: Don't worry, everyone has to start somewhere ;). If you want to read before future contributions, look at [[ArchWiki:Contributing#Resources]]. --[[User:Erus Iluvatar|Erus Iluvatar]] ([[User talk:Erus Iluvatar|talk]]) 13:23, 11 March 2022 (UTC)<br />
<br />
== Minor edit mark ==<br />
<br />
Thank you for your contributions to the wiki. Please mark your edits as [[Wikipedia:Wikipedia:Minor edit|minor]] when necessary, so readers can filter them with "non-minor edits" filter. Thank you. -- [[User:Thmeiov|Thmeiov]] ([[User talk:Thmeiov|talk]]) 12:17, 14 March 2022 (UTC)<br />
<br />
: You're right, I should be more careful on this. Thank you for reminding me ! --[[User:Erus Iluvatar|Erus Iluvatar]] ([[User talk:Erus Iluvatar|talk]]) 12:30, 14 March 2022 (UTC)<br />
<br />
== Thanks for the edits on the Virt-Manager page ==<br />
Thanks for the recent edits you made im pretty new to ArchWiki/MediaWiki and suck formatting so thanks for fixing my bad formating <br />
[[User:ShinobuNarusaka|ShinobuNarusaka]] ([[User talk:ShinobuNarusaka|talk]])<br />
<br />
: Hi ! Thank you for contributing a new page on a subject you're comfortable with. Don't worry, practice makes perfect. To double check your content before future contributions, look at [[ArchWiki:Contributing#Resources]]. --[[User:Erus Iluvatar|Erus Iluvatar]] ([[User talk:Erus Iluvatar|talk]]) 05:56, 27 March 2022 (UTC)<br />
<br />
== $include Readline question ==<br />
Hi, thanks for your work. I've seen that you have added a space in [[Readline#History]]. `man bash` (and some blogs) have no space in "$include /etc/inputrc". Do you have any reference? --[[User:Marzal|Marzal]] ([[User talk:Marzal|talk]]) 22:19, 14 April 2022 (UTC)<br />
<br />
: Hi, thanks for pointing out my mistake: I had read the section too quickly and concluded this line was missing a space between the prompt and the command, but this is not the case. I've reverted my edit, sorry for the confusion. --[[User:Erus Iluvatar|Erus Iluvatar]] ([[User talk:Erus Iluvatar|talk]]) 03:43, 15 April 2022 (UTC)<br />
<br />
== Related links redundancy ==<br />
<br />
Hi, regarding [https://wiki.archlinux.org/index.php?title=MacBookPro11,x&diff=730381&oldid=730380], I have nothing against it specifically, in fact I support it, however in general justifying removing related links only because they exist somewhere else in the content may create a precedent that would affect a vast number of other articles. I don't recall specific style rules that explicitly forbid multiple links to the same article, although of course indeed there is such a thing as too many of them. In particular, personally I think that Related boxes should be allowed to highlight related articles regardless of whether they are already linked in the content.<br />
<br />
I'm not sure if I can follow long discussions, however I'm just dropping this note here in case you have some ideas on how to clarify this issue in our style guides:<br />
<br />
* [[Help:Style#Related articles box]]<br />
* [[Help:Style#Hypertext metaphor]]<br />
* [[Help:Style/Formatting and punctuation#First instances]]<br />
* [[Help:Editing#Links]]<br />
<br />
A very old related discussion: [[Help talk:Style#Related links]]<br />
<br />
I'm also ok to leave this unregulated, I thought I'd just point out that there's nothing currently that disallows repeated internal links.<br />
<br />
Feel free to move this discussion to [[Help talk:Style]] if you're interested in expanding on it :)<br />
<br />
Cheers! -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 18:34, 23 May 2022 (UTC)<br />
<br />
: Woaw, thanks for the detailed response, I have already opened the discussion in [[Help talk:Laptop page guidelines#Related articles]] since I had not seen it was ongoing in [[Help talk:Laptop page guidelines#Using a "See also" section exclusively instead of a related articles box]]. My edit on [[MacBookPro11,x]] was in that vein: specifically on laptop pages, I have not found the [[Template:Related]] use in ways where it added to the page without being cumbersome. --[[User:Erus Iluvatar|Erus Iluvatar]] ([[User talk:Erus Iluvatar|talk]]) 19:04, 23 May 2022 (UTC)<br />
<br />
::And thank you for linking the discussions that I missed, I've added my response to [[Help talk:Laptop page guidelines#Related articles]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 06:28, 24 May 2022 (UTC)<br />
<br />
== Topic inappropriate? ==<br />
<br />
https://wiki.archlinux.org/index.php?title=Talk:Archiso&diff=next&oldid=730338<br><br />
(A) I should not put it on [[Talk:Archiso]]. It belongs outside the wiki.<br><br />
(B) I should not close it.<br><br />
(C) I should have closed it and removed it myself immediately.<br><br />
(D) I should have closed it. It may or may not be removed.<br><br />
[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 02:45, 3 June 2022 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:Archiso&diff=730338Talk:Archiso2022-05-21T13:07:30Z<p>PXf: sign</p>
<hr />
<div>==Archiso doesn't work on non stock kernel==<br />
<br />
I've been having on and off issues when building ISOs with archiso and the other day when I was working on one I did a pacman -Syu before working but didn't reboot. I was running on the stock kernel at that point because the linux-ck kernel had not updated yet. My ISO built fine. Later that day I rebooted and was now running on the updated linux-ck kernel and suddenly the build process would simply die without any errors, even with the -v option. Right after installing all the custom packages, a dd output appears and then a mkfs.vfat version message appears and that's where it dies. Rebooting back to the stock arch kernel fixed the issue. I'm guessing it has something to do with hardcoded names or something like that in the build scripts.<br />
<br />
Is this normal behaviour? I don't mind using the stock kernel on the ISOs I build but I figured I'd at least be able to build them on a different one.<br />
<br />
On that note, is it possible to use a kernel other than the stock one within the ISOs we build? <br />
[[User:Biltong|Biltong]] ([[User talk:Biltong|talk]]) Sun May 6 2012, 21:47 SAST<br />
<br />
== Estimating size? Starting over? ==<br />
<br />
How do you best estimate the size?<br />
<br />
How do you start over? Suppose just take `etc/`, delete the `releng/` directory recopy, put stuff back. [[User:Jasper1984|Jasper1984]] ([[User talk:Jasper1984|talk]]) 13:46, 1 July 2013 (UTC)<br />
<br />
:Best way to start over is delete releng/{work,out} it keeps cached packages, and there is no need to do every step from the beginning. {{Unsigned|14:08, 5 October 2013|Jqvillanova}}<br />
<br />
== Encryption ==<br />
<br />
<br />
* with «cryptsetup», encrypt the file «airootfs.sfs» built with «mkarchiso» :<br />
<br />
# cd /path/to/buildir/<br />
# cd ./work/iso/arch/x86_64/<br />
# cryptsetup --verify-passphrase plainOpen ./airootfs.sfs encrypt<br />
# dd < ./airootfs.sfs > /dev/mapper/encrypt<br />
# sync<br />
# cryptsetup plainClose encrypt<br />
# md5sum ./airootfs.sfs > ./airootfs.md5<br />
# cd -<br />
<br />
''(note that you can't decrypt the encrypted file «airootfs.sfs» in the same «dd» way, instead use {{ic|1=dd of=./airootfs.sfs conv=nocreat,notrunc < /dev/mapper/encrypt}})''<br />
<br />
* add the hook «encrypt» in «mkinitcpio.conf» :<br />
<br />
# grep HOOKS ./work/airootfs/etc/mkinitcpio.conf<br />
HOOKS="... encrypt"<br />
<br />
<br />
* insert these lines in «archiso» hook :<br />
<br />
--- a/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
+++ b/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
@@ -65,6 +65,10 @@<br />
fi<br />
sfs_dev=$(losetup --find --show --read-only "${img}")<br />
echo ${sfs_dev} >> /run/archiso/used_block_devices<br />
+ msg ":: Mapping encrypted squashfs..."<br />
+ local map="${sfs_dev##*/}.map"<br />
+ cryptsetup plainOpen "${sfs_dev}" "${map}"<br />
+ sfs_dev="/dev/mapper/${map}"<br />
_mnt_dev "${sfs_dev}" "${mnt}" "-r" "defaults"<br />
}<br />
<br />
<br />
* rebuild initramfs and iso with «mkarchiso» and test :<br />
<br />
# mkarchiso -r "mkinitcpio -p linux" run<br />
# mkarchiso iso encrypted.iso<br />
# qemu ... ./out/encrypted.iso<br />
<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 21:51, 20 Feb 2016 (UTC)<br />
<br />
: @Lacsap Can't manage to make it working. I managed to build the iso but it can't find <code>/run/iso_name/bootmnt</code>. I think I have missed the decryption part. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 11:43, 17 October 2021 (UTC)<br />
<br />
== Example configurations ==<br />
<br />
Where should sets of ArchISO customizations go? Should there be an "Examples" header added to the bottom? Like for how to enable remote {{ic|ssh}} login, boot with serial console support for headless systems, etc? Or a separate page? [Archiso offline] is a separate page, but it was marked for possible merging since it's an (out of date) clone of this page. [[User:Jamespharvey20|Jamespharvey20]] ([[User talk:Jamespharvey20|talk]]) 02:38, 25 April 2019 (UTC)<br />
:I guess your changes (adding ssh configs) should be done airootfs directory. But I did not yet explored how to add another systemd services to archiso. Adding info about how to enable ssh login to this page seems useful for me. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 17:42, 25 April 2019 (UTC)<br />
<br />
== ISO does not build with secure boot enabled ==<br />
<br />
It seems that if you have secure boot enabled and have signed the Linux kernel, the ISO will fail to build, saying that /boot/vmlinuz-linux does not exist. However, once you disable secure boot, the ISO starts getting built again. Just tried this, and it appears to go back at least to archiso version 36.<br />
<br />
[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 18:58, 26 May 2020 (UTC)<br />
<br />
:To clarify, I don't really know why it doesn't work. If possible, could someone else test this, to see if it's just a problem on my computer or more widespread. If so, then maybe we should add a warning to the wiki page.<br />
:[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 04:54, 27 May 2020 (UTC)<br />
<br />
::I don't use secure boot myself, so I don't know how it works. Since [https://github.com/archlinux/svntogit-packages/commit/43c5745a17e2ebe413a7140d4ef9326e26d6cb20 5.3.8.1] the {{pkg|linux}} package does not install the kernel to {{ic|/boot/vmlinuz-linux}}, but to {{ic|/usr/lib/modules/VERSION/vmlinuz}} and [https://github.com/archlinux/mkinitcpio/tree/master/libalpm/hooks mkinitcpio's pacman hooks] copy it to {{ic|/boot/}}. If the kernel image is not getting copied somewhere in the ISO's chroot, maybe there is something wrong with the hooks... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:39, 30 May 2020 (UTC)<br />
<br />
== Please add a warning with regards to syncthing interoperability ==<br />
<br />
When mkarchiso is executed to use a working directory (e.g. -w ./tmp) inside a folder that is observed by syncthing, there are 2 issues: mkarchiso will fail and a restart is required in order to be able to delete the working directory. As a simple workaround, the working directory can be added to the syncthing ignore patterns.<br />
<br />
I do not know what causes these errors - especially since mkarchiso does not throw any error message. Deleting the working directory fails due to missing rights although it is run as root. After a restart the working directory can be deleted. [[User:ente|ente]] ([[User talk:ente|talk]]) 11:09, 17 September 2020 (UTC)<br />
<br />
== Add a section to Tips and Tricks to build an ISO for installation entirely over a serial console ==<br />
<br />
I've been looking all over for a good way to do this. I think I have an approach that could work (although it's still to be tried). What do we think about adding this? Has anyone got a recipe? If not, I'm happy to give it a go.<br />
<br />
[[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 11:33, 14 November 2020 (UTC)<br />
<br />
:The solution is to simply add a [[Working with the serial console#Kernel|console=ttyS* kernel parameter]] to boot loader configuration. As for why it's not done by default in releng, see https://gitlab.archlinux.org/archlinux/archiso/-/issues/75. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:28, 14 November 2020 (UTC)<br />
<br />
::I get that, but you need to _get_ to the bootloader menu first, and that currently doesn't happen over the console to my knowledge... [[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 13:55, 14 November 2020 (UTC)<br />
<br />
:::I meant editing the boot loader configuration for the ISO and then building the ISO. As for seeing the boot loader over serial, it should work when booting in BIOS mode (this doesn't prevent installing the system for UEFI booting, you just need to install the boot loader to the default/fallback boot path). -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 05:23, 15 November 2020 (UTC)<br />
<br />
== Permissions and File Additions ==<br />
<br />
Would suggest we document the new changes to permissions requirements as implemented on 11/30/20 in Commit c10004df :<br />
<br />
profiledef.sh needs to have explicit permissions now which is quite different than before.<br />
<br />
file_permissions=(<br />
["/etc/shadow"]="0:0:400"<br />
["/root"]="0:0:750"<br />
["/root/.automated_script.sh"]="0:0:755"<br />
["/usr/local/bin/choose-mirror"]="0:0:755"<br />
["/usr/local/bin/Installation_guide"]="0:0:755"<br />
["/usr/local/bin/livecd-sound"]="0:0:755"<br />
<br />
<br />
Also, the fact that a /skel folder cannot be added to airootfs now is different and requires users to put everything in /etc/skel/<br />
<br />
Users can still add services, but I found the best way to add them was to put them in /usr/local/bin and then add a line to profiledef.sh to give them 755.<br />
<br />
[[User:Jdfthetech|Jdfthetech]] ([[User talk:Jdfthetech|talk]]) 05:34, 2 December 2020 (UTC)<br />
<br />
:Thanks for this update, I've just reached this pitfall attempting to create a non-root user with their own home directory, but failing with {{ic|[mkarchiso] ERROR: Failed to set permissions on 'work/x86_64/airootfs/home/myuser'. Outside of valid path.}} Any thoughts on how to get this working? [[User:Yuvadm|Yuvadm]] ([[User talk:Yuvadm|talk]]) 20:34, 14 December 2020 (UTC)<br />
<br />
::https://gitlab.archlinux.org/archlinux/archiso/-/issues/84. The workaround for now is to explicitly set the work dir with the {{ic|-w}} option. If all goes well, it should be fixed in the next archiso version. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:03, 15 December 2020 (UTC)<br />
<br />
== <s>cp -r drops dead links</s> ==<br />
<br />
Section [[Archiso#Prepare a custom profile|#Prepare a custom profile]] suggests {{ic|cp -r}}.<br><br />
If there is a deadlink in {{ic|/usr/share/archiso/configs/releng}}, it is NOT copied.<br><br />
Why do we prefer {{ic|cp -r}} instead of {{ic|cp -dr}}?<br><br />
[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 15:53, 20 May 2022 (UTC)<br />
<br />
:Works for me™.<br />
{{hc|$ cp -r /usr/share/archiso/configs/releng archlive<br />
$ find archlive -xtype l|<br />
archlive/airootfs/etc/resolv.conf<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-config.service<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-final.service<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-init-local.service<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-init.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/hv_fcopy_daemon.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/hv_kvp_daemon.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/hv_vss_daemon.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/iwd.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/livecd-talk.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/qemu-guest-agent.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/vboxservice.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/vmtoolsd.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/vmware-vmblock-fuse.service<br />
}}<br />
: -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 07:10, 21 May 2022 (UTC)<br />
: Guess I (user) should figure out what links I want for myself instead of relying on one unified solution. {{Unsigned|2022-05-21T12:13:36|PXf}} [[User:PXf|PXf]] ([[User talk:PXf|talk]]) 13:07, 21 May 2022 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:Archiso&diff=730335Talk:Archiso2022-05-21T12:13:36Z<p>PXf: close section "cp -r drops dead links" with comment</p>
<hr />
<div>==Archiso doesn't work on non stock kernel==<br />
<br />
I've been having on and off issues when building ISOs with archiso and the other day when I was working on one I did a pacman -Syu before working but didn't reboot. I was running on the stock kernel at that point because the linux-ck kernel had not updated yet. My ISO built fine. Later that day I rebooted and was now running on the updated linux-ck kernel and suddenly the build process would simply die without any errors, even with the -v option. Right after installing all the custom packages, a dd output appears and then a mkfs.vfat version message appears and that's where it dies. Rebooting back to the stock arch kernel fixed the issue. I'm guessing it has something to do with hardcoded names or something like that in the build scripts.<br />
<br />
Is this normal behaviour? I don't mind using the stock kernel on the ISOs I build but I figured I'd at least be able to build them on a different one.<br />
<br />
On that note, is it possible to use a kernel other than the stock one within the ISOs we build? <br />
[[User:Biltong|Biltong]] ([[User talk:Biltong|talk]]) Sun May 6 2012, 21:47 SAST<br />
<br />
== Estimating size? Starting over? ==<br />
<br />
How do you best estimate the size?<br />
<br />
How do you start over? Suppose just take `etc/`, delete the `releng/` directory recopy, put stuff back. [[User:Jasper1984|Jasper1984]] ([[User talk:Jasper1984|talk]]) 13:46, 1 July 2013 (UTC)<br />
<br />
:Best way to start over is delete releng/{work,out} it keeps cached packages, and there is no need to do every step from the beginning. {{Unsigned|14:08, 5 October 2013|Jqvillanova}}<br />
<br />
== Encryption ==<br />
<br />
<br />
* with «cryptsetup», encrypt the file «airootfs.sfs» built with «mkarchiso» :<br />
<br />
# cd /path/to/buildir/<br />
# cd ./work/iso/arch/x86_64/<br />
# cryptsetup --verify-passphrase plainOpen ./airootfs.sfs encrypt<br />
# dd < ./airootfs.sfs > /dev/mapper/encrypt<br />
# sync<br />
# cryptsetup plainClose encrypt<br />
# md5sum ./airootfs.sfs > ./airootfs.md5<br />
# cd -<br />
<br />
''(note that you can't decrypt the encrypted file «airootfs.sfs» in the same «dd» way, instead use {{ic|1=dd of=./airootfs.sfs conv=nocreat,notrunc < /dev/mapper/encrypt}})''<br />
<br />
* add the hook «encrypt» in «mkinitcpio.conf» :<br />
<br />
# grep HOOKS ./work/airootfs/etc/mkinitcpio.conf<br />
HOOKS="... encrypt"<br />
<br />
<br />
* insert these lines in «archiso» hook :<br />
<br />
--- a/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
+++ b/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
@@ -65,6 +65,10 @@<br />
fi<br />
sfs_dev=$(losetup --find --show --read-only "${img}")<br />
echo ${sfs_dev} >> /run/archiso/used_block_devices<br />
+ msg ":: Mapping encrypted squashfs..."<br />
+ local map="${sfs_dev##*/}.map"<br />
+ cryptsetup plainOpen "${sfs_dev}" "${map}"<br />
+ sfs_dev="/dev/mapper/${map}"<br />
_mnt_dev "${sfs_dev}" "${mnt}" "-r" "defaults"<br />
}<br />
<br />
<br />
* rebuild initramfs and iso with «mkarchiso» and test :<br />
<br />
# mkarchiso -r "mkinitcpio -p linux" run<br />
# mkarchiso iso encrypted.iso<br />
# qemu ... ./out/encrypted.iso<br />
<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 21:51, 20 Feb 2016 (UTC)<br />
<br />
: @Lacsap Can't manage to make it working. I managed to build the iso but it can't find <code>/run/iso_name/bootmnt</code>. I think I have missed the decryption part. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 11:43, 17 October 2021 (UTC)<br />
<br />
== Example configurations ==<br />
<br />
Where should sets of ArchISO customizations go? Should there be an "Examples" header added to the bottom? Like for how to enable remote {{ic|ssh}} login, boot with serial console support for headless systems, etc? Or a separate page? [Archiso offline] is a separate page, but it was marked for possible merging since it's an (out of date) clone of this page. [[User:Jamespharvey20|Jamespharvey20]] ([[User talk:Jamespharvey20|talk]]) 02:38, 25 April 2019 (UTC)<br />
:I guess your changes (adding ssh configs) should be done airootfs directory. But I did not yet explored how to add another systemd services to archiso. Adding info about how to enable ssh login to this page seems useful for me. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 17:42, 25 April 2019 (UTC)<br />
<br />
== ISO does not build with secure boot enabled ==<br />
<br />
It seems that if you have secure boot enabled and have signed the Linux kernel, the ISO will fail to build, saying that /boot/vmlinuz-linux does not exist. However, once you disable secure boot, the ISO starts getting built again. Just tried this, and it appears to go back at least to archiso version 36.<br />
<br />
[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 18:58, 26 May 2020 (UTC)<br />
<br />
:To clarify, I don't really know why it doesn't work. If possible, could someone else test this, to see if it's just a problem on my computer or more widespread. If so, then maybe we should add a warning to the wiki page.<br />
:[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 04:54, 27 May 2020 (UTC)<br />
<br />
::I don't use secure boot myself, so I don't know how it works. Since [https://github.com/archlinux/svntogit-packages/commit/43c5745a17e2ebe413a7140d4ef9326e26d6cb20 5.3.8.1] the {{pkg|linux}} package does not install the kernel to {{ic|/boot/vmlinuz-linux}}, but to {{ic|/usr/lib/modules/VERSION/vmlinuz}} and [https://github.com/archlinux/mkinitcpio/tree/master/libalpm/hooks mkinitcpio's pacman hooks] copy it to {{ic|/boot/}}. If the kernel image is not getting copied somewhere in the ISO's chroot, maybe there is something wrong with the hooks... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:39, 30 May 2020 (UTC)<br />
<br />
== Please add a warning with regards to syncthing interoperability ==<br />
<br />
When mkarchiso is executed to use a working directory (e.g. -w ./tmp) inside a folder that is observed by syncthing, there are 2 issues: mkarchiso will fail and a restart is required in order to be able to delete the working directory. As a simple workaround, the working directory can be added to the syncthing ignore patterns.<br />
<br />
I do not know what causes these errors - especially since mkarchiso does not throw any error message. Deleting the working directory fails due to missing rights although it is run as root. After a restart the working directory can be deleted. [[User:ente|ente]] ([[User talk:ente|talk]]) 11:09, 17 September 2020 (UTC)<br />
<br />
== Add a section to Tips and Tricks to build an ISO for installation entirely over a serial console ==<br />
<br />
I've been looking all over for a good way to do this. I think I have an approach that could work (although it's still to be tried). What do we think about adding this? Has anyone got a recipe? If not, I'm happy to give it a go.<br />
<br />
[[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 11:33, 14 November 2020 (UTC)<br />
<br />
:The solution is to simply add a [[Working with the serial console#Kernel|console=ttyS* kernel parameter]] to boot loader configuration. As for why it's not done by default in releng, see https://gitlab.archlinux.org/archlinux/archiso/-/issues/75. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:28, 14 November 2020 (UTC)<br />
<br />
::I get that, but you need to _get_ to the bootloader menu first, and that currently doesn't happen over the console to my knowledge... [[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 13:55, 14 November 2020 (UTC)<br />
<br />
:::I meant editing the boot loader configuration for the ISO and then building the ISO. As for seeing the boot loader over serial, it should work when booting in BIOS mode (this doesn't prevent installing the system for UEFI booting, you just need to install the boot loader to the default/fallback boot path). -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 05:23, 15 November 2020 (UTC)<br />
<br />
== Permissions and File Additions ==<br />
<br />
Would suggest we document the new changes to permissions requirements as implemented on 11/30/20 in Commit c10004df :<br />
<br />
profiledef.sh needs to have explicit permissions now which is quite different than before.<br />
<br />
file_permissions=(<br />
["/etc/shadow"]="0:0:400"<br />
["/root"]="0:0:750"<br />
["/root/.automated_script.sh"]="0:0:755"<br />
["/usr/local/bin/choose-mirror"]="0:0:755"<br />
["/usr/local/bin/Installation_guide"]="0:0:755"<br />
["/usr/local/bin/livecd-sound"]="0:0:755"<br />
<br />
<br />
Also, the fact that a /skel folder cannot be added to airootfs now is different and requires users to put everything in /etc/skel/<br />
<br />
Users can still add services, but I found the best way to add them was to put them in /usr/local/bin and then add a line to profiledef.sh to give them 755.<br />
<br />
[[User:Jdfthetech|Jdfthetech]] ([[User talk:Jdfthetech|talk]]) 05:34, 2 December 2020 (UTC)<br />
<br />
:Thanks for this update, I've just reached this pitfall attempting to create a non-root user with their own home directory, but failing with {{ic|[mkarchiso] ERROR: Failed to set permissions on 'work/x86_64/airootfs/home/myuser'. Outside of valid path.}} Any thoughts on how to get this working? [[User:Yuvadm|Yuvadm]] ([[User talk:Yuvadm|talk]]) 20:34, 14 December 2020 (UTC)<br />
<br />
::https://gitlab.archlinux.org/archlinux/archiso/-/issues/84. The workaround for now is to explicitly set the work dir with the {{ic|-w}} option. If all goes well, it should be fixed in the next archiso version. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:03, 15 December 2020 (UTC)<br />
<br />
== <s>cp -r drops dead links</s> ==<br />
<br />
Section [[Archiso#Prepare a custom profile|#Prepare a custom profile]] suggests {{ic|cp -r}}.<br><br />
If there is a deadlink in {{ic|/usr/share/archiso/configs/releng}}, it is NOT copied.<br><br />
Why do we prefer {{ic|cp -r}} instead of {{ic|cp -dr}}?<br><br />
[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 15:53, 20 May 2022 (UTC)<br />
<br />
:Works for me™.<br />
{{hc|$ cp -r /usr/share/archiso/configs/releng archlive<br />
$ find archlive -xtype l|<br />
archlive/airootfs/etc/resolv.conf<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-config.service<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-final.service<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-init-local.service<br />
archlive/airootfs/etc/systemd/system/cloud-init.target.wants/cloud-init.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/hv_fcopy_daemon.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/hv_kvp_daemon.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/hv_vss_daemon.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/iwd.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/livecd-talk.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/qemu-guest-agent.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/vboxservice.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/vmtoolsd.service<br />
archlive/airootfs/etc/systemd/system/multi-user.target.wants/vmware-vmblock-fuse.service<br />
}}<br />
: -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 07:10, 21 May 2022 (UTC)<br />
: Guess I (user) should figure out what links I want for myself instead of relying on one unified solution.</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:Archiso&diff=730243Talk:Archiso2022-05-20T15:53:07Z<p>PXf: /* cp -r drops dead links */ new section</p>
<hr />
<div>==Archiso doesn't work on non stock kernel==<br />
<br />
I've been having on and off issues when building ISOs with archiso and the other day when I was working on one I did a pacman -Syu before working but didn't reboot. I was running on the stock kernel at that point because the linux-ck kernel had not updated yet. My ISO built fine. Later that day I rebooted and was now running on the updated linux-ck kernel and suddenly the build process would simply die without any errors, even with the -v option. Right after installing all the custom packages, a dd output appears and then a mkfs.vfat version message appears and that's where it dies. Rebooting back to the stock arch kernel fixed the issue. I'm guessing it has something to do with hardcoded names or something like that in the build scripts.<br />
<br />
Is this normal behaviour? I don't mind using the stock kernel on the ISOs I build but I figured I'd at least be able to build them on a different one.<br />
<br />
On that note, is it possible to use a kernel other than the stock one within the ISOs we build? <br />
[[User:Biltong|Biltong]] ([[User talk:Biltong|talk]]) Sun May 6 2012, 21:47 SAST<br />
<br />
== Estimating size? Starting over? ==<br />
<br />
How do you best estimate the size?<br />
<br />
How do you start over? Suppose just take `etc/`, delete the `releng/` directory recopy, put stuff back. [[User:Jasper1984|Jasper1984]] ([[User talk:Jasper1984|talk]]) 13:46, 1 July 2013 (UTC)<br />
<br />
:Best way to start over is delete releng/{work,out} it keeps cached packages, and there is no need to do every step from the beginning. {{Unsigned|14:08, 5 October 2013|Jqvillanova}}<br />
<br />
== Encryption ==<br />
<br />
<br />
* with «cryptsetup», encrypt the file «airootfs.sfs» built with «mkarchiso» :<br />
<br />
# cd /path/to/buildir/<br />
# cd ./work/iso/arch/x86_64/<br />
# cryptsetup --verify-passphrase plainOpen ./airootfs.sfs encrypt<br />
# dd < ./airootfs.sfs > /dev/mapper/encrypt<br />
# sync<br />
# cryptsetup plainClose encrypt<br />
# md5sum ./airootfs.sfs > ./airootfs.md5<br />
# cd -<br />
<br />
''(note that you can't decrypt the encrypted file «airootfs.sfs» in the same «dd» way, instead use {{ic|1=dd of=./airootfs.sfs conv=nocreat,notrunc < /dev/mapper/encrypt}})''<br />
<br />
* add the hook «encrypt» in «mkinitcpio.conf» :<br />
<br />
# grep HOOKS ./work/airootfs/etc/mkinitcpio.conf<br />
HOOKS="... encrypt"<br />
<br />
<br />
* insert these lines in «archiso» hook :<br />
<br />
--- a/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
+++ b/work/airootfs/usr/lib/initcpio/hooks/archiso<br />
@@ -65,6 +65,10 @@<br />
fi<br />
sfs_dev=$(losetup --find --show --read-only "${img}")<br />
echo ${sfs_dev} >> /run/archiso/used_block_devices<br />
+ msg ":: Mapping encrypted squashfs..."<br />
+ local map="${sfs_dev##*/}.map"<br />
+ cryptsetup plainOpen "${sfs_dev}" "${map}"<br />
+ sfs_dev="/dev/mapper/${map}"<br />
_mnt_dev "${sfs_dev}" "${mnt}" "-r" "defaults"<br />
}<br />
<br />
<br />
* rebuild initramfs and iso with «mkarchiso» and test :<br />
<br />
# mkarchiso -r "mkinitcpio -p linux" run<br />
# mkarchiso iso encrypted.iso<br />
# qemu ... ./out/encrypted.iso<br />
<br />
<br />
[[User:Lacsap|Lacsap]] ([[User talk:Lacsap|talk]]) 21:51, 20 Feb 2016 (UTC)<br />
<br />
: @Lacsap Can't manage to make it working. I managed to build the iso but it can't find <code>/run/iso_name/bootmnt</code>. I think I have missed the decryption part. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 11:43, 17 October 2021 (UTC)<br />
<br />
== Example configurations ==<br />
<br />
Where should sets of ArchISO customizations go? Should there be an "Examples" header added to the bottom? Like for how to enable remote {{ic|ssh}} login, boot with serial console support for headless systems, etc? Or a separate page? [Archiso offline] is a separate page, but it was marked for possible merging since it's an (out of date) clone of this page. [[User:Jamespharvey20|Jamespharvey20]] ([[User talk:Jamespharvey20|talk]]) 02:38, 25 April 2019 (UTC)<br />
:I guess your changes (adding ssh configs) should be done airootfs directory. But I did not yet explored how to add another systemd services to archiso. Adding info about how to enable ssh login to this page seems useful for me. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 17:42, 25 April 2019 (UTC)<br />
<br />
== ISO does not build with secure boot enabled ==<br />
<br />
It seems that if you have secure boot enabled and have signed the Linux kernel, the ISO will fail to build, saying that /boot/vmlinuz-linux does not exist. However, once you disable secure boot, the ISO starts getting built again. Just tried this, and it appears to go back at least to archiso version 36.<br />
<br />
[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 18:58, 26 May 2020 (UTC)<br />
<br />
:To clarify, I don't really know why it doesn't work. If possible, could someone else test this, to see if it's just a problem on my computer or more widespread. If so, then maybe we should add a warning to the wiki page.<br />
:[[User:Sunflsks|Sunflsks]] ([[User talk:Sunflsks|talk]]) 04:54, 27 May 2020 (UTC)<br />
<br />
::I don't use secure boot myself, so I don't know how it works. Since [https://github.com/archlinux/svntogit-packages/commit/43c5745a17e2ebe413a7140d4ef9326e26d6cb20 5.3.8.1] the {{pkg|linux}} package does not install the kernel to {{ic|/boot/vmlinuz-linux}}, but to {{ic|/usr/lib/modules/VERSION/vmlinuz}} and [https://github.com/archlinux/mkinitcpio/tree/master/libalpm/hooks mkinitcpio's pacman hooks] copy it to {{ic|/boot/}}. If the kernel image is not getting copied somewhere in the ISO's chroot, maybe there is something wrong with the hooks... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:39, 30 May 2020 (UTC)<br />
<br />
== Please add a warning with regards to syncthing interoperability ==<br />
<br />
When mkarchiso is executed to use a working directory (e.g. -w ./tmp) inside a folder that is observed by syncthing, there are 2 issues: mkarchiso will fail and a restart is required in order to be able to delete the working directory. As a simple workaround, the working directory can be added to the syncthing ignore patterns.<br />
<br />
I do not know what causes these errors - especially since mkarchiso does not throw any error message. Deleting the working directory fails due to missing rights although it is run as root. After a restart the working directory can be deleted. [[User:ente|ente]] ([[User talk:ente|talk]]) 11:09, 17 September 2020 (UTC)<br />
<br />
== Add a section to Tips and Tricks to build an ISO for installation entirely over a serial console ==<br />
<br />
I've been looking all over for a good way to do this. I think I have an approach that could work (although it's still to be tried). What do we think about adding this? Has anyone got a recipe? If not, I'm happy to give it a go.<br />
<br />
[[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 11:33, 14 November 2020 (UTC)<br />
<br />
:The solution is to simply add a [[Working with the serial console#Kernel|console=ttyS* kernel parameter]] to boot loader configuration. As for why it's not done by default in releng, see https://gitlab.archlinux.org/archlinux/archiso/-/issues/75. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:28, 14 November 2020 (UTC)<br />
<br />
::I get that, but you need to _get_ to the bootloader menu first, and that currently doesn't happen over the console to my knowledge... [[User:Bradwood|Bradwood]] ([[User talk:Bradwood|talk]]) 13:55, 14 November 2020 (UTC)<br />
<br />
:::I meant editing the boot loader configuration for the ISO and then building the ISO. As for seeing the boot loader over serial, it should work when booting in BIOS mode (this doesn't prevent installing the system for UEFI booting, you just need to install the boot loader to the default/fallback boot path). -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 05:23, 15 November 2020 (UTC)<br />
<br />
== Permissions and File Additions ==<br />
<br />
Would suggest we document the new changes to permissions requirements as implemented on 11/30/20 in Commit c10004df :<br />
<br />
profiledef.sh needs to have explicit permissions now which is quite different than before.<br />
<br />
file_permissions=(<br />
["/etc/shadow"]="0:0:400"<br />
["/root"]="0:0:750"<br />
["/root/.automated_script.sh"]="0:0:755"<br />
["/usr/local/bin/choose-mirror"]="0:0:755"<br />
["/usr/local/bin/Installation_guide"]="0:0:755"<br />
["/usr/local/bin/livecd-sound"]="0:0:755"<br />
<br />
<br />
Also, the fact that a /skel folder cannot be added to airootfs now is different and requires users to put everything in /etc/skel/<br />
<br />
Users can still add services, but I found the best way to add them was to put them in /usr/local/bin and then add a line to profiledef.sh to give them 755.<br />
<br />
[[User:Jdfthetech|Jdfthetech]] ([[User talk:Jdfthetech|talk]]) 05:34, 2 December 2020 (UTC)<br />
<br />
:Thanks for this update, I've just reached this pitfall attempting to create a non-root user with their own home directory, but failing with {{ic|[mkarchiso] ERROR: Failed to set permissions on 'work/x86_64/airootfs/home/myuser'. Outside of valid path.}} Any thoughts on how to get this working? [[User:Yuvadm|Yuvadm]] ([[User talk:Yuvadm|talk]]) 20:34, 14 December 2020 (UTC)<br />
<br />
::https://gitlab.archlinux.org/archlinux/archiso/-/issues/84. The workaround for now is to explicitly set the work dir with the {{ic|-w}} option. If all goes well, it should be fixed in the next archiso version. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:03, 15 December 2020 (UTC)<br />
<br />
== cp -r drops dead links ==<br />
<br />
Section [[Archiso#Prepare a custom profile|#Prepare a custom profile]] suggests {{ic|cp -r}}.<br><br />
If there is a deadlink in {{ic|/usr/share/archiso/configs/releng}}, it is NOT copied.<br><br />
Why do we prefer {{ic|cp -r}} instead of {{ic|cp -dr}}?<br><br />
[[User:PXf|PXf]] ([[User talk:PXf|talk]]) 15:53, 20 May 2022 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Talk:Partclone&diff=729955Talk:Partclone2022-05-17T02:48:19Z<p>PXf: /* mount */ mount pcl</p>
<hr />
<div>== mount ==<br />
<br />
What about adding a section on how to mount pcl images? [[User:PXf|PXf]] ([[User talk:PXf|talk]]) 02:48, 17 May 2022 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=GTK&diff=723469GTK2022-03-19T04:52:45Z<p>PXf: /* Configuration */ fix links to gtk3 and gtk4 documentation on Gtk.Settings properties</p>
<hr />
<div>[[Category:Widget toolkits]]<br />
[[es:GTK]]<br />
[[ja:GTK]]<br />
[[pt:GTK]]<br />
[[ru:GTK]]<br />
[[zh-hans:GTK]]<br />
{{Related articles start}}<br />
{{Related|Uniform look for Qt and GTK applications}}<br />
{{Related|Qt}}<br />
{{Related|GNU Project}}<br />
{{Related|GTK/Development}}<br />
{{Related articles end}}<br />
From the [https://www.gtk.org/ GTK website]:<br />
:GTK, or the GIMP Toolkit, is a multi-platform toolkit for creating graphical user interfaces. Offering a complete set of widgets, GTK is suitable for projects ranging from small one-off tools to complete application suites.<br />
<br />
GTK, The GIMP Toolkit, was initially made by the [[GNU Project]] for [[GIMP]], but it is now a very popular toolkit with bindings for many languages. This article will explore the tools used to configure the GTK theme, style, icon, font and font size, and also detail manual configuration.<br />
<br />
== Installation ==<br />
<br />
Three versions of GTK are currently available in the [[official repositories]]. They can be [[install]]ed with the following packages:<br />
* '''GTK 4.x''' is available with the {{Pkg|gtk4}} package.<br />
* '''GTK 3.x''' is available with the {{Pkg|gtk3}} package.<br />
* '''GTK 2.x''' is available with the {{Pkg|gtk2}} package.<br />
<br />
*'''GTK 1.x''' is available with the {{AUR|gtk}} package.<br />
<br />
== Themes ==<br />
<br />
In GTK 3 and GTK 4, the default theme is Adwaita, but HighContrast and HighContrastInverse themes are also included.<br />
In GTK 2, the default theme is Raleigh, but Arch Linux has a custom configuration file at {{ic|/usr/share/gtk-2.0/gtkrc}}, which sets the default theme to Adwaita.<br />
<br />
To force a specific theme, set the following [[environment variables]]:<br />
<br />
* For GTK 3 and GTK 4, use {{ic|GTK_THEME}}. For example to launch GNOME Calculator with the dark variant of Adwaita:<br />
<br />
$ GTK_THEME=Adwaita:dark gnome-calculator<br />
<br />
{{Note|To apply the above to desktop shortcuts (or launchers) see [[Desktop entries#Modify environment variables]].}}<br />
<br />
* For GTK 2, use {{ic|GTK2_RC_FILES}}. For example to launch [[GIMP]] with the theme Raleigh:<br />
<br />
$ GTK2_RC_FILES=/usr/share/themes/Raleigh/gtk-2.0/gtkrc gimp<br />
<br />
{{tip|{{ic|gtkrc}} can also be a custom file in your home directory created by any of the [[#Configuration tools]]. See [[#Examples]].}}<br />
<br />
More themes can be installed from the official repositories or the [[AUR]]. Manually extracted themes go in {{ic|~/.themes/}} or {{ic|~/.local/share/themes/}} directory.<br />
<br />
'''Themes supporting GTK 2 and GTK 3:'''<br />
<br />
* {{App|Adapta| An adaptive GTK theme based on Material Design Guidelines. Includes: Adapta, Adapta-Eta, Adapta-Nokto, Adapta-Nokto-Eta|https://github.com/tista500/Adapta|{{Pkg|adapta-gtk-theme}}}}<br />
* {{App|Arc|A flat theme with a modern look and transparent elements. Includes: Arc, Arc-Dark, Arc-Darker|https://github.com/jnsh/arc-theme|with transparency: {{Pkg|arc-gtk-theme}}, without transparency: {{Pkg|arc-solid-gtk-theme}}}}<br />
* {{App|Bluebird|Blue Desktop Suite for Xfce.|https://github.com/shimmerproject/Bluebird|{{AUR|xfce-theme-bluebird}}}}<br />
* {{App|Breeze|GTK version of KDE's default widget theme. Includes: Breeze, Breeze-Dark|https://invent.kde.org/plasma/breeze-gtk|{{Pkg|breeze-gtk}}}}<br />
* {{App|Deepin|Default theme for the Deepin desktop. Includes: deepin, deepin-dark|https://github.com/linuxdeepin/deepin-gtk-theme|{{Pkg|deepin-gtk-theme}}}}<br />
* {{App|GNOME Extra Themes|Extra themes for the GNOME desktop. Includes: Adwaita, Adwaita-dark, HighContrast|https://gitlab.gnome.org/GNOME/gnome-themes-extra|{{Pkg|gnome-themes-extra}}}}<br />
* {{App|Greybird|A grey and blue Xfce theme, used by default in Xubuntu 12.04.|https://github.com/shimmerproject/Greybird|{{AUR|xfce-theme-greybird}}}}<br />
* {{App|Materia|A Material Design-like flat theme for GTK3, GTK2, and GNOME-Shell.|https://github.com/nana-4/materia-theme|{{Pkg|materia-gtk-theme}}}}<br />
* {{App|MATE Themes|Default themes for the MATE desktop. Includes: BlackMATE, Blue-Submarine, BlueMenta, ContrastHighInverse, Green-Submarine, GreenLaguna, Menta, TraditionalGreen, TraditionalOk|https://github.com/mate-desktop/mate-themes|{{Pkg|mate-themes}}}}<br />
* {{App|Numix|A flat and light theme with a modern look (GNOME, Openbox, Unity, Xfce). Includes: Numix|https://github.com/numixproject/numix-gtk-theme|{{AUR|numix-gtk-theme-git}}}}<br />
* {{App|Vertex|Theme for GTK 3, GTK 2, Gnome-Shell and Cinnamon.|https://github.com/horst3180/vertex-theme|{{AUR|vertex-themes}}}}<br />
* {{App|Zuki|Themes for GTK, gnome-shell and more.|https://github.com/lassekongo83/zuki-themes|{{AUR|zuki-themes}}}}<br />
<br />
There are a number of additional GTK themes in the AUR, example: [https://aur.archlinux.org/packages?K=gtk-theme search for gtk-theme].<br />
<br />
=== GTK and Qt ===<br />
<br />
If you have GTK and Qt (KDE) applications on your desktop then you know that their looks do not blend well. If you wish to make your GTK styles match your Qt styles please read [[Uniform look for Qt and GTK applications]].<br />
<br />
== Configuration tools ==<br />
<br />
Most major [[desktop environments]] provide tools to configure the GTK theme, icons, font and font size, and manage these settings via [https://specifications.freedesktop.org/xsettings-spec/ XSettings]:<br />
* If you use [[Cinnamon]], use Themes tool (''cinnamon-settings themes''): go to ''System Settings > Themes''.<br />
* If you use [[Enlightenment]]: go to ''Settings > All > Look > Application Theme''.<br />
* If you use [[GNOME]], use GNOME Tweaks (''gnome-tweaks''): install {{Pkg|gnome-tweaks}}.<br />
* If you use [[MATE]], use the Appearance Preferences tool (''mate-appearance-properties''): go to ''System > Settings > Appearance''.<br />
* If you use [[Xfce]], use the Appearance tool: go to ''Settings > Appearance''.<br />
<br />
Other GUI tools generally overwrite the [[#Configuration|configuration files]].<br />
<br />
'''Both GTK 2 and GTK 3 are supported:'''<br />
* {{App|KDE GTK Configurator|Application that allows you to change style and font of GTK 2 and GTK 3 applications.|https://invent.kde.org/plasma/kde-gtk-config|{{Pkg|kde-gtk-config}}}}<br />
:After installation, {{ic|kde-gtk-config}} can be found in ''System Settings > Appearance > Application Style > Configure GNOME/GTK Application Style''.<br />
* {{App|LXAppearance|Desktop independent GTK 2 and GTK 3 style configuration tool from the LXDE project (it does not require other parts of the LXDE desktop).|https://wiki.lxde.org/en/LXAppearance|{{Pkg|lxappearance-gtk3}}}}<br />
* {{App|Oo-mox| Graphical application for generating different color variations of Numix and Flat-Plat themes (GTK 2 and 3), Archdroid and Gnome-Colors icon themes. Also allows generating pre-scaled GTK 2 themes for HiDPI displays. |https://github.com/actionless/oomox|{{AUR|themix-full-git}}}}<br />
<br />
'''Only GTK 2 is supported:'''<br />
* {{App|GTK Change Theme|Little program that lets you change your GTK 2.0 theme (considered a better alternative to ''switch2'').|http://plasmasturm.org/code/gtk-chtheme/|{{Pkg|gtk-chtheme}}}}<br />
* {{App|GTK Preference Tool|GTK theme selector and font switcher.|https://gtk-win.sourceforge.io/home/index.php/Main/GTKPreferenceTool|{{AUR|gtk2_prefs}}}}<br />
* {{App|GTK Theme Switch|Simple GTK theme switcher.|3=http://muhri.net/nav.php3?node=gts|4={{AUR|gtk-theme-switch2}}}}<br />
<br />
== Configuration ==<br />
<br />
GTK settings can be specified manually in configuration files, but desktop environments and applications can override these settings. Depending on GTK version, these files are located at:<br />
* GTK 2 user specific: {{ic|~/.gtkrc-2.0}}<br />
* GTK 2 system wide: {{ic|/etc/gtk-2.0/gtkrc}}<br />
* GTK 3 user specific: {{ic|$XDG_CONFIG_HOME/gtk-3.0/settings.ini}}, or {{ic|$HOME/.config/gtk-3.0/settings.ini}} if {{ic|$XDG_CONFIG_HOME}} is not set<br />
* GTK 3 system wide: {{ic|/etc/gtk-3.0/settings.ini}}<br />
<br />
{{Note|<br />
*See the [https://docs.gtk.org/gtk4/class.Settings.html#properties GTK4] and [https://docs.gtk.org/gtk3/class.Settings.html#properties GTK3] ''GtkSettings'' properties (and [https://ghostarchive.org/archive/p2BmM GTK 2 properties]) in the GTK programming reference manual for the full list of currently supported GTK configuration options.<br />
*Some of the settings described below (such as {{ic|gtk-icon-sizes}}) are deprecated and ignored since GTK 3.10.<br />
*If you edit your GTK configuration files, only newly started applications will display the changes.}}<br />
<br />
=== Basic theme configuration ===<br />
<br />
To manually change the GTK theme, icons, font and font size, add the following to the configuration files, for example:<br />
<br />
* GTK 2:<br />
{{hc|~/.gtkrc-2.0|2=<br />
gtk-icon-theme-name = "Adwaita"<br />
gtk-theme-name = "Adwaita"<br />
gtk-font-name = "DejaVu Sans 11"<br />
}}<br />
<br />
* GTK 3:<br />
{{hc|$XDG_CONFIG_HOME/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-icon-theme-name = Adwaita<br />
gtk-theme-name = Adwaita<br />
gtk-font-name = DejaVu Sans 11<br />
}}<br />
<br />
If the theme is not applied for GTK 3, use {{ic|gsettings}} in addition:<br />
<br />
$ gsettings set org.gnome.desktop.interface gtk-theme Pop<br />
<br />
{{Note|The icon theme name is the name of its directory, ''not'' the name property in its {{ic|index.theme}}.}}<br />
<br />
=== Dark theme variant ===<br />
<br />
Some GTK 3 themes contain a dark theme variant, but it's only used by default when the application requests it explicitly. To use dark theme variant with all GTK 3 applications, set:<br />
<br />
gtk-application-prefer-dark-theme = true<br />
<br />
=== Keyboard shortcuts ===<br />
<br />
Keyboard shortcuts (otherwise known as ''accelerators'' in GTK) may be changed by hovering the mouse over the respective menu item, and pressing the desired key combination. To enable this feature, set:<br />
<br />
gtk-can-change-accels = 1<br />
<br />
==== Emacs key bindings ====<br />
<br />
To have Emacs-like key bindings in GTK applications add the following:<br />
<br />
{{hc|1=~/.gtkrc-2.0|2=<br />
gtk-key-theme-name = "Emacs"<br />
}}<br />
<br />
{{hc|1=~/.config/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-key-theme-name = Emacs<br />
}}<br />
<br />
For GTK3 also run:<br />
<br />
$ gsettings set org.gnome.desktop.interface gtk-key-theme "Emacs"<br />
<br />
XFCE has a similar setting:<br />
<br />
$ xfconf-query -c xsettings -p /Gtk/KeyThemeName -s Emacs<br />
<br />
The configuration files in {{ic|/usr/share/themes/Emacs/}} determine what the Emacs bindings are, and can be changed. Copying sections to the users {{ic|~/.gtkrc-2.0}} file allows for changes on a per user basis.<br />
<br />
=== GNOME menu delay ===<br />
<br />
This setting controls the delay between pointing the mouse at a menu and that menu opening. This delay is measured in milliseconds.<br />
<br />
gtk-menu-popup-delay = 0<br />
<br />
=== Reduce widget sizes ===<br />
<br />
If you have a small screen or you just do not like big icons and widgets, you can resize things easily. <br />
<br />
To have icons without text in toolbars ([https://developer.gnome.org/gtk3/stable/gtk3-Standard-Enumerations.html#GtkToolbarStyle valid values]), use<br />
<br />
gtk-toolbar-style = GTK_TOOLBAR_ICONS<br />
<br />
To use smaller icons, use a line like this:<br />
<br />
gtk-icon-sizes = "panel-menu=16,16:panel=16,16:gtk-menu=16,16:gtk-large-toolbar=16,16\<br />
:gtk-small-toolbar=16,16:gtk-button=16,16"<br />
<br />
Or to remove icons from buttons completely:<br />
<br />
gtk-button-images = 0<br />
<br />
You can also remove icons from menus:<br />
<br />
gtk-menu-images = 0<br />
<br />
See also [https://martin.ankerl.com/2008/10/11/how-to-make-a-compact-gnome-theme/] and [https://www.gnome-look.org/p/1079374].<br />
<br />
=== Hide CSD buttons ===<br />
<br />
To remove the client-side decorations (CSD)[https://blogs.gnome.org/tbernard/2018/01/26/csd-initiative/] minimize and maximize buttons from ''gtk3'' windows:<br />
<br />
gtk-decoration-layout=menu:close<br />
<br />
See [https://docs.gtk.org/gtk3/property.Settings.gtk-decoration-layout.html GTK docs].<br />
<br />
=== Disable mouse paste ===<br />
<br />
To turn off pasting on middle mouse button click (aka PRIMARY):<br />
<br />
gtk-enable-primary-paste=false<br />
<br />
=== File-chooser start-up location ===<br />
<br />
Open the file-chooser within the '''current working directory''' and not the '''recent''' location. Normally the '''current working directory''' is the ''Home'' directory.<br />
<br />
'''GTK 3'''<br />
<br />
Change [[GNOME#Configuration|setting]] with the following command:<br />
<br />
$ gsettings set org.gtk.Settings.FileChooser startup-mode cwd<br />
<br />
'''GTK 2'''<br />
<br />
Add the following to {{ic|~/.config/gtk-2.0/gtkfilechooser.ini}}:<br />
<br />
StartupMode=cwd<br />
<br />
=== Legacy scrolling behavior ===<br />
<br />
{{Note|This setting is not obeyed by all GTK applications.}}<br />
{{Tip|Legacy scrolling behaviour can be achieved reliably simply by using right click instead of left click.}}<br />
<br />
Prior to GTK 3.6, clicking on either side of the slider in the scrollbar would move the scrollbar in the direction of the click by approximately one page. Since GTK 3.6, the slider will move directly to the position of the click. This behaviour can be reverted in some applications by creating the file with the content below:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|<nowiki><br />
[Settings]<br />
gtk-primary-button-warps-slider = false<br />
</nowiki>}}<br />
<br />
=== Disable overlay scrollbars ===<br />
<br />
Since GTK 3.15, overlay scrollbars are enabled by default, meaning that scrollbars will be shown only on mouseover in GTK 3 applications. This behavior can be reverted by setting the following environment variable: {{ic|1=GTK_OVERLAY_SCROLLING=0}}. See [[Environment variables#Graphical environment]].<br />
<br />
Alternatively, overlay scrollbars can be disabled in the GTK 3 settings since GTK 3.24.9. To do so, the value of gtk-overlay-scrolling has to be set to false in the [Settings] section of the settings file:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-overlay-scrolling = false<br />
}}<br />
<br />
GTK 4 will no longer support {{ic|1=GTK_OVERLAY_SCROLLING}}. It has already been [https://github.com/GNOME/gtk/commit/e49615184a9d85bb0bb4e289b3ee8252adee3813#diff-3cf94c6e1eb009e20985034bc2210bfd dropped] from master. As of GTK 4, the overlay nature of the scrollbars is part of the toolkit. The blanket toggle has been removed to prevent developers from breaking applications that have not been tested with both combinations. To allow application developers to decide what their applications should look like, the toolkit instead provides a mechanism to opt-out or add a setting for users. The function [https://developer.gnome.org/gtk3/stable/GtkScrolledWindow.html#gtk-scrolled-window-set-overlay-scrolling gtk_scrolled_window_set_overlay_scrolling()] can be used to enable/disable overlay scrolling on a ''per-application'' basis. Application developers can optionally use [https://blog.gtk.org/2017/05/01/first-steps-with-gsettings/ GSettings] to have a user setting bound to the property.<br />
<br />
==== Remove overlay scroll indicators ====<br />
<br />
The positions of the overlay scrollbars are indicated by thin dashed lines in the application window. These dashed lines will be present even when overlay scrolling is disabled using the environment variable discussed in the section above. To remove the indicator lines, create the following file:<br />
<br />
{{hc|~/.config/gtk-3.0/gtk.css|<br />
/* Remove dotted lines from GTK 3 applications */<br />
undershoot.top, undershoot.right, undershoot.bottom, undershoot.left { background-image: none; }<br />
}}<br />
<br />
=== Examples ===<br />
<br />
GTK example configurations:<br />
<br />
{{Note|May be ignored by some [[desktop environments]] (e.g. [[GNOME]]).}}<br />
<br />
{{hc|~/.gtkrc-2.0|2=<br />
gtk-theme-name="Arc-Dark"<br />
gtk-icon-theme-name="breeze-dark"<br />
gtk-font-name="Sans 11"<br />
gtk-cursor-theme-name="Breeze_Amber"<br />
gtk-cursor-theme-size=0<br />
gtk-toolbar-style=GTK_TOOLBAR_BOTH_HORIZ<br />
gtk-toolbar-icon-size=GTK_ICON_SIZE_SMALL_TOOLBAR<br />
gtk-button-images=0<br />
gtk-menu-images=0<br />
gtk-enable-event-sounds=0<br />
gtk-enable-input-feedback-sounds=0<br />
gtk-xft-antialias=1<br />
gtk-xft-hinting=1<br />
gtk-xft-hintstyle="hintslight"<br />
gtk-xft-rgba="rgb"<br />
}}<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-theme-name=Arc-Dark<br />
gtk-icon-theme-name=breeze-dark<br />
gtk-font-name=Sans 11<br />
gtk-cursor-theme-name=Breeze_Amber<br />
gtk-cursor-theme-size=0<br />
gtk-toolbar-style=GTK_TOOLBAR_BOTH_HORIZ<br />
gtk-toolbar-icon-size=GTK_ICON_SIZE_SMALL_TOOLBAR<br />
gtk-button-images=0<br />
gtk-menu-images=0<br />
gtk-enable-event-sounds=0<br />
gtk-enable-input-feedback-sounds=0<br />
gtk-xft-antialias=1<br />
gtk-xft-hinting=1<br />
gtk-xft-hintstyle=hintslight<br />
gtk-xft-rgba=rgb<br />
# gtk-decoration-layout=menu:close<br />
# gtk-application-prefer-dark-theme=1<br />
}}<br />
<br />
== GDK backends ==<br />
<br />
GDK (the underlying abstraction layer of GTK) supports multiple backends to display GTK applications.<br />
<br />
=== Wayland backend ===<br />
<br />
The GDK [[Wayland]] backend is supported only by {{Pkg|gtk3}} and is the default backend when using [[Wayland]] display server. <br />
<br />
Applications that use versions of GTK prior to {{Pkg|gtk3}} do not have wayland support, and need to use Xwayland in order to run on a wayland session using the ''X11'' backend.<br />
<br />
=== Xorg backend ===<br />
<br />
If [[Xorg]] display server is in use, the backend defaults to ''x11'' automatically.<br />
<br />
It is possible to force GTK3 applications running on a wayland session to use the ''X11'' backend through Xwayland by setting the environment variable {{ic|1=GDK_BACKEND=x11}}.<br />
<br />
=== Broadway backend ===<br />
<br />
The GDK Broadway backend provides support for displaying GTK applications in a web browser, using HTML5 and web sockets. <br />
[https://developer.gnome.org/gtk3/3.8/gtk-broadway.html]<br />
<br />
When using ''broadwayd'', specify the display number to use, prefixed with a colon, similar to X. The default display number is 0 (zero).<br />
<br />
$ display_number=:5<br />
Start it.<br />
$ broadwayd $display_number <br />
<br />
Port used by default<br />
port = 8080 + $display_number<br />
<br />
Point your browser to http://127.0.0.1:port<br />
<br />
To Start applications<br />
<br />
$ GDK_BACKEND=broadway BROADWAY_DISPLAY=$display_number ''<<application>>''<br />
<br />
Alternatively can set address and port<br />
<br />
$ broadwayd --port $port_number --address $address $display_number<br />
<br />
== Troubleshooting ==<br />
<br />
=== Different themes between GTK 2 and GTK 3 applications ===<br />
<br />
In general, if a selected theme has support for both GTK 2 and GTK 3, the theme will be applied to all GTK 2 and GTK 3 applications. If a selected theme has support for only GTK 2, it will be used for GTK 2 applications and the default GTK theme will be used for GTK 3 applications. If the selected theme has support for only GTK 3, it will be used for GTK 3 applications and the default GTK theme will be used for GTK 2 applications. Thus for application theme consistency, it is best to use a theme which has support for both GTK 2 and GTK 3.<br />
<br />
You could find what themes installed on your system have both an GTK 2 and GTK 3 version by using this command (does not work with names containing spaces):<br />
find $(find ~/.themes /usr/share/themes/ -wholename "*/gtk-3.0" | sed -e "s/^\(.*\)\/gtk-3.0$/\1/") -wholename "*/gtk-2.0" | sed -e "s/.*\/\(.*\)\/gtk-2.0/\1"/<br />
<br />
=== Theme not applied to root applications ===<br />
<br />
As user theme files ({{ic|$XDG_CONFIG_HOME/gtk-3.0/settings.ini}}, {{ic|~/.gtkrc-2.0}}) are not read by other accounts, the selected theme will not apply to [[Running_X_apps_as_root|X applications run as root]]. Possible solutions include:<br />
<br />
* Create symlinks, e.g<br />
# ln -s /home/[username]/.gtkrc-2.0 /etc/gtk-2.0/gtkrc<br />
# ln -s /home/[username]/.config/gtk-3.0/settings.ini /etc/gtk-3.0/settings.ini<br />
* Configure system-wide theme files: {{ic|/etc/gtk-3.0/settings.ini}} (GTK 3) or {{ic|/etc/gtk-2.0/gtkrc}} (GTK 2)<br />
* Adjust the theme as root<br />
# lxappearance<br />
* Use a settings daemon (this is what most desktop environments do). A desktop-agnostic variant using [https://specifications.freedesktop.org/xsettings-spec/ XSettings] is available in the [[AUR]] under {{aur|xsettingsd-git}}.<br />
<br />
=== Client-side decorations ===<br />
<br />
GTK 3.12 introduced [https://blogs.gnome.org/mclasen/2013/12/05/client-side-decorations-in-themes/ client-side decorations], which move the title-bar away from the window manager. This may present issues such as [https://redmine.audacious-media-player.org/boards/1/topics/1135 double title-bars], no title-bar at all, [https://github.com/chjj/compton/issues/189 double shadows] with compositing enabled, or being unable to move a frozen application.<br />
<br />
To remove the shadow and gap around windows (for example in combination with a tiling window manager), create the following file:<br />
<br />
{{hc|~/.config/gtk-3.0/gtk.css|<nowiki>.window-frame, .window-frame:backdrop {<br />
box-shadow: 0 0 0 black;<br />
border-style: none;<br />
margin: 0;<br />
border-radius: 0;<br />
}<br />
<br />
.titlebar {<br />
border-radius: 0;<br />
}<br />
<br />
.window-frame.csd.popup {<br />
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), 0 0 0 1px rgba(0, 0, 0, 0.13);<br />
}<br />
<br />
.header-bar {<br />
background-image: none;<br />
background-color: #ededed;<br />
box-shadow: none;<br />
}<br />
/* You may want to use this if you do not like the double title.<br />
GtkLabel.title {<br />
opacity: 0;<br />
}*/<br />
</nowiki>}}<br />
<br />
Note that if visual problems persist, you may want to use the GTK Inspector to find the offending elements as explained here [https://github.com/numixproject/numix-gtk-theme/issues/206#issuecomment-817660426].<br />
<br />
To adjust the buttons in the header bar, use the {{ic|gtk-decoration-layout}} setting. [https://developer.gnome.org/gtk3/stable/GtkSettings.html#GtkSettings--gtk-decoration-layout] The below examples removes all buttons:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
gtk-decoration-layout=menu:<br />
}}<br />
<br />
To remove client-side decorations altogether, it's possible to use a patched library like {{AUR|gtk3-classic}} or {{AUR|gtk3-nocsd-git}}.<br />
<br />
=== cedilla ç/Ç instead of ć/Ć ===<br />
<br />
See [https://bugs.launchpad.net/ubuntu/+source/ibus/+bug/518056], and [https://bugs.launchpad.net/ubuntu/+source/ibus/+bug/518056/comments/37] for a workaround using Xcompose (US international layout).<br />
<br />
=== Suppress warning about accessibility bus ===<br />
<br />
If you do not use any [https://wiki.gnome.org/Accessibility Gnome Accessibility] features, you may receive warnings like:<br />
<br />
WARNING **: Could not connect to accessibility bus:<br />
<br />
To suppress these warnings, execute programs with {{ic|1=NO_AT_BRIDGE=1}} or set that as a global [[environment variable]].<br />
<br />
=== Titlebar background color mismatch ===<br />
<br />
If you are using a [[window manager]] which uses a window decoration theme that mimics the GTK theme background color, you may find that the titlebar color no longer completely matches the application color in some GTK 3 applications. As a workaround, create the following file:<br />
{{hc|~/.config/gtk-3.0/gtk.css|<br />
/* Always use background color */<br />
GtkWindow {<br />
background-color: @theme_bg_color;<br />
}<br />
<br />
/* Fix tooltip background override */<br />
.tooltip {<br />
background-color: rgba(0, 0, 0, 0.8);<br />
}<br />
<br />
.tooltip * {<br />
background-color: transparent;<br />
}<br />
<br />
/* Fix Nautilus desktop window background override */<br />
NautilusWindow {<br />
background-color: transparent; <br />
}<br />
}}<br />
<br />
=== Wrong focus events with tiling window managers ===<br />
<br />
{{Note|1=This disables smooth scrolling and touchscreen support for GTK3 applications. [https://bugzilla.gnome.org/show_bug.cgi?id=677329#c14]}}<br />
<br />
[[Define]] {{ic|1=GDK_CORE_DEVICE_EVENTS=1}} to use GTK2 style input, instead of xinput2. [https://bugzilla.gnome.org/show_bug.cgi?id=677329#c10]<br />
<br />
=== Thumbnail support for GTK file dialog ===<br />
<br />
Install {{AUR|gtk2-patched-filechooser-icon-view}} and {{AUR|gtk3-patched-filechooser-icon-view}} to have the option to view files as thumbnails instead of list in the GTK file chooser.<br />
<br />
=== Button and menu icons ===<br />
<br />
{{Accuracy|Explain what the issue is. GNOME ignores {{ic|settings.ini}} if GDM is used.}}<br />
For some applications in GNOME's Wayland session. Your {{ic|~/.config/gtk-3.0/settings.ini}} file is misconfigured. This can happen if you try other GTK based desktop environments. These are the offending values:<br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|<nowiki>[Settings]<br />
gtk-button-images=1<br />
gtk-menu-images=1</nowiki>}}<br />
<br />
Simply set them to 0 or remove the whole file to use GNOME defaults.<br />
<br />
=== GTK 3 without polkit ===<br />
<br />
GTK3 depends on polkit through colord, which is required for printing. However printing works fine without polkit installed; at least with a monochrome printer and package versions gtk3-print-backends=3.22.19-2 and colord=1.4.1-1.<br />
<br />
=== Some GTK 2 themes only change the UI color palette ===<br />
<br />
Depending on the theme of choice's support for GTK 2, UI controls may still have the default Raleigh appearance, possibly with a different color palette. This is due to these themes requiring the GTK 2 Murrine engine, which is missing (GTK 2 programs should complain about it on their standard error output). Install the {{Pkg|gtk-engine-murrine}} package.<br />
<br />
=== Patching GTK file chooser to use regular type ahead ===<br />
<br />
GTK file chooser uses the same type-ahead-find feature as [[GNOME/Files]]. This can be very jarring and does not fit in very well with other desktop enviroments.<br />
<br />
Some applications support XDG-desktop-portal which allows application to use the native file chooser. If that does not work you can restore type-ahead functionality by using a patched GTK, for example {{AUR|gtk3-classic}}.<br />
<br />
=== Text in GTK 4 applications is blurry or renders incorrectly ===<br />
<br />
GTK 4 switched to grayscale antialiasing without hinting when rendering fonts. A setting is available that will restore some of the GTK 3 behavior. Subpixel antialiasing is not available.<br />
<br />
== See also ==<br />
<br />
* [https://www.gtk.org/ The official GTK website]<br />
* [[Wikipedia:GTK|Wikipedia article about GTK]]</div>PXfhttps://wiki.archlinux.org/index.php?title=Timidity%2B%2B&diff=712125Timidity++2022-01-20T20:26:00Z<p>PXf: /* Fluidr3 */ you don't "install a package" by "adding some path"</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[de:Timidity++]]<br />
[[ja:Timidity++]]<br />
TiMidity++ is a [[Wikipedia:software synthesizer|software synthesizer]] that can play MIDI files without a hardware synthesizer. It can either render to the sound card in real time, or it can save the result to a file, such as a [[wikipedia:PCM|PCM]] [[wikipedia:WAV|''.wav '']] file.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|timidity++}} package.<br />
<br />
You should also install a [[Wikipedia:SoundFont|SoundFont]] to be able to produce sound. Some popular choices of SoundFont include:<br />
* {{Pkg|freepats-general-midi}}<br />
* {{Pkg|soundfont-fluid}}<br />
* {{AUR|soundfont-generaluser}}<br />
* {{AUR|soundfont-arachno}}<br />
<br />
== Configuration ==<br />
<br />
First you should add yourself to the audio group.<br />
<br />
# gpasswd -a <user> audio<br />
<br />
As with most group changes, you will typically need to restart your user session (e.g. log out and log in again), so that the new group is visible in the output of the {{ic|groups}} command.<br />
<br />
=== SoundFonts ===<br />
<br />
Configure your preferred SoundFont.<br />
<br />
==== Freepats ====<br />
<br />
The [https://freepats.zenvoid.org/ Freepats] project provides a set of instrument samples which are compatible with TiMidity++. <br />
<br />
To use Freepats with TiMidity++, add the following lines to {{ic|timidity.cfg}}:<br />
<br />
{{hc|/etc/timidity/timidity.cfg|<br />
soundfont /usr/share/soundfonts/freepats-general-midi.sf2<br />
}}<br />
<br />
==== Fluidr3 ====<br />
<br />
There are other SoundFonts available. To use the FluidR3 SoundFont, install {{Pkg|soundfont-fluid}} and append its path to the TiMidity++ configuration file:<br />
<br />
{{hc|/etc/timidity/timidity.cfg|<br />
soundfont /usr/share/soundfonts/FluidR3_GM.sf2<br />
}}<br />
<br />
=== Daemon ===<br />
<br />
[[Start/enable]] the {{ic|timidity.service}} user unit.<br />
<br />
Note that starting the service may fail if you have changed your {{ic|audio}} group membership but not yet restarted your session.<br />
<br />
If you are using [[PulseAudio]], that may also cause the service to fail. You may want to add the following command as an auto start program in your desktop environment. Or, if you just want to start TiMidity++ in daemon mode once, you can use the following command which will make console output viewable:<br />
<br />
$ timidity -iA<br />
<br />
== Usage ==<br />
<br />
=== Play files ===<br />
<br />
There are two ways to use TiMidity++. Either as MIDI player or as daemon adding MIDI support to [[ALSA]].<br />
<br />
==== Standalone mode ====<br />
<br />
You can simply use TiMidity++ to play MIDI files:<br />
$ timidity example.midi<br />
<br />
Add option {{ic|-in}} or {{ic|-ig}} for a text-based/GTK interface. E.g. as a Xfce/GNOME user you may want to set MIDI files to open with the custom command {{ic|timidity -ig}}. There are many other options to TiMidity++. See {{man|1|timidity}} or use {{ic|-h}} to get help.<br />
<br />
The GTK interface offers such features as a playlist, track length estimates, volume control, a file load dialog box, play and pause buttons, rewind and fast forward buttons, as well as options to change the pitch of or speed up or slow down the playback of a midi file.<br />
<br />
==== Daemon mode ====<br />
<br />
If you are runing TiMidity++ as a [[#Daemon|daemon]] (ALSA sequencer client), it will provide MIDI output support for other programs such as rosegarden, aplaymidi, vkeybd, etc.<br />
<br />
This will give you four output software MIDI ports (in addition of hardware MIDI ports on your system, if any):<br />
{{hc|$ aconnect -o|2=<br />
client 128: 'TiMidity' [type=user]<br />
0 'TiMidity port 0 '<br />
1 'TiMidity port 1 '<br />
2 'TiMidity port 2 '<br />
3 'TiMidity port 3 '<br />
}}<br />
<br />
You can now play MIDI files using aplaymidi:<br />
<br />
$ aplaymidi filename.mid --port 128:0<br />
<br />
Another example is '''vkeybd''', a virtual MIDI keyboard for X.<br />
<br />
You can [[install]] {{AUR|vkeybd}} from the [[AUR]].<br />
<br />
$ vkeybd --addr 128:0<br />
<br />
Option {{ic|--addr 128:0}} connects the input (readable) software MIDI port provided by vkeybd to the first output (writable) ALSA port provided by Timidity. Alternatively you can use aconnect, {{Pkg|patchage}} or kaconnect. As a result when you play around with the keys on the vkeybd TiMidity++ plays the appropriate notes.<br />
<br />
==== Connect to virtual MIDI device ====<br />
<br />
Once you have the TiMidity++ daemon running and it is working with aplaymidi, you can connect it to a virtual MIDI device that will work in programs such as rosegarden or scala.<br />
<br />
Load the {{ic|snd-virmidi}} '''kernel module''' and (optionally) configure it to be loaded at boot. Read [[Kernel modules]] for more information.<br />
<br />
Use aconnect to verify the port numbers:<br />
<br />
{{hc|$ aconnect -o|2=<br />
client 14: 'Midi Through' [type=kernel]<br />
0 'Midi Through Port-0'<br />
client 20: 'Virtual Raw MIDI 1-0' [type=kernel]<br />
0 'VirMIDI 1-0 '<br />
client 21: 'Virtual Raw MIDI 1-1' [type=kernel]<br />
0 'VirMIDI 1-1 '<br />
client 22: 'Virtual Raw MIDI 1-2' [type=kernel]<br />
0 'VirMIDI 1-2 '<br />
client 23: 'Virtual Raw MIDI 1-3' [type=kernel]<br />
0 'VirMIDI 1-3 '<br />
client 128: 'TiMidity' [type=user]<br />
0 'TiMidity port 0 '<br />
1 'TiMidity port 1 '<br />
2 'TiMidity port 2 '<br />
3 'TiMidity port 3 '<br />
}}<br />
Now create the connection:<br />
$ aconnect 20:0 128:0<br />
<br />
You should now have a working MIDI output device on your system ({{ic|/dev/snd/midiC1D0}}).<br />
<br />
== Troubleshooting ==<br />
<br />
=== TiMidity++ does not play MIDI files ===<br />
<br />
It may be that your SoundFile is not set up correctly. Just run:<br />
$ timidity example.midi<br />
<br />
If you find a line like this in the terminal output, your SoundFile is not set up properly.<br />
<br />
No instrument mapped to tone bank 0, program XX - \<br />
this instrument will not be heard<br />
<br />
Make sure you have installed some samples and your SoundFile is added to {{ic|/etc/timidity/timidity.cfg}}. See [[#SoundFonts|SoundFonts]] for more details.<br />
<br />
=== Daemon mode plays sound out of pace ===<br />
<br />
TiMidity++'s ALSA output module (default) may cause this issue in ALSA server mode. Try another output option, for example, '''libao''':<br />
<br />
$ timidity -iA -OO<br />
<br />
And test it using aplaymidi. If this does not work, you may want to configure [[JACK]] and set TiMidity++'s output to jack.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Convert files ===<br />
<br />
TiMidity++ can also convert MIDI files into other formats. The following command saves the resulting sound to a WAV file:<br />
$ timidity ''input.mid'' -Ow -o ''out.wav''<br />
To convert to another formats, you can use [[FFmpeg]]. This will convert it to mp3:<br />
$ timidity ''input.mid'' -Ow -o - <nowiki>|</nowiki> ffmpeg -i - -acodec libmp3lame -ab 256k ''out.mp3''<br />
<br />
=== How to make DOSBox use TiMidity++ ===<br />
<br />
{{Note|The following method is tested in version [[DOSBox]] 0.72}}<br />
<br />
First of all, you need to write a config file. Input the following in [[DOSBox]] to create a configuration file:<br />
config -writeconf dosbox.conf<br />
you can replace {{ic|dosbox.conf}} by any name that you want, add a dot in front of it if you want to hide it.<br />
<br />
Make sure you started TiMidity++ as [[#Daemon|daemon]] as the instructions above, use the '''aconnect''' command.<br />
<br />
Edit this configuration file with any editor, go to the section:<br />
{{hc|dosbox.conf|2=<br />
[midi]<br />
mpu401=intelligent<br />
device=default<br />
config=<br />
}}<br />
put the ALSA connection port into the back of ''config='', in default:<br />
config=128:0<br />
<br />
Restart DOSBox within a terminal so you can see its debug messages, by no accident you should see a successful initiation on port 128:0.<br />
<br />
== See also ==<br />
<br />
* [[USB MIDI keyboards]]</div>PXfhttps://wiki.archlinux.org/index.php?title=Timidity%2B%2B&diff=712101Timidity++2022-01-20T19:18:27Z<p>PXf: +wikilink pcm wav</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[de:Timidity++]]<br />
[[ja:Timidity++]]<br />
TiMidity++ is a [[Wikipedia:software synthesizer|software synthesizer]] that can play MIDI files without a hardware synthesizer. It can either render to the sound card in real time, or it can save the result to a file, such as a [[wikipedia:PCM|PCM]] [[wikipedia:WAV|''.wav '']] file.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|timidity++}} package.<br />
<br />
You should also install a [[Wikipedia:SoundFont|SoundFont]] to be able to produce sound. Some popular choices of SoundFont include:<br />
* {{Pkg|freepats-general-midi}}<br />
* {{Pkg|soundfont-fluid}}<br />
* {{AUR|soundfont-generaluser}}<br />
* {{AUR|soundfont-arachno}}<br />
<br />
== Configuration ==<br />
<br />
First you should add yourself to the audio group.<br />
<br />
# gpasswd -a <user> audio<br />
<br />
As with most group changes, you will typically need to restart your user session (e.g. log out and log in again), so that the new group is visible in the output of the {{ic|groups}} command.<br />
<br />
=== SoundFonts ===<br />
<br />
Configure your preferred SoundFont.<br />
<br />
==== Freepats ====<br />
<br />
The [https://freepats.zenvoid.org/ Freepats] project provides a set of instrument samples which are compatible with TiMidity++. <br />
<br />
To use Freepats with TiMidity++, add the following lines to {{ic|timidity.cfg}}:<br />
<br />
{{hc|/etc/timidity/timidity.cfg|<br />
soundfont /usr/share/soundfonts/freepats-general-midi.sf2<br />
}}<br />
<br />
==== Fluidr3 ====<br />
<br />
There are other SoundFonts available. To install the {{Pkg|soundfont-fluid}} SoundFont, append its path to the TiMidity++ configuration file:<br />
<br />
{{hc|/etc/timidity/timidity.cfg|<br />
soundfont /usr/share/soundfonts/FluidR3_GM.sf2<br />
}}<br />
<br />
=== Daemon ===<br />
<br />
[[Start/enable]] the {{ic|timidity.service}} user unit.<br />
<br />
Note that starting the service may fail if you have changed your {{ic|audio}} group membership but not yet restarted your session.<br />
<br />
If you are using [[PulseAudio]], that may also cause the service to fail. You may want to add the following command as an auto start program in your desktop environment. Or, if you just want to start TiMidity++ in daemon mode once, you can use the following command which will make console output viewable:<br />
<br />
$ timidity -iA<br />
<br />
== Usage ==<br />
<br />
=== Play files ===<br />
<br />
There are two ways to use TiMidity++. Either as MIDI player or as daemon adding MIDI support to [[ALSA]].<br />
<br />
==== Standalone mode ====<br />
<br />
You can simply use TiMidity++ to play MIDI files:<br />
$ timidity example.midi<br />
<br />
Add option {{ic|-in}} or {{ic|-ig}} for a text-based/GTK interface. E.g. as a Xfce/GNOME user you may want to set MIDI files to open with the custom command {{ic|timidity -ig}}. There are many other options to TiMidity++. See {{man|1|timidity}} or use {{ic|-h}} to get help.<br />
<br />
The GTK interface offers such features as a playlist, track length estimates, volume control, a file load dialog box, play and pause buttons, rewind and fast forward buttons, as well as options to change the pitch of or speed up or slow down the playback of a midi file.<br />
<br />
==== Daemon mode ====<br />
<br />
If you are runing TiMidity++ as a [[#Daemon|daemon]] (ALSA sequencer client), it will provide MIDI output support for other programs such as rosegarden, aplaymidi, vkeybd, etc.<br />
<br />
This will give you four output software MIDI ports (in addition of hardware MIDI ports on your system, if any):<br />
{{hc|$ aconnect -o|2=<br />
client 128: 'TiMidity' [type=user]<br />
0 'TiMidity port 0 '<br />
1 'TiMidity port 1 '<br />
2 'TiMidity port 2 '<br />
3 'TiMidity port 3 '<br />
}}<br />
<br />
You can now play MIDI files using aplaymidi:<br />
<br />
$ aplaymidi filename.mid --port 128:0<br />
<br />
Another example is '''vkeybd''', a virtual MIDI keyboard for X.<br />
<br />
You can [[install]] {{AUR|vkeybd}} from the [[AUR]].<br />
<br />
$ vkeybd --addr 128:0<br />
<br />
Option {{ic|--addr 128:0}} connects the input (readable) software MIDI port provided by vkeybd to the first output (writable) ALSA port provided by Timidity. Alternatively you can use aconnect, {{Pkg|patchage}} or kaconnect. As a result when you play around with the keys on the vkeybd TiMidity++ plays the appropriate notes.<br />
<br />
==== Connect to virtual MIDI device ====<br />
<br />
Once you have the TiMidity++ daemon running and it is working with aplaymidi, you can connect it to a virtual MIDI device that will work in programs such as rosegarden or scala.<br />
<br />
Load the {{ic|snd-virmidi}} '''kernel module''' and (optionally) configure it to be loaded at boot. Read [[Kernel modules]] for more information.<br />
<br />
Use aconnect to verify the port numbers:<br />
<br />
{{hc|$ aconnect -o|2=<br />
client 14: 'Midi Through' [type=kernel]<br />
0 'Midi Through Port-0'<br />
client 20: 'Virtual Raw MIDI 1-0' [type=kernel]<br />
0 'VirMIDI 1-0 '<br />
client 21: 'Virtual Raw MIDI 1-1' [type=kernel]<br />
0 'VirMIDI 1-1 '<br />
client 22: 'Virtual Raw MIDI 1-2' [type=kernel]<br />
0 'VirMIDI 1-2 '<br />
client 23: 'Virtual Raw MIDI 1-3' [type=kernel]<br />
0 'VirMIDI 1-3 '<br />
client 128: 'TiMidity' [type=user]<br />
0 'TiMidity port 0 '<br />
1 'TiMidity port 1 '<br />
2 'TiMidity port 2 '<br />
3 'TiMidity port 3 '<br />
}}<br />
Now create the connection:<br />
$ aconnect 20:0 128:0<br />
<br />
You should now have a working MIDI output device on your system ({{ic|/dev/snd/midiC1D0}}).<br />
<br />
== Troubleshooting ==<br />
<br />
=== TiMidity++ does not play MIDI files ===<br />
<br />
It may be that your SoundFile is not set up correctly. Just run:<br />
$ timidity example.midi<br />
<br />
If you find a line like this in the terminal output, your SoundFile is not set up properly.<br />
<br />
No instrument mapped to tone bank 0, program XX - \<br />
this instrument will not be heard<br />
<br />
Make sure you have installed some samples and your SoundFile is added to {{ic|/etc/timidity/timidity.cfg}}. See [[#SoundFonts|SoundFonts]] for more details.<br />
<br />
=== Daemon mode plays sound out of pace ===<br />
<br />
TiMidity++'s ALSA output module (default) may cause this issue in ALSA server mode. Try another output option, for example, '''libao''':<br />
<br />
$ timidity -iA -OO<br />
<br />
And test it using aplaymidi. If this does not work, you may want to configure [[JACK]] and set TiMidity++'s output to jack.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Convert files ===<br />
<br />
TiMidity++ can also convert MIDI files into other formats. The following command saves the resulting sound to a WAV file:<br />
$ timidity ''input.mid'' -Ow -o ''out.wav''<br />
To convert to another formats, you can use [[FFmpeg]]. This will convert it to mp3:<br />
$ timidity ''input.mid'' -Ow -o - <nowiki>|</nowiki> ffmpeg -i - -acodec libmp3lame -ab 256k ''out.mp3''<br />
<br />
=== How to make DOSBox use TiMidity++ ===<br />
<br />
{{Note|The following method is tested in version [[DOSBox]] 0.72}}<br />
<br />
First of all, you need to write a config file. Input the following in [[DOSBox]] to create a configuration file:<br />
config -writeconf dosbox.conf<br />
you can replace {{ic|dosbox.conf}} by any name that you want, add a dot in front of it if you want to hide it.<br />
<br />
Make sure you started TiMidity++ as [[#Daemon|daemon]] as the instructions above, use the '''aconnect''' command.<br />
<br />
Edit this configuration file with any editor, go to the section:<br />
{{hc|dosbox.conf|2=<br />
[midi]<br />
mpu401=intelligent<br />
device=default<br />
config=<br />
}}<br />
put the ALSA connection port into the back of ''config='', in default:<br />
config=128:0<br />
<br />
Restart DOSBox within a terminal so you can see its debug messages, by no accident you should see a successful initiation on port 128:0.<br />
<br />
== See also ==<br />
<br />
* [[USB MIDI keyboards]]</div>PXfhttps://wiki.archlinux.org/index.php?title=Boot_sequence&diff=709758Boot sequence2022-01-12T09:07:25Z<p>PXf: + redirect Boot sequence -> Arch boot process</p>
<hr />
<div>#REDIRECT[[Arch boot process]]</div>PXfhttps://wiki.archlinux.org/index.php?title=Category_talk:ARM_architecture&diff=704294Category talk:ARM architecture2021-12-04T18:19:03Z<p>PXf: /* Remove all ARM related pages (second attempt) */ see a tip do i remove it</p>
<hr />
<div>== Remove all ARM related pages (second attempt) ==<br />
<br />
I think it's time to stop allowing ARM related content in the wiki. The ARM architecture is not supported by Arch Linux, so they do not belong here.<br />
<br />
ALARM has their own wiki which has now existed for more than 5 years, so the excuse that it's just starting out does not work anymore. Even if these devices are not supported by ALARM, it should not be our problem, since they're also not supported by Arch Linux.<br />
<br />
I propose redirecting all pages in [[:Category:ARM architecture]] and [[:Category:ARM architecture]] itself to [[archlinux-service-agreements:code-of-conduct#arch-linux-distribution-support-only]]. Or alternatively, they could be moved to user pages of the users who created them.<br />
<br />
-- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 07:33, 6 April 2021 (UTC)<br />
<br />
:I support this. My only argument against is that it would be lost documentation, which is in the wrong place anyways, but this is easily solved by moving them to user pages instead.<br />
:-- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 09:18, 6 April 2021 (UTC)<br />
<br />
::Agreed, let's just get rid of it. There's been more than sufficient time to merge relevant information to the ALARM wiki. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 10:16, 5 October 2021 (UTC)<br />
::Flagged all the pages. Now we should decide what to do with the (content in the) category page itself. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 10:21, 5 October 2021 (UTC)<br />
<br />
:I must say I found invaluable information on these pages to run Arch on my ARMv7 server. I would gladly host [[NanoPi_M1]] on my user page if nobody claims it. I guess a page on the ALARM wiki would still be the best solution, but I'm afraid they won't host them - their wiki claims to only have pages for supported hardware, and the NanoPi_M1 isn't among those. [[User:Lafleur|la Fleur]] ([[User talk:Lafleur|talk]]) 19:28, 5 October 2021 (UTC)<br />
<br />
::I'll redirect that article to your user page then if you're willing to maintain it there. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 08:33, 6 October 2021 (UTC)<br />
<br />
:::[[Help:Style#User pages]] says they must not be targets of redirects of other namespaces.<br />
:::-- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 07:35, 7 October 2021 (UTC)<br />
<br />
::::Guess I'll just move it without leaving a redirect then, and add a redirect to [[archlinux-service-agreements:code-of-conduct#arch-linux-distribution-support-only]] after that... -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 09:31, 7 October 2021 (UTC)<br />
<br />
::I copied the page [[User:lafleur/NanoPi_M1|to my user page]] and added an incipit. I just wonder how anyone will be able to find it there then. [[User:Lafleur|la Fleur]] ([[User talk:Lafleur|talk]]) 23:53, 7 October 2021 (UTC)<br />
<br />
:If we see an archlinuxarm-related tip do we remove it? E.g. in [[Kodi#Speedup_video_playback_(synchronized_audio_and_video)_up_to_1.5x|Kodi#S.v.p...]] there is {{ic|1=Arch ARM packages are built with GLES which lacks the support}}. [[User:PXf|PXf]] ([[User talk:PXf|talk]]) 18:18, 4 December 2021 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=Kodi&diff=704285Kodi2021-12-04T17:50:15Z<p>PXf: /* Recommended methods to reboot/shutdown using kodi-standalone service */ fix grammar, reword</p>
<hr />
<div>[[Category:Home theater]]<br />
[[ja:Kodi]]<br />
[[zh-hans:Kodi]]<br />
[https://kodi.tv/ Kodi] (formerly known as XBMC) is an award-winning free and open source (GPL) software media player and entertainment hub that can be installed on Linux, OSX, Windows, iOS and Android, featuring a 10-foot user interface for use with televisions and remote controls. These can all be played directly from a CD/DVD, or from the hard-drive. Kodi can also play multimedia from a computer over a local network (LAN), or play media streams directly from the Internet. It can also be used to play and record live TV using a tuner, a backend server and a PVR plugin; more information about this can be found on the [https://kodi.wiki/view/PVR Kodi wiki].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|kodi}} package. Be sure to review/install optional dependencies listed by pacman to enable additional functionality.<br />
<br />
The {{pkg|kodi}} package supports for several composers, including [[Xorg]], [[Wikipedia:Mesa (computer graphics)#Generic Buffer Management|GBM]], and [[Wayland]]. In terms of functionality, X11 is currently the most mature and feature rich. Wayland and GBM are both a close second and should be considered on-par with X11, however, a known limitation of Wayland is having the resolution and frame rate set in the compositor rather than in Kodi's GUI. As well, Wayland currently does not support VT switching. GBM has some known features it lacks compared to both X11 and Wayland. A complete list can be found in [https://github.com/xbmc/xbmc/issues/14876 Kodi issue 14876]. GBM may be a good choice for standalone operations since it runs directly on the GPU without the X11 layer.<br />
<br />
It is recommended for users to test the various options particularly if the hardware on which Kodi is running is limited. For example, the X11 composer may offer CPU/GPU efficiency gains vs the GBM composer.<br />
<br />
All of the official addons in the {{Grp|kodi-addons}} group are disabled by default and need to be enabled in Kodi's addon menu after installation.<br />
<br />
== Running ==<br />
<br />
There are two general use cases:<br />
<br />
# {{ic|/usr/bin/kodi}} is meant to be run by any user on an on-demand basis. Use it like any other program on the system.<br />
# {{ic|/usr/bin/kodi-standalone}} is meant to be run as the only graphical application, for example on a [[wikipedia:Home theater PC|HTPC]]. See [[#Running standalone]] for more information.<br />
<br />
== Running standalone ==<br />
<br />
Using standalone mode is advantageous for several reasons:<br />
<br />
# One can define an unprivileged user to run kodi and have no access to a shell.<br />
# When paired with a systemd unit (or equivalent, see below), this setup makes the box on which kodi is running more like an appliance.<br />
<br />
{{Warning|Select '''only one''' of the methods listed below.}}<br />
<br />
=== kodi-standalone service ===<br />
<br />
{{AUR|kodi-standalone-service}} provides three services and automatically creates and provisions the unprivileged user to run Kodi in standalone mode.<br />
* {{ic|kodi-x11.service}} (for X11)<br />
* {{ic|kodi-gbm.service}} (for GBM)<br />
* {{ic|kodi-wayland.service}} (for Wayland)<br />
<br />
{{Note|<br />
* The correct video driver and optionally [[hardware video acceleration]] is an assumed dependency.<br />
* The home/userdata directory for the created {{ic|kodi}} user is {{ic|/var/lib/kodi/}}.<br />
* If {{ic|kodi-x11.service}} fails to start, see [[Xorg#Rootless Xorg]] for possible workarounds.<br />
* Certain use cases require environment variables to be passed to the service. Define these variables in {{ic|/etc/conf.d/kodi-standalone}} and they will be passed along to the service.<br />
}}<br />
<br />
==== Recommended methods to reboot/shutdown using kodi-standalone service ====<br />
<br />
Be aware that these services run Kodi in systemd's ''user.slice'', not ''system.slice''. In order to have Kodi exit gracefully, initiate system reboot/shutdown with the respective Kodi actions '''instead of''' {{ic|systemctl}}. Failure to do so will result in an ungraceful exit of Kodi and the loss of GUI settings, Kodi uptime etc. In principal this is no different than data loss occurring from a user doing work when a sysadmin issues a reboot command without prior warning. While it is possible to run Kodi in systemd's system.slice instead, doing so makes it difficult to use USB mounts within Kodi and to use pulseaudio for Kodi sessions.<br />
<br />
* '''Kodi GUI''': selecting the corresponding option under Power menu in the Kodi GUI.<br />
* '''Mobile device''': the official Android/iOS app: can also perform these actions. Assumes that the corresponding options are enabled in Kodi.<br />
* '''CLI''': use {{ic|kodi-send}} provided by {{pkg|kodi-eventclients}} to send the {{ic|ShutDown()}} or the {{ic|Reboot}}. The syntax is:<br />
$ kodi-send -a "Reboot"<br />
$ kodi-send -a "ShutDown()"<br />
<br />
=== Xsession with LightDM ===<br />
<br />
{{Note|<br />
* This assumes that a kodi user named {{ic|kodi}} is on the system and that the following file is present as described.<br />
* {{pkg|lightdm}} does not pull in an X server as a required dependency, it is optional. The X server listed as an optional dependency ({{Pkg|xorg-server-xephyr}}) does not work when run as root by {{ic|lightdm.service}} ({{Bug|52067}}, [https://bugs.launchpad.net/lightdm/+bug/852577 LightDM Bug 852577]). [[Xorg#Installation|Install xorg-server]].<br />
}}<br />
<br />
To use LightDM with automatic login, see [[LightDM#Enabling autologin]] and [[LightDM#Enabling interactive passwordless login]]. ''Kodi'' includes {{ic|kodi.desktop}} as [[xsession]].<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:seat0]<br />
pam-service=lightdm-autologin<br />
autologin-user=kodi<br />
autologin-user-timeout=0<br />
user-session=kodi<br />
}}<br />
<br />
=== Xsession with NoDM ===<br />
<br />
[[Nodm]] is an automatic display manager which automatically starts an X session at system boot.<br />
<br />
By creating a [[user]] for kodi (e.g. {{ic|useradd -mU kodi}}) and [[install]]ing {{Pkg|nodm}} we simply have to specify the kodi user inside:<br />
<br />
{{hc|/etc/nodm.conf|2=<br />
NODM_USER=kodi<br />
NODM_XSESSION=/home/kodi/.xinitrc<br />
}}<br />
<br />
Make sure to execute {{ic|kodi}} inside the [[xinitrc]] file.<br />
<br />
{{Note|The {{ic|.xinitrc}} file must be executable, so the {{ic|kodi}} user's home must not be mounted with the {{ic|noexec}} option.}}<br />
<br />
=== Socket activation ===<br />
<br />
Socket activation can be used to start Kodi when the user issues a Wakeup command from a remote control app like Kore, or makes a connection to Kodi's html control port. Start listening by [[starting]] {{ic|kodi@''user''.socket}} (replace ''user'' with the user running Kodi to be started as).<br />
<br />
There are no packaged {{ic|kodi@.service}} and {{ic|kodi@.socket}} files, one must create them manually. Depending on the setup, one can optionally change the ports in {{ic|kodi@.socket}}.<br />
<br />
{{hc|/etc/systemd/system/kodi@.service|<nowiki><br />
# This fails if the user does not have an X session.<br />
[Unit]<br />
Description=Launch Kodi on main display<br />
Conflicts=kodi.socket<br />
<br />
[Service]<br />
Type=simple<br />
Environment=DISPLAY=:0.0<br />
Nice=-1<br />
ExecStart=/usr/bin/su %i /usr/bin/kodi<br />
ExecStopPost=/usr/bin/systemctl --no-block start kodi@%i.socket<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/kodi@.socket|<nowiki><br />
[Unit]<br />
Conflicts=kodi@%i.service<br />
<br />
[Socket]<br />
# Unset <br />
ListenStream=<br />
# Start when receiving a TCP request on the http control port<br />
ListenStream=8080<br />
# start when receiving an UDP datagram (Wakeup/WOL)<br />
ListenDatagram=9<br />
<br />
[Install]<br />
WantedBy=sockets.target<br />
</nowiki>}}<br />
<br />
=== Start from remote control with LIRC / irexec ===<br />
<br />
Kodi can be configured to start via a key press. Users will need {{AUR|kodi-standalone-service}} and {{Pkg|lirc}}. This can be useful on setups running 24/7 and having kodi up on demand.<br />
<br />
See the corresponding [[LIRC]] article and create a functional setup with a remote. Also, the package {{AUR|kodi-standalone-service}} has to be installed.<br />
<br />
Generate the file {{ic|/var/lib/kodi/.lircrc}} with the following content:<br />
<br />
{{hc|/var/lib/kodi/.lircrc|<nowiki><br />
begin<br />
prog = irexec<br />
remote = devinput<br />
button = KEY_MEDIA<br />
config = pgrep kodi-standalone || /usr/bin/kodi-standalone -l /run/lirc/lircd<br />
repeat = 0<br />
end<br />
</nowiki>}}<br />
<br />
Adopt {{ic|button}} to whatever button on the remote is to start Kodi. One can use ''irw'' (see [[LIRC#Testing]]) to find out the correct values for {{ic|remote}} and {{ic|button}}.<br />
<br />
Create a [[Systemd#Drop-in files|drop-in]] for {{ic|kodi-xxx.service}}:<br />
<br />
{{hc|/etc/systemd/system/kodi-xxx.service.d/lirc.conf|2=<br />
[Service]<br />
ExecStart =<br />
ExecStart = /usr/bin/irexec<br />
}}<br />
<br />
[[Start]] {{ic|kodi-xxx.service}} and [[enable]] it to run at boot time.<br />
<br />
== Using a remote control ==<br />
<br />
As Kodi is geared toward being a remote-controlled media center via an official app, physical remote control, or USB/bluetooth keyboard/mouse.<br />
<br />
=== Using the Android or iOS app ===<br />
<br />
Both Android and iOS users can use the official app (currently free of charge) to control kodi once it is correctly setup to do so. Steps to configure both Kodi and the app are detailed on the [https://kodi.wiki/view/Official_Kodi_Remote Official Kodi Remote] and [https://kodi.wiki/view/Kore_Manual Kore Manual] page.<br />
<br />
{{Tip|Kore provides [[power management]] actions to perform remotely [[suspend]]/[[hibernation]] and [[Wake-on-LAN]] (WoL).}}<br />
<br />
=== Using a physical remote control ===<br />
<br />
Any PC with a supported IR receiver/remote, can use [[LIRC]] or even kernel supported modules to drive it. Configuring specific remotes with lirc is covered on the [[LIRC]] article.<br />
<br />
To work properly with Kodi, a file that maps the lirc events to Kodi keypresses is needed. Create an [[Wikipedia:XML|XML]] file at {{ic|~/.kodi/userdata/Lircmap.xml}} (note the capital 'L'). <br />
<br />
{{Note|Users running Kodi started with {{AUR|kodi-standalone-service}} will find the {{ic|kodi}} user's home ({{ic|~}}) under {{ic|/var/lib/kodi/}} and should substitute this in for the shortcut above. Also make sure that if creating this file as the root user, it gets proper [[ownership]] as {{ic|kodi:kodi}} when finished.}}<br />
<br />
{{ic|Lircmap.xml}} format is as follows: <br />
<br />
{{bc|1=<br />
<lircmap><br />
<remote device="devicename"><br />
<XBMC_button>LIRC_button</XBMC_button><br />
...<br />
</remote><br />
</lircmap><br />
}}<br />
<br />
* '''Device Name''' is whatever LIRC calls the remote. This is set using the '''Name''' directive in lircd.conf and can be viewed by running {{ic|irw}} and pressing a few buttons on the remote. IRW will report the name of the button pressed and the name of the remote will appear on the end of the line.<br />
* '''XBMC_button''' is the name of the button as defined in [https://kodi.wiki/view/Keymap keymap.xml].<br />
* '''LIRC_button''' is the name as defined in {{ic|lircd.conf}}. If {{ic|lircd.conf}} was autogenerated using {{ic|irrecord}}, these are the names selected for the buttons. Refer back to [[LIRC]] for more information.<br />
* A very thorough [https://kodi.wiki/view/LIRC LIRC] page hosted on the Kodi Wiki should be consulted for more help and information on this subject as this is out of scope of this article.<br />
<br />
=== HDMI-CEC ===<br />
<br />
With a supported [https://www.pulse-eight.com/p/104/usb-hdmi-cec-adapter USB-CEC adapter], Kodi can be used to automatically turn on and off the TV and other home theater equipment. Volume control from Kodi can be sent to a supported amplifier, one can manage DVD or Blu-Ray players from inside Kodi, and redirect the active source on the TV to whichever equipment needs it, all from one remote control. For more information see the [https://kodi.wiki/view/CEC official Kodi wiki page on CEC] and [http://libcec.pulse-eight.com/faq libCEC FAQ].<br />
<br />
Install {{Pkg|libcec}}.<br />
<br />
{{Expansion|Add reference for the need to add users to these groups.}}<br />
<br />
When connected, the USB-CEC's {{ic|/dev}} entry (usually {{ic|/dev/ttyACM*}}) will default to being owned by the {{ic|uucp}} group, so in order to use the device the user running Kodi needs to belong to that group. The user also needs to belong to the {{ic|lock}} group, otherwise Kodi will be unable to connect to the device. See [[Users and groups#Group management]] for instructions on how to add users to groups.<br />
<br />
* Add all users that will use Kodi to the {{ic|uucp}} and {{ic|lock}} [[user group]]s.<br />
* Users of {{AUR|kodi-standalone-service}} do not need to take any action as group membership is handled automatically upon installation.<br />
<br />
{{Note|Trying to use the USB-CEC without belonging to above groups may lead to problems, including Kodi crashes, so make sure the correct user belongs to both groups.}}<br />
<br />
== Sharing media and a centralized database across multiple nodes ==<br />
<br />
If multiple PCs on the same network are running Kodi, they can be configured to share a single media library (video and music). The advantage of this is media and key metadata are stored in one place, and are shared/updated by all nodes on the network. For example, users of this setup can:<br />
<br />
* Stop watching a movie or show in one room then finish watching it in another room automatically.<br />
* Share watched and unwatched status for media on all nodes.<br />
* Simplify the setup with only a single library to maintain.<br />
<br />
As well, the media itself can be located in one space thus allowing a lighter footprint of client systems (ie no need for large HDD space).<br />
<br />
Several things are needed for this to work:<br />
<br />
* Network exposed media (via protocols that Kodi can read, e.g. NFS or Samba).<br />
* A [[MariaDB]] server.<br />
<br />
{{Warning|When sharing a database, ALL clients need to be on the same major version of Kodi due to versioned requirements of the database schema. Refer to [https://kodi.wiki/view/Databases#Database_Versions database version table] for a list of database versions.}}<br />
<br />
{{Note|The following guide is only an example of one configuration and is not meant to be limiting but illustrative. Key steps are shown but a detailed discussion is not offered.}}<br />
<br />
These assumptions are used for the guide, substitute as needed:<br />
<br />
* The media is located under following mount points: {{ic|/mnt/shows}} {{ic|/mnt/movies}} {{ic|/mnt/music}}.<br />
* The network addresses of all nodes are within the 192.168.0.* subnet range.<br />
* The IP address of the machine running both the NFS exports and the MariaDB database is 192.168.0.105.<br />
* Each Kodi box is referred to as a node.<br />
* The Linux user running Kodi is 'kodi' on all nodes.<br />
<br />
For additional info, refer to the [https://kodi.wiki/view/MySQL/Setting_up_MySQL#Arch_Linux official Kodi wiki].<br />
<br />
=== NFS server export example ===<br />
<br />
This section provides an example using exports, see [[NFS]] for install and usage.<br />
<br />
{{Note|Users only need one box on the LAN to serve the content, therefore, do not repeat this for each node. The following example assumes the user is running Arch Linux, but any NFS server will work, be it Linux or BSD, etc.}}<br />
<br />
Create an empty directory in NFS root for each media directory to be shared. E.g.:<br />
<br />
# mkdir -p /srv/nfs/{shows,movies,music}<br />
<br />
[[NFS#Server|Bind mount]] the media directories to the empty directories in {{ic|/srv/nfs/}}.<br />
<br />
Setup [[NFS#Server|exports]]:<br />
<br />
{{hc|/etc/exports.d/kodi.exports|2=<br />
/srv/nfs 192.168.0.0/24(ro,fsid=0,no_subtree_check)<br />
/srv/nfs/shows 192.168.0.0/24(ro,no_subtree_check,insecure)<br />
/srv/nfs/movies 192.168.0.0/24(ro,no_subtree_check,insecure)<br />
/srv/nfs/music 192.168.0.0/24(ro,no_subtree_check,insecure)<br />
}}<br />
<br />
=== Install and set up the MariaDB server ===<br />
<br />
See [[MariaDB]] for installation and configuration instructions.<br />
<br />
To create a database for Kodi, use the following commands:<br />
<br />
$ mysql -u root -p<br />
<<enter the mariadb root password assigned in the first step>><br />
MariaDB [(none)]> CREATE USER 'kodi' IDENTIFIED BY 'kodi';<br />
MariaDB [(none)]> GRANT ALL ON *.* TO 'kodi';<br />
MariaDB [(none)]> flush privileges;<br />
MariaDB [(none)]> \q<br />
<br />
=== Set up Kodi to use the MariaDB library and the NFS exports ===<br />
<br />
==== Set up Kodi to use the common SQL database ====<br />
<br />
To tell Kodi to use the common database, insure that Kodi is not running, then create the following file:<br />
<br />
{{hc|~/.kodi/userdata/advancedsettings.xml|<br />
<advancedsettings><br />
<videodatabase><br />
<type>mysql</type><br />
<host>192.168.0.105</host><br />
<port>3306</port><br />
<user>kodi</user><br />
<pass>kodi</pass><br />
</videodatabase><br />
<br />
<musicdatabase><br />
<type>mysql</type><br />
<host>192.168.0.105</host><br />
<port>3306</port><br />
<user>kodi</user><br />
<pass>kodi</pass><br />
</musicdatabase><br />
<br />
<videolibrary><br />
<importwatchedstate>true</importwatchedstate><br />
<importresumepoint>true</importresumepoint><br />
</videolibrary><br />
</advancedsettings><br />
}}<br />
<br />
{{Tip|If using {{AUR|kodi-standalone-service}}, the default for the profile is {{ic|/var/lib/kodi/.kodi}} and be sure to chown the newly created file to the kodi user and group, i.e. {{ic|chown -R kodi:kodi /var/lib/kodi}}}}<br />
<br />
==== Set up network shares ====<br />
<br />
Load Kodi and define the network shares that correspond to the exports by browsing to the following within the interface ''Video > Files > Add Videos > Browse > Network Filesystem(NFS)''.<br />
<br />
After a few seconds, the IP address corresponding to the NFS server should appear.<br />
<br />
Select {{ic|/srv/nfs/shows}} from the list of share and then ''OK'' from the menu on the right. Assign this share the category of ''TV Shows'' to setup the appropriate scraper and to populate the SQL database with the correct metadata.<br />
<br />
Repeat this browsing process for the "movies" and "music" and then exit Kodi once properly configured. At this point, the SQL tables should have been created.<br />
<br />
{{Note|Even if Kodi is running on the same box that is also running the NFS exports and SQL server, one '''must''' setup the media using the nfs shares only.}}<br />
<br />
=== Cloning the configuration to other nodes on the network ===<br />
<br />
To set up another Kodi node on the network to use this library, simply copy {{ic|~/.kodi/userdata/advancedsettings.xml}} to that box and restart Kodi. There is NO need to copy any other files or to do any other setup steps on the new kodi node. The nfs exports, the metadata for the programming, any stop/start times, view status, etc. are all stored in the SQL tables.<br />
<br />
{{Note|One can optionally define other media sources that are not managed by kodi database, but they will be specific to that particular node.}}<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Keep a log of what is watched ===<br />
<br />
Keep track of every video watched on kodi with {{AUR|kodi-logger}}.<br />
<br />
=== Speedup video playback (synchronized audio and video) up to 1.5x ===<br />
<br />
{{Note|Only x86_64 packages can make use of this as full OpenGL is required. Arch ARM packages are built with GLES which lacks the support.}}<br />
<br />
To enable speed-up and slow-down with audio/video sync (0.8x - 1.5x) do the following:<br />
* Create the following file that will map the {{ic|[}} and {{ic|]}} keys to the {{ic|tempo down}} and {{ic|tempo up}} actions, respectively:<br />
<br />
{{hc|~/.kodi/userdata/keymaps/custom.xml|2=<br />
<keymap><br />
<FullscreenVideo><br />
<keyboard><br />
<opensquarebracket>PlayerControl(tempodown)</opensquarebracket><br />
<closesquarebracket>PlayerControl(tempoup)</closesquarebracket><br />
</keyboard><br />
</FullscreenVideo><br />
<VideoMenu><br />
<keyboard><br />
<opensquarebracket>PlayerControl(tempodown)</opensquarebracket><br />
<closesquarebracket>PlayerControl(tempoup)</closesquarebracket><br />
</keyboard><br />
</VideoMenu><br />
</keymap><br />
}}<br />
<br />
* Restart kodi which will read in these changes.<br />
* Navigate to ''System > Player > Videos > Playback'' and enable "Sync playback to display" option.<br />
<br />
=== Modify default values for watch and resume points ===<br />
<br />
Some users may wish to make the thresholds Kodi uses to create a resume point/consider a video "watched" entirely. Do so by editing {{ic|~/.kodi/userdata/advancedsettings.xml}} inserting the following three xml fields:<br />
<br />
* '''ignoresecondsatstart''': the number of seconds to wait before keeping track of the start point. If users watch a value below the one defined, no start point is recorded. Default is 180.<br />
* '''playcountminimumpercent''': the percentage of total play time to consider something watched. If users watch more of the video that this number but not the entire video, it is considered watched and any previously recorded resume point is deleted upon stopping and finally, the video is flagged as watched. Default is 90.<br />
* '''ignorepercentatend''': the percentage of total play time at the end of a video to ignore making a resume point. This is related to the previous setting except it considers the last x percent of the video. If users watch enough content to enter this space of the file, no resume point is saved and the video is flagged as watched. Default is 8.<br />
<br />
{{hc|~/.kodi/userdata/advancedsettings.xml|2=<br />
<advancedsettings><br />
<video><br />
<!-- see https://kodi.wiki/view/HOW-TO:Modify_automatic_watch_and_resume_points --><br />
<ignoresecondsatstart>10</ignoresecondsatstart><br />
<playcountminimumpercent>90</playcountminimumpercent><br />
<ignorepercentatend>8</ignorepercentatend><br />
</video><br />
</advancedsettings><br />
}}<br />
<br />
=== CLI for kodi ===<br />
<br />
* {{pkg|kodi-eventclients}} package provides {{ic|kodi-send}} which can send valid [https://kodi.wiki/view/Action_IDs kodi action] or [https://kodi.wiki/view/List_of_built-in_functions#List_of_functions kodi function] to kodi from the shell.<br />
<br />
* {{AUR|texturecache}} can handle many aspects of library management, from clean-up of unused images, to searching, to querying what is currently playing.<br />
<br />
=== Hardware video acceleration ===<br />
<br />
Enable and configure [[hardware video acceleration]] to speed up playback performance.<br />
<br />
Restart Kodi and enable the hardware backend(s) in Playback under Settings.<br />
<br />
=== Use Kodi to view security camera streams (rtsp or rtmp) ===<br />
<br />
Since Kodi uses ffmpeg for video playback, it is able to play streams such as rtsp and rtmp can be viewed. To do so, simply create a txt file in the filesystem exposed to the kodi user containing the stream. For example:<br />
$ cat front-door.strm<br />
rtsp://username:password@10.1.10.101<br />
<br />
Optionally meta-data, such as cover art and summaries can also be associated to the .strm file just like normal entries in a library by using an NFO file.<br />
<br />
=== UPnP and DLNA ===<br />
<br />
Go to ''Settings > Services > UPnP/DLNA'' and toggle ''Enable UPnP support''.<br />
<br />
=== Adjusting CD/DVD drive speed ===<br />
<br />
The ''eject'' program from the {{Pkg|util-linux}} package does a nice job for this, but its setting is cleared as soon as the media is changed.<br />
<br />
This udev-rule reduces the speed permanently:<br />
<br />
{{hc|/etc/udev/rules.d/dvd-speed.rules|2=<br />
KERNEL=="sr0", ACTION=="change", ENV{DISK_MEDIA_CHANGE}=="1", RUN+="/usr/bin/eject -x 2 /dev/sr0"<br />
}}<br />
<br />
Replace {{ic|sr0}} with the device name of the optical drive. Replace {{ic|-x 2}} with {{ic|-x 4}} if the preference is 4x-speed instead of 2x-speed.<br />
<br />
After creating the file, reload the udev rules with<br />
<br />
# udevadm control --reload<br />
<br />
=== Use port 80 for webserver ===<br />
<br />
Kodi has a webservice that allows interaction through a web-interface. By default, it uses port {{ic|8080}} as {{ic|80}} requires root privileges. Use the following to permit it to use low port numbers:<br />
<br />
# setcap 'cap_net_bind_service=+ep' /usr/lib/kodi/kodi.bin<br />
<br />
Restart Kodi and set port {{ic|80}} in the configuration menu (''Services > Webserver > Port'').<br />
<br />
=== Using ALSA ===<br />
<br />
If [[PulseAudio]] does not work properly, try using [[ALSA]] directly by starting Kodi with the {{ic|1=KODI_AE_SINK=ALSA}} [[environment variable]]. The Kodi wiki for NUC devices provides [https://kodi.wiki/view/Archive:Install_Kodi_on_an_Intel_NUC#disable_PulseAudio instructions]<br />
<br />
If using {{ic|kodi-standalone}}, change the {{ic|APP}} variable in {{ic|/usr/bin/kodi-standalone}} to<br />
<br />
APP="${bindir}/pasuspender -- env KODI_AE_SINK=ALSA ${bindir}/${bin_name} --standalone $@"<br />
<br />
If the above fix still does not work with kodi-standalone try editing the following<br />
<br />
{{hc|/usr/bin/kodi-standalone|<nowiki><br />
systemctl --user mask pulseaudio.socket<br />
systemctl --user stop pulseaudio<br />
<br />
APP=Kodi<br />
prefix="/usr"<br />
exec_prefix="/usr"<br />
bindir="/usr/bin"<br />
bin_name=kodi<br />
APP="${bindir}/${bin_name} --standalone $@"<br />
<br />
#PULSE_START="$(command -v start-pulseaudio-x11)"<br />
#if [ -n "$PULSE_START" ]; then<br />
# $PULSE_START<br />
#else<br />
# PULSE_SESSION="$(command -v pulse-session)"<br />
# if [ -n "$PULSE_SESSION" ]; then<br />
# XBMC="$PULSE_SESSION $XBMC"<br />
# fi<br />
#fi<br />
<br />
</nowiki>}}<br />
<br />
=== Audio Passthrough ===<br />
<br />
One can allow an external receiver or sound bar to decode audio by enabling passthrough. This is useful for files encoded in TrueHD or Atmos. If using PulseAudio, follow the instructions at https://kodi.wiki/view/PulseAudio to first enable passthrough in PulseAudio. Once complete, the corresponding passthrough options should appear in Kodi. If using ALSA, the passthrough options will appear in Kodi without modifications provided that the {{ic|1=AE_SINK=ALSA}} environment variable is defined prior to starting kodi.<br />
<br />
{{Warning|PulseAudio requires the output in Kodi to be set to 2 channel. Audio encoded in formats not passed through will only be sent as stereo audio. Use ALSA to support passthrough and passing decoded surround audio signals}}<br />
<br />
{{Note|PulseAudio does not support TrueHD, DTS-MA, or Atmos passthrough. Use ALSA to pass these to through the receiver.}}<br />
<br />
Another way of getting TrueHD and DTS-MA passthrough without disabling Pulseaudio or Pipewire-Pulse is to use an external player like MPV, first create the file {{ic|~/.kodi/userdata/playercorefactory.xml}} then paste the following into it:<br />
<br />
<playercorefactory><br />
<players><br />
<player name="MPV" type="ExternalPlayer" audio="false" video="true"><br />
<filename>/usr/bin/mpv</filename><br />
<args>--fs=yes "{1}"</args><br />
<hidexbmc>true</hidexbmc><br />
</player><br />
</players><br />
<rules action="prepend"><br />
<rule video="true" player="MPV"/><br />
</rules><br />
</playercorefactory><br />
<br />
{{Merge|mpv|Appears to partially duplicate [[mpv#Specify an audio output]] and [[mpv#HD Audio passthrough]].}}<br />
<br />
MPV should now be the default media player for Kodi, now you need to set the correct audio output device for MPV, you can use the following command to show a list of available audio devices:<br />
<br />
$ mpv --audio-device=help<br />
<br />
For example:<br />
<br />
alsa/hdmi:CARD=NVidia,DEV=1<br />
<br />
Now edit {{ic|~/.config/mpv/mpv.conf}} and add the following lines:<br />
<br />
audio-spdif=ac3,eac3,dts-hd,truehd<br />
audio-device=alsa/hdmi:CARD=NVidia,DEV=1<br />
<br />
To have auto switching of refresh rates create the following folder {{ic|~/.config/mpv/scripts}} then download and place [https://github.com/lvml/mpv-plugin-xrandr/blob/master/xrandr.lua mpv-plugin-xrandr/xrandr.lua] into the scripts folder you just created.<br />
<br />
=== Kodi JSON-RPC API to alter settings from external tools ===<br />
Users can interact directly with Kodi on the CLI or from a python script etc. by making use of the [https://kodi.wiki/view/JSON-RPC_API/v12 JSON-RPC API].<br />
<br />
For example, using {{pkg|curl}}:<br />
$ curl -v -H "Content-type: application/json" -d \<br />
'{"jsonrpc":"2.0","id":1,"method":"Settings.GetSettingValue","params":{"setting":"audiooutput.audiodevice"}}' \<br />
http://localhost:8080/jsonrpc -u xbmc:xbmc<br />
<br />
Another example is [https://github.com/graysky2/streamzap/blob/master/kodi/audio_switch/audio_switch.py this python script] which simply toggles between two groups of settings, in this case, toggling the audio source back-and-forth between HDMI and optical out.<br />
<br />
=== Fix for delayed startup on wifi ===<br />
<br />
If running with WiFi only (wired network unplugged) while [[#Sharing media and a centralized database across multiple nodes]], kodi will likely start before the wireless network is up, which will result in failure to connect to the shares and to the SQL server. Assuming the network is managed by the default [[systemd-networkd]], this can be fixed by using a [[Systemd#Drop-in files]] for {{ic|systemd-networkd-wait-online.service}}:<br />
<br />
# systemctl edit systemd-networkd-wait-online.service<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --ignore eth0<br />
<br />
=== Run kodi in a window manager ===<br />
<br />
Users running kodi in a [[Window manager]] may see a black screen at exit. To fix this, try switching to another tty. A possible solution is to run kodi with this script (running as the root user):<br />
<br />
{{hc|kodi.sh|<br />
#!/bin/bash<br />
kodi-standalone<br />
sudo chvt 2 <br />
sleep 1<br />
sudo chvt 1<br />
}}<br />
<br />
To make sure that [[sudo]] does not ask for password for {{ic|chvt}} add this line to {{ic|sudoers}} file:<br />
<br />
{{hc|/etc/sudoers|<br />
''UserNameHere'' ALL&#61;NOPASSWD: /usr/bin/chvt<br />
}}<br />
<br />
=== USB DAC not working ===<br />
<br />
Users of USB DAC/sound cards may experience distorted sound/clicks/pops or no sound at all when selecting it from Audio settings. A possible fix: <br />
<br />
Open {{ic|guisettings.xml}} (it should be under {{ic|/var/lib/kodi/.kodi/userdata/}} if using the supplied {{ic|kodi-xxx.service}}) and change<br />
<br />
<processquality default="'''true'''">'''101'''</processquality><br />
<br />
to<br />
<br />
<processquality default="'''false'''">'''100'''</processquality><br />
<br />
=== Virtual file system support ===<br />
<br />
Kodi provides addons for accessing various virtual file systems from within Kodi. RAR archives can be accessed using {{AUR|kodi-addon-vfs-rar}}. SFTP shares can be accessed using {{AUR|kodi-addon-vfs-sftp}}. Super Audio CD ISO files can be access using {{AUR|kodi-addon-vfs-sacd}}. Each of these addons must be enabled within Kodi's addon manager in order to be utilized.<br />
<br />
=== Inhibit KDE automatic sleep during playback ===<br />
<br />
Using the add-on [https://sourceforge.net/projects/osscreensavermanager/ ossscreensavermanager] in combination with commands using kwriteconfig5 it is possible to inhibit KDE's power saving functions during playback. Install the add-on, then under its advanced settings write under "Command to suspend screen saver":<br />
<br />
kwriteconfig5 --file powermanagementprofilesrc --group AC --group SuspendSession --key idleTime 1800000<br />
<br />
Under "Command to resume screen saver", write:<br />
<br />
kwriteconfig5 --file powermanagementprofilesrc --group AC --group SuspendSession --key idleTime 86400000<br />
<br />
In this example, the system suspends after 360 minutes during playback, and after 30 minutes without playback.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Accessing Kodi logs ===<br />
<br />
In case of an error the first point to start investigation can be {{ic|~/.kodi/temp/kodi.log}}.<br />
<br />
=== Fullscreen mode stretches Kodi across multiple displays ===<br />
<br />
For a multi-monitor setup, Kodi may default to stretching across all screens. One can restrict the fullscreen mode to one display by setting the [[environment variable]] {{ic|SDL_VIDEO_FULLSCREEN_HEAD}} to the number of the desired target display. For example, having Kodi show up on display 0, add the following line to the Kodi user's {{ic|~/.bashrc}} configuration:<br />
<br />
SDL_VIDEO_FULLSCREEN_HEAD=0<br />
<br />
{{Note|Mouse cursor will be held inside screen with Kodi.}}<br />
<br />
=== H.264 playback is using only a single core ===<br />
<br />
{{Tip|By default, press {{ic|O}} during playback to show codec information and CPU usage. More information about this overlay can be found at https://kodi.wiki/view/Codecinfo.}}<br />
<br />
If the hardware does not or cannot make use of acceleration, disable it and explicitly set video decoding to software.<br />
This is because [https://forum.kodi.tv/showthread.php?tid=170084&pid=1789661#pid1789661 H.264 decoding is only multithreaded when video decoding is set to software].<br />
<br />
To achieve this, go to ''System Settings > Video''. Set the {{ic|settings level}} to {{ic|Advanced}} or {{ic|Expert}}. Then go to ''Acceleration'' and set {{ic|Decoding method}} to {{ic|software}}.<br />
<br />
=== Kodi hangs on exit, fully occupying one CPU core, UI unresponsive ===<br />
<br />
This problem can arise with third-party plugins installed, there is some issue with their termination[https://www.linuxquestions.org/questions/linux-software-2/kodi-freezes-on-exit-kodi-bin-won't-die-4175588180/],[https://www.reddit.com/r/archlinux/comments/5029oo/kodi_freezes_on_exit_kodibin_wont_die/].<br />
<br />
Workaround: find proper UI description file ({{ic|DialogButtonMenu.xml}}) and tweak exit button type from internal Kodi's {{ic|Quit()}} function call to sending signal from outside system to Kodi. Here is one-liner that makes modifications to any skin from the default Kodi package:<br />
<br />
# find /usr/share/kodi/addons/skin.* -name DialogButtonMenu.xml -exec sed -i 's%<onclick>Quit()</onclick>%<onclick>System.Exec ("killall --signal SIGHUP kodi.bin")</onclick>%' {} \;<br />
<br />
=== kodi-standalone will not play DVDs ===<br />
<br />
If kodi-standalone will not play DVDs, it may help to install [[udisks]].<br />
<br />
== See also ==<br />
<br />
* [https://kodi.wiki/view/Main_Page Kodi Wiki] - Excellent resource with much information about Arch Linux specifically<br />
* [[Wikipedia:Kodi (software)]]<br />
* http://www.hdpfans.com/thread-329076-1-1.html - Kodi/xbmc Chinese plug-in library installation method<br />
* https://github.com/taxigps/xbmc-addons-chinese - xbmc-addons-chinese: Addon scripts, plugins, and skins for XBMC Media Center. Special for chinese laguage.</div>PXfhttps://wiki.archlinux.org/index.php?title=Kodi&diff=704216Kodi2021-12-04T06:14:52Z<p>PXf: /* Running standalone */ add link to archlinuxarm kodi packages</p>
<hr />
<div>[[Category:Home theater]]<br />
[[ja:Kodi]]<br />
[[zh-hans:Kodi]]<br />
[https://kodi.tv/ Kodi] (formerly known as XBMC) is an award-winning free and open source (GPL) software media player and entertainment hub that can be installed on Linux, OSX, Windows, iOS and Android, featuring a 10-foot user interface for use with televisions and remote controls. These can all be played directly from a CD/DVD, or from the hard-drive. Kodi can also play multimedia from a computer over a local network (LAN), or play media streams directly from the Internet. It can also be used to play and record live TV using a tuner, a backend server and a PVR plugin; more information about this can be found on the [https://kodi.wiki/view/PVR Kodi wiki].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|kodi}} package. Be sure to review/install optional dependencies listed by pacman to enable additional functionality.<br />
<br />
The {{pkg|kodi}} package supports for several composers, including [[Xorg]], [[Wikipedia:Mesa (computer graphics)#Generic Buffer Management|GBM]], and [[Wayland]]. In terms of functionality, X11 is currently the most mature and feature rich. Wayland and GBM are both a close second and should be considered on-par with X11, however, a known limitation of Wayland is having the resolution and frame rate set in the compositor rather than in Kodi's GUI. As well, Wayland currently does not support VT switching. GBM has some known features it lacks compared to both X11 and Wayland. A complete list can be found in [https://github.com/xbmc/xbmc/issues/14876 Kodi issue 14876]. GBM may be a good choice for standalone operations since it runs directly on the GPU without the X11 layer.<br />
<br />
It is recommended for users to test the various options particularly if the hardware on which Kodi is running is limited. For example, the X11 composer may offer CPU/GPU efficiency gains vs the GBM composer.<br />
<br />
All of the official addons in the {{Grp|kodi-addons}} group are disabled by default and need to be enabled in Kodi's addon menu after installation.<br />
<br />
== Running ==<br />
<br />
There are two general use cases:<br />
<br />
# {{ic|/usr/bin/kodi}} is meant to be run by any user on an on-demand basis. Use it like any other program on the system.<br />
# {{ic|/usr/bin/kodi-standalone}} is meant to be run as the only graphical application, for example on a [[wikipedia:Home theater PC|HTPC]]. See [[#Running standalone]] for more information.<br />
<br />
== Running standalone ==<br />
<br />
Using standalone mode is advantageous for several reasons:<br />
<br />
# One can define an unprivileged user to run kodi and have no access to a shell.<br />
# When paired with a systemd unit (or equivalent, see below), this setup makes the box on which kodi is running more like an appliance.<br />
<br />
{{Warning|Select '''only one''' of the methods listed below.}}<br />
{{Warning|1=Users of Arch Linux ARM should not attempt to configure any of the options presented below as the kodi [https://archlinuxarm.org/packages?q=kodi packages] for Arch Linux ARM ship with {{ic|kodi.service}} to allow standalone operation on these platforms.}}<br />
<br />
=== kodi-standalone service ===<br />
<br />
{{AUR|kodi-standalone-service}} provides three services and automatically creates and provisions the unprivileged user to run Kodi in standalone mode.<br />
* {{ic|kodi-x11.service}} (for X11)<br />
* {{ic|kodi-gbm.service}} (for GBM)<br />
* {{ic|kodi-wayland.service}} (for Wayland)<br />
<br />
{{Note|<br />
* The correct video driver and optionally [[hardware video acceleration]] is an assumed dependency.<br />
* The home/userdata directory for the created {{ic|kodi}} user is {{ic|/var/lib/kodi/}}.<br />
* If {{ic|kodi-x11.service}} fails to start, see [[Xorg#Rootless Xorg]] for possible workarounds.<br />
* Certain use cases require environment variables to be passed to the service. Define these variables in {{ic|/etc/conf.d/kodi-standalone}} and they will be passed along to the service.<br />
}}<br />
<br />
==== Recommended methods to reboot/shutdown using kodi-standalone service ====<br />
<br />
Be aware that these services run Kodi in systemd's ''user.slice'' not in the ''system.slice''. In order to have Kodi gracefully exit, the system should be called to shutdown or to reboot using the respective Kodi actions '''not''' by a call to {{ic|systemctl}}. Failure to do so will result in an ungraceful exit of Kodi and the saving of GUI settings, Kodi uptime etc. will not occur. In principal this is no different than data loss occurring from a user doing work when a sysadmin issues a reboot command without prior warning. While it is possible to run Kodi in systemd's system.slice instead, doing so makes it difficult to use USB mounts within Kodi and to use pulseaudio for Kodi sessions.<br />
<br />
* '''Kodi GUI''': selecting the corresponding option under Power menu in the Kodi GUI.<br />
* '''Mobile device''': the official Android/iOS app: can also perform these actions. Assumes that the corresponding options are enabled in Kodi.<br />
* '''CLI''': use {{ic|kodi-send}} provided by {{pkg|kodi-eventclients}} to send the {{ic|ShutDown()}} or the {{ic|Reboot}}. The syntax is:<br />
$ kodi-send -a "Reboot"<br />
$ kodi-send -a "ShutDown()"<br />
<br />
=== Xsession with LightDM ===<br />
<br />
{{Note|<br />
* This assumes that a kodi user named {{ic|kodi}} is on the system and that the following file is present as described.<br />
* {{pkg|lightdm}} does not pull in an X server as a required dependency, it is optional. The X server listed as an optional dependency ({{Pkg|xorg-server-xephyr}}) does not work when run as root by {{ic|lightdm.service}} ({{Bug|52067}}, [https://bugs.launchpad.net/lightdm/+bug/852577 LightDM Bug 852577]). [[Xorg#Installation|Install xorg-server]].<br />
}}<br />
<br />
To use LightDM with automatic login, see [[LightDM#Enabling autologin]] and [[LightDM#Enabling interactive passwordless login]]. ''Kodi'' includes {{ic|kodi.desktop}} as [[xsession]].<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:seat0]<br />
pam-service=lightdm-autologin<br />
autologin-user=kodi<br />
autologin-user-timeout=0<br />
user-session=kodi<br />
}}<br />
<br />
=== Xsession with NoDM ===<br />
<br />
[[Nodm]] is an automatic display manager which automatically starts an X session at system boot.<br />
<br />
By creating a [[user]] for kodi (e.g. {{ic|useradd -mU kodi}}) and [[install]]ing {{Pkg|nodm}} we simply have to specify the kodi user inside:<br />
<br />
{{hc|/etc/nodm.conf|2=<br />
NODM_USER=kodi<br />
NODM_XSESSION=/home/kodi/.xinitrc<br />
}}<br />
<br />
Make sure to execute {{ic|kodi}} inside the [[xinitrc]] file.<br />
<br />
{{Note|The {{ic|.xinitrc}} file must be executable, so the {{ic|kodi}} user's home must not be mounted with the {{ic|noexec}} option.}}<br />
<br />
=== Socket activation ===<br />
<br />
Socket activation can be used to start Kodi when the user issues a Wakeup command from a remote control app like Kore, or makes a connection to Kodi's html control port. Start listening by [[starting]] {{ic|kodi@''user''.socket}} (replace ''user'' with the user running Kodi to be started as).<br />
<br />
There are no packaged {{ic|kodi@.service}} and {{ic|kodi@.socket}} files, one must create them manually. Depending on the setup, one can optionally change the ports in {{ic|kodi@.socket}}.<br />
<br />
{{hc|/etc/systemd/system/kodi@.service|<nowiki><br />
# This fails if the user does not have an X session.<br />
[Unit]<br />
Description=Launch Kodi on main display<br />
Conflicts=kodi.socket<br />
<br />
[Service]<br />
Type=simple<br />
Environment=DISPLAY=:0.0<br />
Nice=-1<br />
ExecStart=/usr/bin/su %i /usr/bin/kodi<br />
ExecStopPost=/usr/bin/systemctl --no-block start kodi@%i.socket<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/kodi@.socket|<nowiki><br />
[Unit]<br />
Conflicts=kodi@%i.service<br />
<br />
[Socket]<br />
# Unset <br />
ListenStream=<br />
# Start when receiving a TCP request on the http control port<br />
ListenStream=8080<br />
# start when receiving an UDP datagram (Wakeup/WOL)<br />
ListenDatagram=9<br />
<br />
[Install]<br />
WantedBy=sockets.target<br />
</nowiki>}}<br />
<br />
=== Start from remote control with LIRC / irexec ===<br />
<br />
Kodi can be configured to start via a key press. Users will need {{AUR|kodi-standalone-service}} and {{Pkg|lirc}}. This can be useful on setups running 24/7 and having kodi up on demand.<br />
<br />
See the corresponding [[LIRC]] article and create a functional setup with a remote. Also, the package {{AUR|kodi-standalone-service}} has to be installed.<br />
<br />
Generate the file {{ic|/var/lib/kodi/.lircrc}} with the following content:<br />
<br />
{{hc|/var/lib/kodi/.lircrc|<nowiki><br />
begin<br />
prog = irexec<br />
remote = devinput<br />
button = KEY_MEDIA<br />
config = pgrep kodi-standalone || /usr/bin/kodi-standalone -l /run/lirc/lircd<br />
repeat = 0<br />
end<br />
</nowiki>}}<br />
<br />
Adopt {{ic|button}} to whatever button on the remote is to start Kodi. One can use ''irw'' (see [[LIRC#Testing]]) to find out the correct values for {{ic|remote}} and {{ic|button}}.<br />
<br />
Create a [[Systemd#Drop-in files|drop-in]] for {{ic|kodi-xxx.service}}:<br />
<br />
{{hc|/etc/systemd/system/kodi-xxx.service.d/lirc.conf|2=<br />
[Service]<br />
ExecStart =<br />
ExecStart = /usr/bin/irexec<br />
}}<br />
<br />
[[Start]] {{ic|kodi-xxx.service}} and [[enable]] it to run at boot time.<br />
<br />
== Using a remote control ==<br />
<br />
As Kodi is geared toward being a remote-controlled media center via an official app, physical remote control, or USB/bluetooth keyboard/mouse.<br />
<br />
=== Using the Android or iOS app ===<br />
<br />
Both Android and iOS users can use the official app (currently free of charge) to control kodi once it is correctly setup to do so. Steps to configure both Kodi and the app are detailed on the [https://kodi.wiki/view/Official_Kodi_Remote Official Kodi Remote] and [https://kodi.wiki/view/Kore_Manual Kore Manual] page.<br />
<br />
{{Tip|Kore provides [[power management]] actions to perform remotely [[suspend]]/[[hibernation]] and [[Wake-on-LAN]] (WoL).}}<br />
<br />
=== Using a physical remote control ===<br />
<br />
Any PC with a supported IR receiver/remote, can use [[LIRC]] or even kernel supported modules to drive it. Configuring specific remotes with lirc is covered on the [[LIRC]] article.<br />
<br />
To work properly with Kodi, a file that maps the lirc events to Kodi keypresses is needed. Create an [[Wikipedia:XML|XML]] file at {{ic|~/.kodi/userdata/Lircmap.xml}} (note the capital 'L'). <br />
<br />
{{Note|Users running Kodi started with {{AUR|kodi-standalone-service}} will find the {{ic|kodi}} user's home ({{ic|~}}) under {{ic|/var/lib/kodi/}} and should substitute this in for the shortcut above. Also make sure that if creating this file as the root user, it gets proper [[ownership]] as {{ic|kodi:kodi}} when finished.}}<br />
<br />
{{ic|Lircmap.xml}} format is as follows: <br />
<br />
{{bc|1=<br />
<lircmap><br />
<remote device="devicename"><br />
<XBMC_button>LIRC_button</XBMC_button><br />
...<br />
</remote><br />
</lircmap><br />
}}<br />
<br />
* '''Device Name''' is whatever LIRC calls the remote. This is set using the '''Name''' directive in lircd.conf and can be viewed by running {{ic|irw}} and pressing a few buttons on the remote. IRW will report the name of the button pressed and the name of the remote will appear on the end of the line.<br />
* '''XBMC_button''' is the name of the button as defined in [https://kodi.wiki/view/Keymap keymap.xml].<br />
* '''LIRC_button''' is the name as defined in {{ic|lircd.conf}}. If {{ic|lircd.conf}} was autogenerated using {{ic|irrecord}}, these are the names selected for the buttons. Refer back to [[LIRC]] for more information.<br />
* A very thorough [https://kodi.wiki/view/LIRC LIRC] page hosted on the Kodi Wiki should be consulted for more help and information on this subject as this is out of scope of this article.<br />
<br />
=== HDMI-CEC ===<br />
<br />
With a supported [https://www.pulse-eight.com/p/104/usb-hdmi-cec-adapter USB-CEC adapter], Kodi can be used to automatically turn on and off the TV and other home theater equipment. Volume control from Kodi can be sent to a supported amplifier, one can manage DVD or Blu-Ray players from inside Kodi, and redirect the active source on the TV to whichever equipment needs it, all from one remote control. For more information see the [https://kodi.wiki/view/CEC official Kodi wiki page on CEC] and [http://libcec.pulse-eight.com/faq libCEC FAQ].<br />
<br />
Install {{Pkg|libcec}}.<br />
<br />
{{Expansion|Add reference for the need to add users to these groups.}}<br />
<br />
When connected, the USB-CEC's {{ic|/dev}} entry (usually {{ic|/dev/ttyACM*}}) will default to being owned by the {{ic|uucp}} group, so in order to use the device the user running Kodi needs to belong to that group. The user also needs to belong to the {{ic|lock}} group, otherwise Kodi will be unable to connect to the device. See [[Users and groups#Group management]] for instructions on how to add users to groups.<br />
<br />
* Add all users that will use Kodi to the {{ic|uucp}} and {{ic|lock}} [[user group]]s.<br />
* Users of {{AUR|kodi-standalone-service}} do not need to take any action as group membership is handled automatically upon installation.<br />
<br />
{{Note|Trying to use the USB-CEC without belonging to above groups may lead to problems, including Kodi crashes, so make sure the correct user belongs to both groups.}}<br />
<br />
== Sharing media and a centralized database across multiple nodes ==<br />
<br />
If multiple PCs on the same network are running Kodi, they can be configured to share a single media library (video and music). The advantage of this is media and key metadata are stored in one place, and are shared/updated by all nodes on the network. For example, users of this setup can:<br />
<br />
* Stop watching a movie or show in one room then finish watching it in another room automatically.<br />
* Share watched and unwatched status for media on all nodes.<br />
* Simplify the setup with only a single library to maintain.<br />
<br />
As well, the media itself can be located in one space thus allowing a lighter footprint of client systems (ie no need for large HDD space).<br />
<br />
Several things are needed for this to work:<br />
<br />
* Network exposed media (via protocols that Kodi can read, e.g. NFS or Samba).<br />
* A [[MariaDB]] server.<br />
<br />
{{Warning|When sharing a database, ALL clients need to be on the same major version of Kodi due to versioned requirements of the database schema. Refer to [https://kodi.wiki/view/Databases#Database_Versions database version table] for a list of database versions.}}<br />
<br />
{{Note|The following guide is only an example of one configuration and is not meant to be limiting but illustrative. Key steps are shown but a detailed discussion is not offered.}}<br />
<br />
These assumptions are used for the guide, substitute as needed:<br />
<br />
* The media is located under following mount points: {{ic|/mnt/shows}} {{ic|/mnt/movies}} {{ic|/mnt/music}}.<br />
* The network addresses of all nodes are within the 192.168.0.* subnet range.<br />
* The IP address of the machine running both the NFS exports and the MariaDB database is 192.168.0.105.<br />
* Each Kodi box is referred to as a node.<br />
* The Linux user running Kodi is 'kodi' on all nodes.<br />
<br />
For additional info, refer to the [https://kodi.wiki/view/MySQL/Setting_up_MySQL#Arch_Linux official Kodi wiki].<br />
<br />
=== NFS server export example ===<br />
<br />
This section provides an example using exports, see [[NFS]] for install and usage.<br />
<br />
{{Note|Users only need one box on the LAN to serve the content, therefore, do not repeat this for each node. The following example assumes the user is running Arch Linux, but any NFS server will work, be it Linux or BSD, etc.}}<br />
<br />
Create an empty directory in NFS root for each media directory to be shared. E.g.:<br />
<br />
# mkdir -p /srv/nfs/{shows,movies,music}<br />
<br />
[[NFS#Server|Bind mount]] the media directories to the empty directories in {{ic|/srv/nfs/}}.<br />
<br />
Setup [[NFS#Server|exports]]:<br />
<br />
{{hc|/etc/exports.d/kodi.exports|2=<br />
/srv/nfs 192.168.0.0/24(ro,fsid=0,no_subtree_check)<br />
/srv/nfs/shows 192.168.0.0/24(ro,no_subtree_check,insecure)<br />
/srv/nfs/movies 192.168.0.0/24(ro,no_subtree_check,insecure)<br />
/srv/nfs/music 192.168.0.0/24(ro,no_subtree_check,insecure)<br />
}}<br />
<br />
=== Install and set up the MariaDB server ===<br />
<br />
See [[MariaDB]] for installation and configuration instructions.<br />
<br />
To create a database for Kodi, use the following commands:<br />
<br />
$ mysql -u root -p<br />
<<enter the mariadb root password assigned in the first step>><br />
MariaDB [(none)]> CREATE USER 'kodi' IDENTIFIED BY 'kodi';<br />
MariaDB [(none)]> GRANT ALL ON *.* TO 'kodi';<br />
MariaDB [(none)]> flush privileges;<br />
MariaDB [(none)]> \q<br />
<br />
=== Set up Kodi to use the MariaDB library and the NFS exports ===<br />
<br />
==== Set up Kodi to use the common SQL database ====<br />
<br />
To tell Kodi to use the common database, insure that Kodi is not running, then create the following file:<br />
<br />
{{hc|~/.kodi/userdata/advancedsettings.xml|<br />
<advancedsettings><br />
<videodatabase><br />
<type>mysql</type><br />
<host>192.168.0.105</host><br />
<port>3306</port><br />
<user>kodi</user><br />
<pass>kodi</pass><br />
</videodatabase><br />
<br />
<musicdatabase><br />
<type>mysql</type><br />
<host>192.168.0.105</host><br />
<port>3306</port><br />
<user>kodi</user><br />
<pass>kodi</pass><br />
</musicdatabase><br />
<br />
<videolibrary><br />
<importwatchedstate>true</importwatchedstate><br />
<importresumepoint>true</importresumepoint><br />
</videolibrary><br />
</advancedsettings><br />
}}<br />
<br />
{{Tip|If using {{AUR|kodi-standalone-service}}, the default for the profile is {{ic|/var/lib/kodi/.kodi}} and be sure to chown the newly created file to the kodi user and group, i.e. {{ic|chown -R kodi:kodi /var/lib/kodi}}}}<br />
<br />
==== Set up network shares ====<br />
<br />
Load Kodi and define the network shares that correspond to the exports by browsing to the following within the interface ''Video > Files > Add Videos > Browse > Network Filesystem(NFS)''.<br />
<br />
After a few seconds, the IP address corresponding to the NFS server should appear.<br />
<br />
Select {{ic|/srv/nfs/shows}} from the list of share and then ''OK'' from the menu on the right. Assign this share the category of ''TV Shows'' to setup the appropriate scraper and to populate the SQL database with the correct metadata.<br />
<br />
Repeat this browsing process for the "movies" and "music" and then exit Kodi once properly configured. At this point, the SQL tables should have been created.<br />
<br />
{{Note|Even if Kodi is running on the same box that is also running the NFS exports and SQL server, one '''must''' setup the media using the nfs shares only.}}<br />
<br />
=== Cloning the configuration to other nodes on the network ===<br />
<br />
To set up another Kodi node on the network to use this library, simply copy {{ic|~/.kodi/userdata/advancedsettings.xml}} to that box and restart Kodi. There is NO need to copy any other files or to do any other setup steps on the new kodi node. The nfs exports, the metadata for the programming, any stop/start times, view status, etc. are all stored in the SQL tables.<br />
<br />
{{Note|One can optionally define other media sources that are not managed by kodi database, but they will be specific to that particular node.}}<br />
<br />
== Tips and Tricks ==<br />
<br />
=== Keep a log of what is watched ===<br />
<br />
Keep track of every video watched on kodi with {{AUR|kodi-logger}}.<br />
<br />
=== Speedup video playback (synchronized audio and video) up to 1.5x ===<br />
<br />
{{Note|Only x86_64 packages can make use of this as full OpenGL is required. Arch ARM packages are built with GLES which lacks the support.}}<br />
<br />
To enable speed-up and slow-down with audio/video sync (0.8x - 1.5x) do the following:<br />
* Create the following file that will map the {{ic|[}} and {{ic|]}} keys to the {{ic|tempo down}} and {{ic|tempo up}} actions, respectively:<br />
<br />
{{hc|~/.kodi/userdata/keymaps/custom.xml|2=<br />
<keymap><br />
<FullscreenVideo><br />
<keyboard><br />
<opensquarebracket>PlayerControl(tempodown)</opensquarebracket><br />
<closesquarebracket>PlayerControl(tempoup)</closesquarebracket><br />
</keyboard><br />
</FullscreenVideo><br />
<VideoMenu><br />
<keyboard><br />
<opensquarebracket>PlayerControl(tempodown)</opensquarebracket><br />
<closesquarebracket>PlayerControl(tempoup)</closesquarebracket><br />
</keyboard><br />
</VideoMenu><br />
</keymap><br />
}}<br />
<br />
* Restart kodi which will read in these changes.<br />
* Navigate to ''System > Player > Videos > Playback'' and enable "Sync playback to display" option.<br />
<br />
=== Modify default values for watch and resume points ===<br />
<br />
Some users may wish to make the thresholds Kodi uses to create a resume point/consider a video "watched" entirely. Do so by editing {{ic|~/.kodi/userdata/advancedsettings.xml}} inserting the following three xml fields:<br />
<br />
* '''ignoresecondsatstart''': the number of seconds to wait before keeping track of the start point. If users watch a value below the one defined, no start point is recorded. Default is 180.<br />
* '''playcountminimumpercent''': the percentage of total play time to consider something watched. If users watch more of the video that this number but not the entire video, it is considered watched and any previously recorded resume point is deleted upon stopping and finally, the video is flagged as watched. Default is 90.<br />
* '''ignorepercentatend''': the percentage of total play time at the end of a video to ignore making a resume point. This is related to the previous setting except it considers the last x percent of the video. If users watch enough content to enter this space of the file, no resume point is saved and the video is flagged as watched. Default is 8.<br />
<br />
{{hc|~/.kodi/userdata/advancedsettings.xml|2=<br />
<advancedsettings><br />
<video><br />
<!-- see https://kodi.wiki/view/HOW-TO:Modify_automatic_watch_and_resume_points --><br />
<ignoresecondsatstart>10</ignoresecondsatstart><br />
<playcountminimumpercent>90</playcountminimumpercent><br />
<ignorepercentatend>8</ignorepercentatend><br />
</video><br />
</advancedsettings><br />
}}<br />
<br />
=== CLI for kodi ===<br />
<br />
* {{pkg|kodi-eventclients}} package provides {{ic|kodi-send}} which can send valid [https://kodi.wiki/view/Action_IDs kodi action] or [https://kodi.wiki/view/List_of_built-in_functions#List_of_functions kodi function] to kodi from the shell.<br />
<br />
* {{AUR|texturecache}} can handle many aspects of library management, from clean-up of unused images, to searching, to querying what is currently playing.<br />
<br />
=== Hardware video acceleration ===<br />
<br />
Enable and configure [[hardware video acceleration]] to speed up playback performance.<br />
<br />
Restart Kodi and enable the hardware backend(s) in Playback under Settings.<br />
<br />
=== Use Kodi to view security camera streams (rtsp or rtmp) ===<br />
<br />
Since Kodi uses ffmpeg for video playback, it is able to play streams such as rtsp and rtmp can be viewed. To do so, simply create a txt file in the filesystem exposed to the kodi user containing the stream. For example:<br />
$ cat front-door.strm<br />
rtsp://username:password@10.1.10.101<br />
<br />
Optionally meta-data, such as cover art and summaries can also be associated to the .strm file just like normal entries in a library by using an NFO file.<br />
<br />
=== UPnP and DLNA ===<br />
<br />
Go to ''Settings > Services > UPnP/DLNA'' and toggle ''Enable UPnP support''.<br />
<br />
=== Adjusting CD/DVD drive speed ===<br />
<br />
The ''eject'' program from the {{Pkg|util-linux}} package does a nice job for this, but its setting is cleared as soon as the media is changed.<br />
<br />
This udev-rule reduces the speed permanently:<br />
<br />
{{hc|/etc/udev/rules.d/dvd-speed.rules|2=<br />
KERNEL=="sr0", ACTION=="change", ENV{DISK_MEDIA_CHANGE}=="1", RUN+="/usr/bin/eject -x 2 /dev/sr0"<br />
}}<br />
<br />
Replace {{ic|sr0}} with the device name of the optical drive. Replace {{ic|-x 2}} with {{ic|-x 4}} if the preference is 4x-speed instead of 2x-speed.<br />
<br />
After creating the file, reload the udev rules with<br />
<br />
# udevadm control --reload<br />
<br />
=== Use port 80 for webserver ===<br />
<br />
Kodi has a webservice that allows interaction through a web-interface. By default, it uses port {{ic|8080}} as {{ic|80}} requires root privileges. Use the following to permit it to use low port numbers:<br />
<br />
# setcap 'cap_net_bind_service=+ep' /usr/lib/kodi/kodi.bin<br />
<br />
Restart Kodi and set port {{ic|80}} in the configuration menu (''Services > Webserver > Port'').<br />
<br />
=== Using ALSA ===<br />
<br />
If [[PulseAudio]] does not work properly, try using [[ALSA]] directly by starting Kodi with the {{ic|1=KODI_AE_SINK=ALSA}} [[environment variable]]. The Kodi wiki for NUC devices provides [https://kodi.wiki/view/Archive:Install_Kodi_on_an_Intel_NUC#disable_PulseAudio instructions]<br />
<br />
If using {{ic|kodi-standalone}}, change the {{ic|APP}} variable in {{ic|/usr/bin/kodi-standalone}} to<br />
<br />
APP="${bindir}/pasuspender -- env KODI_AE_SINK=ALSA ${bindir}/${bin_name} --standalone $@"<br />
<br />
If the above fix still does not work with kodi-standalone try editing the following<br />
<br />
{{hc|/usr/bin/kodi-standalone|<nowiki><br />
systemctl --user mask pulseaudio.socket<br />
systemctl --user stop pulseaudio<br />
<br />
APP=Kodi<br />
prefix="/usr"<br />
exec_prefix="/usr"<br />
bindir="/usr/bin"<br />
bin_name=kodi<br />
APP="${bindir}/${bin_name} --standalone $@"<br />
<br />
#PULSE_START="$(command -v start-pulseaudio-x11)"<br />
#if [ -n "$PULSE_START" ]; then<br />
# $PULSE_START<br />
#else<br />
# PULSE_SESSION="$(command -v pulse-session)"<br />
# if [ -n "$PULSE_SESSION" ]; then<br />
# XBMC="$PULSE_SESSION $XBMC"<br />
# fi<br />
#fi<br />
<br />
</nowiki>}}<br />
<br />
=== Audio Passthrough ===<br />
<br />
One can allow an external receiver or sound bar to decode audio by enabling passthrough. This is useful for files encoded in TrueHD or Atmos. If using PulseAudio, follow the instructions at https://kodi.wiki/view/PulseAudio to first enable passthrough in PulseAudio. Once complete, the corresponding passthrough options should appear in Kodi. If using ALSA, the passthrough options will appear in Kodi without modifications provided that the {{ic|1=AE_SINK=ALSA}} environment variable is defined prior to starting kodi.<br />
<br />
{{Warning|PulseAudio requires the output in Kodi to be set to 2 channel. Audio encoded in formats not passed through will only be sent as stereo audio. Use ALSA to support passthrough and passing decoded surround audio signals}}<br />
<br />
{{Note|PulseAudio does not support TrueHD, DTS-MA, or Atmos passthrough. Use ALSA to pass these to through the receiver.}}<br />
<br />
Another way of getting TrueHD and DTS-MA passthrough without disabling Pulseaudio or Pipewire-Pulse is to use an external player like MPV, first create the file {{ic|~/.kodi/userdata/playercorefactory.xml}} then paste the following into it:<br />
<br />
<playercorefactory><br />
<players><br />
<player name="MPV" type="ExternalPlayer" audio="false" video="true"><br />
<filename>/usr/bin/mpv</filename><br />
<args>--fs=yes "{1}"</args><br />
<hidexbmc>true</hidexbmc><br />
</player><br />
</players><br />
<rules action="prepend"><br />
<rule video="true" player="MPV"/><br />
</rules><br />
</playercorefactory><br />
<br />
{{Merge|mpv|Appears to partially duplicate [[mpv#Specify an audio output]] and [[mpv#HD Audio passthrough]].}}<br />
<br />
MPV should now be the default media player for Kodi, now you need to set the correct audio output device for MPV, you can use the following command to show a list of available audio devices:<br />
<br />
$ mpv --audio-device=help<br />
<br />
For example:<br />
<br />
alsa/hdmi:CARD=NVidia,DEV=1<br />
<br />
Now edit {{ic|~/.config/mpv/mpv.conf}} and add the following lines:<br />
<br />
audio-spdif=ac3,eac3,dts-hd,truehd<br />
audio-device=alsa/hdmi:CARD=NVidia,DEV=1<br />
<br />
To have auto switching of refresh rates create the following folder {{ic|~/.config/mpv/scripts}} then download and place [https://github.com/lvml/mpv-plugin-xrandr/blob/master/xrandr.lua mpv-plugin-xrandr/xrandr.lua] into the scripts folder you just created.<br />
<br />
=== Kodi JSON-RPC API to alter settings from external tools ===<br />
Users can interact directly with Kodi on the CLI or from a python script etc. by making use of the [https://kodi.wiki/view/JSON-RPC_API/v12 JSON-RPC API].<br />
<br />
For example, using {{pkg|curl}}:<br />
$ curl -v -H "Content-type: application/json" -d \<br />
'{"jsonrpc":"2.0","id":1,"method":"Settings.GetSettingValue","params":{"setting":"audiooutput.audiodevice"}}' \<br />
http://localhost:8080/jsonrpc -u xbmc:xbmc<br />
<br />
Another example is [https://github.com/graysky2/streamzap/blob/master/kodi/audio_switch/audio_switch.py this python script] which simply toggles between two groups of settings, in this case, toggling the audio source back-and-forth between HDMI and optical out.<br />
<br />
=== Fix for delayed startup on wifi ===<br />
<br />
If running with WiFi only (wired network unplugged) while [[#Sharing media and a centralized database across multiple nodes]], kodi will likely start before the wireless network is up, which will result in failure to connect to the shares and to the SQL server. Assuming the network is managed by the default [[systemd-networkd]], this can be fixed by using a [[Systemd#Drop-in files]] for {{ic|systemd-networkd-wait-online.service}}:<br />
<br />
# systemctl edit systemd-networkd-wait-online.service<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --ignore eth0<br />
<br />
=== Run kodi in a window manager ===<br />
<br />
Users running kodi in a [[Window manager]] may see a black screen at exit. To fix this, try switching to another tty. A possible solution is to run kodi with this script (running as the root user):<br />
<br />
{{hc|kodi.sh|<br />
#!/bin/bash<br />
kodi-standalone<br />
sudo chvt 2 <br />
sleep 1<br />
sudo chvt 1<br />
}}<br />
<br />
To make sure that [[sudo]] does not ask for password for {{ic|chvt}} add this line to {{ic|sudoers}} file:<br />
<br />
{{hc|/etc/sudoers|<br />
''UserNameHere'' ALL&#61;NOPASSWD: /usr/bin/chvt<br />
}}<br />
<br />
=== USB DAC not working ===<br />
<br />
Users of USB DAC/sound cards may experience distorted sound/clicks/pops or no sound at all when selecting it from Audio settings. A possible fix: <br />
<br />
Open {{ic|guisettings.xml}} (it should be under {{ic|/var/lib/kodi/.kodi/userdata/}} if using the supplied {{ic|kodi-xxx.service}}) and change<br />
<br />
<processquality default="'''true'''">'''101'''</processquality><br />
<br />
to<br />
<br />
<processquality default="'''false'''">'''100'''</processquality><br />
<br />
=== Virtual file system support ===<br />
<br />
Kodi provides addons for accessing various virtual file systems from within Kodi. RAR archives can be accessed using {{AUR|kodi-addon-vfs-rar}}. SFTP shares can be accessed using {{AUR|kodi-addon-vfs-sftp}}. Super Audio CD ISO files can be access using {{AUR|kodi-addon-vfs-sacd}}. Each of these addons must be enabled within Kodi's addon manager in order to be utilized.<br />
<br />
=== Inhibit KDE automatic sleep during playback ===<br />
<br />
Using the add-on [https://sourceforge.net/projects/osscreensavermanager/ ossscreensavermanager] in combination with commands using kwriteconfig5 it is possible to inhibit KDE's power saving functions during playback. Install the add-on, then under its advanced settings write under "Command to suspend screen saver":<br />
<br />
kwriteconfig5 --file powermanagementprofilesrc --group AC --group SuspendSession --key idleTime 1800000<br />
<br />
Under "Command to resume screen saver", write:<br />
<br />
kwriteconfig5 --file powermanagementprofilesrc --group AC --group SuspendSession --key idleTime 86400000<br />
<br />
In this example, the system suspends after 360 minutes during playback, and after 30 minutes without playback.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Accessing Kodi logs ===<br />
<br />
In case of an error the first point to start investigation can be {{ic|~/.kodi/temp/kodi.log}}.<br />
<br />
=== Fullscreen mode stretches Kodi across multiple displays ===<br />
<br />
For a multi-monitor setup, Kodi may default to stretching across all screens. One can restrict the fullscreen mode to one display by setting the [[environment variable]] {{ic|SDL_VIDEO_FULLSCREEN_HEAD}} to the number of the desired target display. For example, having Kodi show up on display 0, add the following line to the Kodi user's {{ic|~/.bashrc}} configuration:<br />
<br />
SDL_VIDEO_FULLSCREEN_HEAD=0<br />
<br />
{{Note|Mouse cursor will be held inside screen with Kodi.}}<br />
<br />
=== H.264 playback is using only a single core ===<br />
<br />
{{Tip|By default, press {{ic|O}} during playback to show codec information and CPU usage. More information about this overlay can be found at https://kodi.wiki/view/Codecinfo.}}<br />
<br />
If the hardware does not or cannot make use of acceleration, disable it and explicitly set video decoding to software.<br />
This is because [https://forum.kodi.tv/showthread.php?tid=170084&pid=1789661#pid1789661 H.264 decoding is only multithreaded when video decoding is set to software].<br />
<br />
To achieve this, go to ''System Settings > Video''. Set the {{ic|settings level}} to {{ic|Advanced}} or {{ic|Expert}}. Then go to ''Acceleration'' and set {{ic|Decoding method}} to {{ic|software}}.<br />
<br />
=== Kodi hangs on exit, fully occupying one CPU core, UI unresponsive ===<br />
<br />
This problem can arise with third-party plugins installed, there is some issue with their termination[https://www.linuxquestions.org/questions/linux-software-2/kodi-freezes-on-exit-kodi-bin-won't-die-4175588180/],[https://www.reddit.com/r/archlinux/comments/5029oo/kodi_freezes_on_exit_kodibin_wont_die/].<br />
<br />
Workaround: find proper UI description file ({{ic|DialogButtonMenu.xml}}) and tweak exit button type from internal Kodi's {{ic|Quit()}} function call to sending signal from outside system to Kodi. Here is one-liner that makes modifications to any skin from the default Kodi package:<br />
<br />
# find /usr/share/kodi/addons/skin.* -name DialogButtonMenu.xml -exec sed -i 's%<onclick>Quit()</onclick>%<onclick>System.Exec ("killall --signal SIGHUP kodi.bin")</onclick>%' {} \;<br />
<br />
=== kodi-standalone will not play DVDs ===<br />
<br />
If kodi-standalone will not play DVDs, it may help to install [[udisks]].<br />
<br />
== See also ==<br />
<br />
* [https://kodi.wiki/view/Main_Page Kodi Wiki] - Excellent resource with much information about Arch Linux specifically<br />
* [[Wikipedia:Kodi (software)]]<br />
* http://www.hdpfans.com/thread-329076-1-1.html - Kodi/xbmc Chinese plug-in library installation method<br />
* https://github.com/taxigps/xbmc-addons-chinese - xbmc-addons-chinese: Addon scripts, plugins, and skins for XBMC Media Center. Special for chinese laguage.</div>PXfhttps://wiki.archlinux.org/index.php?title=Arch_Testing_Team&diff=700747Arch Testing Team2021-11-04T15:15:10Z<p>PXf: /* Guidelines */ [typo] package that ships executable packages -> package that ships executables (pkg don't ship pkg)</p>
<hr />
<div>[[Category:Arch development]]<br />
[[Category:Teams]]<br />
[[es:Arch Testing Team]]<br />
[[ja:Arch テストチーム]]<br />
[[pt:Arch Testing Team]]<br />
[[zh-hans:Arch Testing Team]]<br />
The Arch Testing Team is a group within the Arch community in charge of making sure that packages submitted to the [[testing]] repositories are functional. This includes, making sure that the package installs correctly, that it does not cause breakage with packages of which it depends on, among others.<br />
<br />
Arch Testers [[DeveloperWiki:CoreSignoffs|sign off]] packages after vouching for their correctness so that they can be moved from the ''testing'' repositories into the ''core'', ''extra'' or ''community'' repositories.<br />
<br />
== Contributing ==<br />
<br />
You can apply to be an official Arch tester by contacting [https://archlinux.org/people/developers/#bluewind Florian Pritz] via [mailto:bluewind@xinu.at email] and requesting a [https://lists.archlinux.org/pipermail/arch-dev-public/2016-July/028191.html tester account]. <br />
<br />
If you are given a tester account, you should be able to log in into [https://archlinux.org/devel archweb] and see a ''signoffs'' tab on it. The ''signoffs'' tab will contain a list of packages that are currently in the testing repositories and need at least two ''signoffs'' (i.e., a rubber-stamp vouching for the correctness of a package). <br />
<br />
You may then test the listed packages locally and signing them off if they are correct by clicking on the ''signoff'' button for each package.<br />
<br />
{{Tip|You can simplify the process by signing off packages from the command line with {{man|1|signoff}} from the {{Pkg|arch-signoff}} package.}}<br />
<br />
== Guidelines ==<br />
<br />
In order to test an arch package, keep the following aspects in mind:<br />
<br />
* If you are testing a kernel or a package that relies on kernel modules, you '''should restart the machine and ensure that it boots correctly'''<br />
* Although testing on virtualization software is not prohibited, it may not be as useful as testing a package in a bare-metal installation. This applies specially to packages that are susceptible to different types of hardware, such as kernel packages.<br />
* If you are testing a library, you may want to execute a binary that uses such library. Make sure the shared object file is loaded using ldd.<br />
* Likewise, if there is a package that ships executables, testing their basic functionality is encouraged.<br />
* If you notice an error when testing a package, add a detailed bug report on the [https://bugs.archlinux.org/ bugtracker]:<br />
** Package name, version and pkgrel<br />
** Which component of the package was the one to error (e.g., one of the binaries, or a configuration file)<br />
** Root of the error (e.g., during installation, or usage, etc.)<br />
** Any relevant error messages/logs<br />
** Make sure the bug is filed with the category ''Packages: Testing''<br />
<br />
== Coordination ==<br />
<br />
{{Note|It is expected that people using the ''testing'' repositories frequently check the [https://lists.archlinux.org/listinfo/arch-dev-public arch-dev-public] mailing list for any announced changes or considerations affecting testing users.}}<br />
<br />
You can coordinate with other testers on the [ircs://irc.libera.chat/archlinux-testing #archlinux-testing] IRC channel.<br />
<br />
You can follow updates by packager activity on the [https://lists.archlinux.org/pipermail/arch-commits arch-commits] mailing list (high traffic).</div>PXfhttps://wiki.archlinux.org/index.php?title=Pgp&diff=698977Pgp2021-10-13T07:35:17Z<p>PXf: redirect "pgp" to "GnuPG"</p>
<hr />
<div>#redirect [[GnuPG]]</div>PXfhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=698976User talk:Lahwaacz2021-10-13T06:45:52Z<p>PXf: /* cow_* */ re: re:</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== The pip section in [[Python package guidelines]] ==<br />
<br />
Hi, you wanted the warning about using pip or wheels restored but accidentally(?) reverted my whole set of changes. I redid them, leaving the warning in place. – [[User:Flying sheep|flying sheep]] 08:17, 8 March 2019 (UTC)<br />
<br />
:Full revert was intentional, because the "wheel" section is not a full replacement for "pip" because there are packages which don't provide wheel files. As I said in the edit summary, there is no reason to recommend one or the other due to the warning. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:21, 8 March 2019 (UTC)<br />
::That still doesn’t explain why you reverted the first part, that had nothing to do with the pip/wheel section and simple improves the files.pythonhosted.org URLs. I restored that one while we’re discussing the pip/wheel section. And about that: There’s no reason to use pip for anything else, and pip is only used because some people (me included) didn’t understand that you can install most wheels by just extracting them to the correct location. So what do you think is missing from my wheels section that the former pip section had? – [[User:Flying_sheep|flying sheep]] 11:41, 11 March 2019 (UTC)<br />
<br />
:::If you didn't notice, the page includes "guidelines" in the title. So the page should contain only common and recommended ways to do things, not everything that is possible to do. If you think that your way to install "wheels" should be followed by everybody, feel free to discuss it on the talk page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:26, 11 March 2019 (UTC)<br />
::::Well, extracting static archives sounds much more recommended than running pip with like 7 options to make it behave. I added a talk item: [[Talk:Python package guidelines#Remove_pip_section_in_favor_of_wheels_section?]] – [[User:Flying_sheep|flying sheep]]<br />
<br />
== wpa_supplicant ==<br />
<br />
Regarding https://wiki.archlinux.org/index.php?title=WPA_supplicant&diff=577215&oldid=577167, one person ran into this problem in March of this year and spent too much time diagnosing it:<br />
<br />
https://bbs.archlinux.org/viewtopic.php?id=244950<br />
<br />
It took me a few days to find the problem. I want to make sure the next time someone encounters it, they easily find relevant information about what the cause is. Since you've reverted my edits to both netctl and wpa_supplicant, what do you suggest?<br />
<br />
--<br />
<br />
[[User:Pooryorick|Pooryorick]] ([[User talk:Pooryorick|talk]]) 08:24, 18 July 2019 (UTC)<br />
<br />
== F2FS and GRUB ==<br />
<br />
Hello. :) I'm here to address a recent disagreement. I noticed a reversion of my edit regarding the F2FS filesystem, in particular regarding the configuration file to edit (with you representing /boot/grub/grub.cfg and me representing /etc/default/grub). I run F2FS on my daily driver with an encrypted root filesystem and encrypted boot on a separate partition, and have never had to touch grub.cfg. I only automatically generate it. It's possible to use either, but /etc/default/grub would make more sense as a recommendation in my mind because grub.cfg has the potential to be overwritten during updates, whereas /etc/default/grub doesn't. <br />
<br />
If there's a compelling reason to use grub.cfg over /etc/default/grub, please let me know. ^^ I'm always eager to learn more about Arch. I don't want to get in a reversion war so I've left your change untouched for the time being.<br />
<br />
[[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 00:17, 8 September 2019 (UTC)<br />
<br />
:The reason is explained in the section: "If GRUB is used with an unsupported filesystem it is not able to extract the UUID of your drive so it uses classic non-persistent /dev/sdXx names instead." If it does not apply to F2FS, it should be made clear. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:29, 8 September 2019 (UTC)<br />
<br />
::You can specify UUID's in GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, so my proposed solution would work for F2FS and other unsupported filesystems, without the burden of manually editing grub.cfg. If there's anything I need to clarify or something else I'm missing, just let me know. :) [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 19:37, 8 September 2019 (UTC)<br />
<br />
:::The {{ic|1=root=}} parameter is not supposed to be in GRUB_CMDLINE_LINUX_DEFAULT, regardless if UUID is used or not. ''grub-mkconfig'' automatically detects the root filesystem and adds the appropriate {{ic|1=root=}} parameter based on GRUB_DISABLE_LINUX_UUID. In any case, your change to the paragraph does not make sense. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:02, 8 September 2019 (UTC)<br />
<br />
::::It could simply be because I use full disk encryption, and adding a kernel parameter for the encrypted disk's UUID is correct in that situation. You're more experienced with contributing to the wiki, so I guess I'll defer to your judgment. It felt like a reasonable edit and solution to me and I don't see the downside to including it in GRUB_CMDLINE_LINUX_DEFAULT. [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 05:38, 9 September 2019 (UTC)<br />
<br />
== dracut executable link ==<br />
<br />
Hello, your last edit on the dracut page (https://wiki.archlinux.org/index.php?title=Dracut&oldid=596388) that undid my 'Link to direct "make executable" section for executable link' commit states: "the redirect executable points exactly to that section", but it doesn't. Following the [[executable]] link just points to the top of the Help:Reading page.<br />
<br />
{{unsigned|17:06, 28 January 2020|Krathalan}}<br />
<br />
:In that case your browser probably does not work correctly, because the redirect [https://wiki.archlinux.org/index.php?title=Executable&redirect=no really points to the section]. Or MediaWiki, there was a bug several years ago... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 28 January 2020 (UTC)<br />
<br />
:: How strange... thanks for pointing that out. It does indeed appear to be some issue with my Firefox configuration. [[User:Krathalan|Krathalan]] ([[User talk:Krathalan|talk]]) 19:51, 28 January 2020 (UTC)<br />
<br />
== Getting install.php work in DokuWiki ==<br />
<br />
Hi, than you for having undone my contribution and pointed to the right solution on [[Dokuwiki#Configuration]]. Indeed I had read this solution before, but I was misled by the condition "if you are using lighttpd or nginx and your PHP version is lower than 7": as I use Apache with php v. 7.4.3 I didn't take it into account. Do you know what a correct rephrasing could be? Maybe it should be deleted?<br />
<br />
Also, I think that, at the end of this same section, one should add something like "verify that {{Pkg|php-gd}} is installed and restart {{ic|php-fpm.service}}".<br />
<br />
Naturally I can do it myself, but I prefer to ask before.<br />
[[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 17:31, 19 February 2020 (UTC)<br />
<br />
:Hi, apparently it depends on whether you had {{ic|open_basedir}} set previously or not. I've changed the page, feel free to update the gd extension. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:16, 19 February 2020 (UTC)<br />
<br />
::Thank you! However, while, I didn't have {{ic|open_basedir}} set previously, I couldn't access ''install.php''. I suspect there is another thing to do, since the configuration editor in DokuWiki complains that it cannot modify the configuration files although ownership and permissions are correctly set for the relevant symlinks, directories and files, and so is {{ic|open_basedir}}. However I can edit my pages. Maybe a return from a new user with a fresh installation would be more useful, though. [[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 08:20, 20 February 2020 (UTC)<br />
<br />
== Dead link in Simple stateful firewall#See Also ==<br />
<br />
Hi, Jakub. I am about [https://wiki.archlinux.org/index.php?title=Simple_stateful_firewall&diff=599725&oldid=599717 this] edit. I tried to follow that link one more time and it is not require entering captcha. I am not see any content limitations and my colleague (he uses Tor) does not see them too. I am not sure how it works, so I leave it on your descision. -- [[User:Duodai|Duodai]] ([[User talk:Duodai|talk]]) 14:29, 1 March 2020 (UTC)<br />
<br />
:Well, maybe it depends on the location from which the request comes. But I don't know how it works either... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:33, 1 March 2020 (UTC)<br />
<br />
::my guess is it returns captcha for crawlers only -- [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 01:59, 2 March 2020 (UTC)<br />
<br />
:::I'm getting it in my browser... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:14, 2 March 2020 (UTC)<br />
<br />
== SystemD user units depending on graphical session ==<br />
Hi,<br />
regarding reverting my addition to [[Systemd/User]], could you please explain why? I referenced [[https://www.freedesktop.org/software/systemd/man/systemd.special.html]] which directly contradicts what you said in your summary.<br />
<br />
{{unsigned|19:53, 5 May 2020|Fuero}}<br />
<br />
:The note in [[Systemd/User#How it works]] still applies - systemd services are never per-session, but per-user. The service does not magically get the correct DISPLAY or WAYLAND_DISPLAY variable, it does not work if you have multiple sessions per user, etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:45, 6 May 2020 (UTC)<br />
<br />
== Plymouth ==<br />
<br />
Actually with just Plymouth it does not work properly. Even 0dd17y had the same issue in https://bbs.archlinux.org/viewtopic.php?id=220900.<br />
<br />
The reason I did not file a bug report is that it is anyway fixed in the git version and the latest release (0.9.4) is around 2 years behind master<br />
<br />
{{unsigned|09:50, 6 May 2020|M.Srikanth}}<br />
<br />
:So if you don't have to file a bug report, add a full troubleshooting entry or at least properly reference your inline note instead of resorting to plain "if that does not work, try this instead". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:15, 6 May 2020 (UTC)<br />
<br />
== [Bitcoin core] build the code and run the test suites ==<br />
<br />
Hello,<br />
<br />
This week, I managed to build the Bitcoin code and run all the test suites with the help of this page: https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests<br />
<br />
Archlinux has two particularities:<br />
* being in rolling release, it takes to manually use the library {{ic|Berkeley DB (BDB) v4.8}}<br />
* the {{ic|/tmp}} directory is by default limited to half the size of the Ram<br />
<br />
For these reason, maybe it could be interesting to have a page in the wiki to explain how to build the Bitcoin core?<br />
<br />
Cheers,<br />
<br />
Thomas<br />
<br />
[[User:Thomasb|Thomasb]] ([[User talk:Thomasb|talk]]) 20:29, 9 May 2020 (UTC)<br />
<br />
:I don't think that this is useful. There is the {{AUR|bitcoin-core-git}} package and nothing more should be needed. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:53, 26 May 2020 (UTC)<br />
<br />
== Double linefeed results in extra line ==<br />
<br />
If you look at templates that end with double linefeed before noinclude this would result in extra line in resulting page.<br />
<br />
It may be a minor point but since you are perfectionist about wikitext I should mention this is a tradeoff and it results in slightly worse result.<br />
<br />
Removing just one linefeed removes the problem while still allowing it to not jumble all the tags into same line.<br />
<br />
-- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 16:30, 11 May 2020 (UTC)<br />
<br />
:If this is about [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=next&oldid=612179], the spaces I added back are not included when the template is used elsewhere, because the spaces are inside the noinclude tags. The extra space is only on the template page itself, but it does not result from template inclusion. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:41, 11 May 2020 (UTC)<br />
<br />
::OFC, I mean the template page render has extra line. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 21:21, 11 May 2020 (UTC)<br />
<br />
:::I agree with [[User:Svito|Svito]], isn't it good to delete the extra blank lines? -- [[User:Blackteahamburger|Blackteahamburger]] ([[User talk:Blackteahamburger|talk]]) 05:39, 12 May 2020 (UTC)<br />
<br />
::::OK, let's do it. [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=616382&oldid=612181] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:47, 26 May 2020 (UTC)<br />
<br />
== Re: lighttpd: remove python2 version ==<br />
<br />
Instead of removing the example we could as well add an example using a Python3 library like https://pypi.org/project/flup6/.<br />
<br />
{{unsigned|15:23, 18 May 2020|Gruentee}}<br />
<br />
:Feel free to add it if you find it useful. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:56, 18 May 2020 (UTC)<br />
<br />
== Xbindkeys removal ==<br />
<br />
Hi, just wondering why you [https://wiki.archlinux.org/index.php?title=Xbindkeys&diff=617675&oldid=617670 removed my edit] from [[Xbindkeys]]? The xbindkeys page has a number of quick tips but no mention of how to bind anything to the Print Screen key so I thought it would be useful to add. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:27, 3 June 2020 (UTC)<br />
<br />
:Giving examples for all keys on the keyboard is useless, there is [[Xbindkeys#Identifying keycodes]] which teaches how to find the keycodes and keysyms of any key. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 3 June 2020 (UTC)<br />
<br />
:: So how come you left the examples for the volume up/down and brightness? What is different between those examples and a screenshot example? Aren't more examples better to save people from hunting all over the place trying to piece things together themselves? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 14:03, 4 June 2020 (UTC)<br />
<br />
:::The difference is that when it comes to volume control, there are 1 or 2 options for the 99% most common cases, but for screenshot taking there are dozens of different options. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:15, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for edit to XDG Base Directory page regarding python_history ==<br />
<br />
I understand the justification for reverting the change I made, however I would like to point out that similar entries on the page (such as Maven) also have instructions for what contents to put in files (even though there is native documentation for those settings). Additionally, it took me a bit of re-reading on the linked Python documentation to reason out how the documentation's example needed to be modified, since it's not clear from the Python documentation whether placing such code in the PYTHONSTARTUP file will actually ''override'' the default behavior. [[User:Varriount|Varriount]] ([[User talk:Varriount|talk]]) 20:44, 20 June 2020 (UTC)<br />
<br />
:Even maven's note can be [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=631704&oldid=631630 shortened]. The notes in the table must be as short as possible, there is no place for extended explanations or long code snippets like in the upstream documentation. If the Python's documentation is not clear enough, I don't think any note in a massive convoluted table will ever be better. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:47, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for Backlight page ==<br />
<br />
Hi, you reverted my change to [[Backlight]] page that mentioned WIP patches for controlling OLED panel brightness. I don't really understand justification for reverting it since currently the page says that OLED brightness can be controlled only by changing gamma ramp. That is wrong - since it's not the only way - these panels can control brightness with a PWM. Moreover controlling brightness with gamma ramp is not optimal - it essentially reduces dynamic range, i.e. at 50% you have 7 bits per pixel, at 25% - 6 bit per pixel, etc. That results in banding artifacts at lower brightness level.<br />
<br />
As far waiting for the patches to be merged before mentioning it there - it'll take ~3-6 months (yes, that's the process) and I haven't found *any* reference to these changes on the internet - everyone recommends using gamma ramp instead of fixing it properly. I'm absolutely sure that having information about these patches would not hurt [[User:Anarsoul|Anarsoul]] ([[User talk:Anarsoul|talk]]) 15:56, 30 June 2020 (UTC)<br />
<br />
:Linking to a repo which which has 2 custom commits on top of some arbitrary development version of the Linux kernel tree is not helpful for users. Nobody will compile directly from this repo which is already significantly outdated compared to recent kernel versions and there is no indication if the patches actually work with newer (or older) kernels. We can mention the PWM control as a general concept though. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:32, 12 August 2020 (UTC)<br />
<br />
== Automatic template correction ==<br />
<br />
Per [[Help:Template#Style]], templates should be used with the capitalization shown in the examples in their pages, so {{ic|&#123;{AUR&#124;...}} is correct, while {{ic|&#123;{aur&#124;...}} is not.<br />
<br />
However, there are pages that don't respect that rule (e.g. [[Android_Debug_Bridge]] until recently).<br />
<br />
I beleive this correction should be easy to implement using a bot. What do you think?<br />
<br />
{{unsigned|07:24, 25 August 2020|Relrel}}<br />
<br />
:Yes, this should be easy, but the bot should not make a huge amount of simple style-only changes - they should be combined with corrections for more complex rules. Anyway, there is an idea to create a [https://github.com/lahwaacz/wiki-scripts/issues/22 style linter] for the ArchWiki rules. Would you like to help? ;-) – [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:21, 25 August 2020 (UTC)<br />
<br />
== Failed to create tun device ==<br />
<br />
I don't understand your reason for [[https://wiki.archlinux.org/index.php?title=NetworkManager&diff=0&oldid=634880 removing my section in NetworkManager]]. Could you elaborate?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 07:40, 11 September 2020 (UTC)<br />
<br />
:You can't use [[systemd-networkd]] and [[NetworkManager]] at the same time. Even if you don't have any ''.network'' file for systemd-networkd, you can't solve NetworkManager's problems with systemd-networkd. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:43, 11 September 2020 (UTC)<br />
<br />
::Ok, thanks, in this case it solved the error I got. Now the VPN works. Do you have an idea about how to solve it without systemd-networkd?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 22:27, 11 September 2020 (UTC)<br />
<br />
:::You should really fix the permission problem for {{Pkg|networkmanager-openvpn}}. The tun interface should be managed by OpenVPN which needs rights to create it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 12 September 2020 (UTC)<br />
<br />
::I don't think this statement is entirely correct. [[systemd-networkd]] and [[NetworkManager]] can happily co-exist together if they are managing different interfaces. I unfortunately don't have a reference to point to this, but I came across this being mentioned a couple of times on forums. I personally use [[NetworkManager]] on my laptop to handle wifi, while [[systemd-networkd]] is in control of virtual ethernet and bridges for all my [[systemd-nspawn]] instances. [[User:Romstor|Romstor]] ([[User talk:Romstor|talk]]) 03:24, 12 September 2020 (UTC)<br />
<br />
== [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&oldid=636526/ XDG Base Directory]: Undo revision 636525 ==<br />
<br />
Dear Lahwaacz,<br />
<br />
maybe my changes were to rushed and from my point of view only. But I have two points to consider:<br />
<br />
# If I put the quotes around my vimrc and source it from my .bash_profile, I get the vim-error E471 (Argument required). Without quotes, this doesn't happen. So this change based on experience.<br />
# The rtp should includes directories, which are needed at runtime. (in plain vim e.g. ~/.vim). This is not a typical configuration directory. My mistake was, that I supposed that everyone put their vim plug-ins in $XDG_DATA_HOME and not in $XDG_CONFIG_HOME, because from my point of view a plug-in doesn't belong to the configuration. Maybe it is a good idea to add a remark, which explains the addition of $XDG_CONFIG_HOME to the rtp.<br />
<br />
[[User:Grrr|Grrr]] ([[User talk:Grrr|talk]]) 13:53, 26 September 2020 (UTC)<br />
<br />
# Quotes are there because $XDG_CONFIG_HOME may contain spaces.<br />
# It's not only about quotes - the runtimepath has subdirectories for color schemes, keymaps, autoload scripts etc.<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 26 September 2020 (UTC)<br />
<br />
== Readability in Wiki ==<br />
<br />
I noticed that you and the other admins and moderators often want sentences to continue endlessly, without line breaks.<br />
For example in the introduction of [[Wayland]].<br />
<br />
I think it would be better to have more seperated sentences, so it is easier to read and "important" information is easier visible for people.<br />
I don't know who is responsible, but maybe some options in MediaWiki (or whatever this wiki software is) could be changed as well, to make make line breaks etc. easier and reduce the height-space (if you know what I mean) between sentences, so it looks better, even though line breaks are used.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:38, 15 October 2020 (UTC) G3ro<br />
<br />
:I don't know exactly what you mean. Is it about the readability of the rendered HTML or the "source code" of the page? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 15 October 2020 (UTC)<br />
<br />
:: Well I guess it can be about both. But mainly it is about what people see on the page.<br />
:: There are three seperate topics I mentioned:<br />
<br />
:: 1. Use line breaks: I would like to use more line breaks, because if you have long sentences that are written after each other without line breaks, it gets "harder" to recognize when the next sentence starts.<br />
:: While I agree to what you said somewhere, that sentences that belong directly together, should be written in one "paragraph", it would be useful for sentences that cover (slightly) different "topics" to be visibly parted.<br />
<br />
:: 2. Adjust margin options: I notice that when line breaks are used, there is a vertical space added between two sentences. Just like in this post. If you would use line breaks more often, this is a little too much spacing in my oppinion.<br />
<br />
:: 3. Potential options to make line breaks easier: It would be very convenient if a line break in the source code would lead to a line break in displayed text as well, instead of needing to add an empty line.<br />
<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:33, 15 October 2020 (UTC) G3ro<br />
<br />
:::OK, now I understand. I agree that splitting different topics usually improves legibility, but they should be split into separate paragraphs and not just by line breaks (e.g. using the &lt;br> tags). Paragraphs are semantic units whereas line breaks inside a paragraph are usually typographic errors.<br />
:::Also note that such splitting alone may not be enough to improve the text flow. For example, if we consider the intro for [[Wayland]], the second sentence about XWayland would not constitute a good paragraph - it is just a plain statement and the new topic is not nicely introduced. Ideally, you'd split the topic and make some wording changes for the second paragraph.<br />
:::As for the margin options, that is the difference between paragraph splitting and non-semantic line breaks. In my opinion, the styling is correct in this respect, as paragraphs should be discernible. You mentioned that you like line breaks to easily recognize where a sentence ends - but reading should be based on whole paragraphs, not sentences. There should be no reason to skip anything in the middle of a paragraph, otherwise it should be probably split into multiple paragraphs or otherwise rephrased.<br />
:::If you find it hard to follow a long sentence horizontally on a wide screen, we might consider enforcing some maximum width for the whole content. I think the readability would be better, since there would be more top-to-bottom eye movement at the cost of left-to-right-and-back.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:59, 15 October 2020 (UTC)<br />
<br />
== Xorg parentheses ==<br />
<br />
I actually think that X(org) is very useful to imply that it is one and the same thing.<br />
<br />
It might even be more confusing now, as we use both Xorg and X, because the wiki title and the package titles are Xorg.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:30, 17 October 2020 (UTC) G3ro<br />
<br />
:Well the conventions should be established on the [[Xorg]] page, not anywhere else... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:36, 17 October 2020 (UTC)<br />
<br />
:: Imo the conventions are established by upstream and they use a wide variety of X, X.org, X(org), Xorg etc.<br />
:: As I said I always prefer X(org) because then it is clear, that both are same thing.<br />
:: But ultimately it's your decision. <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:43, 17 October 2020 (UTC) G3ro<br />
<br />
:::When upstream is not capable of making a unambiguous decision, it makes sense that other projects pick some option and stick with it wherever they can to keep at least some consistency. So for this wiki, pages should use the same style as the [[Xorg]] page. But feel free to start a discussion about this in [[Talk:Xorg]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:56, 17 October 2020 (UTC)<br />
<br />
== SSHFS - systemd edit ==<br />
<br />
The edit was removed because "there is no advantage over using fstab entries".<br />
<br />
Is not only about the dis/advantages of the systemd option, is about that it is another possibility to achieve the task, that is why it was created in another level and the fstab section was left alone.<br />
<br />
Reconsider the edit as it presents another option which people can use.<br />
<br />
[[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 16:22, 22 October 2020 (UTC)<br />
<br />
:There is no need to use anything else, fstab just works well enough. Configuring mounts with systemd services is not a good idea - it is much more bloated than fstab and not the right tool for it. If anything, a different type of systemd units should be used: {{man|5|systemd.mount}}. But creating the mount units manually is still pretty useless since everything can be configured in fstab and systemd will generate the unit for you. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:22, 22 October 2020 (UTC)<br />
<br />
:: It is about the ability to use the user's .config file and all the proper options that are saved there. Also systemd gives the possibility to use different targets, so the user could mount it when an specific user logs in or when a graphical session starts. I could argue that bad a modification of fstab could lead to a system that doesnt boot, but such poorly configured systemd unit file just fails and the system is fine. Just give the user the information and let it decide what they can use depending on their use case. [[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 08:08, 24 October 2020 (UTC)<br />
<br />
:::You can configure systemd targets in fstab using the {{ic|x-systemd.wanted-by}} and {{ic|x-systemd.required-by}} options, there are also {{ic|nofail}} and {{ic|noauto}} options. Please read the {{man|5|systemd.mount}} manual.<br />
:::Using hosts from the user's {{ic|.ssh/config}} is the only thing which is not possible with fstab, but this does not warrant using the wrong tool for the task. Simple copy the full {{ic|user@hostname}} into fstab and you're done.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:47, 24 October 2020 (UTC)<br />
<br />
== [[Self-encrypting drives]] ==<br />
<br />
Hi, I'd like to respectfully disagree with the rollback. It's specific to sedutil that with most commands you need to input /dev/nvme0 (when encrypting the device) but for the sleep commands it requires /dev/nvme0n1 or it fails with a very unspecific error (Error saving the password to the kernel errno = 25), as found out in the discussion https://github.com/Drive-Trust-Alliance/sedutil/issues/90<br />
<br />
All in all I believe that it is important to keep this piece of information which was found out in a long discussion between the reporter and the developers. I ran into it and I believe many people may run into it, considering most of the new SSD will be NVMe. Best, [[User:Przemub|Przemub]] ([[User talk:Przemub|talk]]) 13:34, 28 October 2020 (UTC)<br />
<br />
:OK, then it makes sense. But it should be probably explained before, not in the section about the sleep command. Also please add the link to the note as a reference. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:27, 28 October 2020 (UTC)<br />
<br />
== Nvidia Installation ==<br />
<br />
The whole guide is unnecessary long and overcomplicated formulated.<br />
Shorter is better, most people will know their graphic card for example, so the determination etc. is only optional.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:21, 10 November 2020 (UTC) G3ro<br />
<br />
:Moving some info to some other page and leaving a tip behind does not make it shorter, but harder to follow. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:36, 10 November 2020 (UTC)<br />
<br />
== Btrfs layout ==<br />
<br />
Hi, Lahwaacz<br />
<br />
Thanks for maintaining [[Snapper]]! However I think the layout is not openSUSE specific and beneficial to all btrfs users. Can you elaborate your reason of undoing the edits? IMO the previous 'simple layout' complicates the rollback procedure.<br />
<br />
Cheers,<br />
[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 07:26, 3 December 2020 (UTC)<br />
<br />
:It is not overcomplicated, it is just doing things right. You can read about that in the forum thread, see the first note in [[Snapper#Suggested filesystem layout]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:24, 3 December 2020 (UTC)<br />
<br />
::Anyway I've moved the guides to my user page. It's not that I haven't read the 5-year-old forum post, it's that before the current layout I followed that post and resulted in a not fully rolled-back system. That post also sourced (then current) information from openSUSE. openSUSE has since massively overhauled the layout, as I pointed out in an edit you undid earlier.[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 09:02, 3 December 2020 (UTC)<br />
<br />
::Since last message I've extensively documented the new layout at [[User:I2Oc9/Btrfs_subvolumes]] and [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption]]. Have a look for yourself. Nothing new really, but IMO [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my take]] is much more simpler and complete than the supposedly [[Snapper#Restoring_/_to_a_previous_snapshot_of_@|simpler one]]. That one does not leverage native {{ic|snapper rollback}} or {{Pkg|grub-btrfs}}, among other things. I strongly suggest you try if you have time. [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 11:55, 3 December 2020 (UTC)<br />
<br />
::Actually if you look closely, none of [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my recovery methods]] is specific to [[User:I2Oc9/Btrfs_subvolumes#A_new_kind_of_layout|the new 'complex' layout]], it will work totally fine with the old one. I just don't think moving @ around in live environment is appropriate.<br />
<br />
::On the other hand, the layout recommendation has been updated by openSUSE [https://en.opensuse.org/SDB:BTRFS], why stick with the old one? [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 12:37, 3 December 2020 (UTC)<br />
<br />
:::The main reasons why I reverted your edits on the [[Snapper]] page are: 1) it was a huge change which was not discussed previously as required by [[ArchWiki:Contributing#The 3 fundamental rules]], and 2) it has some elements which do not apply to Arch (see below). If you wish to propose a better layout of the subvolumes, it should be discussed in [[Talk:Snapper]] first. Your user pages would serve as great drafts.<br />
:::Note that the current suggested layout is not ''flat'' in the sense of [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|your section]] - it has a separate subvolume for {{ic|.snapshots}} so it does not lead to the recursive mess. So your proposed layout seemed very similar to the current suggested layout. The real difference is which subvolume gets mounted at {{ic|/}}, but I did not find it explained anywhere on the Snapper page before I reverted the changes (I get it now from your user page). I also did not find a proper documentation of the openSUSE's layout - it seems to be just the product of their installer and the documentation only deals with the result, saying at most that [https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha-snapper.html#sec-snapper-snapshot-boot the subvolume configuration must not be changed] for rollbacks to work.<br />
:::Now the openSUSE-specific elements: some Arch packages actually install software into {{ic|/opt}}, so the recommended layout should not suggest a separate subvolume for this path. Even more importantly, the pacman database is located at {{ic|/var/lib/pacman/local/}} and it must be rolled back along with the system, so there should be no separate subvolume for {{ic|/var}}. Instead, users should be encouraged to create (even nested) subvolumes for specific data directories under {{ic|/var}}, such as {{ic|/var/log}}, {{ic|/var/tmp}}, {{ic|/var/cache/pacman}}, {{ic|/var/lib/machines}}, etc.<br />
:::Finally, the suggested layout should not be GRUB-specific, there should be no recommendations regarding a boot loader. Sure it is useful to include non-trivial tips, but people may actually use a different boot loader.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:31, 4 December 2020 (UTC)<br />
<br />
::::Thanks for your detailed reply. I admit that I'm not knowledgeable on the intricate differences between distributions and shouldn't have made the changes without properly discussing them first.<br />
::::Yes, I get that the current layout is not [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|the one described in this section]] and indeed properly separates {{ic|/.snapshot}} and {{ic|/}}. The layout I proposed attempts to add some "niceties" such as supporting multi-distribution installations (complex and unnecessary, I agree) and bring the openSUSE layout here, which is a mistake, as you've pointed out.<br />
::::As for GRUB, since I use LUKS all the time and it's the only bootloader supporting encrypted {{ic|/boot}} on Btrfs on LUKS1, I really didn't think of any other possibilities.<br />
::::I will incorporate your recommendations to my user page and add a new section in [[Talk:Snapper]] pointing to those pages.<br />
::::Cheers -- [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:09, 4 December 2020 (UTC)<br />
<br />
:::::I've adopted [[Install_Arch_Linux_on_ZFS#System_datasets|Archlinux Root on ZFS layout]] to [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Create_subvolumes|my proposal]]. [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:56, 4 December 2020 (UTC)<br />
<br />
== Reflector Revert ==<br />
<br />
Hi Lahwaacz, about your [https://wiki.archlinux.org/index.php?title=Reflector&oldid=643749 revert], it seems like there's precedence for including AUR packages that replicate the code on the wiki. For example, in [[dash#Relinking /bin/sh]].<br />
<br />
In addition, I believe that there's value for linking the AUR package because it allows a simpler user experience where the AUR package is maintained for them. That way, if it is ever updated, they can easily fetch the update instead of religiously checking the wiki page (which most users probably don't do).<br />
<br />
Thanks!<br />
<br />
[[User:Denton-l|Denton-l]] ([[User talk:Denton-l|talk]]) 01:52, 7 December 2020 (UTC)<br />
<br />
:That precedence was only created by [https://wiki.archlinux.org/index.php?title=Dash&type=revision&diff=561587&oldid=518398 yourself]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:35, 5 May 2021 (UTC)<br />
<br />
== firefox zoom ==<br />
<br />
"no reason to zoom manually, see HiDPI)" - fractional scaling doesn't work [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 02:38, 26 December 2020 (UTC)<br />
<br />
:That should be explained in [[HiDPI#Firefox]] anyway. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:48, 26 December 2020 (UTC)<br />
<br />
::it's good to have this mentioned somewhere clearly so people know about it before they say "fonts on linux suck" [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 15:51, 29 December 2020 (UTC)<br />
<br />
== Intel GVT-g edits ==<br />
<br />
Hello Lahwaacz,<br />
<br />
I have noticed that you reverted one of the edits I have performed on [[Intel_GVT-g]].<br />
<br />
About this revert: [https://wiki.archlinux.org/index.php?title=Intel_GVT-g&oldid=648062 Windows problems are out of scope]<br />
<br />
While I understand that the ArchWiki is about ArchLinux, this article in particular mentions Windows in the introduction, and already includes another troubleshooting point about Windows. The issue I have encountered with the black bars is somewhat common, as I have found other people discussing it online, and I really fail to see why not including this piece of information in this article would be better than including it.<br />
<br />
Please, let me know your thoughts. If you think that the point can be improved, I will be happy to do that.<br />
<br />
Ciao,<br />
<br />
[[User:Wilcomir|Wilcomir]] ([[User talk:Wilcomir|talk]]) 09:14, 3 January 2021 (UTC)<br />
<br />
:Well, the existing section about a Windows problem is actually solved by configuring the Linux host. I think anything involving configuration or installation of programs in Windows is not appropriate for long troubleshooting sections. At most, they could be mentioned in a short reference to other sites which describe the problem in detail. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:34, 3 January 2021 (UTC)<br />
<br />
== <s>XDG configuration for Vim</s> ==<br />
<br />
Hi Lahwaacz,<br />
<br />
You have reverted the updated Notes for Vim on [[XDG Base Directory]], because "copy-pasted from a blog post".<br />
<br />
The problem is, not only is the configuration presented currently also copied from a blog post too, but is already 10 years old.<br />
<br />
Would it be OK, if we bring back the more up to date version? Or at least remove the obsolete one and leave link to newer?<br><br />
(Although I think a copy on wiki would be beneficial in case my blog ceases to exist)<br />
<br />
[[User:Jorengarenar|Jorengarenar]] ([[User talk:Jorengarenar|talk]]) 02:05, 12 January 2021 (UTC)<br />
<br />
:OK let's close this. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:49, 29 August 2021 (UTC)<br />
<br />
== Root on ZFS draft ==<br />
<br />
Hi, I submitted [https://github.com/openzfs/openzfs-docs/pull/104 a Root on ZFS draft] to official doc repo.<br />
<br />
In the draft, the following directories are separated from root filesystem:<br />
home,root,srv,usr/local,var/log,var/spool,var/tmp<br />
<br />
Is this appropriate for Arch Linux? Or do you have any suggestion on the draft?<br />
Any comment is appreciated.<br />
[[User:M0p|M0p]] ([[User talk:M0p|talk]]) 01:28, 23 January 2021 (UTC)<br />
<br />
== Re: undo GRUB - Common installation errors ==<br />
<br />
Concerning your undo of [https://wiki.archlinux.org/index.php?title=GRUB&diff=next&oldid=649799 Add the error message `Could not prepare Boot variable: No space left on device`)]<br />
Is there a better place to for this Information? One can find the solution in various forums, but I thought it could be helpful to have it in this wiki somewhere. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 12:51, 25 January 2021 (UTC)<br />
<br />
:The error message is not specific to the {{ic|/sys/fs/pstore/}} filesystem (which does not even seem to be used by default on Arch...) Where did you find that? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:16, 25 January 2021 (UTC)<br />
<br />
::I did not find anything Arch specific, but this post about Debian helped: [https://donjajo.com/fix-grub-efibootmgr-not-set-variable-no-space-left-device/ Post]. I also found something about [https://askubuntu.com/questions/1072618/could-not-prepare-boot-variable-no-space-left-on-device-grub-install-error-ef /sys/fs/efi/efivars/dump-*] The problem is that the actual efi-partition does not seam to be the problem, there is more than 70% space left. If there is better information to guide the user in the right direction that wuld be more helpful. This is what I found worked, but I admit that I don't know much about how grub operates. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 16:20, 25 January 2021 (UTC)<br />
<br />
:::This wiki ''is'' Arch specific so old posts about Debian or Ubuntu do not apply. Even if they did, this is hardly a ''common'' installation problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:29, 26 January 2021 (UTC)<br />
<br />
::::I know that, and would not have put it there if it didn't occur on my Arch Linux installation. If this is something that should not be documented in this wiki, I understand that. Is there any other place you would recommend? An issue for grub-install maybe? [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 22:24, 26 January 2021 (UTC)<br />
<br />
== Kernel Compilation time ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Kernel&diff=next&oldid=650896 link]<br />
<br />
I don't think we should judge information by what is obvious to experts.<br />
People might have experience with compilation of other programs, which mostly is fast, and then there is the kernel which takes forever to compile.<br />
I think it does not hurt anyone to make people aware of it.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:03, 6 February 2021 (UTC)<br />
<br />
:It is an unnecessary information without a definite answer which can even be [https://html.duckduckgo.com/html?q=how%20long%20does%20it%20take%20to%20compile%20Linux%20kernel searched elsewhere]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:23, 6 February 2021 (UTC)<br />
<br />
:: I disagree, with that argument nearly any tip and note is unnecessary. These things are intended to inform users about things that should be taken into consideration and that are different from the norm.<br />
:: Also do you search for the compilation time for every program you intend to compile? I don't.<br />
:: Furthermore this info is included, why not tell it to people directly on the start, so they don't read over it? <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:36, 6 February 2021 (UTC)<br />
<br />
:::If someone wants to compile the Linux kernel, they should obviously expect that it will take ''some time''. Stating that it "can take up to several hours" does not make sense without referring to a specific hardware. Obviously, it will take much longer on a poor laptop than on a powerful workstation with a many-core processor, but people can assume that themselves. Without a reference to a specific hardware, the note is unnecessarily discouraging because the compilation can be as fast as some tens of minutes - it is by far not the most expensive package to compile...<br />
:::As you said, people can find better notes later along with advices to enable parallel build etc. which is all that's needed IMO.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:03, 6 February 2021 (UTC)<br />
<br />
== Wayland style ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Wayland&diff=prev&oldid=650979 link]<br />
<br />
I think in the old version it was much easier to read the "source code", so I don't see why there can't be spaces between it.<br />
Things shouldn't be complicated more than necessary.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:11, 6 February 2021 (UTC)<br />
<br />
:Most templates on the wiki are written without spaces around the |. When we [https://github.com/archlinux/archwiki/pull/32 switch the editor], there will even be syntax highlighting. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:25, 6 February 2021 (UTC)<br />
<br />
== Bluetooth keyboard ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php/Bluetooth_keyboard link]<br />
<br />
On your last change you said "not specific to keyboards, all of this is already mentioned on the Bluetooth page", the point is that this is extremely relevant for bluetooth keyboard since it is required to perform the login! If this little piece cannot be duplicated I would suggest at least to leave a link saying "If you want to autoconnect at boot please refer to...". I'm new here and I would not touch it further, but please evaluate the suggestion (this is because after reading bluetooth keyboard page and not finding the solution I had to look for it on forums)<br />
<br />
{{unsigned|21:17, 20 February 2021|Stevexyz}}<br />
<br />
:Well, basically the whole page is flagged to be merged with the main [[Bluetooth]] page, so it's expected to be incomplete. Other tips may always be found on a more general page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:40, 21 February 2021 (UTC)<br />
<br />
== Re: Steam Needs to be online error ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Steam/Troubleshooting&diff=next&oldid=653073 link]<br />
<br />
The problem here is that DNS resolution in general works already (yes even outside browsers), i.e. <br />
<br />
dig media.steampowered.com<br />
<br />
would run successfully, but the Steam client couldn’t resolve it. The DNS request from 'dig' shows up in my nameserver’s log, the one Steam should send doesn’t. This indicates it might indeed a problem specific to Steam, and it’s not as easy as just say "go fix your DNS resolution", as it already may work correctly for everything but Steam.<br />
<br />
Additionally, at no point does [[Domain name resolution]] even mention nscd, so you effectively removed a fix/workaround for the problem from the Wiki. So I was definitely not "duplicating an article" here. [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 08:12, 22 February 2021 (UTC)<br />
<br />
:Could I please hear your opinion on this? I’d be happy to just add something along the lines of "if you made sure DNS resolution works but Steam still can’t resolve it, try additionally enabling the nscd service" to the Steam troubleshooting page. Unfortounately I don’t know why running the service helps, but I’d still like to give others an easier time finding this solution than I had myself. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 09:15, 28 February 2021 (UTC)<br />
<br />
::Hi, I'm sorry for the delay. Could you test if using a different program for DNS caching (e.g. [[systemd-resolved]]) instead of {{ic|nscd.service}} fixes the problem? If not, then it's probably not due to DNS - {{man|8|nscd}} actually caches more than just DNS. Also if you have a reference to some website where you found about nscd, it would be nice to add it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 28 February 2021 (UTC)<br />
<br />
:::No worries. Using [[systemd-resolved]] for DNS resolution (and caching I guess, I wasn’t aware it does that, too) was a thing I did try, but that didn’t fix it for me. The place I found out about nscd fixing it was actually the [https://bbs.archlinux.org/viewtopic.php?id=263356 Arch forums]. When I search the web for Steam in combination with nscd, all I can seem to find are more forum entries of people that don’t know why that fixes it either. I can try a bit to find out what nscd does to make it work, but I’m not too confident I will be successful. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 14:51, 28 February 2021 (UTC)<br />
<br />
::::Okay, so {{ic|nscd}} allows to [https://man7.org/linux/man-pages/man5/nscd.conf.5.html dis-/enable caching per service], and it’s indeed enabling it for {{ic|hosts}} that makes it work. That’s weird though, since [[systemd-resolved]] has caching enabled by default, and using it for resolution didn’t make {{ic|steam}} work for me. Leads me to think that I didn’t set it up correctly, although resolving via {{ic|dig}} *did* work. Since [[steam]] depends on [[Name Service Switch]], I tried resolving using {{ic|getent}} manually with nscd disabled, but that worked while steam did not. I’m not really sure what to make of this, since I have no idea how this low level networking/resolving stuff works really. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 15:39, 28 February 2021 (UTC)<br />
<br />
:::::Hmm, I don't know the details either. Steam needs the multilib packages so maybe that's part of the problem. Could you add your findings to the section and use [[Template:Expansion]] for the missing details? Maybe someone can figure it out. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:44, 28 February 2021 (UTC)<br />
<br />
::::::Sure, I can do that. I’ll probably need a minute to figure out how to use the template though, but I should have the time later today. Thanks for your input on this. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 17:56, 28 February 2021 (UTC)<br />
<br />
== Removal of website link ==<br />
<br />
Refers to this: https://wiki.archlinux.org/index.php?title=PipeWire&diff=next&oldid=653701<br />
<br />
I don't understand why that has to be removed. The official website should be always worth a mention, even if it is somehow mentioned in the text already.<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:02, 28 February 2021 (UTC)<br />
<br />
:The "See also" section is for additional links, it is not intended as a collection of all links used on a page. Adding links which are clearly mentioned in the appropriate place only clutters the list. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:24, 28 February 2021 (UTC)<br />
<br />
:: There are just three links and only one of them is really useful, the others could maybe even be removed as they link to old blog posts.<br />
:: I can only repeat myself, that things don't always have to be made more complicated than necessary.<br />
:: The official website is a central point which links to many more useful ressources, so it's one link for much information.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:34, 28 February 2021 (UTC)<br />
<br />
== Removal of bootia32.efi generation procedure from X205TA install page. ==<br />
<br />
Those [https://wiki.archlinux.org/index.php?title=ASUS_x205ta&diff=596239&oldid=562734 instructions] were really straightforward and useful, imho in comparison present ones require too much material to be confident with. I think it's (paradoxically) way easier to generate the file than to configure a `grub.cfg` from zero to boot a live cd. Can we undo the edit? Otherwise we could put them in a new page or section in the GRUB page and link to them maybe. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 05:07, 4 March 2021 (UTC)<br />
<br />
:If there is something wrong with the information on the [https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#Booting_64-bit_kernel_on_32-bit_UEFI general page], it should be improved instead of describing the same procedure in a different way on a completely unrelated page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:16, 6 March 2021 (UTC)<br />
<br />
:: I didn't know we had that info in the UEFI article. I think it could be appropriate to insert the [https://en.wikipedia.org/wiki/Template:See_also#Examples See also] archwiki equivalent (which I couldn't find) for UEFI page on top of the aforementioned section, what do you think? [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 13:28, 7 March 2021 (UTC)<br />
<br />
:::Well, the removed section was previously flagged with "Duplicates [[Unified Extensible Firmware Interface#Booting 64-bit kernel on 32-bit UEFI]]"...<br />
:::Also the laptops pages are usually related to most of the general pages on this wiki, adding all of them would be pretty useless. Users should not expect to find everything on a single laptop page, they should always check if there is a general page for their topic with more details.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 7 March 2021 (UTC)<br />
<br />
== Re: Show how to use systemd/Timers with wg-quick@.service ==<br />
<br />
I don't think using service is the appropriate when you want to start Wireguard at boot. For most people connecting to a VPN is not exactly part system startup.<br />
A timer should more appropriate.<br />
[[User:ENV25|ENV25]] ([[User talk:ENV25|talk]]) 10:03, 11 April 2021 (UTC)<br />
<br />
:I don't see how OnBootSec=1min is more appropriate than an automatically starting service. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:19, 11 April 2021 (UTC)<br />
<br />
== USB flash installation medium (BIOS bootable) ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=USB_flash_installation_medium&diff=next&oldid=673926 revert]: "making the partition bootable is discussed below"<br />
Do you mean installing syslinux and `dd` the [gpt]mbr with "discussed below"? This was not enought for my setup (Sandisk Ultra 64GB, Dell XPS 9370) to make the partition BIOS bootable. It did work right after I checked "Legacy BIOS Bootable" checkbox using gnome-disks.<br />
<br />
{{Unsigned|13:42, 30 May 2021 (UTC)|Auipga}}<br />
<br />
:Yes, that's what I meant. If it does not work, it should be fixed rather than providing a duplicate instruction without a reason. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:16, 30 May 2021 (UTC)<br />
<br />
== Systemd-networkd systemd-networkd-wait-online.service discussion modifications ==<br />
<br />
I'm not sure why you're reverting my edits.<br />
<br />
You said: "''empty ExecStart is explained in Systemd#Examples''"<br />
<br />
Exactly: Systemd#Examples clearly states "''As another example, in order to replace the ExecStart directive for a unit that is '''not of type oneshot'''''"<br />
<br />
'''systemd-networkd-wait-online''' is a oneshot service. By having the superfluous empty ExecStart you're just confusing people.<br />
<br />
Regarding the file naming, yes the name is irrelevant, but it's generally helpful to non-expert users to stick to canonical naming conventions.<br />
<br />
Please make sure you're on solid ground before reverting edits; you're just discouraging people from engaging with the Wiki. Thanks. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 16:51, 9 June 2021 (UTC)<br />
<br />
:{{man|5|systemd.service}} says: "Unless Type= is oneshot, exactly one command must be given. When Type=oneshot is used, zero or more commands may be specified."<br />
:So when a service is not oneshot, users ''must'' clear ExecStart before adding a modified command in the drop-in file. If a service is oneshot, they ''may or may not'' clear ExecStart, since the service may have multiple ExecStart commands.<br />
:In case of systemd-networkd-wait-online, I don't see why you would want to run multiple instances with different options: one to wait for ''all'' links (which is the default command) and another one to wait for ''any'' link (which is the command in the drop-in example). So clearing ExecStart really makes sense for systemd-networkd-wait-online.<br />
:— [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:44, 9 June 2021 (UTC)<br />
<br />
== Pacman: Install missing dependencies ==<br />
<br />
Hi. [https://wiki.archlinux.org/index.php?title=Pacman&type=revision&diff=690774&oldid=690762 "Pacman" Revision as of 21:50, 4 August 2021 (undo)] - maybe at least put that into [[System_maintenance#Avoid_certain_pacman_commands]]?<br />
<br />
[[User:Galeksandrp|Galeksandrp]] ([[User talk:Galeksandrp|talk]])<br />
<br />
:[[System_maintenance#Avoid_certain_pacman_commands]] already mentions {{ic|-Rdd}}. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:12, 14 August 2021 (UTC)<br />
<br />
== DPMS: "\033[9;0]" ==<br />
<br />
Hi. It seems that you removed {{ic|echo -ne "\033[9;0]"}} from [[Display Power Management Signaling|DPMS]]<br />
<br />
https://wiki.archlinux.org/index.php?title=Display_Power_Management_Signaling&diff=629705&oldid=625073<br />
<br />
[https://www.denx.de/wiki/view/DULG/SwitchOffScreenSaverAndBlinkingCursor A DULG page] and [https://unix.stackexchange.com/a/23636 a U&L post] brought me here.<br />
<br />
May I ask (1) if this method is still working; and (2) where is this escape sequence documented? [not found in {{man|4|console_codes}}]<br />
<br />
Thanks.<br />
<br />
{{Unsigned|05:23, 15 August 2021 (UTC)|PXf}}<br />
<br />
:[[Display Power Management Signaling#DPMS interaction in a Linux console with setterm]] says that setterm works by writing escape codes to the terminal device. The first subsection shows how to reverse-engineer the escape codes. Note that the escape codes are an implementation detail that users should not be concerned with, their documentation is certainly not our job. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:40, 15 August 2021 (UTC)<br />
<br />
== Linux console/Keyboard configuration ==<br />
<br />
Hi, you recently reverted my edit https://wiki.archlinux.org/index.php?title=Linux_console/Keyboard_configuration&oldid=693887. The reason I made that edit, was that I used to put my custom keymap in {{ic|/usr/local/share/kbd/keymaps/personal}} per the previous version of the wiki page. But this doesn't work with ''sd-vconsole'', as it's include files don't get loaded. Your suggested workaround by adding all required files using [[mkinitcpio#BINARIES and FILES|mkinitcpio BINARIES and FILES]] is rather tedious, as all the include files need to be in there, added by hand. This is done automatically by ''sd-vconsole'' if the file was put in {{ic|/usr/share/kbd/keymaps/}}. The reason I made this edit is due to https://bugs.archlinux.org/task/71788. See Giancarlo Razzolini's comment. [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 09:43, 2 September 2021 (UTC)<br />
<br />
:It's just one custom file under {{ic|/usr/local}} and one entry in {{ic|FILES}}. What is so tedious about it? — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:37, 2 September 2021 (UTC)<br />
<br />
:: It's not just one file. All the dependencies need to be included too under {{ic|/usr/share/kbd/keymaps/}}. There are quite a few in my case, when I just include ''us.map'' to modify it slightly. See the ''sd-vconsole'' hook script. That script has a part where it finds all the dependencies of a keymap.<br />
<br />
:: * ''/usr/share/kbd/keymaps/i386/include/compose.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/euro1.map''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/linux-keys-bare.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/linux-with-alt-and-altgr.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/qwerty-layout.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/qwerty/personal.map''<br />
:: * ''/usr/share/kbd/keymaps/i386/qwerty/us.map''<br />
:: * ''/usr/share/kbd/keymaps/include/compose.latin1''<br />
<br />
:: [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 12:01, 2 September 2021 (UTC)<br />
<br />
::: I moved this to the talk page so I remember it and others can discuss too. [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 09:18, 4 September 2021 (UTC)<br />
<br />
::: Oh, I see. In that case I suggest we add a tip like this:<br />
::: {{Tip|If you use the {{ic|sd-vconsole}} [[mkinitcpio#Common hooks|mkinitcpio hook]] instead of {{ic|keymap}}, keymaps located under {{ic|/usr/local}} as well as their dependencies from {{ic|/usr/share/kbd/keymaps}} need to be manually specified in the {{ic|FILES}} array in {{ic|mkinitcpio.conf}}. On the other hand, custom files located in {{ic|/usr/share/kbd/keymaps}} will be added automatically when configured in {{ic|/etc/vconsole.conf}}.}}<br />
::: Because this is relevant only for people using the {{ic|sd-vconsole}} hook and otherwise it does not make sense to pollute {{ic|/usr/share/kbd/keymaps}} with custom files.<br />
::: — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:55, 5 September 2021 (UTC)<br />
<br />
== cow_* ==<br />
<br />
Hi Lahwaacz. About the [https://wiki.archlinux.org/index.php?title=Archiso&diff=next&oldid=692981 how/why issue] (there will be no more &lt;!-- --&gt;). What if, for once, that I want to install some large packages after booting archiso, and would not bother modifying packages.x86_64 and building again? [https://www.memesmonkey.com/topic/works+on+my+machine <s>''on my machine''</s>] Darren "Un1Gfn" "[[User:PXf|PXf]]" Ng ([[User talk:PXf|talk]]) 08:18, 12 October 2021 (UTC)<br />
<br />
:It is a subsection of "Tips and tricks", not "Troubleshooting", so it should start with a clear motivation saying ''why'' the tip is useful, rather than an error message that the user has no idea if they will face or not. If you have such description, feel free to rewrite the section. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 05:42, 13 October 2021 (UTC)<br />
<br />
::What about making it a subsection of "[[Archiso#Troubleshooting|Troubleshooting]]" and renaming it to {{ic|partition / too full}}? [[User:PXf|PXf]] ([[User talk:PXf|talk]]) 06:45, 13 October 2021 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=698902User talk:Lahwaacz2021-10-12T08:18:15Z<p>PXf: /* cow_* */ sign!!!</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== The pip section in [[Python package guidelines]] ==<br />
<br />
Hi, you wanted the warning about using pip or wheels restored but accidentally(?) reverted my whole set of changes. I redid them, leaving the warning in place. – [[User:Flying sheep|flying sheep]] 08:17, 8 March 2019 (UTC)<br />
<br />
:Full revert was intentional, because the "wheel" section is not a full replacement for "pip" because there are packages which don't provide wheel files. As I said in the edit summary, there is no reason to recommend one or the other due to the warning. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:21, 8 March 2019 (UTC)<br />
::That still doesn’t explain why you reverted the first part, that had nothing to do with the pip/wheel section and simple improves the files.pythonhosted.org URLs. I restored that one while we’re discussing the pip/wheel section. And about that: There’s no reason to use pip for anything else, and pip is only used because some people (me included) didn’t understand that you can install most wheels by just extracting them to the correct location. So what do you think is missing from my wheels section that the former pip section had? – [[User:Flying_sheep|flying sheep]] 11:41, 11 March 2019 (UTC)<br />
<br />
:::If you didn't notice, the page includes "guidelines" in the title. So the page should contain only common and recommended ways to do things, not everything that is possible to do. If you think that your way to install "wheels" should be followed by everybody, feel free to discuss it on the talk page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:26, 11 March 2019 (UTC)<br />
::::Well, extracting static archives sounds much more recommended than running pip with like 7 options to make it behave. I added a talk item: [[Talk:Python package guidelines#Remove_pip_section_in_favor_of_wheels_section?]] – [[User:Flying_sheep|flying sheep]]<br />
<br />
== wpa_supplicant ==<br />
<br />
Regarding https://wiki.archlinux.org/index.php?title=WPA_supplicant&diff=577215&oldid=577167, one person ran into this problem in March of this year and spent too much time diagnosing it:<br />
<br />
https://bbs.archlinux.org/viewtopic.php?id=244950<br />
<br />
It took me a few days to find the problem. I want to make sure the next time someone encounters it, they easily find relevant information about what the cause is. Since you've reverted my edits to both netctl and wpa_supplicant, what do you suggest?<br />
<br />
--<br />
<br />
[[User:Pooryorick|Pooryorick]] ([[User talk:Pooryorick|talk]]) 08:24, 18 July 2019 (UTC)<br />
<br />
== F2FS and GRUB ==<br />
<br />
Hello. :) I'm here to address a recent disagreement. I noticed a reversion of my edit regarding the F2FS filesystem, in particular regarding the configuration file to edit (with you representing /boot/grub/grub.cfg and me representing /etc/default/grub). I run F2FS on my daily driver with an encrypted root filesystem and encrypted boot on a separate partition, and have never had to touch grub.cfg. I only automatically generate it. It's possible to use either, but /etc/default/grub would make more sense as a recommendation in my mind because grub.cfg has the potential to be overwritten during updates, whereas /etc/default/grub doesn't. <br />
<br />
If there's a compelling reason to use grub.cfg over /etc/default/grub, please let me know. ^^ I'm always eager to learn more about Arch. I don't want to get in a reversion war so I've left your change untouched for the time being.<br />
<br />
[[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 00:17, 8 September 2019 (UTC)<br />
<br />
:The reason is explained in the section: "If GRUB is used with an unsupported filesystem it is not able to extract the UUID of your drive so it uses classic non-persistent /dev/sdXx names instead." If it does not apply to F2FS, it should be made clear. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:29, 8 September 2019 (UTC)<br />
<br />
::You can specify UUID's in GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, so my proposed solution would work for F2FS and other unsupported filesystems, without the burden of manually editing grub.cfg. If there's anything I need to clarify or something else I'm missing, just let me know. :) [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 19:37, 8 September 2019 (UTC)<br />
<br />
:::The {{ic|1=root=}} parameter is not supposed to be in GRUB_CMDLINE_LINUX_DEFAULT, regardless if UUID is used or not. ''grub-mkconfig'' automatically detects the root filesystem and adds the appropriate {{ic|1=root=}} parameter based on GRUB_DISABLE_LINUX_UUID. In any case, your change to the paragraph does not make sense. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:02, 8 September 2019 (UTC)<br />
<br />
::::It could simply be because I use full disk encryption, and adding a kernel parameter for the encrypted disk's UUID is correct in that situation. You're more experienced with contributing to the wiki, so I guess I'll defer to your judgment. It felt like a reasonable edit and solution to me and I don't see the downside to including it in GRUB_CMDLINE_LINUX_DEFAULT. [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 05:38, 9 September 2019 (UTC)<br />
<br />
== dracut executable link ==<br />
<br />
Hello, your last edit on the dracut page (https://wiki.archlinux.org/index.php?title=Dracut&oldid=596388) that undid my 'Link to direct "make executable" section for executable link' commit states: "the redirect executable points exactly to that section", but it doesn't. Following the [[executable]] link just points to the top of the Help:Reading page.<br />
<br />
{{unsigned|17:06, 28 January 2020|Krathalan}}<br />
<br />
:In that case your browser probably does not work correctly, because the redirect [https://wiki.archlinux.org/index.php?title=Executable&redirect=no really points to the section]. Or MediaWiki, there was a bug several years ago... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 28 January 2020 (UTC)<br />
<br />
:: How strange... thanks for pointing that out. It does indeed appear to be some issue with my Firefox configuration. [[User:Krathalan|Krathalan]] ([[User talk:Krathalan|talk]]) 19:51, 28 January 2020 (UTC)<br />
<br />
== Getting install.php work in DokuWiki ==<br />
<br />
Hi, than you for having undone my contribution and pointed to the right solution on [[Dokuwiki#Configuration]]. Indeed I had read this solution before, but I was misled by the condition "if you are using lighttpd or nginx and your PHP version is lower than 7": as I use Apache with php v. 7.4.3 I didn't take it into account. Do you know what a correct rephrasing could be? Maybe it should be deleted?<br />
<br />
Also, I think that, at the end of this same section, one should add something like "verify that {{Pkg|php-gd}} is installed and restart {{ic|php-fpm.service}}".<br />
<br />
Naturally I can do it myself, but I prefer to ask before.<br />
[[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 17:31, 19 February 2020 (UTC)<br />
<br />
:Hi, apparently it depends on whether you had {{ic|open_basedir}} set previously or not. I've changed the page, feel free to update the gd extension. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:16, 19 February 2020 (UTC)<br />
<br />
::Thank you! However, while, I didn't have {{ic|open_basedir}} set previously, I couldn't access ''install.php''. I suspect there is another thing to do, since the configuration editor in DokuWiki complains that it cannot modify the configuration files although ownership and permissions are correctly set for the relevant symlinks, directories and files, and so is {{ic|open_basedir}}. However I can edit my pages. Maybe a return from a new user with a fresh installation would be more useful, though. [[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 08:20, 20 February 2020 (UTC)<br />
<br />
== Dead link in Simple stateful firewall#See Also ==<br />
<br />
Hi, Jakub. I am about [https://wiki.archlinux.org/index.php?title=Simple_stateful_firewall&diff=599725&oldid=599717 this] edit. I tried to follow that link one more time and it is not require entering captcha. I am not see any content limitations and my colleague (he uses Tor) does not see them too. I am not sure how it works, so I leave it on your descision. -- [[User:Duodai|Duodai]] ([[User talk:Duodai|talk]]) 14:29, 1 March 2020 (UTC)<br />
<br />
:Well, maybe it depends on the location from which the request comes. But I don't know how it works either... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:33, 1 March 2020 (UTC)<br />
<br />
::my guess is it returns captcha for crawlers only -- [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 01:59, 2 March 2020 (UTC)<br />
<br />
:::I'm getting it in my browser... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:14, 2 March 2020 (UTC)<br />
<br />
== SystemD user units depending on graphical session ==<br />
Hi,<br />
regarding reverting my addition to [[Systemd/User]], could you please explain why? I referenced [[https://www.freedesktop.org/software/systemd/man/systemd.special.html]] which directly contradicts what you said in your summary.<br />
<br />
{{unsigned|19:53, 5 May 2020|Fuero}}<br />
<br />
:The note in [[Systemd/User#How it works]] still applies - systemd services are never per-session, but per-user. The service does not magically get the correct DISPLAY or WAYLAND_DISPLAY variable, it does not work if you have multiple sessions per user, etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:45, 6 May 2020 (UTC)<br />
<br />
== Plymouth ==<br />
<br />
Actually with just Plymouth it does not work properly. Even 0dd17y had the same issue in https://bbs.archlinux.org/viewtopic.php?id=220900.<br />
<br />
The reason I did not file a bug report is that it is anyway fixed in the git version and the latest release (0.9.4) is around 2 years behind master<br />
<br />
{{unsigned|09:50, 6 May 2020|M.Srikanth}}<br />
<br />
:So if you don't have to file a bug report, add a full troubleshooting entry or at least properly reference your inline note instead of resorting to plain "if that does not work, try this instead". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:15, 6 May 2020 (UTC)<br />
<br />
== [Bitcoin core] build the code and run the test suites ==<br />
<br />
Hello,<br />
<br />
This week, I managed to build the Bitcoin code and run all the test suites with the help of this page: https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests<br />
<br />
Archlinux has two particularities:<br />
* being in rolling release, it takes to manually use the library {{ic|Berkeley DB (BDB) v4.8}}<br />
* the {{ic|/tmp}} directory is by default limited to half the size of the Ram<br />
<br />
For these reason, maybe it could be interesting to have a page in the wiki to explain how to build the Bitcoin core?<br />
<br />
Cheers,<br />
<br />
Thomas<br />
<br />
[[User:Thomasb|Thomasb]] ([[User talk:Thomasb|talk]]) 20:29, 9 May 2020 (UTC)<br />
<br />
:I don't think that this is useful. There is the {{AUR|bitcoin-core-git}} package and nothing more should be needed. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:53, 26 May 2020 (UTC)<br />
<br />
== Double linefeed results in extra line ==<br />
<br />
If you look at templates that end with double linefeed before noinclude this would result in extra line in resulting page.<br />
<br />
It may be a minor point but since you are perfectionist about wikitext I should mention this is a tradeoff and it results in slightly worse result.<br />
<br />
Removing just one linefeed removes the problem while still allowing it to not jumble all the tags into same line.<br />
<br />
-- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 16:30, 11 May 2020 (UTC)<br />
<br />
:If this is about [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=next&oldid=612179], the spaces I added back are not included when the template is used elsewhere, because the spaces are inside the noinclude tags. The extra space is only on the template page itself, but it does not result from template inclusion. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:41, 11 May 2020 (UTC)<br />
<br />
::OFC, I mean the template page render has extra line. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 21:21, 11 May 2020 (UTC)<br />
<br />
:::I agree with [[User:Svito|Svito]], isn't it good to delete the extra blank lines? -- [[User:Blackteahamburger|Blackteahamburger]] ([[User talk:Blackteahamburger|talk]]) 05:39, 12 May 2020 (UTC)<br />
<br />
::::OK, let's do it. [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=616382&oldid=612181] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:47, 26 May 2020 (UTC)<br />
<br />
== Re: lighttpd: remove python2 version ==<br />
<br />
Instead of removing the example we could as well add an example using a Python3 library like https://pypi.org/project/flup6/.<br />
<br />
{{unsigned|15:23, 18 May 2020|Gruentee}}<br />
<br />
:Feel free to add it if you find it useful. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:56, 18 May 2020 (UTC)<br />
<br />
== Xbindkeys removal ==<br />
<br />
Hi, just wondering why you [https://wiki.archlinux.org/index.php?title=Xbindkeys&diff=617675&oldid=617670 removed my edit] from [[Xbindkeys]]? The xbindkeys page has a number of quick tips but no mention of how to bind anything to the Print Screen key so I thought it would be useful to add. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:27, 3 June 2020 (UTC)<br />
<br />
:Giving examples for all keys on the keyboard is useless, there is [[Xbindkeys#Identifying keycodes]] which teaches how to find the keycodes and keysyms of any key. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 3 June 2020 (UTC)<br />
<br />
:: So how come you left the examples for the volume up/down and brightness? What is different between those examples and a screenshot example? Aren't more examples better to save people from hunting all over the place trying to piece things together themselves? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 14:03, 4 June 2020 (UTC)<br />
<br />
:::The difference is that when it comes to volume control, there are 1 or 2 options for the 99% most common cases, but for screenshot taking there are dozens of different options. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:15, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for edit to XDG Base Directory page regarding python_history ==<br />
<br />
I understand the justification for reverting the change I made, however I would like to point out that similar entries on the page (such as Maven) also have instructions for what contents to put in files (even though there is native documentation for those settings). Additionally, it took me a bit of re-reading on the linked Python documentation to reason out how the documentation's example needed to be modified, since it's not clear from the Python documentation whether placing such code in the PYTHONSTARTUP file will actually ''override'' the default behavior. [[User:Varriount|Varriount]] ([[User talk:Varriount|talk]]) 20:44, 20 June 2020 (UTC)<br />
<br />
:Even maven's note can be [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=631704&oldid=631630 shortened]. The notes in the table must be as short as possible, there is no place for extended explanations or long code snippets like in the upstream documentation. If the Python's documentation is not clear enough, I don't think any note in a massive convoluted table will ever be better. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:47, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for Backlight page ==<br />
<br />
Hi, you reverted my change to [[Backlight]] page that mentioned WIP patches for controlling OLED panel brightness. I don't really understand justification for reverting it since currently the page says that OLED brightness can be controlled only by changing gamma ramp. That is wrong - since it's not the only way - these panels can control brightness with a PWM. Moreover controlling brightness with gamma ramp is not optimal - it essentially reduces dynamic range, i.e. at 50% you have 7 bits per pixel, at 25% - 6 bit per pixel, etc. That results in banding artifacts at lower brightness level.<br />
<br />
As far waiting for the patches to be merged before mentioning it there - it'll take ~3-6 months (yes, that's the process) and I haven't found *any* reference to these changes on the internet - everyone recommends using gamma ramp instead of fixing it properly. I'm absolutely sure that having information about these patches would not hurt [[User:Anarsoul|Anarsoul]] ([[User talk:Anarsoul|talk]]) 15:56, 30 June 2020 (UTC)<br />
<br />
:Linking to a repo which which has 2 custom commits on top of some arbitrary development version of the Linux kernel tree is not helpful for users. Nobody will compile directly from this repo which is already significantly outdated compared to recent kernel versions and there is no indication if the patches actually work with newer (or older) kernels. We can mention the PWM control as a general concept though. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:32, 12 August 2020 (UTC)<br />
<br />
== Automatic template correction ==<br />
<br />
Per [[Help:Template#Style]], templates should be used with the capitalization shown in the examples in their pages, so {{ic|&#123;{AUR&#124;...}} is correct, while {{ic|&#123;{aur&#124;...}} is not.<br />
<br />
However, there are pages that don't respect that rule (e.g. [[Android_Debug_Bridge]] until recently).<br />
<br />
I beleive this correction should be easy to implement using a bot. What do you think?<br />
<br />
{{unsigned|07:24, 25 August 2020|Relrel}}<br />
<br />
:Yes, this should be easy, but the bot should not make a huge amount of simple style-only changes - they should be combined with corrections for more complex rules. Anyway, there is an idea to create a [https://github.com/lahwaacz/wiki-scripts/issues/22 style linter] for the ArchWiki rules. Would you like to help? ;-) – [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:21, 25 August 2020 (UTC)<br />
<br />
== Failed to create tun device ==<br />
<br />
I don't understand your reason for [[https://wiki.archlinux.org/index.php?title=NetworkManager&diff=0&oldid=634880 removing my section in NetworkManager]]. Could you elaborate?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 07:40, 11 September 2020 (UTC)<br />
<br />
:You can't use [[systemd-networkd]] and [[NetworkManager]] at the same time. Even if you don't have any ''.network'' file for systemd-networkd, you can't solve NetworkManager's problems with systemd-networkd. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:43, 11 September 2020 (UTC)<br />
<br />
::Ok, thanks, in this case it solved the error I got. Now the VPN works. Do you have an idea about how to solve it without systemd-networkd?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 22:27, 11 September 2020 (UTC)<br />
<br />
:::You should really fix the permission problem for {{Pkg|networkmanager-openvpn}}. The tun interface should be managed by OpenVPN which needs rights to create it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 12 September 2020 (UTC)<br />
<br />
::I don't think this statement is entirely correct. [[systemd-networkd]] and [[NetworkManager]] can happily co-exist together if they are managing different interfaces. I unfortunately don't have a reference to point to this, but I came across this being mentioned a couple of times on forums. I personally use [[NetworkManager]] on my laptop to handle wifi, while [[systemd-networkd]] is in control of virtual ethernet and bridges for all my [[systemd-nspawn]] instances. [[User:Romstor|Romstor]] ([[User talk:Romstor|talk]]) 03:24, 12 September 2020 (UTC)<br />
<br />
== [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&oldid=636526/ XDG Base Directory]: Undo revision 636525 ==<br />
<br />
Dear Lahwaacz,<br />
<br />
maybe my changes were to rushed and from my point of view only. But I have two points to consider:<br />
<br />
# If I put the quotes around my vimrc and source it from my .bash_profile, I get the vim-error E471 (Argument required). Without quotes, this doesn't happen. So this change based on experience.<br />
# The rtp should includes directories, which are needed at runtime. (in plain vim e.g. ~/.vim). This is not a typical configuration directory. My mistake was, that I supposed that everyone put their vim plug-ins in $XDG_DATA_HOME and not in $XDG_CONFIG_HOME, because from my point of view a plug-in doesn't belong to the configuration. Maybe it is a good idea to add a remark, which explains the addition of $XDG_CONFIG_HOME to the rtp.<br />
<br />
[[User:Grrr|Grrr]] ([[User talk:Grrr|talk]]) 13:53, 26 September 2020 (UTC)<br />
<br />
# Quotes are there because $XDG_CONFIG_HOME may contain spaces.<br />
# It's not only about quotes - the runtimepath has subdirectories for color schemes, keymaps, autoload scripts etc.<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 26 September 2020 (UTC)<br />
<br />
== Readability in Wiki ==<br />
<br />
I noticed that you and the other admins and moderators often want sentences to continue endlessly, without line breaks.<br />
For example in the introduction of [[Wayland]].<br />
<br />
I think it would be better to have more seperated sentences, so it is easier to read and "important" information is easier visible for people.<br />
I don't know who is responsible, but maybe some options in MediaWiki (or whatever this wiki software is) could be changed as well, to make make line breaks etc. easier and reduce the height-space (if you know what I mean) between sentences, so it looks better, even though line breaks are used.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:38, 15 October 2020 (UTC) G3ro<br />
<br />
:I don't know exactly what you mean. Is it about the readability of the rendered HTML or the "source code" of the page? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 15 October 2020 (UTC)<br />
<br />
:: Well I guess it can be about both. But mainly it is about what people see on the page.<br />
:: There are three seperate topics I mentioned:<br />
<br />
:: 1. Use line breaks: I would like to use more line breaks, because if you have long sentences that are written after each other without line breaks, it gets "harder" to recognize when the next sentence starts.<br />
:: While I agree to what you said somewhere, that sentences that belong directly together, should be written in one "paragraph", it would be useful for sentences that cover (slightly) different "topics" to be visibly parted.<br />
<br />
:: 2. Adjust margin options: I notice that when line breaks are used, there is a vertical space added between two sentences. Just like in this post. If you would use line breaks more often, this is a little too much spacing in my oppinion.<br />
<br />
:: 3. Potential options to make line breaks easier: It would be very convenient if a line break in the source code would lead to a line break in displayed text as well, instead of needing to add an empty line.<br />
<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:33, 15 October 2020 (UTC) G3ro<br />
<br />
:::OK, now I understand. I agree that splitting different topics usually improves legibility, but they should be split into separate paragraphs and not just by line breaks (e.g. using the &lt;br> tags). Paragraphs are semantic units whereas line breaks inside a paragraph are usually typographic errors.<br />
:::Also note that such splitting alone may not be enough to improve the text flow. For example, if we consider the intro for [[Wayland]], the second sentence about XWayland would not constitute a good paragraph - it is just a plain statement and the new topic is not nicely introduced. Ideally, you'd split the topic and make some wording changes for the second paragraph.<br />
:::As for the margin options, that is the difference between paragraph splitting and non-semantic line breaks. In my opinion, the styling is correct in this respect, as paragraphs should be discernible. You mentioned that you like line breaks to easily recognize where a sentence ends - but reading should be based on whole paragraphs, not sentences. There should be no reason to skip anything in the middle of a paragraph, otherwise it should be probably split into multiple paragraphs or otherwise rephrased.<br />
:::If you find it hard to follow a long sentence horizontally on a wide screen, we might consider enforcing some maximum width for the whole content. I think the readability would be better, since there would be more top-to-bottom eye movement at the cost of left-to-right-and-back.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:59, 15 October 2020 (UTC)<br />
<br />
== Xorg parentheses ==<br />
<br />
I actually think that X(org) is very useful to imply that it is one and the same thing.<br />
<br />
It might even be more confusing now, as we use both Xorg and X, because the wiki title and the package titles are Xorg.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:30, 17 October 2020 (UTC) G3ro<br />
<br />
:Well the conventions should be established on the [[Xorg]] page, not anywhere else... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:36, 17 October 2020 (UTC)<br />
<br />
:: Imo the conventions are established by upstream and they use a wide variety of X, X.org, X(org), Xorg etc.<br />
:: As I said I always prefer X(org) because then it is clear, that both are same thing.<br />
:: But ultimately it's your decision. <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:43, 17 October 2020 (UTC) G3ro<br />
<br />
:::When upstream is not capable of making a unambiguous decision, it makes sense that other projects pick some option and stick with it wherever they can to keep at least some consistency. So for this wiki, pages should use the same style as the [[Xorg]] page. But feel free to start a discussion about this in [[Talk:Xorg]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:56, 17 October 2020 (UTC)<br />
<br />
== SSHFS - systemd edit ==<br />
<br />
The edit was removed because "there is no advantage over using fstab entries".<br />
<br />
Is not only about the dis/advantages of the systemd option, is about that it is another possibility to achieve the task, that is why it was created in another level and the fstab section was left alone.<br />
<br />
Reconsider the edit as it presents another option which people can use.<br />
<br />
[[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 16:22, 22 October 2020 (UTC)<br />
<br />
:There is no need to use anything else, fstab just works well enough. Configuring mounts with systemd services is not a good idea - it is much more bloated than fstab and not the right tool for it. If anything, a different type of systemd units should be used: {{man|5|systemd.mount}}. But creating the mount units manually is still pretty useless since everything can be configured in fstab and systemd will generate the unit for you. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:22, 22 October 2020 (UTC)<br />
<br />
:: It is about the ability to use the user's .config file and all the proper options that are saved there. Also systemd gives the possibility to use different targets, so the user could mount it when an specific user logs in or when a graphical session starts. I could argue that bad a modification of fstab could lead to a system that doesnt boot, but such poorly configured systemd unit file just fails and the system is fine. Just give the user the information and let it decide what they can use depending on their use case. [[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 08:08, 24 October 2020 (UTC)<br />
<br />
:::You can configure systemd targets in fstab using the {{ic|x-systemd.wanted-by}} and {{ic|x-systemd.required-by}} options, there are also {{ic|nofail}} and {{ic|noauto}} options. Please read the {{man|5|systemd.mount}} manual.<br />
:::Using hosts from the user's {{ic|.ssh/config}} is the only thing which is not possible with fstab, but this does not warrant using the wrong tool for the task. Simple copy the full {{ic|user@hostname}} into fstab and you're done.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:47, 24 October 2020 (UTC)<br />
<br />
== [[Self-encrypting drives]] ==<br />
<br />
Hi, I'd like to respectfully disagree with the rollback. It's specific to sedutil that with most commands you need to input /dev/nvme0 (when encrypting the device) but for the sleep commands it requires /dev/nvme0n1 or it fails with a very unspecific error (Error saving the password to the kernel errno = 25), as found out in the discussion https://github.com/Drive-Trust-Alliance/sedutil/issues/90<br />
<br />
All in all I believe that it is important to keep this piece of information which was found out in a long discussion between the reporter and the developers. I ran into it and I believe many people may run into it, considering most of the new SSD will be NVMe. Best, [[User:Przemub|Przemub]] ([[User talk:Przemub|talk]]) 13:34, 28 October 2020 (UTC)<br />
<br />
:OK, then it makes sense. But it should be probably explained before, not in the section about the sleep command. Also please add the link to the note as a reference. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:27, 28 October 2020 (UTC)<br />
<br />
== Nvidia Installation ==<br />
<br />
The whole guide is unnecessary long and overcomplicated formulated.<br />
Shorter is better, most people will know their graphic card for example, so the determination etc. is only optional.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:21, 10 November 2020 (UTC) G3ro<br />
<br />
:Moving some info to some other page and leaving a tip behind does not make it shorter, but harder to follow. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:36, 10 November 2020 (UTC)<br />
<br />
== Btrfs layout ==<br />
<br />
Hi, Lahwaacz<br />
<br />
Thanks for maintaining [[Snapper]]! However I think the layout is not openSUSE specific and beneficial to all btrfs users. Can you elaborate your reason of undoing the edits? IMO the previous 'simple layout' complicates the rollback procedure.<br />
<br />
Cheers,<br />
[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 07:26, 3 December 2020 (UTC)<br />
<br />
:It is not overcomplicated, it is just doing things right. You can read about that in the forum thread, see the first note in [[Snapper#Suggested filesystem layout]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:24, 3 December 2020 (UTC)<br />
<br />
::Anyway I've moved the guides to my user page. It's not that I haven't read the 5-year-old forum post, it's that before the current layout I followed that post and resulted in a not fully rolled-back system. That post also sourced (then current) information from openSUSE. openSUSE has since massively overhauled the layout, as I pointed out in an edit you undid earlier.[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 09:02, 3 December 2020 (UTC)<br />
<br />
::Since last message I've extensively documented the new layout at [[User:I2Oc9/Btrfs_subvolumes]] and [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption]]. Have a look for yourself. Nothing new really, but IMO [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my take]] is much more simpler and complete than the supposedly [[Snapper#Restoring_/_to_a_previous_snapshot_of_@|simpler one]]. That one does not leverage native {{ic|snapper rollback}} or {{Pkg|grub-btrfs}}, among other things. I strongly suggest you try if you have time. [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 11:55, 3 December 2020 (UTC)<br />
<br />
::Actually if you look closely, none of [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my recovery methods]] is specific to [[User:I2Oc9/Btrfs_subvolumes#A_new_kind_of_layout|the new 'complex' layout]], it will work totally fine with the old one. I just don't think moving @ around in live environment is appropriate.<br />
<br />
::On the other hand, the layout recommendation has been updated by openSUSE [https://en.opensuse.org/SDB:BTRFS], why stick with the old one? [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 12:37, 3 December 2020 (UTC)<br />
<br />
:::The main reasons why I reverted your edits on the [[Snapper]] page are: 1) it was a huge change which was not discussed previously as required by [[ArchWiki:Contributing#The 3 fundamental rules]], and 2) it has some elements which do not apply to Arch (see below). If you wish to propose a better layout of the subvolumes, it should be discussed in [[Talk:Snapper]] first. Your user pages would serve as great drafts.<br />
:::Note that the current suggested layout is not ''flat'' in the sense of [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|your section]] - it has a separate subvolume for {{ic|.snapshots}} so it does not lead to the recursive mess. So your proposed layout seemed very similar to the current suggested layout. The real difference is which subvolume gets mounted at {{ic|/}}, but I did not find it explained anywhere on the Snapper page before I reverted the changes (I get it now from your user page). I also did not find a proper documentation of the openSUSE's layout - it seems to be just the product of their installer and the documentation only deals with the result, saying at most that [https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha-snapper.html#sec-snapper-snapshot-boot the subvolume configuration must not be changed] for rollbacks to work.<br />
:::Now the openSUSE-specific elements: some Arch packages actually install software into {{ic|/opt}}, so the recommended layout should not suggest a separate subvolume for this path. Even more importantly, the pacman database is located at {{ic|/var/lib/pacman/local/}} and it must be rolled back along with the system, so there should be no separate subvolume for {{ic|/var}}. Instead, users should be encouraged to create (even nested) subvolumes for specific data directories under {{ic|/var}}, such as {{ic|/var/log}}, {{ic|/var/tmp}}, {{ic|/var/cache/pacman}}, {{ic|/var/lib/machines}}, etc.<br />
:::Finally, the suggested layout should not be GRUB-specific, there should be no recommendations regarding a boot loader. Sure it is useful to include non-trivial tips, but people may actually use a different boot loader.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:31, 4 December 2020 (UTC)<br />
<br />
::::Thanks for your detailed reply. I admit that I'm not knowledgeable on the intricate differences between distributions and shouldn't have made the changes without properly discussing them first.<br />
::::Yes, I get that the current layout is not [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|the one described in this section]] and indeed properly separates {{ic|/.snapshot}} and {{ic|/}}. The layout I proposed attempts to add some "niceties" such as supporting multi-distribution installations (complex and unnecessary, I agree) and bring the openSUSE layout here, which is a mistake, as you've pointed out.<br />
::::As for GRUB, since I use LUKS all the time and it's the only bootloader supporting encrypted {{ic|/boot}} on Btrfs on LUKS1, I really didn't think of any other possibilities.<br />
::::I will incorporate your recommendations to my user page and add a new section in [[Talk:Snapper]] pointing to those pages.<br />
::::Cheers -- [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:09, 4 December 2020 (UTC)<br />
<br />
:::::I've adopted [[Install_Arch_Linux_on_ZFS#System_datasets|Archlinux Root on ZFS layout]] to [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Create_subvolumes|my proposal]]. [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:56, 4 December 2020 (UTC)<br />
<br />
== Reflector Revert ==<br />
<br />
Hi Lahwaacz, about your [https://wiki.archlinux.org/index.php?title=Reflector&oldid=643749 revert], it seems like there's precedence for including AUR packages that replicate the code on the wiki. For example, in [[dash#Relinking /bin/sh]].<br />
<br />
In addition, I believe that there's value for linking the AUR package because it allows a simpler user experience where the AUR package is maintained for them. That way, if it is ever updated, they can easily fetch the update instead of religiously checking the wiki page (which most users probably don't do).<br />
<br />
Thanks!<br />
<br />
[[User:Denton-l|Denton-l]] ([[User talk:Denton-l|talk]]) 01:52, 7 December 2020 (UTC)<br />
<br />
:That precedence was only created by [https://wiki.archlinux.org/index.php?title=Dash&type=revision&diff=561587&oldid=518398 yourself]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:35, 5 May 2021 (UTC)<br />
<br />
== firefox zoom ==<br />
<br />
"no reason to zoom manually, see HiDPI)" - fractional scaling doesn't work [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 02:38, 26 December 2020 (UTC)<br />
<br />
:That should be explained in [[HiDPI#Firefox]] anyway. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:48, 26 December 2020 (UTC)<br />
<br />
::it's good to have this mentioned somewhere clearly so people know about it before they say "fonts on linux suck" [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 15:51, 29 December 2020 (UTC)<br />
<br />
== Intel GVT-g edits ==<br />
<br />
Hello Lahwaacz,<br />
<br />
I have noticed that you reverted one of the edits I have performed on [[Intel_GVT-g]].<br />
<br />
About this revert: [https://wiki.archlinux.org/index.php?title=Intel_GVT-g&oldid=648062 Windows problems are out of scope]<br />
<br />
While I understand that the ArchWiki is about ArchLinux, this article in particular mentions Windows in the introduction, and already includes another troubleshooting point about Windows. The issue I have encountered with the black bars is somewhat common, as I have found other people discussing it online, and I really fail to see why not including this piece of information in this article would be better than including it.<br />
<br />
Please, let me know your thoughts. If you think that the point can be improved, I will be happy to do that.<br />
<br />
Ciao,<br />
<br />
[[User:Wilcomir|Wilcomir]] ([[User talk:Wilcomir|talk]]) 09:14, 3 January 2021 (UTC)<br />
<br />
:Well, the existing section about a Windows problem is actually solved by configuring the Linux host. I think anything involving configuration or installation of programs in Windows is not appropriate for long troubleshooting sections. At most, they could be mentioned in a short reference to other sites which describe the problem in detail. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:34, 3 January 2021 (UTC)<br />
<br />
== <s>XDG configuration for Vim</s> ==<br />
<br />
Hi Lahwaacz,<br />
<br />
You have reverted the updated Notes for Vim on [[XDG Base Directory]], because "copy-pasted from a blog post".<br />
<br />
The problem is, not only is the configuration presented currently also copied from a blog post too, but is already 10 years old.<br />
<br />
Would it be OK, if we bring back the more up to date version? Or at least remove the obsolete one and leave link to newer?<br><br />
(Although I think a copy on wiki would be beneficial in case my blog ceases to exist)<br />
<br />
[[User:Jorengarenar|Jorengarenar]] ([[User talk:Jorengarenar|talk]]) 02:05, 12 January 2021 (UTC)<br />
<br />
:OK let's close this. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:49, 29 August 2021 (UTC)<br />
<br />
== Root on ZFS draft ==<br />
<br />
Hi, I submitted [https://github.com/openzfs/openzfs-docs/pull/104 a Root on ZFS draft] to official doc repo.<br />
<br />
In the draft, the following directories are separated from root filesystem:<br />
home,root,srv,usr/local,var/log,var/spool,var/tmp<br />
<br />
Is this appropriate for Arch Linux? Or do you have any suggestion on the draft?<br />
Any comment is appreciated.<br />
[[User:M0p|M0p]] ([[User talk:M0p|talk]]) 01:28, 23 January 2021 (UTC)<br />
<br />
== Re: undo GRUB - Common installation errors ==<br />
<br />
Concerning your undo of [https://wiki.archlinux.org/index.php?title=GRUB&diff=next&oldid=649799 Add the error message `Could not prepare Boot variable: No space left on device`)]<br />
Is there a better place to for this Information? One can find the solution in various forums, but I thought it could be helpful to have it in this wiki somewhere. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 12:51, 25 January 2021 (UTC)<br />
<br />
:The error message is not specific to the {{ic|/sys/fs/pstore/}} filesystem (which does not even seem to be used by default on Arch...) Where did you find that? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:16, 25 January 2021 (UTC)<br />
<br />
::I did not find anything Arch specific, but this post about Debian helped: [https://donjajo.com/fix-grub-efibootmgr-not-set-variable-no-space-left-device/ Post]. I also found something about [https://askubuntu.com/questions/1072618/could-not-prepare-boot-variable-no-space-left-on-device-grub-install-error-ef /sys/fs/efi/efivars/dump-*] The problem is that the actual efi-partition does not seam to be the problem, there is more than 70% space left. If there is better information to guide the user in the right direction that wuld be more helpful. This is what I found worked, but I admit that I don't know much about how grub operates. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 16:20, 25 January 2021 (UTC)<br />
<br />
:::This wiki ''is'' Arch specific so old posts about Debian or Ubuntu do not apply. Even if they did, this is hardly a ''common'' installation problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:29, 26 January 2021 (UTC)<br />
<br />
::::I know that, and would not have put it there if it didn't occur on my Arch Linux installation. If this is something that should not be documented in this wiki, I understand that. Is there any other place you would recommend? An issue for grub-install maybe? [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 22:24, 26 January 2021 (UTC)<br />
<br />
== Kernel Compilation time ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Kernel&diff=next&oldid=650896 link]<br />
<br />
I don't think we should judge information by what is obvious to experts.<br />
People might have experience with compilation of other programs, which mostly is fast, and then there is the kernel which takes forever to compile.<br />
I think it does not hurt anyone to make people aware of it.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:03, 6 February 2021 (UTC)<br />
<br />
:It is an unnecessary information without a definite answer which can even be [https://html.duckduckgo.com/html?q=how%20long%20does%20it%20take%20to%20compile%20Linux%20kernel searched elsewhere]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:23, 6 February 2021 (UTC)<br />
<br />
:: I disagree, with that argument nearly any tip and note is unnecessary. These things are intended to inform users about things that should be taken into consideration and that are different from the norm.<br />
:: Also do you search for the compilation time for every program you intend to compile? I don't.<br />
:: Furthermore this info is included, why not tell it to people directly on the start, so they don't read over it? <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:36, 6 February 2021 (UTC)<br />
<br />
:::If someone wants to compile the Linux kernel, they should obviously expect that it will take ''some time''. Stating that it "can take up to several hours" does not make sense without referring to a specific hardware. Obviously, it will take much longer on a poor laptop than on a powerful workstation with a many-core processor, but people can assume that themselves. Without a reference to a specific hardware, the note is unnecessarily discouraging because the compilation can be as fast as some tens of minutes - it is by far not the most expensive package to compile...<br />
:::As you said, people can find better notes later along with advices to enable parallel build etc. which is all that's needed IMO.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:03, 6 February 2021 (UTC)<br />
<br />
== Wayland style ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Wayland&diff=prev&oldid=650979 link]<br />
<br />
I think in the old version it was much easier to read the "source code", so I don't see why there can't be spaces between it.<br />
Things shouldn't be complicated more than necessary.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:11, 6 February 2021 (UTC)<br />
<br />
:Most templates on the wiki are written without spaces around the |. When we [https://github.com/archlinux/archwiki/pull/32 switch the editor], there will even be syntax highlighting. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:25, 6 February 2021 (UTC)<br />
<br />
== Bluetooth keyboard ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php/Bluetooth_keyboard link]<br />
<br />
On your last change you said "not specific to keyboards, all of this is already mentioned on the Bluetooth page", the point is that this is extremely relevant for bluetooth keyboard since it is required to perform the login! If this little piece cannot be duplicated I would suggest at least to leave a link saying "If you want to autoconnect at boot please refer to...". I'm new here and I would not touch it further, but please evaluate the suggestion (this is because after reading bluetooth keyboard page and not finding the solution I had to look for it on forums)<br />
<br />
{{unsigned|21:17, 20 February 2021|Stevexyz}}<br />
<br />
:Well, basically the whole page is flagged to be merged with the main [[Bluetooth]] page, so it's expected to be incomplete. Other tips may always be found on a more general page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:40, 21 February 2021 (UTC)<br />
<br />
== Re: Steam Needs to be online error ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Steam/Troubleshooting&diff=next&oldid=653073 link]<br />
<br />
The problem here is that DNS resolution in general works already (yes even outside browsers), i.e. <br />
<br />
dig media.steampowered.com<br />
<br />
would run successfully, but the Steam client couldn’t resolve it. The DNS request from 'dig' shows up in my nameserver’s log, the one Steam should send doesn’t. This indicates it might indeed a problem specific to Steam, and it’s not as easy as just say "go fix your DNS resolution", as it already may work correctly for everything but Steam.<br />
<br />
Additionally, at no point does [[Domain name resolution]] even mention nscd, so you effectively removed a fix/workaround for the problem from the Wiki. So I was definitely not "duplicating an article" here. [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 08:12, 22 February 2021 (UTC)<br />
<br />
:Could I please hear your opinion on this? I’d be happy to just add something along the lines of "if you made sure DNS resolution works but Steam still can’t resolve it, try additionally enabling the nscd service" to the Steam troubleshooting page. Unfortounately I don’t know why running the service helps, but I’d still like to give others an easier time finding this solution than I had myself. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 09:15, 28 February 2021 (UTC)<br />
<br />
::Hi, I'm sorry for the delay. Could you test if using a different program for DNS caching (e.g. [[systemd-resolved]]) instead of {{ic|nscd.service}} fixes the problem? If not, then it's probably not due to DNS - {{man|8|nscd}} actually caches more than just DNS. Also if you have a reference to some website where you found about nscd, it would be nice to add it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 28 February 2021 (UTC)<br />
<br />
:::No worries. Using [[systemd-resolved]] for DNS resolution (and caching I guess, I wasn’t aware it does that, too) was a thing I did try, but that didn’t fix it for me. The place I found out about nscd fixing it was actually the [https://bbs.archlinux.org/viewtopic.php?id=263356 Arch forums]. When I search the web for Steam in combination with nscd, all I can seem to find are more forum entries of people that don’t know why that fixes it either. I can try a bit to find out what nscd does to make it work, but I’m not too confident I will be successful. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 14:51, 28 February 2021 (UTC)<br />
<br />
::::Okay, so {{ic|nscd}} allows to [https://man7.org/linux/man-pages/man5/nscd.conf.5.html dis-/enable caching per service], and it’s indeed enabling it for {{ic|hosts}} that makes it work. That’s weird though, since [[systemd-resolved]] has caching enabled by default, and using it for resolution didn’t make {{ic|steam}} work for me. Leads me to think that I didn’t set it up correctly, although resolving via {{ic|dig}} *did* work. Since [[steam]] depends on [[Name Service Switch]], I tried resolving using {{ic|getent}} manually with nscd disabled, but that worked while steam did not. I’m not really sure what to make of this, since I have no idea how this low level networking/resolving stuff works really. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 15:39, 28 February 2021 (UTC)<br />
<br />
:::::Hmm, I don't know the details either. Steam needs the multilib packages so maybe that's part of the problem. Could you add your findings to the section and use [[Template:Expansion]] for the missing details? Maybe someone can figure it out. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:44, 28 February 2021 (UTC)<br />
<br />
::::::Sure, I can do that. I’ll probably need a minute to figure out how to use the template though, but I should have the time later today. Thanks for your input on this. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 17:56, 28 February 2021 (UTC)<br />
<br />
== Removal of website link ==<br />
<br />
Refers to this: https://wiki.archlinux.org/index.php?title=PipeWire&diff=next&oldid=653701<br />
<br />
I don't understand why that has to be removed. The official website should be always worth a mention, even if it is somehow mentioned in the text already.<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:02, 28 February 2021 (UTC)<br />
<br />
:The "See also" section is for additional links, it is not intended as a collection of all links used on a page. Adding links which are clearly mentioned in the appropriate place only clutters the list. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:24, 28 February 2021 (UTC)<br />
<br />
:: There are just three links and only one of them is really useful, the others could maybe even be removed as they link to old blog posts.<br />
:: I can only repeat myself, that things don't always have to be made more complicated than necessary.<br />
:: The official website is a central point which links to many more useful ressources, so it's one link for much information.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:34, 28 February 2021 (UTC)<br />
<br />
== Removal of bootia32.efi generation procedure from X205TA install page. ==<br />
<br />
Those [https://wiki.archlinux.org/index.php?title=ASUS_x205ta&diff=596239&oldid=562734 instructions] were really straightforward and useful, imho in comparison present ones require too much material to be confident with. I think it's (paradoxically) way easier to generate the file than to configure a `grub.cfg` from zero to boot a live cd. Can we undo the edit? Otherwise we could put them in a new page or section in the GRUB page and link to them maybe. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 05:07, 4 March 2021 (UTC)<br />
<br />
:If there is something wrong with the information on the [https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#Booting_64-bit_kernel_on_32-bit_UEFI general page], it should be improved instead of describing the same procedure in a different way on a completely unrelated page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:16, 6 March 2021 (UTC)<br />
<br />
:: I didn't know we had that info in the UEFI article. I think it could be appropriate to insert the [https://en.wikipedia.org/wiki/Template:See_also#Examples See also] archwiki equivalent (which I couldn't find) for UEFI page on top of the aforementioned section, what do you think? [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 13:28, 7 March 2021 (UTC)<br />
<br />
:::Well, the removed section was previously flagged with "Duplicates [[Unified Extensible Firmware Interface#Booting 64-bit kernel on 32-bit UEFI]]"...<br />
:::Also the laptops pages are usually related to most of the general pages on this wiki, adding all of them would be pretty useless. Users should not expect to find everything on a single laptop page, they should always check if there is a general page for their topic with more details.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 7 March 2021 (UTC)<br />
<br />
== Re: Show how to use systemd/Timers with wg-quick@.service ==<br />
<br />
I don't think using service is the appropriate when you want to start Wireguard at boot. For most people connecting to a VPN is not exactly part system startup.<br />
A timer should more appropriate.<br />
[[User:ENV25|ENV25]] ([[User talk:ENV25|talk]]) 10:03, 11 April 2021 (UTC)<br />
<br />
:I don't see how OnBootSec=1min is more appropriate than an automatically starting service. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:19, 11 April 2021 (UTC)<br />
<br />
== USB flash installation medium (BIOS bootable) ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=USB_flash_installation_medium&diff=next&oldid=673926 revert]: "making the partition bootable is discussed below"<br />
Do you mean installing syslinux and `dd` the [gpt]mbr with "discussed below"? This was not enought for my setup (Sandisk Ultra 64GB, Dell XPS 9370) to make the partition BIOS bootable. It did work right after I checked "Legacy BIOS Bootable" checkbox using gnome-disks.<br />
<br />
{{Unsigned|13:42, 30 May 2021 (UTC)|Auipga}}<br />
<br />
:Yes, that's what I meant. If it does not work, it should be fixed rather than providing a duplicate instruction without a reason. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:16, 30 May 2021 (UTC)<br />
<br />
== Systemd-networkd systemd-networkd-wait-online.service discussion modifications ==<br />
<br />
I'm not sure why you're reverting my edits.<br />
<br />
You said: "''empty ExecStart is explained in Systemd#Examples''"<br />
<br />
Exactly: Systemd#Examples clearly states "''As another example, in order to replace the ExecStart directive for a unit that is '''not of type oneshot'''''"<br />
<br />
'''systemd-networkd-wait-online''' is a oneshot service. By having the superfluous empty ExecStart you're just confusing people.<br />
<br />
Regarding the file naming, yes the name is irrelevant, but it's generally helpful to non-expert users to stick to canonical naming conventions.<br />
<br />
Please make sure you're on solid ground before reverting edits; you're just discouraging people from engaging with the Wiki. Thanks. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 16:51, 9 June 2021 (UTC)<br />
<br />
:{{man|5|systemd.service}} says: "Unless Type= is oneshot, exactly one command must be given. When Type=oneshot is used, zero or more commands may be specified."<br />
:So when a service is not oneshot, users ''must'' clear ExecStart before adding a modified command in the drop-in file. If a service is oneshot, they ''may or may not'' clear ExecStart, since the service may have multiple ExecStart commands.<br />
:In case of systemd-networkd-wait-online, I don't see why you would want to run multiple instances with different options: one to wait for ''all'' links (which is the default command) and another one to wait for ''any'' link (which is the command in the drop-in example). So clearing ExecStart really makes sense for systemd-networkd-wait-online.<br />
:— [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:44, 9 June 2021 (UTC)<br />
<br />
== Pacman: Install missing dependencies ==<br />
<br />
Hi. [https://wiki.archlinux.org/index.php?title=Pacman&type=revision&diff=690774&oldid=690762 "Pacman" Revision as of 21:50, 4 August 2021 (undo)] - maybe at least put that into [[System_maintenance#Avoid_certain_pacman_commands]]?<br />
<br />
[[User:Galeksandrp|Galeksandrp]] ([[User talk:Galeksandrp|talk]])<br />
<br />
:[[System_maintenance#Avoid_certain_pacman_commands]] already mentions {{ic|-Rdd}}. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:12, 14 August 2021 (UTC)<br />
<br />
== DPMS: "\033[9;0]" ==<br />
<br />
Hi. It seems that you removed {{ic|echo -ne "\033[9;0]"}} from [[Display Power Management Signaling|DPMS]]<br />
<br />
https://wiki.archlinux.org/index.php?title=Display_Power_Management_Signaling&diff=629705&oldid=625073<br />
<br />
[https://www.denx.de/wiki/view/DULG/SwitchOffScreenSaverAndBlinkingCursor A DULG page] and [https://unix.stackexchange.com/a/23636 a U&L post] brought me here.<br />
<br />
May I ask (1) if this method is still working; and (2) where is this escape sequence documented? [not found in {{man|4|console_codes}}]<br />
<br />
Thanks.<br />
<br />
{{Unsigned|05:23, 15 August 2021 (UTC)|PXf}}<br />
<br />
:[[Display Power Management Signaling#DPMS interaction in a Linux console with setterm]] says that setterm works by writing escape codes to the terminal device. The first subsection shows how to reverse-engineer the escape codes. Note that the escape codes are an implementation detail that users should not be concerned with, their documentation is certainly not our job. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:40, 15 August 2021 (UTC)<br />
<br />
== Linux console/Keyboard configuration ==<br />
<br />
Hi, you recently reverted my edit https://wiki.archlinux.org/index.php?title=Linux_console/Keyboard_configuration&oldid=693887. The reason I made that edit, was that I used to put my custom keymap in {{ic|/usr/local/share/kbd/keymaps/personal}} per the previous version of the wiki page. But this doesn't work with ''sd-vconsole'', as it's include files don't get loaded. Your suggested workaround by adding all required files using [[mkinitcpio#BINARIES and FILES|mkinitcpio BINARIES and FILES]] is rather tedious, as all the include files need to be in there, added by hand. This is done automatically by ''sd-vconsole'' if the file was put in {{ic|/usr/share/kbd/keymaps/}}. The reason I made this edit is due to https://bugs.archlinux.org/task/71788. See Giancarlo Razzolini's comment. [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 09:43, 2 September 2021 (UTC)<br />
<br />
:It's just one custom file under {{ic|/usr/local}} and one entry in {{ic|FILES}}. What is so tedious about it? — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:37, 2 September 2021 (UTC)<br />
<br />
:: It's not just one file. All the dependencies need to be included too under {{ic|/usr/share/kbd/keymaps/}}. There are quite a few in my case, when I just include ''us.map'' to modify it slightly. See the ''sd-vconsole'' hook script. That script has a part where it finds all the dependencies of a keymap.<br />
<br />
:: * ''/usr/share/kbd/keymaps/i386/include/compose.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/euro1.map''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/linux-keys-bare.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/linux-with-alt-and-altgr.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/qwerty-layout.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/qwerty/personal.map''<br />
:: * ''/usr/share/kbd/keymaps/i386/qwerty/us.map''<br />
:: * ''/usr/share/kbd/keymaps/include/compose.latin1''<br />
<br />
:: [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 12:01, 2 September 2021 (UTC)<br />
<br />
::: I moved this to the talk page so I remember it and others can discuss too. [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 09:18, 4 September 2021 (UTC)<br />
<br />
::: Oh, I see. In that case I suggest we add a tip like this:<br />
::: {{Tip|If you use the {{ic|sd-vconsole}} [[mkinitcpio#Common hooks|mkinitcpio hook]] instead of {{ic|keymap}}, keymaps located under {{ic|/usr/local}} as well as their dependencies from {{ic|/usr/share/kbd/keymaps}} need to be manually specified in the {{ic|FILES}} array in {{ic|mkinitcpio.conf}}. On the other hand, custom files located in {{ic|/usr/share/kbd/keymaps}} will be added automatically when configured in {{ic|/etc/vconsole.conf}}.}}<br />
::: Because this is relevant only for people using the {{ic|sd-vconsole}} hook and otherwise it does not make sense to pollute {{ic|/usr/share/kbd/keymaps}} with custom files.<br />
::: — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:55, 5 September 2021 (UTC)<br />
<br />
== cow_* ==<br />
<br />
Hi Lahwaacz. About the [https://wiki.archlinux.org/index.php?title=Archiso&diff=next&oldid=692981 how/why issue] (there will be no more &lt;!-- --&gt;). What if, for once, that I want to install some large packages after booting archiso, and would not bother modifying packages.x86_64 and building again? [https://www.memesmonkey.com/topic/works+on+my+machine <s>''on my machine''</s>] Darren "Un1Gfn" "[[User:PXf|PXf]]" Ng ([[User talk:PXf|talk]]) 08:18, 12 October 2021 (UTC)</div>PXfhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=698901User talk:Lahwaacz2021-10-12T08:17:50Z<p>PXf: /* cow_* */ new section</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== The pip section in [[Python package guidelines]] ==<br />
<br />
Hi, you wanted the warning about using pip or wheels restored but accidentally(?) reverted my whole set of changes. I redid them, leaving the warning in place. – [[User:Flying sheep|flying sheep]] 08:17, 8 March 2019 (UTC)<br />
<br />
:Full revert was intentional, because the "wheel" section is not a full replacement for "pip" because there are packages which don't provide wheel files. As I said in the edit summary, there is no reason to recommend one or the other due to the warning. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:21, 8 March 2019 (UTC)<br />
::That still doesn’t explain why you reverted the first part, that had nothing to do with the pip/wheel section and simple improves the files.pythonhosted.org URLs. I restored that one while we’re discussing the pip/wheel section. And about that: There’s no reason to use pip for anything else, and pip is only used because some people (me included) didn’t understand that you can install most wheels by just extracting them to the correct location. So what do you think is missing from my wheels section that the former pip section had? – [[User:Flying_sheep|flying sheep]] 11:41, 11 March 2019 (UTC)<br />
<br />
:::If you didn't notice, the page includes "guidelines" in the title. So the page should contain only common and recommended ways to do things, not everything that is possible to do. If you think that your way to install "wheels" should be followed by everybody, feel free to discuss it on the talk page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:26, 11 March 2019 (UTC)<br />
::::Well, extracting static archives sounds much more recommended than running pip with like 7 options to make it behave. I added a talk item: [[Talk:Python package guidelines#Remove_pip_section_in_favor_of_wheels_section?]] – [[User:Flying_sheep|flying sheep]]<br />
<br />
== wpa_supplicant ==<br />
<br />
Regarding https://wiki.archlinux.org/index.php?title=WPA_supplicant&diff=577215&oldid=577167, one person ran into this problem in March of this year and spent too much time diagnosing it:<br />
<br />
https://bbs.archlinux.org/viewtopic.php?id=244950<br />
<br />
It took me a few days to find the problem. I want to make sure the next time someone encounters it, they easily find relevant information about what the cause is. Since you've reverted my edits to both netctl and wpa_supplicant, what do you suggest?<br />
<br />
--<br />
<br />
[[User:Pooryorick|Pooryorick]] ([[User talk:Pooryorick|talk]]) 08:24, 18 July 2019 (UTC)<br />
<br />
== F2FS and GRUB ==<br />
<br />
Hello. :) I'm here to address a recent disagreement. I noticed a reversion of my edit regarding the F2FS filesystem, in particular regarding the configuration file to edit (with you representing /boot/grub/grub.cfg and me representing /etc/default/grub). I run F2FS on my daily driver with an encrypted root filesystem and encrypted boot on a separate partition, and have never had to touch grub.cfg. I only automatically generate it. It's possible to use either, but /etc/default/grub would make more sense as a recommendation in my mind because grub.cfg has the potential to be overwritten during updates, whereas /etc/default/grub doesn't. <br />
<br />
If there's a compelling reason to use grub.cfg over /etc/default/grub, please let me know. ^^ I'm always eager to learn more about Arch. I don't want to get in a reversion war so I've left your change untouched for the time being.<br />
<br />
[[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 00:17, 8 September 2019 (UTC)<br />
<br />
:The reason is explained in the section: "If GRUB is used with an unsupported filesystem it is not able to extract the UUID of your drive so it uses classic non-persistent /dev/sdXx names instead." If it does not apply to F2FS, it should be made clear. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:29, 8 September 2019 (UTC)<br />
<br />
::You can specify UUID's in GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, so my proposed solution would work for F2FS and other unsupported filesystems, without the burden of manually editing grub.cfg. If there's anything I need to clarify or something else I'm missing, just let me know. :) [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 19:37, 8 September 2019 (UTC)<br />
<br />
:::The {{ic|1=root=}} parameter is not supposed to be in GRUB_CMDLINE_LINUX_DEFAULT, regardless if UUID is used or not. ''grub-mkconfig'' automatically detects the root filesystem and adds the appropriate {{ic|1=root=}} parameter based on GRUB_DISABLE_LINUX_UUID. In any case, your change to the paragraph does not make sense. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:02, 8 September 2019 (UTC)<br />
<br />
::::It could simply be because I use full disk encryption, and adding a kernel parameter for the encrypted disk's UUID is correct in that situation. You're more experienced with contributing to the wiki, so I guess I'll defer to your judgment. It felt like a reasonable edit and solution to me and I don't see the downside to including it in GRUB_CMDLINE_LINUX_DEFAULT. [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 05:38, 9 September 2019 (UTC)<br />
<br />
== dracut executable link ==<br />
<br />
Hello, your last edit on the dracut page (https://wiki.archlinux.org/index.php?title=Dracut&oldid=596388) that undid my 'Link to direct "make executable" section for executable link' commit states: "the redirect executable points exactly to that section", but it doesn't. Following the [[executable]] link just points to the top of the Help:Reading page.<br />
<br />
{{unsigned|17:06, 28 January 2020|Krathalan}}<br />
<br />
:In that case your browser probably does not work correctly, because the redirect [https://wiki.archlinux.org/index.php?title=Executable&redirect=no really points to the section]. Or MediaWiki, there was a bug several years ago... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 28 January 2020 (UTC)<br />
<br />
:: How strange... thanks for pointing that out. It does indeed appear to be some issue with my Firefox configuration. [[User:Krathalan|Krathalan]] ([[User talk:Krathalan|talk]]) 19:51, 28 January 2020 (UTC)<br />
<br />
== Getting install.php work in DokuWiki ==<br />
<br />
Hi, than you for having undone my contribution and pointed to the right solution on [[Dokuwiki#Configuration]]. Indeed I had read this solution before, but I was misled by the condition "if you are using lighttpd or nginx and your PHP version is lower than 7": as I use Apache with php v. 7.4.3 I didn't take it into account. Do you know what a correct rephrasing could be? Maybe it should be deleted?<br />
<br />
Also, I think that, at the end of this same section, one should add something like "verify that {{Pkg|php-gd}} is installed and restart {{ic|php-fpm.service}}".<br />
<br />
Naturally I can do it myself, but I prefer to ask before.<br />
[[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 17:31, 19 February 2020 (UTC)<br />
<br />
:Hi, apparently it depends on whether you had {{ic|open_basedir}} set previously or not. I've changed the page, feel free to update the gd extension. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:16, 19 February 2020 (UTC)<br />
<br />
::Thank you! However, while, I didn't have {{ic|open_basedir}} set previously, I couldn't access ''install.php''. I suspect there is another thing to do, since the configuration editor in DokuWiki complains that it cannot modify the configuration files although ownership and permissions are correctly set for the relevant symlinks, directories and files, and so is {{ic|open_basedir}}. However I can edit my pages. Maybe a return from a new user with a fresh installation would be more useful, though. [[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 08:20, 20 February 2020 (UTC)<br />
<br />
== Dead link in Simple stateful firewall#See Also ==<br />
<br />
Hi, Jakub. I am about [https://wiki.archlinux.org/index.php?title=Simple_stateful_firewall&diff=599725&oldid=599717 this] edit. I tried to follow that link one more time and it is not require entering captcha. I am not see any content limitations and my colleague (he uses Tor) does not see them too. I am not sure how it works, so I leave it on your descision. -- [[User:Duodai|Duodai]] ([[User talk:Duodai|talk]]) 14:29, 1 March 2020 (UTC)<br />
<br />
:Well, maybe it depends on the location from which the request comes. But I don't know how it works either... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:33, 1 March 2020 (UTC)<br />
<br />
::my guess is it returns captcha for crawlers only -- [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 01:59, 2 March 2020 (UTC)<br />
<br />
:::I'm getting it in my browser... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:14, 2 March 2020 (UTC)<br />
<br />
== SystemD user units depending on graphical session ==<br />
Hi,<br />
regarding reverting my addition to [[Systemd/User]], could you please explain why? I referenced [[https://www.freedesktop.org/software/systemd/man/systemd.special.html]] which directly contradicts what you said in your summary.<br />
<br />
{{unsigned|19:53, 5 May 2020|Fuero}}<br />
<br />
:The note in [[Systemd/User#How it works]] still applies - systemd services are never per-session, but per-user. The service does not magically get the correct DISPLAY or WAYLAND_DISPLAY variable, it does not work if you have multiple sessions per user, etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:45, 6 May 2020 (UTC)<br />
<br />
== Plymouth ==<br />
<br />
Actually with just Plymouth it does not work properly. Even 0dd17y had the same issue in https://bbs.archlinux.org/viewtopic.php?id=220900.<br />
<br />
The reason I did not file a bug report is that it is anyway fixed in the git version and the latest release (0.9.4) is around 2 years behind master<br />
<br />
{{unsigned|09:50, 6 May 2020|M.Srikanth}}<br />
<br />
:So if you don't have to file a bug report, add a full troubleshooting entry or at least properly reference your inline note instead of resorting to plain "if that does not work, try this instead". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:15, 6 May 2020 (UTC)<br />
<br />
== [Bitcoin core] build the code and run the test suites ==<br />
<br />
Hello,<br />
<br />
This week, I managed to build the Bitcoin code and run all the test suites with the help of this page: https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests<br />
<br />
Archlinux has two particularities:<br />
* being in rolling release, it takes to manually use the library {{ic|Berkeley DB (BDB) v4.8}}<br />
* the {{ic|/tmp}} directory is by default limited to half the size of the Ram<br />
<br />
For these reason, maybe it could be interesting to have a page in the wiki to explain how to build the Bitcoin core?<br />
<br />
Cheers,<br />
<br />
Thomas<br />
<br />
[[User:Thomasb|Thomasb]] ([[User talk:Thomasb|talk]]) 20:29, 9 May 2020 (UTC)<br />
<br />
:I don't think that this is useful. There is the {{AUR|bitcoin-core-git}} package and nothing more should be needed. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:53, 26 May 2020 (UTC)<br />
<br />
== Double linefeed results in extra line ==<br />
<br />
If you look at templates that end with double linefeed before noinclude this would result in extra line in resulting page.<br />
<br />
It may be a minor point but since you are perfectionist about wikitext I should mention this is a tradeoff and it results in slightly worse result.<br />
<br />
Removing just one linefeed removes the problem while still allowing it to not jumble all the tags into same line.<br />
<br />
-- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 16:30, 11 May 2020 (UTC)<br />
<br />
:If this is about [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=next&oldid=612179], the spaces I added back are not included when the template is used elsewhere, because the spaces are inside the noinclude tags. The extra space is only on the template page itself, but it does not result from template inclusion. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:41, 11 May 2020 (UTC)<br />
<br />
::OFC, I mean the template page render has extra line. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 21:21, 11 May 2020 (UTC)<br />
<br />
:::I agree with [[User:Svito|Svito]], isn't it good to delete the extra blank lines? -- [[User:Blackteahamburger|Blackteahamburger]] ([[User talk:Blackteahamburger|talk]]) 05:39, 12 May 2020 (UTC)<br />
<br />
::::OK, let's do it. [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=616382&oldid=612181] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:47, 26 May 2020 (UTC)<br />
<br />
== Re: lighttpd: remove python2 version ==<br />
<br />
Instead of removing the example we could as well add an example using a Python3 library like https://pypi.org/project/flup6/.<br />
<br />
{{unsigned|15:23, 18 May 2020|Gruentee}}<br />
<br />
:Feel free to add it if you find it useful. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:56, 18 May 2020 (UTC)<br />
<br />
== Xbindkeys removal ==<br />
<br />
Hi, just wondering why you [https://wiki.archlinux.org/index.php?title=Xbindkeys&diff=617675&oldid=617670 removed my edit] from [[Xbindkeys]]? The xbindkeys page has a number of quick tips but no mention of how to bind anything to the Print Screen key so I thought it would be useful to add. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:27, 3 June 2020 (UTC)<br />
<br />
:Giving examples for all keys on the keyboard is useless, there is [[Xbindkeys#Identifying keycodes]] which teaches how to find the keycodes and keysyms of any key. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 3 June 2020 (UTC)<br />
<br />
:: So how come you left the examples for the volume up/down and brightness? What is different between those examples and a screenshot example? Aren't more examples better to save people from hunting all over the place trying to piece things together themselves? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 14:03, 4 June 2020 (UTC)<br />
<br />
:::The difference is that when it comes to volume control, there are 1 or 2 options for the 99% most common cases, but for screenshot taking there are dozens of different options. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:15, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for edit to XDG Base Directory page regarding python_history ==<br />
<br />
I understand the justification for reverting the change I made, however I would like to point out that similar entries on the page (such as Maven) also have instructions for what contents to put in files (even though there is native documentation for those settings). Additionally, it took me a bit of re-reading on the linked Python documentation to reason out how the documentation's example needed to be modified, since it's not clear from the Python documentation whether placing such code in the PYTHONSTARTUP file will actually ''override'' the default behavior. [[User:Varriount|Varriount]] ([[User talk:Varriount|talk]]) 20:44, 20 June 2020 (UTC)<br />
<br />
:Even maven's note can be [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=631704&oldid=631630 shortened]. The notes in the table must be as short as possible, there is no place for extended explanations or long code snippets like in the upstream documentation. If the Python's documentation is not clear enough, I don't think any note in a massive convoluted table will ever be better. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:47, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for Backlight page ==<br />
<br />
Hi, you reverted my change to [[Backlight]] page that mentioned WIP patches for controlling OLED panel brightness. I don't really understand justification for reverting it since currently the page says that OLED brightness can be controlled only by changing gamma ramp. That is wrong - since it's not the only way - these panels can control brightness with a PWM. Moreover controlling brightness with gamma ramp is not optimal - it essentially reduces dynamic range, i.e. at 50% you have 7 bits per pixel, at 25% - 6 bit per pixel, etc. That results in banding artifacts at lower brightness level.<br />
<br />
As far waiting for the patches to be merged before mentioning it there - it'll take ~3-6 months (yes, that's the process) and I haven't found *any* reference to these changes on the internet - everyone recommends using gamma ramp instead of fixing it properly. I'm absolutely sure that having information about these patches would not hurt [[User:Anarsoul|Anarsoul]] ([[User talk:Anarsoul|talk]]) 15:56, 30 June 2020 (UTC)<br />
<br />
:Linking to a repo which which has 2 custom commits on top of some arbitrary development version of the Linux kernel tree is not helpful for users. Nobody will compile directly from this repo which is already significantly outdated compared to recent kernel versions and there is no indication if the patches actually work with newer (or older) kernels. We can mention the PWM control as a general concept though. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:32, 12 August 2020 (UTC)<br />
<br />
== Automatic template correction ==<br />
<br />
Per [[Help:Template#Style]], templates should be used with the capitalization shown in the examples in their pages, so {{ic|&#123;{AUR&#124;...}} is correct, while {{ic|&#123;{aur&#124;...}} is not.<br />
<br />
However, there are pages that don't respect that rule (e.g. [[Android_Debug_Bridge]] until recently).<br />
<br />
I beleive this correction should be easy to implement using a bot. What do you think?<br />
<br />
{{unsigned|07:24, 25 August 2020|Relrel}}<br />
<br />
:Yes, this should be easy, but the bot should not make a huge amount of simple style-only changes - they should be combined with corrections for more complex rules. Anyway, there is an idea to create a [https://github.com/lahwaacz/wiki-scripts/issues/22 style linter] for the ArchWiki rules. Would you like to help? ;-) – [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:21, 25 August 2020 (UTC)<br />
<br />
== Failed to create tun device ==<br />
<br />
I don't understand your reason for [[https://wiki.archlinux.org/index.php?title=NetworkManager&diff=0&oldid=634880 removing my section in NetworkManager]]. Could you elaborate?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 07:40, 11 September 2020 (UTC)<br />
<br />
:You can't use [[systemd-networkd]] and [[NetworkManager]] at the same time. Even if you don't have any ''.network'' file for systemd-networkd, you can't solve NetworkManager's problems with systemd-networkd. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:43, 11 September 2020 (UTC)<br />
<br />
::Ok, thanks, in this case it solved the error I got. Now the VPN works. Do you have an idea about how to solve it without systemd-networkd?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 22:27, 11 September 2020 (UTC)<br />
<br />
:::You should really fix the permission problem for {{Pkg|networkmanager-openvpn}}. The tun interface should be managed by OpenVPN which needs rights to create it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 12 September 2020 (UTC)<br />
<br />
::I don't think this statement is entirely correct. [[systemd-networkd]] and [[NetworkManager]] can happily co-exist together if they are managing different interfaces. I unfortunately don't have a reference to point to this, but I came across this being mentioned a couple of times on forums. I personally use [[NetworkManager]] on my laptop to handle wifi, while [[systemd-networkd]] is in control of virtual ethernet and bridges for all my [[systemd-nspawn]] instances. [[User:Romstor|Romstor]] ([[User talk:Romstor|talk]]) 03:24, 12 September 2020 (UTC)<br />
<br />
== [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&oldid=636526/ XDG Base Directory]: Undo revision 636525 ==<br />
<br />
Dear Lahwaacz,<br />
<br />
maybe my changes were to rushed and from my point of view only. But I have two points to consider:<br />
<br />
# If I put the quotes around my vimrc and source it from my .bash_profile, I get the vim-error E471 (Argument required). Without quotes, this doesn't happen. So this change based on experience.<br />
# The rtp should includes directories, which are needed at runtime. (in plain vim e.g. ~/.vim). This is not a typical configuration directory. My mistake was, that I supposed that everyone put their vim plug-ins in $XDG_DATA_HOME and not in $XDG_CONFIG_HOME, because from my point of view a plug-in doesn't belong to the configuration. Maybe it is a good idea to add a remark, which explains the addition of $XDG_CONFIG_HOME to the rtp.<br />
<br />
[[User:Grrr|Grrr]] ([[User talk:Grrr|talk]]) 13:53, 26 September 2020 (UTC)<br />
<br />
# Quotes are there because $XDG_CONFIG_HOME may contain spaces.<br />
# It's not only about quotes - the runtimepath has subdirectories for color schemes, keymaps, autoload scripts etc.<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 26 September 2020 (UTC)<br />
<br />
== Readability in Wiki ==<br />
<br />
I noticed that you and the other admins and moderators often want sentences to continue endlessly, without line breaks.<br />
For example in the introduction of [[Wayland]].<br />
<br />
I think it would be better to have more seperated sentences, so it is easier to read and "important" information is easier visible for people.<br />
I don't know who is responsible, but maybe some options in MediaWiki (or whatever this wiki software is) could be changed as well, to make make line breaks etc. easier and reduce the height-space (if you know what I mean) between sentences, so it looks better, even though line breaks are used.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:38, 15 October 2020 (UTC) G3ro<br />
<br />
:I don't know exactly what you mean. Is it about the readability of the rendered HTML or the "source code" of the page? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 15 October 2020 (UTC)<br />
<br />
:: Well I guess it can be about both. But mainly it is about what people see on the page.<br />
:: There are three seperate topics I mentioned:<br />
<br />
:: 1. Use line breaks: I would like to use more line breaks, because if you have long sentences that are written after each other without line breaks, it gets "harder" to recognize when the next sentence starts.<br />
:: While I agree to what you said somewhere, that sentences that belong directly together, should be written in one "paragraph", it would be useful for sentences that cover (slightly) different "topics" to be visibly parted.<br />
<br />
:: 2. Adjust margin options: I notice that when line breaks are used, there is a vertical space added between two sentences. Just like in this post. If you would use line breaks more often, this is a little too much spacing in my oppinion.<br />
<br />
:: 3. Potential options to make line breaks easier: It would be very convenient if a line break in the source code would lead to a line break in displayed text as well, instead of needing to add an empty line.<br />
<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:33, 15 October 2020 (UTC) G3ro<br />
<br />
:::OK, now I understand. I agree that splitting different topics usually improves legibility, but they should be split into separate paragraphs and not just by line breaks (e.g. using the &lt;br> tags). Paragraphs are semantic units whereas line breaks inside a paragraph are usually typographic errors.<br />
:::Also note that such splitting alone may not be enough to improve the text flow. For example, if we consider the intro for [[Wayland]], the second sentence about XWayland would not constitute a good paragraph - it is just a plain statement and the new topic is not nicely introduced. Ideally, you'd split the topic and make some wording changes for the second paragraph.<br />
:::As for the margin options, that is the difference between paragraph splitting and non-semantic line breaks. In my opinion, the styling is correct in this respect, as paragraphs should be discernible. You mentioned that you like line breaks to easily recognize where a sentence ends - but reading should be based on whole paragraphs, not sentences. There should be no reason to skip anything in the middle of a paragraph, otherwise it should be probably split into multiple paragraphs or otherwise rephrased.<br />
:::If you find it hard to follow a long sentence horizontally on a wide screen, we might consider enforcing some maximum width for the whole content. I think the readability would be better, since there would be more top-to-bottom eye movement at the cost of left-to-right-and-back.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:59, 15 October 2020 (UTC)<br />
<br />
== Xorg parentheses ==<br />
<br />
I actually think that X(org) is very useful to imply that it is one and the same thing.<br />
<br />
It might even be more confusing now, as we use both Xorg and X, because the wiki title and the package titles are Xorg.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:30, 17 October 2020 (UTC) G3ro<br />
<br />
:Well the conventions should be established on the [[Xorg]] page, not anywhere else... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:36, 17 October 2020 (UTC)<br />
<br />
:: Imo the conventions are established by upstream and they use a wide variety of X, X.org, X(org), Xorg etc.<br />
:: As I said I always prefer X(org) because then it is clear, that both are same thing.<br />
:: But ultimately it's your decision. <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:43, 17 October 2020 (UTC) G3ro<br />
<br />
:::When upstream is not capable of making a unambiguous decision, it makes sense that other projects pick some option and stick with it wherever they can to keep at least some consistency. So for this wiki, pages should use the same style as the [[Xorg]] page. But feel free to start a discussion about this in [[Talk:Xorg]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:56, 17 October 2020 (UTC)<br />
<br />
== SSHFS - systemd edit ==<br />
<br />
The edit was removed because "there is no advantage over using fstab entries".<br />
<br />
Is not only about the dis/advantages of the systemd option, is about that it is another possibility to achieve the task, that is why it was created in another level and the fstab section was left alone.<br />
<br />
Reconsider the edit as it presents another option which people can use.<br />
<br />
[[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 16:22, 22 October 2020 (UTC)<br />
<br />
:There is no need to use anything else, fstab just works well enough. Configuring mounts with systemd services is not a good idea - it is much more bloated than fstab and not the right tool for it. If anything, a different type of systemd units should be used: {{man|5|systemd.mount}}. But creating the mount units manually is still pretty useless since everything can be configured in fstab and systemd will generate the unit for you. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:22, 22 October 2020 (UTC)<br />
<br />
:: It is about the ability to use the user's .config file and all the proper options that are saved there. Also systemd gives the possibility to use different targets, so the user could mount it when an specific user logs in or when a graphical session starts. I could argue that bad a modification of fstab could lead to a system that doesnt boot, but such poorly configured systemd unit file just fails and the system is fine. Just give the user the information and let it decide what they can use depending on their use case. [[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 08:08, 24 October 2020 (UTC)<br />
<br />
:::You can configure systemd targets in fstab using the {{ic|x-systemd.wanted-by}} and {{ic|x-systemd.required-by}} options, there are also {{ic|nofail}} and {{ic|noauto}} options. Please read the {{man|5|systemd.mount}} manual.<br />
:::Using hosts from the user's {{ic|.ssh/config}} is the only thing which is not possible with fstab, but this does not warrant using the wrong tool for the task. Simple copy the full {{ic|user@hostname}} into fstab and you're done.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:47, 24 October 2020 (UTC)<br />
<br />
== [[Self-encrypting drives]] ==<br />
<br />
Hi, I'd like to respectfully disagree with the rollback. It's specific to sedutil that with most commands you need to input /dev/nvme0 (when encrypting the device) but for the sleep commands it requires /dev/nvme0n1 or it fails with a very unspecific error (Error saving the password to the kernel errno = 25), as found out in the discussion https://github.com/Drive-Trust-Alliance/sedutil/issues/90<br />
<br />
All in all I believe that it is important to keep this piece of information which was found out in a long discussion between the reporter and the developers. I ran into it and I believe many people may run into it, considering most of the new SSD will be NVMe. Best, [[User:Przemub|Przemub]] ([[User talk:Przemub|talk]]) 13:34, 28 October 2020 (UTC)<br />
<br />
:OK, then it makes sense. But it should be probably explained before, not in the section about the sleep command. Also please add the link to the note as a reference. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:27, 28 October 2020 (UTC)<br />
<br />
== Nvidia Installation ==<br />
<br />
The whole guide is unnecessary long and overcomplicated formulated.<br />
Shorter is better, most people will know their graphic card for example, so the determination etc. is only optional.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:21, 10 November 2020 (UTC) G3ro<br />
<br />
:Moving some info to some other page and leaving a tip behind does not make it shorter, but harder to follow. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:36, 10 November 2020 (UTC)<br />
<br />
== Btrfs layout ==<br />
<br />
Hi, Lahwaacz<br />
<br />
Thanks for maintaining [[Snapper]]! However I think the layout is not openSUSE specific and beneficial to all btrfs users. Can you elaborate your reason of undoing the edits? IMO the previous 'simple layout' complicates the rollback procedure.<br />
<br />
Cheers,<br />
[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 07:26, 3 December 2020 (UTC)<br />
<br />
:It is not overcomplicated, it is just doing things right. You can read about that in the forum thread, see the first note in [[Snapper#Suggested filesystem layout]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:24, 3 December 2020 (UTC)<br />
<br />
::Anyway I've moved the guides to my user page. It's not that I haven't read the 5-year-old forum post, it's that before the current layout I followed that post and resulted in a not fully rolled-back system. That post also sourced (then current) information from openSUSE. openSUSE has since massively overhauled the layout, as I pointed out in an edit you undid earlier.[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 09:02, 3 December 2020 (UTC)<br />
<br />
::Since last message I've extensively documented the new layout at [[User:I2Oc9/Btrfs_subvolumes]] and [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption]]. Have a look for yourself. Nothing new really, but IMO [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my take]] is much more simpler and complete than the supposedly [[Snapper#Restoring_/_to_a_previous_snapshot_of_@|simpler one]]. That one does not leverage native {{ic|snapper rollback}} or {{Pkg|grub-btrfs}}, among other things. I strongly suggest you try if you have time. [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 11:55, 3 December 2020 (UTC)<br />
<br />
::Actually if you look closely, none of [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my recovery methods]] is specific to [[User:I2Oc9/Btrfs_subvolumes#A_new_kind_of_layout|the new 'complex' layout]], it will work totally fine with the old one. I just don't think moving @ around in live environment is appropriate.<br />
<br />
::On the other hand, the layout recommendation has been updated by openSUSE [https://en.opensuse.org/SDB:BTRFS], why stick with the old one? [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 12:37, 3 December 2020 (UTC)<br />
<br />
:::The main reasons why I reverted your edits on the [[Snapper]] page are: 1) it was a huge change which was not discussed previously as required by [[ArchWiki:Contributing#The 3 fundamental rules]], and 2) it has some elements which do not apply to Arch (see below). If you wish to propose a better layout of the subvolumes, it should be discussed in [[Talk:Snapper]] first. Your user pages would serve as great drafts.<br />
:::Note that the current suggested layout is not ''flat'' in the sense of [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|your section]] - it has a separate subvolume for {{ic|.snapshots}} so it does not lead to the recursive mess. So your proposed layout seemed very similar to the current suggested layout. The real difference is which subvolume gets mounted at {{ic|/}}, but I did not find it explained anywhere on the Snapper page before I reverted the changes (I get it now from your user page). I also did not find a proper documentation of the openSUSE's layout - it seems to be just the product of their installer and the documentation only deals with the result, saying at most that [https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha-snapper.html#sec-snapper-snapshot-boot the subvolume configuration must not be changed] for rollbacks to work.<br />
:::Now the openSUSE-specific elements: some Arch packages actually install software into {{ic|/opt}}, so the recommended layout should not suggest a separate subvolume for this path. Even more importantly, the pacman database is located at {{ic|/var/lib/pacman/local/}} and it must be rolled back along with the system, so there should be no separate subvolume for {{ic|/var}}. Instead, users should be encouraged to create (even nested) subvolumes for specific data directories under {{ic|/var}}, such as {{ic|/var/log}}, {{ic|/var/tmp}}, {{ic|/var/cache/pacman}}, {{ic|/var/lib/machines}}, etc.<br />
:::Finally, the suggested layout should not be GRUB-specific, there should be no recommendations regarding a boot loader. Sure it is useful to include non-trivial tips, but people may actually use a different boot loader.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:31, 4 December 2020 (UTC)<br />
<br />
::::Thanks for your detailed reply. I admit that I'm not knowledgeable on the intricate differences between distributions and shouldn't have made the changes without properly discussing them first.<br />
::::Yes, I get that the current layout is not [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|the one described in this section]] and indeed properly separates {{ic|/.snapshot}} and {{ic|/}}. The layout I proposed attempts to add some "niceties" such as supporting multi-distribution installations (complex and unnecessary, I agree) and bring the openSUSE layout here, which is a mistake, as you've pointed out.<br />
::::As for GRUB, since I use LUKS all the time and it's the only bootloader supporting encrypted {{ic|/boot}} on Btrfs on LUKS1, I really didn't think of any other possibilities.<br />
::::I will incorporate your recommendations to my user page and add a new section in [[Talk:Snapper]] pointing to those pages.<br />
::::Cheers -- [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:09, 4 December 2020 (UTC)<br />
<br />
:::::I've adopted [[Install_Arch_Linux_on_ZFS#System_datasets|Archlinux Root on ZFS layout]] to [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Create_subvolumes|my proposal]]. [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:56, 4 December 2020 (UTC)<br />
<br />
== Reflector Revert ==<br />
<br />
Hi Lahwaacz, about your [https://wiki.archlinux.org/index.php?title=Reflector&oldid=643749 revert], it seems like there's precedence for including AUR packages that replicate the code on the wiki. For example, in [[dash#Relinking /bin/sh]].<br />
<br />
In addition, I believe that there's value for linking the AUR package because it allows a simpler user experience where the AUR package is maintained for them. That way, if it is ever updated, they can easily fetch the update instead of religiously checking the wiki page (which most users probably don't do).<br />
<br />
Thanks!<br />
<br />
[[User:Denton-l|Denton-l]] ([[User talk:Denton-l|talk]]) 01:52, 7 December 2020 (UTC)<br />
<br />
:That precedence was only created by [https://wiki.archlinux.org/index.php?title=Dash&type=revision&diff=561587&oldid=518398 yourself]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:35, 5 May 2021 (UTC)<br />
<br />
== firefox zoom ==<br />
<br />
"no reason to zoom manually, see HiDPI)" - fractional scaling doesn't work [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 02:38, 26 December 2020 (UTC)<br />
<br />
:That should be explained in [[HiDPI#Firefox]] anyway. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:48, 26 December 2020 (UTC)<br />
<br />
::it's good to have this mentioned somewhere clearly so people know about it before they say "fonts on linux suck" [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 15:51, 29 December 2020 (UTC)<br />
<br />
== Intel GVT-g edits ==<br />
<br />
Hello Lahwaacz,<br />
<br />
I have noticed that you reverted one of the edits I have performed on [[Intel_GVT-g]].<br />
<br />
About this revert: [https://wiki.archlinux.org/index.php?title=Intel_GVT-g&oldid=648062 Windows problems are out of scope]<br />
<br />
While I understand that the ArchWiki is about ArchLinux, this article in particular mentions Windows in the introduction, and already includes another troubleshooting point about Windows. The issue I have encountered with the black bars is somewhat common, as I have found other people discussing it online, and I really fail to see why not including this piece of information in this article would be better than including it.<br />
<br />
Please, let me know your thoughts. If you think that the point can be improved, I will be happy to do that.<br />
<br />
Ciao,<br />
<br />
[[User:Wilcomir|Wilcomir]] ([[User talk:Wilcomir|talk]]) 09:14, 3 January 2021 (UTC)<br />
<br />
:Well, the existing section about a Windows problem is actually solved by configuring the Linux host. I think anything involving configuration or installation of programs in Windows is not appropriate for long troubleshooting sections. At most, they could be mentioned in a short reference to other sites which describe the problem in detail. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:34, 3 January 2021 (UTC)<br />
<br />
== <s>XDG configuration for Vim</s> ==<br />
<br />
Hi Lahwaacz,<br />
<br />
You have reverted the updated Notes for Vim on [[XDG Base Directory]], because "copy-pasted from a blog post".<br />
<br />
The problem is, not only is the configuration presented currently also copied from a blog post too, but is already 10 years old.<br />
<br />
Would it be OK, if we bring back the more up to date version? Or at least remove the obsolete one and leave link to newer?<br><br />
(Although I think a copy on wiki would be beneficial in case my blog ceases to exist)<br />
<br />
[[User:Jorengarenar|Jorengarenar]] ([[User talk:Jorengarenar|talk]]) 02:05, 12 January 2021 (UTC)<br />
<br />
:OK let's close this. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:49, 29 August 2021 (UTC)<br />
<br />
== Root on ZFS draft ==<br />
<br />
Hi, I submitted [https://github.com/openzfs/openzfs-docs/pull/104 a Root on ZFS draft] to official doc repo.<br />
<br />
In the draft, the following directories are separated from root filesystem:<br />
home,root,srv,usr/local,var/log,var/spool,var/tmp<br />
<br />
Is this appropriate for Arch Linux? Or do you have any suggestion on the draft?<br />
Any comment is appreciated.<br />
[[User:M0p|M0p]] ([[User talk:M0p|talk]]) 01:28, 23 January 2021 (UTC)<br />
<br />
== Re: undo GRUB - Common installation errors ==<br />
<br />
Concerning your undo of [https://wiki.archlinux.org/index.php?title=GRUB&diff=next&oldid=649799 Add the error message `Could not prepare Boot variable: No space left on device`)]<br />
Is there a better place to for this Information? One can find the solution in various forums, but I thought it could be helpful to have it in this wiki somewhere. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 12:51, 25 January 2021 (UTC)<br />
<br />
:The error message is not specific to the {{ic|/sys/fs/pstore/}} filesystem (which does not even seem to be used by default on Arch...) Where did you find that? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:16, 25 January 2021 (UTC)<br />
<br />
::I did not find anything Arch specific, but this post about Debian helped: [https://donjajo.com/fix-grub-efibootmgr-not-set-variable-no-space-left-device/ Post]. I also found something about [https://askubuntu.com/questions/1072618/could-not-prepare-boot-variable-no-space-left-on-device-grub-install-error-ef /sys/fs/efi/efivars/dump-*] The problem is that the actual efi-partition does not seam to be the problem, there is more than 70% space left. If there is better information to guide the user in the right direction that wuld be more helpful. This is what I found worked, but I admit that I don't know much about how grub operates. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 16:20, 25 January 2021 (UTC)<br />
<br />
:::This wiki ''is'' Arch specific so old posts about Debian or Ubuntu do not apply. Even if they did, this is hardly a ''common'' installation problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:29, 26 January 2021 (UTC)<br />
<br />
::::I know that, and would not have put it there if it didn't occur on my Arch Linux installation. If this is something that should not be documented in this wiki, I understand that. Is there any other place you would recommend? An issue for grub-install maybe? [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 22:24, 26 January 2021 (UTC)<br />
<br />
== Kernel Compilation time ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Kernel&diff=next&oldid=650896 link]<br />
<br />
I don't think we should judge information by what is obvious to experts.<br />
People might have experience with compilation of other programs, which mostly is fast, and then there is the kernel which takes forever to compile.<br />
I think it does not hurt anyone to make people aware of it.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:03, 6 February 2021 (UTC)<br />
<br />
:It is an unnecessary information without a definite answer which can even be [https://html.duckduckgo.com/html?q=how%20long%20does%20it%20take%20to%20compile%20Linux%20kernel searched elsewhere]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:23, 6 February 2021 (UTC)<br />
<br />
:: I disagree, with that argument nearly any tip and note is unnecessary. These things are intended to inform users about things that should be taken into consideration and that are different from the norm.<br />
:: Also do you search for the compilation time for every program you intend to compile? I don't.<br />
:: Furthermore this info is included, why not tell it to people directly on the start, so they don't read over it? <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:36, 6 February 2021 (UTC)<br />
<br />
:::If someone wants to compile the Linux kernel, they should obviously expect that it will take ''some time''. Stating that it "can take up to several hours" does not make sense without referring to a specific hardware. Obviously, it will take much longer on a poor laptop than on a powerful workstation with a many-core processor, but people can assume that themselves. Without a reference to a specific hardware, the note is unnecessarily discouraging because the compilation can be as fast as some tens of minutes - it is by far not the most expensive package to compile...<br />
:::As you said, people can find better notes later along with advices to enable parallel build etc. which is all that's needed IMO.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:03, 6 February 2021 (UTC)<br />
<br />
== Wayland style ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Wayland&diff=prev&oldid=650979 link]<br />
<br />
I think in the old version it was much easier to read the "source code", so I don't see why there can't be spaces between it.<br />
Things shouldn't be complicated more than necessary.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:11, 6 February 2021 (UTC)<br />
<br />
:Most templates on the wiki are written without spaces around the |. When we [https://github.com/archlinux/archwiki/pull/32 switch the editor], there will even be syntax highlighting. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:25, 6 February 2021 (UTC)<br />
<br />
== Bluetooth keyboard ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php/Bluetooth_keyboard link]<br />
<br />
On your last change you said "not specific to keyboards, all of this is already mentioned on the Bluetooth page", the point is that this is extremely relevant for bluetooth keyboard since it is required to perform the login! If this little piece cannot be duplicated I would suggest at least to leave a link saying "If you want to autoconnect at boot please refer to...". I'm new here and I would not touch it further, but please evaluate the suggestion (this is because after reading bluetooth keyboard page and not finding the solution I had to look for it on forums)<br />
<br />
{{unsigned|21:17, 20 February 2021|Stevexyz}}<br />
<br />
:Well, basically the whole page is flagged to be merged with the main [[Bluetooth]] page, so it's expected to be incomplete. Other tips may always be found on a more general page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:40, 21 February 2021 (UTC)<br />
<br />
== Re: Steam Needs to be online error ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Steam/Troubleshooting&diff=next&oldid=653073 link]<br />
<br />
The problem here is that DNS resolution in general works already (yes even outside browsers), i.e. <br />
<br />
dig media.steampowered.com<br />
<br />
would run successfully, but the Steam client couldn’t resolve it. The DNS request from 'dig' shows up in my nameserver’s log, the one Steam should send doesn’t. This indicates it might indeed a problem specific to Steam, and it’s not as easy as just say "go fix your DNS resolution", as it already may work correctly for everything but Steam.<br />
<br />
Additionally, at no point does [[Domain name resolution]] even mention nscd, so you effectively removed a fix/workaround for the problem from the Wiki. So I was definitely not "duplicating an article" here. [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 08:12, 22 February 2021 (UTC)<br />
<br />
:Could I please hear your opinion on this? I’d be happy to just add something along the lines of "if you made sure DNS resolution works but Steam still can’t resolve it, try additionally enabling the nscd service" to the Steam troubleshooting page. Unfortounately I don’t know why running the service helps, but I’d still like to give others an easier time finding this solution than I had myself. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 09:15, 28 February 2021 (UTC)<br />
<br />
::Hi, I'm sorry for the delay. Could you test if using a different program for DNS caching (e.g. [[systemd-resolved]]) instead of {{ic|nscd.service}} fixes the problem? If not, then it's probably not due to DNS - {{man|8|nscd}} actually caches more than just DNS. Also if you have a reference to some website where you found about nscd, it would be nice to add it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 28 February 2021 (UTC)<br />
<br />
:::No worries. Using [[systemd-resolved]] for DNS resolution (and caching I guess, I wasn’t aware it does that, too) was a thing I did try, but that didn’t fix it for me. The place I found out about nscd fixing it was actually the [https://bbs.archlinux.org/viewtopic.php?id=263356 Arch forums]. When I search the web for Steam in combination with nscd, all I can seem to find are more forum entries of people that don’t know why that fixes it either. I can try a bit to find out what nscd does to make it work, but I’m not too confident I will be successful. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 14:51, 28 February 2021 (UTC)<br />
<br />
::::Okay, so {{ic|nscd}} allows to [https://man7.org/linux/man-pages/man5/nscd.conf.5.html dis-/enable caching per service], and it’s indeed enabling it for {{ic|hosts}} that makes it work. That’s weird though, since [[systemd-resolved]] has caching enabled by default, and using it for resolution didn’t make {{ic|steam}} work for me. Leads me to think that I didn’t set it up correctly, although resolving via {{ic|dig}} *did* work. Since [[steam]] depends on [[Name Service Switch]], I tried resolving using {{ic|getent}} manually with nscd disabled, but that worked while steam did not. I’m not really sure what to make of this, since I have no idea how this low level networking/resolving stuff works really. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 15:39, 28 February 2021 (UTC)<br />
<br />
:::::Hmm, I don't know the details either. Steam needs the multilib packages so maybe that's part of the problem. Could you add your findings to the section and use [[Template:Expansion]] for the missing details? Maybe someone can figure it out. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:44, 28 February 2021 (UTC)<br />
<br />
::::::Sure, I can do that. I’ll probably need a minute to figure out how to use the template though, but I should have the time later today. Thanks for your input on this. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 17:56, 28 February 2021 (UTC)<br />
<br />
== Removal of website link ==<br />
<br />
Refers to this: https://wiki.archlinux.org/index.php?title=PipeWire&diff=next&oldid=653701<br />
<br />
I don't understand why that has to be removed. The official website should be always worth a mention, even if it is somehow mentioned in the text already.<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:02, 28 February 2021 (UTC)<br />
<br />
:The "See also" section is for additional links, it is not intended as a collection of all links used on a page. Adding links which are clearly mentioned in the appropriate place only clutters the list. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:24, 28 February 2021 (UTC)<br />
<br />
:: There are just three links and only one of them is really useful, the others could maybe even be removed as they link to old blog posts.<br />
:: I can only repeat myself, that things don't always have to be made more complicated than necessary.<br />
:: The official website is a central point which links to many more useful ressources, so it's one link for much information.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:34, 28 February 2021 (UTC)<br />
<br />
== Removal of bootia32.efi generation procedure from X205TA install page. ==<br />
<br />
Those [https://wiki.archlinux.org/index.php?title=ASUS_x205ta&diff=596239&oldid=562734 instructions] were really straightforward and useful, imho in comparison present ones require too much material to be confident with. I think it's (paradoxically) way easier to generate the file than to configure a `grub.cfg` from zero to boot a live cd. Can we undo the edit? Otherwise we could put them in a new page or section in the GRUB page and link to them maybe. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 05:07, 4 March 2021 (UTC)<br />
<br />
:If there is something wrong with the information on the [https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#Booting_64-bit_kernel_on_32-bit_UEFI general page], it should be improved instead of describing the same procedure in a different way on a completely unrelated page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:16, 6 March 2021 (UTC)<br />
<br />
:: I didn't know we had that info in the UEFI article. I think it could be appropriate to insert the [https://en.wikipedia.org/wiki/Template:See_also#Examples See also] archwiki equivalent (which I couldn't find) for UEFI page on top of the aforementioned section, what do you think? [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 13:28, 7 March 2021 (UTC)<br />
<br />
:::Well, the removed section was previously flagged with "Duplicates [[Unified Extensible Firmware Interface#Booting 64-bit kernel on 32-bit UEFI]]"...<br />
:::Also the laptops pages are usually related to most of the general pages on this wiki, adding all of them would be pretty useless. Users should not expect to find everything on a single laptop page, they should always check if there is a general page for their topic with more details.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 7 March 2021 (UTC)<br />
<br />
== Re: Show how to use systemd/Timers with wg-quick@.service ==<br />
<br />
I don't think using service is the appropriate when you want to start Wireguard at boot. For most people connecting to a VPN is not exactly part system startup.<br />
A timer should more appropriate.<br />
[[User:ENV25|ENV25]] ([[User talk:ENV25|talk]]) 10:03, 11 April 2021 (UTC)<br />
<br />
:I don't see how OnBootSec=1min is more appropriate than an automatically starting service. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:19, 11 April 2021 (UTC)<br />
<br />
== USB flash installation medium (BIOS bootable) ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=USB_flash_installation_medium&diff=next&oldid=673926 revert]: "making the partition bootable is discussed below"<br />
Do you mean installing syslinux and `dd` the [gpt]mbr with "discussed below"? This was not enought for my setup (Sandisk Ultra 64GB, Dell XPS 9370) to make the partition BIOS bootable. It did work right after I checked "Legacy BIOS Bootable" checkbox using gnome-disks.<br />
<br />
{{Unsigned|13:42, 30 May 2021 (UTC)|Auipga}}<br />
<br />
:Yes, that's what I meant. If it does not work, it should be fixed rather than providing a duplicate instruction without a reason. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:16, 30 May 2021 (UTC)<br />
<br />
== Systemd-networkd systemd-networkd-wait-online.service discussion modifications ==<br />
<br />
I'm not sure why you're reverting my edits.<br />
<br />
You said: "''empty ExecStart is explained in Systemd#Examples''"<br />
<br />
Exactly: Systemd#Examples clearly states "''As another example, in order to replace the ExecStart directive for a unit that is '''not of type oneshot'''''"<br />
<br />
'''systemd-networkd-wait-online''' is a oneshot service. By having the superfluous empty ExecStart you're just confusing people.<br />
<br />
Regarding the file naming, yes the name is irrelevant, but it's generally helpful to non-expert users to stick to canonical naming conventions.<br />
<br />
Please make sure you're on solid ground before reverting edits; you're just discouraging people from engaging with the Wiki. Thanks. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 16:51, 9 June 2021 (UTC)<br />
<br />
:{{man|5|systemd.service}} says: "Unless Type= is oneshot, exactly one command must be given. When Type=oneshot is used, zero or more commands may be specified."<br />
:So when a service is not oneshot, users ''must'' clear ExecStart before adding a modified command in the drop-in file. If a service is oneshot, they ''may or may not'' clear ExecStart, since the service may have multiple ExecStart commands.<br />
:In case of systemd-networkd-wait-online, I don't see why you would want to run multiple instances with different options: one to wait for ''all'' links (which is the default command) and another one to wait for ''any'' link (which is the command in the drop-in example). So clearing ExecStart really makes sense for systemd-networkd-wait-online.<br />
:— [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:44, 9 June 2021 (UTC)<br />
<br />
== Pacman: Install missing dependencies ==<br />
<br />
Hi. [https://wiki.archlinux.org/index.php?title=Pacman&type=revision&diff=690774&oldid=690762 "Pacman" Revision as of 21:50, 4 August 2021 (undo)] - maybe at least put that into [[System_maintenance#Avoid_certain_pacman_commands]]?<br />
<br />
[[User:Galeksandrp|Galeksandrp]] ([[User talk:Galeksandrp|talk]])<br />
<br />
:[[System_maintenance#Avoid_certain_pacman_commands]] already mentions {{ic|-Rdd}}. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:12, 14 August 2021 (UTC)<br />
<br />
== DPMS: "\033[9;0]" ==<br />
<br />
Hi. It seems that you removed {{ic|echo -ne "\033[9;0]"}} from [[Display Power Management Signaling|DPMS]]<br />
<br />
https://wiki.archlinux.org/index.php?title=Display_Power_Management_Signaling&diff=629705&oldid=625073<br />
<br />
[https://www.denx.de/wiki/view/DULG/SwitchOffScreenSaverAndBlinkingCursor A DULG page] and [https://unix.stackexchange.com/a/23636 a U&L post] brought me here.<br />
<br />
May I ask (1) if this method is still working; and (2) where is this escape sequence documented? [not found in {{man|4|console_codes}}]<br />
<br />
Thanks.<br />
<br />
{{Unsigned|05:23, 15 August 2021 (UTC)|PXf}}<br />
<br />
:[[Display Power Management Signaling#DPMS interaction in a Linux console with setterm]] says that setterm works by writing escape codes to the terminal device. The first subsection shows how to reverse-engineer the escape codes. Note that the escape codes are an implementation detail that users should not be concerned with, their documentation is certainly not our job. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:40, 15 August 2021 (UTC)<br />
<br />
== Linux console/Keyboard configuration ==<br />
<br />
Hi, you recently reverted my edit https://wiki.archlinux.org/index.php?title=Linux_console/Keyboard_configuration&oldid=693887. The reason I made that edit, was that I used to put my custom keymap in {{ic|/usr/local/share/kbd/keymaps/personal}} per the previous version of the wiki page. But this doesn't work with ''sd-vconsole'', as it's include files don't get loaded. Your suggested workaround by adding all required files using [[mkinitcpio#BINARIES and FILES|mkinitcpio BINARIES and FILES]] is rather tedious, as all the include files need to be in there, added by hand. This is done automatically by ''sd-vconsole'' if the file was put in {{ic|/usr/share/kbd/keymaps/}}. The reason I made this edit is due to https://bugs.archlinux.org/task/71788. See Giancarlo Razzolini's comment. [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 09:43, 2 September 2021 (UTC)<br />
<br />
:It's just one custom file under {{ic|/usr/local}} and one entry in {{ic|FILES}}. What is so tedious about it? — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:37, 2 September 2021 (UTC)<br />
<br />
:: It's not just one file. All the dependencies need to be included too under {{ic|/usr/share/kbd/keymaps/}}. There are quite a few in my case, when I just include ''us.map'' to modify it slightly. See the ''sd-vconsole'' hook script. That script has a part where it finds all the dependencies of a keymap.<br />
<br />
:: * ''/usr/share/kbd/keymaps/i386/include/compose.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/euro1.map''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/linux-keys-bare.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/linux-with-alt-and-altgr.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/include/qwerty-layout.inc''<br />
:: * ''/usr/share/kbd/keymaps/i386/qwerty/personal.map''<br />
:: * ''/usr/share/kbd/keymaps/i386/qwerty/us.map''<br />
:: * ''/usr/share/kbd/keymaps/include/compose.latin1''<br />
<br />
:: [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 12:01, 2 September 2021 (UTC)<br />
<br />
::: I moved this to the talk page so I remember it and others can discuss too. [[User:Simonzack|Simonzack]] ([[User talk:Simonzack|talk]]) 09:18, 4 September 2021 (UTC)<br />
<br />
::: Oh, I see. In that case I suggest we add a tip like this:<br />
::: {{Tip|If you use the {{ic|sd-vconsole}} [[mkinitcpio#Common hooks|mkinitcpio hook]] instead of {{ic|keymap}}, keymaps located under {{ic|/usr/local}} as well as their dependencies from {{ic|/usr/share/kbd/keymaps}} need to be manually specified in the {{ic|FILES}} array in {{ic|mkinitcpio.conf}}. On the other hand, custom files located in {{ic|/usr/share/kbd/keymaps}} will be added automatically when configured in {{ic|/etc/vconsole.conf}}.}}<br />
::: Because this is relevant only for people using the {{ic|sd-vconsole}} hook and otherwise it does not make sense to pollute {{ic|/usr/share/kbd/keymaps}} with custom files.<br />
::: — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:55, 5 September 2021 (UTC)<br />
<br />
== cow_* ==<br />
<br />
Hi Lahwaacz. About the [https://wiki.archlinux.org/index.php?title=Archiso&diff=next&oldid=692981 how/why issue] (there will be no more &lt;!-- --&gt;). What if, for once, that I want to install some large packages after booting archiso, and would not bother modifying packages.x86_64 and building again?</div>PXfhttps://wiki.archlinux.org/index.php?title=Kernel_mode_setting&diff=698737Kernel mode setting2021-10-10T15:29:38Z<p>PXf: /* Early KMS start */ recommend against early KMS for GM45</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:Kernel]]<br />
[[de:KMS]]<br />
[[es:Kernel mode setting]]<br />
[[fr:Kernel mode setting]]<br />
[[ja:Kernel Mode Setting]]<br />
[[ru:Kernel mode setting]]<br />
[[zh-hans:Kernel mode setting]]<br />
{{Related articles start}}<br />
{{Related|ATI}}<br />
{{Related|Intel graphics}}<br />
{{Related|Nouveau}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|KMS and rootless X (1.16), see [[Talk:Kernel mode setting]] and [[Xorg#Rootless Xorg (v1.16)]].}}<br />
<br />
Kernel [[Wikipedia:Mode-setting|Mode Setting]] (KMS) is a method for setting display resolution and depth in the kernel space rather than user space.<br />
<br />
The Linux kernel's implementation of KMS enables native resolution in the framebuffer and allows for instant console (tty) switching. KMS also enables newer technologies (such as DRI2) which will help reduce artifacts and increase 3D performance, even kernel space power-saving.<br />
<br />
{{Note|The proprietary [[NVIDIA]] driver (since 364.12) also implements kernel mode-setting, but it does not use the built-in kernel implementation and it lacks an fbdev driver for the high-resolution console.}}<br />
<br />
== Background ==<br />
<br />
Previously, setting up the video card was the job of the X server. Because of this, it was not easily possible to have fancy graphics in [[virtual console]]s. Also, each time a switch from X to a virtual console was made ({{ic|Ctrl+Alt+F2}}), the server had to give control over the video card to the kernel, which was slow and caused flickering. The same "painful" process happened when the control was given back to the X server ({{ic|Alt+F7}} when X runs in VT7).<br />
<br />
With Kernel Mode Setting (KMS), the kernel is now able to set the mode of the video card. This makes fancy graphics during bootup, virtual console and X fast switching possible, among other things.<br />
<br />
== Installation ==<br />
<br />
At first, note that for ''any'' method you use, you should ''always'' disable:<br />
<br />
* Any {{ic|<nowiki>vga=</nowiki>}} options in your bootloader as these will conflict with the native resolution enabled by KMS.<br />
* Any {{ic|<nowiki>video=</nowiki>}} lines that enable a framebuffer that conflicts with the driver.<br />
* Any other framebuffer drivers (such as [[uvesafb]]).<br />
<br />
=== Late KMS start ===<br />
<br />
[[Intel]], [[Nouveau]], [[ATI]] and [[AMDGPU]] drivers already enable KMS automatically for all chipsets, so you need not install it manually.<br />
<br />
The proprietary [[NVIDIA]] driver supports KMS (since 364.12), which has to be [[NVIDIA#DRM kernel mode setting|manually enabled]].<br />
<br />
=== Early KMS start ===<br />
{{Tip|If you encounter problems with the resolution, you can check whether [[#Forcing modes and EDID|enforcing the mode]] helps.}}<br />
{{Warning|With early KMS, Intel [https://web.archive.org/web/20210807102641/https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/4-chipset-family-datasheet.pdf GM45 series] tend to be laggy and might freeze when playing videos. If so, consider {{Pkg|xf86-video-intel}} instead.}}<br />
<br />
KMS is typically initialized after the [[Arch boot process#initramfs|initramfs stage]]. However it is possible to already enable KMS during the initramfs stage. Add the required module for the [[Xorg#Driver_installation|video driver]] to the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}}:<br />
* {{ic|amdgpu}} for [[AMDGPU]], or {{ic|radeon}} when using the legacy [[ATI]] driver.<br />
* {{ic|i915}} for [[Intel graphics]].<br />
* {{ic|nouveau}} for the open-source [[Nouveau]] driver.<br />
* {{ic|mgag200}} for Matrox graphics.<br />
* Depending on [[QEMU]] graphics in use: {{ic|virtio-gpu}} for VirtIO, {{ic|qxl}} for QXL, or {{ic|cirrus}} for Cirrus.<br />
* {{ic|nvidia nvidia_modeset nvidia_uvm nvidia_drm}} for {{Pkg|nvidia}} driver. See [[NVIDIA#DRM kernel mode setting]] for details.<br />
<br />
For example to enable early KMS for the Intel graphics driver:<br />
{{hc|/etc/mkinitcpio.conf|2=MODULES=(... i915 ...)}}<br />
<br />
{{Note|1=Intel users may need to add {{ic|intel_agp}} before {{ic|i915}} to suppress the ACPI errors (check the output of {{ic|lsmod}} on your running system to see if {{ic|intel_agp}} is loaded). This may be required for resuming from hibernation to work with a changed display configuration. If you use PRIME GPU with Intel IGP being your primary GPU and AMD as the discrete one, adding {{ic|intel_agp}} may lead to troubles when resuming from hibernation (monitor gets no signal). See [https://bbs.archlinux.org/viewtopic.php?id=262043] for details.}}<br />
<br />
If you are using a custom EDID file (not applicable for the built-in resolutions), you should embed it into [[initramfs]] as well:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/usr/lib/firmware/edid/your_edid.bin)<br />
}}<br />
<br />
Then [[regenerate the initramfs]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== My fonts are too tiny ===<br />
<br />
See [[Linux console#Fonts]] for how to change your console font to a large font. The Terminus font ({{Pkg|terminus-font}}) is available in many sizes, such as {{ic|ter-132n}} which is larger.<br />
<br />
Alternatively, [[#Disabling modesetting|disabling modesetting]] might switch to lower resolution and make fonts appear larger.<br />
<br />
=== Problem upon bootloading and dmesg ===<br />
<br />
Polling for connected display devices on older systems can be quite expensive. Poll will happen periodically and can in worst cases take several hundred milliseconds, depending on the hardware. This will cause visible stalls, for example in video playback. These stalls might happen even when your video is on HDP output but you have other non HDP outputs in your hw configuration. If you experience stalls in display output occurring every 10 seconds, disabling polling might help.<br />
<br />
If you see an error code of {{ic|0x00000010 (2)}} while booting up, (you will get about 10 lines of text, the last part denoting that error code), use:<br />
<br />
{{hc|/etc/modprobe.d/modprobe.conf|2=<br />
options drm_kms_helper poll=0<br />
}}<br />
<br />
== Forcing modes and EDID ==<br />
<br />
If your native resolution is not automatically configured or no display at all is detected, then your monitor might send none or just a skewed [[Wikipedia:EDID|EDID]] file. The kernel will try to catch this case and will set one of the most typical resolutions.<br />
<br />
In case you have the EDID file for your monitor you merely need to explicitly enforce it (see below). However most often one does not have direct access to a sane file and it is necessary to either extract an existing one and fix it or to generate a new one.<br />
<br />
Generating new EDID binaries for various resolutions and configurations is possible during kernel compilation by following the [https://www.kernel.org/doc/html/latest/admin-guide/edid.html upstream documentation] (also see [https://www.osadl.org/Single-View.111+M5315d29dd12.0.html here] for a short guide). Other solutions are outlined in details in this [https://kodi.wiki/view/Archive:Creating_and_using_edid.bin_via_xorg.conf article].<br />
Extracting an existing one is in most cases easier, e.g. if your monitor works fine under Windows you might have luck extracting the EDID from the corresponding driver, or if a similar monitor works which has the same settings you may use {{ic|get-edid}} from the {{Pkg|read-edid}} package. You can also try looking in {{ic|/sys/class/drm/*/edid}}.<br />
<br />
After having prepared your EDID place it in a folder, e.g. called {{ic|edid}} under {{ic|/usr/lib/firmware}} and copy your binary into it.<br />
<br />
To load it at boot, specify the following in the [[kernel command line]]:<br />
<br />
drm.edid_firmware=edid/your_edid.bin<br />
<br />
For kernels older than 4.13, use this line instead:<br />
<br />
drm_kms_helper.edid_firmware=edid/your_edid.bin<br />
<br />
In order to apply it only to a specific connector use:<br />
<br />
drm.edid_firmware=VGA-1:edid/your_edid.bin<br />
<br />
For the built-in resolutions, refer to the table below. The '''Name''' column specifies the name which one is supposed to use in order to enforce its usage.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Resolution !! Name<br />
|-<br />
| 800x600 || edid/800x600.bin <br />
|-<br />
| 1024x768 || edid/1024x768.bin <br />
|-<br />
| 1280x1024 || edid/1280x1024.bin <br />
|-<br />
| 1600x1200 (kernel 3.10 or higher) || edid/1600x1200.bin<br />
|-<br />
| 1680x1050 || edid/1680x1050.bin <br />
|-<br />
| 1920x1080 || edid/1920x1080.bin <br />
|}<br />
<br />
If you are doing [[#Early KMS start|early KMS]], you must include the custom EDID file in the initramfs, otherwise you will run into problems.<br />
<br />
The value of the {{ic|drm.edid_firmware}} parameter may also be altered after boot by writing to {{ic|/sys/module/drm/parameters/edid_firmware}}:<br />
<br />
# echo edid/your_edid.bin > /sys/module/drm/parameters/edid_firmware<br />
<br />
This will only take affect for newly plugged in displays, already plugged-in screens will continue to use their existing EDID settings. For external displays replugging them is sufficient to see the effect however.<br />
<br />
Since kernel 3.15, to load an EDID after boot, you can use debugfs instead of a kernel command line parameter if the kernel is not in [[Security#Kernel_lockdown_mode|lockdown mode]]. This is very useful if you swap the monitors on a connector or just for testing. Once you have an EDID file as above, run:<br />
<br />
# cat correct-edid.bin > /sys/kernel/debug/dri/0/HDMI-A-2/edid_override<br />
<br />
And to disable:<br />
<br />
# echo -n reset > /sys/kernel/debug/dri/0/HDMI-A-2/edid_override<br />
<br />
=== Forcing modes ===<br />
<br />
{{Warning|The method described below is somehow incomplete because e.g. [[Xorg]] does not take into account the resolution specified, so users are encouraged to use the method described above. However, specifying resolution with {{ic|1=video=}} command line may be useful in some scenarios.}}<br />
<br />
From [https://nouveau.freedesktop.org/wiki/KernelModeSetting the nouveau wiki]:<br />
:A mode can be forced on the kernel command line. Unfortunately, the command line option video is poorly documented in the DRM case. Bits and pieces on how to use it can be found in<br />
:* https://cgit.freedesktop.org/nouveau/linux-2.6/tree/Documentation/fb/modedb.txt<br />
:* https://cgit.freedesktop.org/nouveau/linux-2.6/tree/drivers/gpu/drm/drm_fb_helper.c <br />
<br />
The format is: <br />
<br />
video=<conn>:<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]<br />
<br />
* {{ic|<conn>}}: Connector, e.g. DVI-I-1, see {{ic|/sys/class/drm/}} for available connectors<br />
* {{ic|<xres> x <yres>}}: resolution<br />
* {{ic|M}}: compute a CVT mode?<br />
* {{ic|R}}: reduced blanking?<br />
* {{ic|-<bpp>}}: color depth<br />
* {{ic|@<refresh>}}: refresh rate<br />
* {{ic|i}}: interlaced (non-CVT mode)<br />
* {{ic|m}}: margins?<br />
* {{ic|e}}: output forced to on<br />
* {{ic|d}}: output forced to off<br />
* {{ic|D}}: digital output forced to on (e.g. DVI-I connector) <br />
<br />
You can override the modes of several outputs using {{ic|<nowiki>video=</nowiki>}} several times, for instance, to force {{ic|DVI}} to ''1024x768'' at ''85 Hz'' and {{ic|TV-out}} off: <br />
<br />
video=DVI-I-1:1024x768@85 video=TV-1:d<br />
<br />
To get the name and current status of connectors, you can use the following shell oneliner:<br />
<br />
{{hc|<nowiki>$ for p in /sys/class/drm/*/status; do con=${p%/status}; echo -n "${con#*/card?-}: "; cat $p; done</nowiki>|<br />
DVI-I-1: connected<br />
HDMI-A-1: disconnected<br />
VGA-1: disconnected<br />
}}<br />
<br />
== Disabling modesetting ==<br />
<br />
You may want to disable KMS for various reasons. To disable KMS add {{ic|nomodeset}} as a kernel parameter. See [[Kernel parameters]] for more info.<br />
<br />
Along with {{ic|nomodeset}} kernel parameter, for Intel graphics card you need to add {{ic|1=i915.modeset=0}} and for Nvidia graphics card you need to add {{ic|1=nouveau.modeset=0}}. For Nvidia Optimus dual-graphics system, you need to add all the three kernel parameters (i.e. {{ic|1="nomodeset i915.modeset=0 nouveau.modeset=0"}}).<br />
<br />
{{Note|Some [[Xorg]] drivers will not work with KMS disabled. See the wiki page on your specific driver for details.}}</div>PXfhttps://wiki.archlinux.org/index.php?title=Archiso&diff=698661Archiso2021-10-09T12:09:02Z<p>PXf: /* Prepare an ISO for an installation via SSH */ don't remove the section - keep manual method along with cloud-init method - clean up the section</p>
<hr />
<div>[[Category:Live Arch systems]]<br />
[[Category:Installation process]]<br />
[[Category:Arch projects]]<br />
[[ar:Archiso]]<br />
[[el:Archiso]]<br />
[[es:Archiso]]<br />
[[fr:Archiso]]<br />
[[it:Archiso]]<br />
[[ja:Archiso]]<br />
[[nl:Archiso]]<br />
[[pt:Archiso]]<br />
[[ru:Archiso]]<br />
[[sk:Archiso]]<br />
[[zh-hans:Archiso]]<br />
{{Related articles start}}<br />
{{Related|Archiso as pxe server}}<br />
{{Related|Archboot}}<br />
{{Related|Offline installation}}<br />
{{Related articles end}} <br />
[https://gitlab.archlinux.org/archlinux/archiso Archiso] is a highly-customizable tool for building Arch Linux live CD/USB ISO images. The [https://archlinux.org/download/ official images] are built with Archiso. It can be used as the basis for rescue systems, linux installers or other systems. This wiki article explains how to install Archiso, and how to configure it to control aspects of the resulting ISO image such as included packages and files. Technical requirements and build steps can be found in the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs official project documentation]. Archiso is implemented with a number of bash scripts. The core component of Archiso is the ''mkarchiso'' command. Its options are documented in ''mkarchiso -h'' and not covered here.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package.<br />
<br />
== Prepare a custom profile ==<br />
<br />
Archiso comes with two profiles, '''releng''' and '''baseline'''.<br />
<br />
* '''releng''' is used to create the official monthly installation ISO. It can be used as a starting point for creating a customized ISO image.<br />
* '''baseline''' is a minimalistic configuration, that includes only the bare minimum packages required to boot the live environment from the medium.<br />
<br />
To build an unmodified version of the profiles, skip to [[#Build the ISO]]. Otherwise, if you wish to adapt or customize one of archiso's shipped profiles, copy it from {{ic|/usr/share/archiso/configs/''profile-name''/}} to a writable directory with a name of your choice. For example:<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile''/ ''archlive''<br />
<br />
Proceed to the following sections to customize and build the custom profile.<br />
<br />
=== Profile structure ===<br />
<br />
An archiso profile contains configuration that defines the resulting ISO image. The profile structure is documented in {{ic|/usr/share/doc/archiso/README.profile.rst}}[https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst].<br />
<br />
=== Selecting packages ===<br />
<br />
Edit {{ic|packages.x86_64}} to select which packages are to be installed on the live system image, listing packages line by line.<br />
<br />
==== Custom local repository ====<br />
<br />
To add packages not located in standard Arch repositories (e.g. custom packages or packages from [[AUR]]/[[ABS]]), set up a [[custom local repository]] and add your custom packages to it. Then add your repository to {{ic|pacman.conf}} as follows: <br />
<br />
{{hc|''archlive''/pacman.conf|2=<br />
...<br />
[''customrepo'']<br />
SigLevel = Optional TrustAll<br />
Server = file://''/path/to/customrepo''<br />
...<br />
}}<br />
<br />
{{Note|The ordering within {{ic|pacman.conf}} matters. To give top priority to your custom repository, place it above the other repository entries.}}<br />
<br />
==== Packages from multilib ====<br />
<br />
To install packages from the [[multilib]] repository, simply uncomment that repository in {{ic|pacman.conf}}.<br />
<br />
=== Adding files to image ===<br />
<br />
The airootfs directory is used as the starting point for the [[Wikipedia:Root directory|root directory]] ({{ic|/}}) of the live system on the image. All its contents will be copied over to the working directory before packages are installed.<br />
<br />
Place any custom files and/or directories in the desired location under {{ic|airootfs/}}. For example, if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:<br />
<br />
$ cp -r /etc/iptables ''archlive''/airootfs/etc<br />
<br />
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. Missing parts of the directory structure can be simply created with {{man|1|mkdir}}.<br />
<br />
{{Tip|To add a file to the install user's home directory, place it in {{ic|''archlive''/airootfs/root/}}. To add a file to all other users home directories, place it in {{ic|''archlive''/airootfs/etc/skel/}}.}}<br />
<br />
{{Note|Custom files that conflict with those provided by packages will be overwritten unless a package specifies them as [[pacman/Pacnew and Pacsave#Package backup files|backup files]].}}<br />
<br />
By default, [[permissions]] will be {{ic|644}} for files and {{ic|755}} for directories. All of them will be owned by the root user. To set different permissions or ownership for specific files and/or folders, use the {{ic|file_permissions}} associative array in {{ic|profiledef.sh}}. See [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst README.profile.rst] for details.<br />
<br />
=== Kernel ===<br />
<br />
Although both archiso's included profiles only have {{Pkg|linux}}, ISOs can be made to include other or even multiple [[kernels]].<br />
<br />
First, edit {{ic|packages.x86_64}} to include kernel package names that you want. When ''mkarchiso'' runs, it will include all {{ic|''work_dir''/airootfs/boot/vmlinuz-*}} and {{ic|''work_dir''/boot/initramfs-*.img}} files in the ISO (and additionally in the FAT image used for UEFI booting).<br />
<br />
[[mkinitcpio]] presets by default will build fallback initramfs images. For an ISO, the main initramfs image would not typically include the {{ic|autodetect}} hook, thus making an additional fallback image unnecessary. To prevent the creation of an fallback initramfs image, so that it does not take up space or slow down the build process, place a custom preset in {{ic|''archlive''/airootfs/etc/mkinitcpio.d/''pkgbase''.preset}}. For example, for {{Pkg|linux-lts}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/mkinitcpio.d/linux-lts.preset|2=<br />
PRESETS=('archiso')<br />
<br />
ALL_kver='/boot/vmlinuz-linux-lts'<br />
ALL_config='/etc/mkinitcpio.conf'<br />
<br />
archiso_image="/boot/initramfs-linux-lts.img"<br />
}}<br />
<br />
Finally create [[#Boot loader|boot loader configuration]] to allow booting the kernel(s).<br />
<br />
=== Boot loader ===<br />
<br />
Archiso supports [[syslinux]] for BIOS booting and [[systemd-boot]] for UEFI booting. Refer to the articles of the boot loaders for information on their configuration syntax.<br />
<br />
{{Tip|1=<nowiki></nowiki><br />
* The '''releng''' profile by default builds into an ISO that supports both BIOS and UEFI booting when burned to an optical disc using El Torito, or when written to a hard disk (or USB flash drive, or similar) using [https://wiki.syslinux.org/wiki/index.php?title=Isohybrid Isohybrid].<br />
* Due to the modular nature of isolinux, you are able to use lots of addons since all ''.c32'' files are copied and available to you. Take a look at the [https://wiki.syslinux.org/wiki/index.php/SYSLINUX official syslinux site] and the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/configs/releng/syslinux archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [https://wiki.syslinux.org/wiki/index.php/Comboot/menu.c32].<br />
}}<br />
<br />
mkarchiso expects that [[systemd-boot]] configuration is in the {{ic|efiboot}} directory, and [[syslinux]] configuration in {{ic|syslinux}} and {{ic|isolinux}} directories.<br />
<br />
==== UEFI Secure Boot ====<br />
<br />
If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed boot loader. You can follow the instructions on [[Secure Boot#Booting an installation medium]].<br />
<br />
=== systemd units ===<br />
<br />
To [[enable]] systemd services/sockets/timers for the live environment, you need to manually create the symbolic links just as {{ic|systemctl enable}} does it.<br />
<br />
For example, to enable {{ic|gpm.service}}, which contains {{ic|1=WantedBy=multi-user.target}}, run:<br />
<br />
$ mkdir -p ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants<br />
$ ln -s /usr/lib/systemd/system/gpm.service ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants/<br />
<br />
The required symlinks can be found out by reading the systemd unit, or if you have the service installed, by [[enabling]] it and observing the systemctl output.<br />
<br />
==== Login manager ====<br />
<br />
Starting X at boot is done by enabling your login manager's [[systemd]] service. If you do not know which ''.service'' enable, you can easily find out in case you are using the same program on the system you build your ISO on. Just use:<br />
<br />
$ ls -l /etc/systemd/system/display-manager.service<br />
<br />
Now create the same symlink in {{ic|''archlive''/airootfs/etc/systemd/system/}}. For LXDM:<br />
<br />
$ ln -s /usr/lib/systemd/system/lxdm.service ''archlive''/airootfs/etc/systemd/system/display-manager.service<br />
<br />
This will enable LXDM at system start on your live system.<br />
<br />
==== Changing automatic login ====<br />
<br />
The configuration for getty's automatic login is located under {{ic|airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf}}.<br />
<br />
You can modify this file to change the auto login user:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty --autologin '''''username''''' --noclear %I 38400 linux<br />
<br />
Or remove it altogether to disable auto login.<br />
<br />
=== Users and passwords ===<br />
<br />
To create a [[user]] which will be available in the live environment, you must manually edit {{ic|''archlive''/airootfs/etc/passwd}}, {{ic|''archlive''/airootfs/etc/shadow}}, {{ic|''archlive''/airootfs/etc/group}} and {{ic|''archlive''/airootfs/etc/gshadow}}.<br />
<br />
{{Note|If these files exist, they must contain the root user and group.}}<br />
<br />
For example, to add a user {{ic|archie}}. Add them to {{ic|''archlive''/airootfs/etc/passwd}} following the {{man|5|passwd}} syntax:<br />
<br />
{{hc|''archlive''/airootfs/etc/passwd|<br />
root:x:0:0:root:/root:/usr/bin/zsh<br />
archie:x:1000:1000::/home/archie:/usr/bin/zsh<br />
}}<br />
<br />
Generate a password hash with {{ic|openssl passwd -6}} and add it to {{ic|''archlive''/airootfs/etc/shadow}} following the syntax of {{man|5|shadow}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/shadow|2=<br />
root::14871::::::<br />
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::<br />
}}<br />
<br />
Add the user's group and the groups which they will part of to {{ic|''archlive''/airootfs/etc/group}} according to {{man|5|group}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/group|2=<br />
root:x:0:root<br />
adm:x:4:archie<br />
wheel:x:10:archie<br />
uucp:x:14:archie<br />
archie:x:1000:<br />
}}<br />
<br />
Create the appropriate {{ic|''archlive''/airootfs/etc/gshadow}} according to {{man|5|gshadow}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/gshadow|2=<br />
root:!*::root<br />
archie:!*::<br />
}}<br />
<br />
Make sure {{ic|/etc/shadow}} and {{ic|/etc/gshadow}} have the correct permissions:<br />
<br />
{{hc|''archlive''/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/etc/shadow"]="0:0:0400"<br />
["/etc/gshadow"]="0:0:0400"<br />
)<br />
}}<br />
<br />
After package installation, ''mkarchiso'' will create all specified home directories for users listed in {{ic|''archlive''/airootfs/etc/passwd}} and copy {{ic|''work_directory''/x86_64/airootfs/etc/skel/*}} to them. The copied files will have proper user and group ownership.<br />
<br />
== Build the ISO ==<br />
<br />
Build an ISO which you can then burn to CD or USB by running:<br />
<br />
# mkarchiso -v -w ''/path/to/work_dir'' -o ''/path/to/out_dir'' ''/path/to/profile/''<br />
<br />
* {{ic|-w}} specifies the working directory. If the option is not specified, it will default to {{ic|work}} in the current directory.<br />
* {{ic|-o}} specifies the directory where the built ISO image will be placed. If the option is not specified, it will default to {{ic|out}} in the current directory.<br />
* It should be noted the profile file {{ic|profiledef.sh}} cannot be specified when running mkarchiso, only the path to the file<br />
<br />
Replace {{ic|''/path/to/profile/''}} with the path to your custom profile, or with {{ic|/usr/share/archiso/configs/releng/}} if you are building an unmodified profile.<br />
<br />
{{Tip|If memory allows, it is preferred to place the working directory on [[tmpfs]]. E.g.:<br />
<br />
# mkarchiso -v -w /tmp/archiso-tmp ''/path/to/profile/''<br />
<br />
}}<br />
<br />
When run, the script will download and install the packages you specified to {{ic|''work_directory''/x86_64/airootfs}}, create the kernel and init images, apply your customizations and finally build the ISO into the output directory.<br />
<br />
=== Removal of work directory ===<br />
<br />
{{Warning|If ''mkarchiso'' is interrupted, run {{man|8|findmnt}} to make sure there are no mount binds before deleting it - otherwise, '''you may lose data''' (e.g. an external device mounted at {{ic|/run/media/''user''/''label''}} gets bound within {{ic|work/x86_64/airootfs/run/media/''user''/''label''}} during the build process).}}<br />
<br />
The temporary files are copied into work directory. After successfully building the ISO , the work directory and its contents can be deleted. E.g.:<br />
<br />
# rm -rf ''/path/to/work_dir''<br />
<br />
== Using the ISO ==<br />
<br />
See [[Installation guide#Prepare an installation medium]] for various options.<br />
<br />
== Test the ISO in QEMU ==<br />
<br />
[[Install]] the optional dependencies {{pkg|qemu}} and {{pkg|edk2-ovmf}}.<br />
<br />
Use the convenience script {{ic|run_archiso}} to run a built image using [[QEMU]].<br />
<br />
$ run_archiso -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
The virtual machine can also be run using UEFI emulation:<br />
<br />
$ run_archiso -u -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
== Tips and tricks ==<br />
<br />
=== Prepare an ISO for an installation via SSH ===<br />
<br />
{{Note|Since {{ic|archlinux-2021.02.01-x86_64.iso}}, [https://gitlab.archlinux.org/archlinux/archiso/-/tree/bd2b861aa39167e4fc658a354071b95fbd050c0f/configs/releng/airootfs/etc/systemd/system/cloud-init.target.wants cloud-init support] is provided, and {{ic|sshd.service}} is [https://gitlab.archlinux.org/archlinux/archiso/-/blob/bd2b861aa39167e4fc658a354071b95fbd050c0f/configs/releng/airootfs/etc/systemd/system/multi-user.target.wants/sshd.service enabled by default].}}<br />
<br />
To [[install Arch Linux via SSH]] without any interaction with the system, an SSH public key must be placed in {{ic|authorized_keys}}.<br />
<br />
Adding the SSH key can either be done manually (explained here), or [[Install Arch Linux via SSH#Installation on a headless server|by cloud-init]].<br />
<br />
To add the key manually, first [[#Prepare a custom profile|copy Archiso's releng profile]] to a writable directory. The following example uses {{ic|archlive}}.<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile/'' archlive<br />
<br />
Create a {{ic|.ssh}} directory in the home directory of the user which will be used to log in. The following example will be using the root user.<br />
<br />
$ mkdir archlive/airootfs/root/.ssh<br />
<br />
Add the SSH public key(s), which will be used to log in, to {{ic|authorized_keys}}:<br />
<br />
$ cat ~/.ssh/''key1''.pub >> archlive/airootfs/root/.ssh/authorized_keys<br />
$ cat ~/.ssh/''key2''.pub >> archlive/airootfs/root/.ssh/authorized_keys<br />
<br />
Set correct [[permissions]] and ownership for the {{ic|.ssh}} directory and the {{ic|authorized_keys}} file:<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/root"]="0:0:0750"<br />
["/root/.ssh"]="0:0:0700"<br />
["/root/.ssh/authorized_keys"]="0:0:0600"<br />
)<br />
}}<br />
<br />
Finally [[#Build the ISO|build the ISO]]. Upon booting the ISO, [[OpenSSH]] will start and it will be possible to log in using the corresponding SSH private key(s).<br />
<br />
=== Automatically connect to a Wi-Fi network using iwd ===<br />
<br />
Create {{ic|/var/lib/iwd/}} inside the profile's {{ic|airootfs}} directory and set the correct permissions:<br />
<br />
$ mkdir -p ''archlive''/airootfs/var/lib/iwd<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/var/lib/iwd"]="0:0:0700"<br />
)<br />
}}<br />
<br />
Follow the instructions in [[iwd#Network configuration]] and {{man|5|iwd.network}} to create a network configuration file for your Wi-Fi network.<br />
<br />
Save the configuration file inside {{ic|''archlive''/airootfs/var/lib/iwd/}}.<br />
<br />
=== Adjusting the size of root partition on the fly ===<br />
<br />
{{Accuracy|Explaining ''how'' but omitting the ''why'' renders the whole section useless.}}<br />
<br />
If you get the following error message when downloading files or installing packages in the booted ISO environment, you may need to shutdown and adjust the size of the root partition while booting the Archiso again.<br />
<br />
error: partition / too full: 63256 blocks needed, 61450 blocks free<br />
error: not enough free disk space<br />
error: failed to commit transaction (not enough free disk space) <br />
Errors occurred: no packages were upgraded.<br />
<br />
To adjust the size of the root partition on the live Archlinux system, hit the TAB key to edit the kernel parameters.<br />
Append {{ic|1=cow_spacesize=2G}} at the end to get 2G size for the root partition.<br />
Press Enter to continue booting into the live system.<br />
You can check the size of the filesystems by running:<br />
$ df -h<br />
<br />
You can also adjust the root partition size on the fly by running this command:<br />
# mount -o remount,size=2G /run/archiso/cowspace<br />
<br />
See more boot parameters [https://gitlab.archlinux.org/mkinitcpio/mkinitcpio-archiso/blob/master/docs/README.bootparams here]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Window manager freezes ===<br />
<br />
If you want to use a [[window manager]] in the Live CD then you must add the necessary and correct [[video drivers]], or the WM may freeze on loading.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.archlinux.org/archlinux/archiso Archiso project page]<br />
* [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs Official documentation]<br />
* [https://lists.archlinux.org/listinfo/arch-releng Arch Linux Release Engineering mailing list]<br />
* [ircs://irc.libera.chat/archlinux-releng #archlinux-releng — Arch Linux Release Engineering IRC channel]<br />
* [https://github.com/pierres/archiso-manager archiso-manager — the tool used for building the official monthly ISOs]</div>PXfhttps://wiki.archlinux.org/index.php?title=Install_Arch_Linux_via_SSH&diff=698660Install Arch Linux via SSH2021-10-09T11:51:14Z<p>PXf: /* Prepare cloud-init configuration files */ one more wikilink</p>
<hr />
<div>[[Category:Installation process]]<br />
[[Category:Secure Shell]]<br />
[[cs:Install Arch Linux via SSH]]<br />
[[es:Install Arch Linux via SSH]]<br />
[[ja:SSH からインストール]]<br />
[[pt:Install Arch Linux via SSH]]<br />
[[ru:Install Arch Linux via SSH]]<br />
This article is intended to show users how to install Arch remotely via an [[SSH]] connection. Consider this approach when the host is located remotely or you wish to use the copy/paste ability of an SSH client to do the Arch install.<br />
<br />
== On the remote (target) machine ==<br />
<br />
{{Note|These steps require physical access to the machine. If the host is physically located elsewhere, this may need to be coordinated with another person.}}<br />
<br />
Boot the target machine into a live Arch environment via the [[Getting and installing Arch|Live CD/USB image]]: this will log the user in as root.<br />
<br />
At this point, setup the network on the target machine as for example suggested in [[Installation guide#Connect to the internet]].<br />
<br />
Secondly, setup a root password which is needed for an SSH connection, since the default Arch password for root is empty:<br />
<br />
# passwd<br />
<br />
Now check that {{ic|PermitRootLogin yes}} is present (and uncommented) in {{ic|/etc/ssh/sshd_config}}. This setting allows root login with password authentication on the SSH server.<br />
<br />
Finally, [[start]] the openssh daemon with {{ic|sshd.service}}, which is included by default on the live CD.<br />
<br />
{{Note|Unless required, after installation it is recommended to remove {{ic|PermitRootLogin yes}} from {{ic|/etc/ssh/sshd_config}}.}}<br />
<br />
{{Tip|If the target machine is behind a NAT router, and you require external access, the SSH port (22 by default) will need to be forwarded to the target machine's LAN IP address.}}<br />
<br />
== On the local machine ==<br />
<br />
On the local machine, connect to the target machine via SSH with the following command:<br />
<br />
$ ssh root@''ip.address.of.target''<br />
<br />
From here one is presented with the live environment's welcome message and is able to administer the target machine as if sitting at the physical keyboard. At this point, if the intent is to simply install Arch from the live media, follow the guide at [[Installation guide]]. If the intent is to edit an existing Linux install that got broken, follow the [[Install from existing Linux]] wiki article.<br />
<br />
{{Tip|Consider using [[GNU Screen]] or [[tmux]] on the target machine (both are available in the live environment), so that if you are disconnected you can reattach to your multiplexer's session.}}<br />
<br />
== Installation on a headless server ==<br />
<br />
{{Note|These steps may require physical access to the headless machine. Somebody has to insert the installation medium and power up the headless server.}}<br />
<br />
This section describes installation of Arch Linux on a headless server without a keyboard, mouse or display. It uses an additional drive with [[cloud-init]] NoCloud configuration to automatically configure [[OpenSSH]] authorized keys and optionally [[iwd]] connection(s).<br />
<br />
=== Prepare cloud-init configuration files ===<br />
<br />
There are two required [[cloud-init]] configuration files: {{ic|meta-data}} and {{ic|user-data}}.<br />
<br />
The {{ic|meta-data}} file can be empty:<br />
<br />
$ printf "" > meta-data<br />
<br />
{{ic|user-data}} will contain the relevant configuration:<br />
<br />
{{hc|user-data|2=<br />
#cloud-config<br />
users:<br />
- name: root<br />
ssh_authorized_keys:<br />
- ssh-ed25519 ''XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''<br />
- ssh-ed25519 ''YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY''<br />
}}<br />
<br />
Replace {{ic|ssh-ed25519 ''XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''}} with your public [[SSH key]]. To add multiple keys, simply repeat the statement as shown above.<br />
<br />
To automatically connect to a Wi-Fi network, use the {{ic|write_files:}} statement to create [[iwd#Network configuration|iwd network configuration files]] in the correct directory. For example:<br />
<br />
{{hc|user-data|2=<br />
#cloud-config<br />
users:<br />
- name: root<br />
ssh_authorized_keys:<br />
- ssh-ed25519 ''XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''<br />
- ssh-ed25519 ''YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY''<br />
<br />
write_files:<br />
- content: {{!}}<br />
[Security]<br />
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295<br />
path: /var/lib/iwd/spaceship.psk<br />
}}<br />
<br />
Once both files are created they need to be placed on a drive with an ISO 9660 or FAT volume labeled {{ic|CIDATA}}.<br />
<br />
=== Using an additional FAT formatted drive ===<br />
<br />
Use a [[FAT]] formatted drive. Copy {{ic|meta-data}} and {{ic|user-data}} to the drive and change the file system's [[LABEL]] to {{ic|CIDATA}}.<br />
<br />
You will need to attach this drive to the headless machine in addition to the one with the official ISO.<br />
<br />
=== Using an additional ISO ===<br />
<br />
Create a {{ic|cloud-init.iso}} file using ''xorriso'' from {{Pkg|libisoburn}}:<br />
<br />
$ xorrisofs -output cloud-init.iso -volid CIDATA -joliet -rational-rock meta-data user-data<br />
<br />
Prepare the cloud-init data medium by [[Optical disc drive#Burning|burning]] {{ic|cloud-init.iso}} to an optical disc or, if deployment options permit, use the ISO as is.<br />
<br />
=== Using a single USB flash drive ===<br />
<br />
If the installation image is written to e.g. a USB flash drive, provided there is enough space on the drive, and additional partition to house cloud-init data can be created.<br />
<br />
First follow [[USB flash installation medium#Using the ISO as is (BIOS and UEFI)]] to prepare the USB flash drive installation medium.<br />
<br />
Use [[fdisk]] to edit drive's MBR partition table '''without touching the ISO 9660 or invalid GPT structures''':<br />
<br />
# fdisk -t mbr --wipe never /dev/''sdX''<br />
<br />
Create a new (third) partition and set its partition type to {{ic|0c}}. When done, write the partition table to disk.<br />
<br />
Format the newly created partition with a [[FAT]] file system and set its [[LABEL]] to {{ic|CIDATA}}:<br />
<br />
# mkfs.fat -n CIDATA /dev/''sdX''3<br />
<br />
[[Mount]] the file system and copy the {{ic|meta-data}} and {{ic|user-data}} to the root of it.<br />
<br />
=== Using a single custom-built ISO ===<br />
<br />
Alternatively, create a custom ISO using [[Archiso]]. This allows using only one drive regardless of type.<br />
<br />
Use the releng profile as basis. Place [[#Prepare cloud-init configuration files|the cloud-init configuration files]] in {{ic|airootfs/var/lib/cloud/seed/nocloud/}} and build the ISO.<br />
<br />
=== Boot from the installation medium ===<br />
<br />
Once finished, deploy the installation medium and the cloud-init data medium (if it is separate) to the headless machine using the appropriate method.<br />
<br />
Power up the headless machine and boot into a live Arch environment from the installation medium. Wait for a minute or so to allow the headless machine time to boot up and connect to the network.<br />
<br />
From your existing machine (with keyboard and display) [[SSH]] into the live Arch environment on the headless server and complete the installation as described in the [[Installation guide]]. <br />
<br />
{{Note|To belabor the obvious, all the Wi-Fi and SSH configuration that was carried out in the boot image needs to be done again in the actual Arch Linux installation to allow WiFi SSH access to the headless machine after installation.}}</div>PXfhttps://wiki.archlinux.org/index.php?title=IOS&diff=693755IOS2021-09-01T11:35:28Z<p>PXf: /* Pairing */ it is "udid", not "uuid" - proof - https://github.com/libimobiledevice/ifuse/blob/cce061d2ce2729387a40ece89dd0e34849ebdf4c/src/ifuse.c#L623</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:IOS]]<br />
[[ja:iOS]]<br />
[[zh-hans:IOS]]<br />
{{Related articles start}}<br />
{{Related|Audiobook}}<br />
{{Related|iPhone tethering}}<br />
{{Related articles end}}<br />
{{Style|Numerous style issues, see [[Help:Style]]}}<br />
The purpose of this article is to demonstrate the use of iOS devices with Arch Linux.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|libimobiledevice}} libraries and optionally {{AUR|ifuse}} the mounting utility<br />
<br />
== Connecting to a device ==<br />
<br />
=== Usbmux daemon ===<br />
<br />
{{ic|usbmuxd}} is required to make connections to iOS devices all. [[systemd]] comes with udev rule to automatically start and stop this daemon so no user interaction is required.<br />
<br />
Insert the iOS device and verify that {{ic|usbmuxd.service}} automatically started.<br />
<br />
{{hc|systemctl status usbmuxd.service|<br />
''...''<br />
Active: active (running) since Sun 2020-01-19 19:23:18 UTC; 22s ago<br />
''...''<br />
}}<br />
<br />
=== Pairing ===<br />
<br />
In order to be able to connect to the iOS device, it must be connected via USB to the computer.<br />
<br />
{{Note|Device screen must be unlocked}}<br />
<br />
{{hc|idevicepair pair|<br />
SUCCESS: Paired with device d8e8fca2dc0f896fd7cb4cb0031ba249<br />
}}<br />
<br />
If you have multiple iOS devices connected {{ic|--udid ''ios_udid''}} parameter can be passed to target specific device.<br />
<br />
=== Application integration ===<br />
<br />
Applications which use GVFS, such as some file managers (GNOME Files, Thunar) or media players (Rhythmbox) can interact with iOS devices after [[Install|installing]] the {{Pkg|gvfs-afc}} and {{Pkg|gvfs-gphoto2}} packages. Restarting the file manager or application might be needed.<br />
<br />
=== Manual mounting ===<br />
<br />
[[Install]] the {{AUR|ifuse}} package.<br />
<br />
==== Mounting the media directory ====<br />
<br />
The simplest way to mount your iPhone's filesystem to your mount folder, is using the following:<br />
# ifuse -o allow_other ''mountpoint''<br />
If you do not use the ''allow_other option'', you will not be able to access the mountpoint folder, even if you attempt to sudo into it.<br />
<br />
Application documents are not included in the iPhone's media directory and are mounted separately.<br />
<br />
==== Mounting application documents ====<br />
<br />
To list all available applications (and their APPIDs), run the following:<br />
<br />
# ifuse --list-apps<br />
<br />
For example, if VLC is installed on device, you can mount VLC's files:<br />
<br />
# ifuse --documents org.videolan.vlc-ios ''mountpoint''<br />
<br />
{{ic|org.videolan.vlc-ios}} is the APPID listed in the output of the previous command.<br />
<br />
The ''mountpoint'' field is where you want to have it mounted.<br />
<br />
== Changing iPod mountpoint ==<br />
<br />
Traditional iPods are accessed just like a normal USB storage device containing a ''vfat'' file system (in rare cases ''hfsplus''), and can be accessed as such. See the [[USB storage devices]] article for detailed instructions.<br />
<br />
{{Tip|If you cannot see the iPod file system, it is likely that it is ''hfsplus'' formatted. For convenience, as Arch kernel is built with no support for that filesystem, you might want to restore your iPod using iTunes on Windows. This will erase all data on your iPod, and format it as a ''vfat'' filesystem}}<br />
<br />
If {{pkg|udisks2}} is installed, it will mount an attached iPod to {{ic|/run/media/''$USER''/''iPod_name''}}.<br />
<br />
If the volume label of the iPod is long, or contains a mixture of spaces, and/or lower-case and capital letters, it may present an inconvenience. You may easily change the volume label for more expedient access using {{ic|dosfslabel}} from the {{pkg|dosfstools}} package:<br />
<br />
* Get and confirm the current volume label:<br />
# dosfslabel /dev/sd''XY''<br />
* Set the new volume label:<br />
# dosfslabel /dev/sd''XY'' ArchPod<br />
* Unmount the device:<br />
$ udisksctl unmount -b /dev/sd''XY''<br />
* Mount it again:<br />
$ udisksctl mount -b /dev/sd''XY''<br />
where {{ic|/dev/sdxx}} is the current device node of your iPod.<br />
<br />
== Importing videos and pictures ==<br />
<br />
Both videos and photos can be found in typically in {{ic|''&lt;mountpoint&gt;''/DCIM/100APPLE}}.<br />
<br />
=== HTML5 videos ===<br />
<br />
Typically you want to convert MOV files to a HTML5 video format like OGV using {{Pkg|ffmpeg2theora}}. Note that the creation date metadata is not in the converted video, so you need to use a script like:<br />
<br />
{{bc|1=<br />
#!/usr/bin/sh<br />
<br />
find -name "*.MOV" {{!}} while read mov<br />
do<br />
d=$(gst-discoverer-1.0 -v $mov {{!}} awk '/datetime:/{print $2}' {{!}} tr -d \")<br />
base=${mov%.*}<br />
if test -f $base.ogv<br />
then<br />
touch -d${d} $base.ogv<br />
ls -l $base.ogv<br />
else<br />
echo $base.ogv missing<br />
fi<br />
done<br />
}}<br />
<br />
And use {{ic|cp -a}} or {{ic|rsync -t}} in order to preserve the file's date & time.<br />
<br />
=== Importing pictures and deleting them ===<br />
<br />
You can move photos and videos out of {{ic|''&lt;mountpoint&gt;''/DCIM/100APPLE}}, however you need to trigger a rebuild of the "Camera Roll" database by deleting the old databases.<br />
<br />
# cd ''&lt;mountpoint&gt;''/PhotoData<br />
# rm Photos* com.apple.photos.caches_metadata.plist<br />
<br />
== Converting video for devices ==<br />
<br />
=== Handbrake ===<br />
<br />
[https://handbrake.fr/ Handbrake] is a nifty tool with presets for a variety of iPod versions. CLI and GTK versions are available with the {{pkg|handbrake-cli}} and {{pkg|handbrake}} packages respectively.<br />
<br />
If you do decide to take the CLI way, a good guide is available at https://handbrake.fr/docs/en/latest/cli/command-line-reference.html.<br />
<br />
=== Avidemux ===<br />
<br />
[[Install]] the {{Pkg|avidemux-qt}} package.<br />
<br />
This can convert to mp4 files. If you enforce a hard max of bit rate @ 700ish and keep the video size to 720x480 or 320x240 than it works fine for video file exporting.<br />
<br />
=== Mencoder ===<br />
<br />
[[Install]] the {{pkg|mplayer}} package.<br />
<br />
Has ''extremely'' comprehensive configuration support, which will be able to spit out iPod-compatible video files. Check out {{man|1|mencoder}}; a lot of MPlayer opts will also affect encoding.<br />
<br />
A basic guide is also available at [[MEncoder]].<br />
<br />
An example command to encode iPhone/iPod Touch-compatible video:<br />
<br />
mencoder INPUT -o output.mp4 \<br />
-vf scale=480:-10,harddup \<br />
-oac faac -faacopts mpeg=4:object=2:raw:br=128 \<br />
-of lavf -lavfopts format=mp4 \<br />
-ovc x264 -x264encopts nocabac:level_idc=30:bframes=0<br />
<br />
=== FFmpeg ===<br />
<br />
[[Install]] the {{pkg|ffmpeg}} package.<br />
<br />
Another encoder with comprehensive configuration support. Example command to encode for 5G iPod:<br />
<br />
$ ffmpeg -vcodec xvid -b 300 -qmin 3 -qmax 5 -bufsize 4096 \<br />
-g 300 -acodec aac -ab 96 -i INPUT -s 320x240 \<br />
-aspect 4:3 output.mp4<br />
<br />
or iPod Touch/iPhone compatible video output:<br />
<br />
$ ffmpeg -f mp4 -vcodec mpeg4 -maxrate 1000 -b 700 -qmin 3 -qmax 5\<br />
-bufsize 4096 -g 300 -acodec aac -ab 192 -s 480×320 -aspect 4:3 -i INPUT output.mp4<br />
<br />
== Device specific ==<br />
<br />
=== iPhone/iPod Touch ===<br />
<br />
By default, neither the iPhone nor the iPod Touch present mass storage capability over USB, though there is a solution for accessing your files.<br />
<br />
The proposed solution is to use a FUSE file system called {{AUR|ifuse}}, which allows you to mount your device through USB, as you normally would. After installing ifuse, for instance, you should see your iPhone appear in the left navigation of Gnome Files and other supporting file managers.<br />
<br />
{{Tip|You can also use other [[#iPod management apps]] to transfer pictures and music.}}<br />
<br />
Refer to this page:[https://help.ubuntu.com/community/PortableDevices/iPhone]<br />
<br />
==== The iFuse Way ====<br />
<br />
{{Note|If your device has a screen password, you must unlock the device to gain access through the USB interface.}}<br />
<br />
[[Install]] the {{AUR|ifuse}} package.<br />
<br />
Now make sure that you have the fuse module loaded by doing {{ic|modprobe fuse}}, assuming that you do not have it in {{ic|/etc/modules-load.d/}} already.<br />
<br />
You can now mount your device. Make sure it is unlocked before you plug it in, or it will not be recognized.<br />
# ifuse <mountpoint><br />
The mountpoint field is where you want to have it mounted.<br />
<br />
And you are done! You should be able to point your syncing software of choice to the mount point and be able to transfer files.<br />
<br />
To unmount your device:<br />
# umount <mountpoint><br />
<br />
Members of group {{ic|fuse}} can mount devices as regular user:<br />
$ ifuse <mountpoint><br />
<br />
To unmount:<br />
$ fusermount -u <mountpoint><br />
<br />
==== Generating HashInfo file ====<br />
<br />
If you have never synced your device using ''iTunes'', you will get error messages telling you that the HashInfo file is missing. This can be fixed by syncing once with iTunes in order to create it.<br />
Alternatively one can create this file using the site http://ihash.marcansoft.com/. Enter the serial number of the iPod on the website. It will generate a file named {{ic|HashInfo}} which you will place under the {{ic|/mnt/ipod/iPod_Control/Device/}} directory. Unplug the iPod device and plug it back.<br />
<br />
==== Unobfuscating the Database ====<br />
<br />
Since firmware version 2.0, Apple has obfuscated the music database. If you are using recent firmware, the file {{ic|/System/Library/Lockdown/Checkpoint.xml}} can be modified to enable use of the older, non-obfuscated database. If that file does not exist then try to copy from {{ic| /System/Library/CoreServices/Checkpoint.xml}} to {{ic|/System/Library/Lockdown/Checkpoint.xml}} then replace:<br />
<key>DBVersion</key><br />
<integer>4</integer><br />
with:<br />
<key>DBVersion</key><br />
<integer>2</integer><br />
Then reboot your device.<br />
<br />
If syncing fails with "ERROR: Unsupported checksum type '0' in cbk file generation!", you may need to leave this at 4. libgpod seems to [http://gitorious.org/libgpod/libgpod/blobs/b9b83dc8b6c3d1f0c53ed32f05279ca838d54e02/src/itdb_sqlite.c#line2064 expect a hashed database.]<br />
<br />
=== iPod Classic/Nano (3rd generation) ===<br />
<br />
You need to set up the iPod to make libgpod able to find its Firewire ID. For this, you will need to get your FireWire ID manually<br />
<br />
1) Mount the iPod as a rw mount point. In the following example, use {{ic|/mnt/ipod}}.<br />
<br />
2 ) Find the serial number by typing<br />
<br />
# lsusb -v | grep -i Serial <br />
<br />
this should print a 16 character long string like 00A1234567891231 (it will have no colons or hyphens) <br />
<br />
3) Once you have that number, create or edit {{ic|/mnt/ipod/iPod_Control/Device/SysInfo}}. Add to that file the line below:<br />
<br />
FirewireGuid: 0xffffffffffffffff<br />
<br />
(replace ffffffffffffffff with the 16 digit string you obtained at the previous step and do not forget the leading 0x before the string)<br />
<br />
Your iPod can now be managed with Amarok or gtkpod.<br />
<br />
=== iPod Nano 5th generation ===<br />
<br />
Follow the instructions above [[#Generating HashInfo file]] in order to set up the hash file, it is needed to write into the device music library.<br />
To be able to use the iPod Nano with {{pkg|libgpod}}, a {{ic|SysInfoExtended}} file is also needed to be placed in the directory {{ic|/mnt/ipod/iPod_Control/Device/}}. It can be generated using:<br />
# ipod-read-sysinfo-extended '''bus''' '''device''' '''mountpoint'''<br />
for example:<br />
# ipod-read-sysinfo-extended 001 011 /mnt/ipod/<br />
<br />
=== iPod Nano 6th generation ===<br />
<br />
By default libgpod does not seem to be able to syncronize on a iPod Nano 6th generation. It copies data, but as soon as USB is disconnected, everything is as before. The package {{AUR|libhashab-git}} fix this.<br />
<br />
=== iPod Shuffle 1st and 2nd generation ===<br />
<br />
Due to the simple structure of the Shuffle (compared to the "big" iPods), it is possible to use the player almost like any other USB flash MP3 player. What is necessary is [https://sourceforge.net/projects/shuffle-db/files/latest/download rebuild_db.py] file stored in the iPod's root directory. Simply copy MP3 files onto the iPod Shuffle (sub-folders are allowed too) and run:<br />
<br />
$ python2 /path/to/rebuild_db.py<br />
<br />
[http://shuffle-db.sourceforge.net/ Source]<br />
<br />
=== iPod Shuffle 4th generation ===<br />
<br />
In order to use this version of the iPod Shuffle under linux, you can use the python based command line tool {{AUR|ipod-shuffle-4g}}. It also provides advanced voiceover and (auto)playlist generation support.<br />
<br />
=== iPod Video (5th and 5.5th generation) ===<br />
<br />
iPods in the mainline series up to and including this model do not support the AAC PNS feature, and will display audible artifacts when encountering it. Disable the feature in {{Pkg|ffmpeg}} when encoding AAC files for these devices.<br />
<br />
$ ffmpeg -i input.ogg -c:a aac -b:a 256k -aac_pns 0 -movflags +faststart -vn output.m4a<br />
<br />
The {{ic|-movflags +faststart}} options place the moov atom at the start of the file, which helps the iPod parse the file faster.<br />
<br />
== iPod management apps ==<br />
<br />
These tools use the ''libgpod'' library:<br />
<br />
* {{App|Strawberry|Fork of Clementine aimed at audio enthusiasts and music collectors.|https://www.strawberrymusicplayer.org/|{{Pkg|strawberry}}}}<br />
<br />
* {{App|[[Rhythmbox]]|GTK clone of iTunes, used by default in GNOME.|https://wiki.gnome.org/Apps/Rhythmbox|{{Pkg|rhythmbox}}}}<br />
<br />
* {{App|[[Wikipedia:Banshee (media player)|Banshee]]|[[Wikipedia:iTunes|iTunes]] clone, built with GTK and [[Mono]], feature-rich.|http://banshee.fm/|{{AUR|banshee}}}}<br />
<br />
* {{App|[[Wikipedia:gtkpod|gtkpod]]|GUI for Apple's iPod using GTK. It allows you to import your existing iTunes database, add songs, podcasts, videos and cover art, and to edit ID3 tags.|https://sourceforge.net/projects/gtkpod/|{{AUR|gtkpod}}}}<br />
<br />
* {{App|[[Amarok]]|Mature Qt-based player known for its plethora of features.|https://amarok.kde.org/|{{AUR|amarok}}}}<br />
<br />
* {{App|Yamipod|Lightweight application for managing ONLY music on your iPod (not on your computer)|http://www.yamipod.com|}}<br />
<br />
These tools use their own implementation to communicate with the iPod:<br />
<br />
* {{App|Floola|GTK interface|http://www.floola.com|}}<br />
<br />
* {{App|GNUpod|Command line only, collection of tools written in Perl.|https://www.gnu.org/software/gnupod/|{{aur|gnupod-git}}}}<br />
<br />
* {{App|qpod|KDE/qt front end for ''GNUpod''|https://qpod.sourceforge.net|}}<br />
<br />
* {{App|jakpod|JakPod is based on Java and allows to copy music and video files to your iPod|http://www.jakpod.de/|}}<br />
<br />
== See also ==<br />
<br />
* [https://help.ubuntu.com/community/PortableDevices/iPhone More information about iPhone/iPod Touch support]<br />
* [http://wiki.gotux.net/code/perl/atget Apple trailers downloader script]{{Dead link|2020|03|29|status=domain name not resolved}}</div>PXfhttps://wiki.archlinux.org/index.php?title=System_time&diff=693575System time2021-08-31T08:05:38Z<p>PXf: /* Per-user/session or temporary settings */ +manpagelink</p>
<hr />
<div>[[Category:Mainboards and BIOS]]<br />
[[Category:System administration]]<br />
[[es:System time]]<br />
[[fa:زمان]]<br />
[[fr:System time]]<br />
[[ja:時刻]]<br />
[[zh-hans:System time]]<br />
[[zh-hant:System time]]<br />
{{Related articles start}}<br />
{{Related|Network Time Protocol daemon}}<br />
{{Related|OpenNTPD}}<br />
{{Related|Chrony}}<br />
{{Related|systemd-timesyncd}}<br />
{{Related articles end}}<br />
{{Expansion|This article mostly documents [[systemd]] ''timedatectl''; explain basic commands like ''date'' and ''hwclock'' first}}<br />
In an operating system, the time (clock) is determined by three parts: time value, whether it is local time or UTC or something else, time zone, and Daylight Saving Time ''(DST)'' if applicable. This article explains what they are and how to read/set them. Two clocks are present on systems: a hardware clock and a system clock which are also detailed in this article.<br />
<br />
Standard behavior of most operating systems is:<br />
<br />
* Set the system clock from the hardware clock on boot.<br />
* Keep accurate time of the system clock, see [[#Time synchronization]].<br />
* Set the hardware clock from the system clock on shutdown.<br />
<br />
== Hardware clock ==<br />
<br />
The '''hardware clock''' (a.k.a. the Real Time Clock (RTC) or CMOS clock) stores the values of: Year, Month, Day, Hour, Minute, and Seconds. Only 2016, or later, [[UEFI]] firmware has the ability to store the timezone, and whether DST is used.<br />
<br />
=== Read hardware clock ===<br />
<br />
# hwclock --show<br />
<br />
=== Set hardware clock from system clock ===<br />
<br />
The following sets the hardware clock from the system clock. Additionally it updates {{ic|/etc/adjtime}} or creates it if not present. See {{man|8|hwclock}} section "The Adjtime File" for more information on this file as well as the [[#Time skew]] section.<br />
<br />
# hwclock --systohc<br />
<br />
== System clock ==<br />
<br />
The '''system clock''' (a.k.a. the software clock) keeps track of: time, time zone, and DST if applicable. It is calculated by the Linux kernel as the number of seconds since midnight January 1st 1970, UTC. The initial value of the system clock is calculated from the hardware clock, dependent on the contents of {{ic|/etc/adjtime}}. After boot-up has completed, the system clock runs independently of the hardware clock. The Linux kernel keeps track of the system clock by counting timer interrupts.<br />
<br />
=== Read clock ===<br />
<br />
To check the current system clock time (presented both in local time and UTC) as well as the RTC (hardware clock):<br />
<br />
$ timedatectl<br />
<br />
=== Set system clock ===<br />
<br />
To set the local time of the system clock directly:<br />
# timedatectl set-time "yyyy-MM-dd hh:mm:ss"<br />
<br />
For example:<br />
# timedatectl set-time "2014-05-26 11:13:54"<br />
sets the time to May 26th, year 2014, 11:13 and 54 seconds.<br />
<br />
== Time standard ==<br />
<br />
There are two time standards: '''localtime''' and [[Wikipedia:Coordinated Universal Time|Coordinated Universal Time]] ('''UTC'''). The localtime standard is dependent on the current ''time zone'', while UTC is the ''global'' time standard and is independent of time zone values. Though conceptually different, UTC is also known as GMT (Greenwich Mean Time).<br />
<br />
The standard used by the hardware clock (CMOS clock, the BIOS time) is set by the operating system. By default, ''Windows'' uses localtime, ''macOS'' uses UTC, and other ''UNIX-like'' systems vary. An OS that uses the UTC standard will generally consider the hardware clock as UTC and make an adjustment to it to set the OS time at boot according to the time zone.<br />
<br />
If multiple operating systems are installed on a machine, they will all derive the current time from the same hardware clock: it is recommended to adopt a unique standard for the hardware clock to avoid conflicts across systems and set it to UTC. Otherwise, if the hardware clock is set to ''localtime'', more than one operating system may adjust it after a [[Wikipedia:Daylight_saving_time|DST]] change for example, thus resulting in an over-correction; problems may also arise when traveling between different time zones and using one of the operating systems to reset the system/hardware clock.<br />
<br />
The hardware clock can be queried and set with the {{ic|timedatectl}} command. <br />
You can see the current hardware clock time standard of the Arch system using:<br />
<br />
{{hc|$ timedatectl {{!}} grep local|RTC in local TZ: no}}<br />
<br />
To change the hardware clock time standard to localtime, use:<br />
<br />
# timedatectl set-local-rtc '''1'''<br />
<br />
To revert to the hardware clock being in UTC, type:<br />
<br />
# timedatectl set-local-rtc '''0'''<br />
<br />
These generate {{ic|/etc/adjtime}} automatically and update the RTC accordingly; no further configuration is required.<br />
<br />
During kernel startup, at the point when the RTC driver is loaded, the system clock may be set from the hardware clock. Whether this occurs depends on the hardware platform, the version of the kernel and kernel build options. If this does occur, at this point in the boot sequence, the hardware clock time is assumed to be UTC and the value of {{ic|/sys/class/rtc/rtc''N''/hctosys}} (N=0,1,2,..) will be set to 1. <br />
<br />
Later, the system clock is set again from the hardware clock by systemd, dependent on values in {{ic|/etc/adjtime}}. Hence, having the hardware clock using localtime may cause some unexpected behavior during the boot sequence; e.g system time going backwards, which is always a bad idea ([https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html there is a lot more to it]). To avoid it systemd [https://mailman.archlinux.org/pipermail/arch-dev-public/2014-August/026577.html will only synchronize back], if the hardware clock is set to UTC and keep the kernel uninformed about the local timezone. As a consequence timestamps on a FAT filesystem touched by the Linux system will be in UTC. <br />
<br />
{{Note|<br />
* The use of {{ic|timedatectl}} requires an active [[D-Bus]]. Therefore, it may not be possible to use this command under a [[chroot]] (such as during installation). In these cases, you can revert back to the hwclock command, or use [[systemd-nspawn]] instead of chroot.<br />
* If {{ic|/etc/adjtime}} is not present, [[systemd]] assumes the hardware clock is set to UTC.<br />
}}<br />
<br />
=== UTC in Microsoft Windows ===<br />
<br />
To [[dual boot with Windows]] it is recommended to configure Windows to use UTC, rather than Linux to use localtime. (Windows by default uses localtime [https://devblogs.microsoft.com/oldnewthing/20040902-00/?p=37983].)<br />
<br />
It can be done by a simple registry fix: Open {{ic|regedit}} and add a {{ic|DWORD}} value with hexadecimal value {{ic|1}} to the registry:<br />
<br />
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\RealTimeIsUniversal<br />
<br />
You can do this from an Administrator Command Prompt running:<br />
<br />
reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /d 1 /t REG_DWORD /f<br />
<br />
<br />
Alternatively, create a {{ic|*.reg}} file (on the desktop) with the following content and double-click it to import it into registry:<br />
<br />
Windows Registry Editor Version 5.00<br />
<br />
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation]<br />
"RealTimeIsUniversal"=dword:00000001<br />
<br />
<br />
Should Windows ask to update the clock due to DST changes, let it. It will leave the clock in UTC as expected, only correcting the displayed time.<br />
<br />
The [[#Hardware clock]] and [[#System clock]] time may need to be updated after setting this value.<br />
<br />
If you are having issues with the offset of the time, try reinstalling {{Pkg|tzdata}} and then setting your time zone again:<br />
<br />
# timedatectl set-timezone America/Los_Angeles<br />
<br />
==== Historical notes ====<br />
<br />
For ''really old'' Windows, the above method fails, due to Windows bugs. More precisely,<br />
<br />
* For 64-bit versions of Windows 7 and older builds of Windows 10, there was a bug that made it necessary to have a {{ic|QWORD}} value with hexadecimal value of {{ic|1}} instead of a {{ic|DWORD}} value. This bug has been fixed in newer builds and now only {{ic|DWORD}} works.<br />
* Before Vista SP2, there is a bug that resets the clock to ''localtime'' after resuming from the suspend/hibernation state.<br />
* For XP and older, there is a bug related to the daylight saving time. See [https://mskb.pkisolutions.com/kb/2687252] for details.<br />
* For ''even older'' versions of Windows, you might want to read https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html - the functionality was not even documented nor officially supported then.<br />
<br />
For these operating systems, it is recommended to use ''localtime''.<br />
<br />
=== UTC in Ubuntu ===<br />
<br />
Ubuntu and its derivatives have the hardware clock set to be interpreted as in "localtime" if Windows was detected on any disk during Ubuntu installation. This is apparently done deliberately to allow new Linux users to try out Ubuntu on their Windows computers without editing the registry.<br />
<br />
For changing this behavior, see above.<br />
<br />
== Time zone ==<br />
<br />
To check the current zone defined for the system:<br />
<br />
$ timedatectl status<br />
<br />
To list available zones:<br />
<br />
$ timedatectl list-timezones<br />
<br />
To set your time zone:<br />
<br />
# timedatectl set-timezone ''Zone''/''SubZone''<br />
<br />
Example:<br />
<br />
# timedatectl set-timezone Canada/Eastern<br />
<br />
This will create an {{ic|/etc/localtime}} symlink that points to a zoneinfo file under {{ic|/usr/share/zoneinfo/}}. In case you choose to create the link manually (for example during [[chroot]] where {{ic|timedatectl}} will not work), keep in mind that it must be a symbolic link, as specified in {{man|7|archlinux}}{{Dead link|2021|02|08}}:<br />
<br />
# ln -sf /usr/share/zoneinfo/''Zone''/''SubZone'' /etc/localtime<br />
<br />
{{Tip|The time zone can also be selected interactively with ''tzselect''.}}<br />
<br />
See {{man|1|timedatectl}}, {{man|5|localtime}} and {{man|7|archlinux}}{{Dead link|2021|02|08}} for details.<br />
<br />
=== Setting based on geolocation ===<br />
<br />
{{Note|Some desktop environments have support for automatic time zone selection (e.g. see [[GNOME#Date & time]]).}}<br />
<br />
To set the timezone automatically based on the IP address location, one can use a geolocation API to retrieve the timezone, for example {{ic|curl <nowiki>https://ipapi.co/timezone</nowiki>}}, and pass the output to {{ic|timedatectl set-timezone}} for automatic setting. Some geo-IP APIs that provide free or partly free services are listed below:<br />
<br />
* [https://www.abstractapi.com/ip-geolocation-api Abstract IP geolocation API]<br />
* [https://freegeoip.app FreegeoIP]<br />
* [https://ip-api.com/ IP-api]<br />
* [https://ipapi.co/ IPAPI]<br />
* [https://ipdata.co Ipdata]<br />
* [https://ipstack.com/ Ipstack]<br />
* [https://timezoneapi.io/ TimezoneApi]<br />
<br />
==== Update timezone every time NetworkManager connects to a network ====<br />
<br />
Create a [[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|<br />
#!/bin/sh<br />
case "$2" in<br />
up)<br />
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"<br />
;;<br />
esac<br />
}}<br />
<br />
Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.<br />
<br />
== Time skew ==<br />
<br />
Every clock has a value that differs from ''real time'' (the best representation of which being [[Wikipedia:International Atomic Time|International Atomic Time]]); no clock is perfect. A quartz-based electronic clock keeps imperfect time, but maintains a consistent inaccuracy. This base 'inaccuracy' is known as 'time skew' or 'time drift'.<br />
<br />
When the hardware clock is set with {{ic|hwclock}}, a new drift value is calculated in seconds per day. The drift value is calculated by using the difference between the new value set and the hardware clock value just before the set, taking into account the value of the previous drift value and the last time the hardware clock was set. The new drift value and the time when the clock was set is written to the file {{ic|/etc/adjtime}} overwriting the previous values. The hardware clock can therefore be adjusted for drift when the command {{ic|hwclock --adjust}} is run; this also occurs on shutdown but only if the {{ic|hwclock}} daemon is enabled, hence for Arch systems which use systemd, this does not happen.<br />
<br />
{{Note|If the hwclock has been set again less than 24 hours after a previous set, the drift is not recalculated as {{ic|hwclock}} considers the elapsed time period too short to accurately calculate the drift.}}<br />
<br />
If the hardware clock keeps losing or gaining time in large increments, it is possible that an invalid drift has been recorded (but only applicable, if the hwclock daemon is running). This can happen if you have set the hardware clock time incorrectly or your [[#Time standard|time standard]] is not synchronized with a Windows or macOS install. The drift value can be removed by first removing the file {{ic|/etc/adjtime}}, then setting the correct hardware clock and system clock time. You should then check if your time standard is correct.<br />
<br />
{{Note|If you wish to make use of the drift value stored in {{ic|/etc/adjtime}} even when using systemd, (e.g. you cannot or do not want to use NTP), you must call {{ic|hwclock --adjust}} on a regular basis, perhaps by creating a [[cron]] job.}}<br />
<br />
The software clock is very accurate but like most clocks is not perfectly accurate and will drift as well. Though rarely, the system clock can lose accuracy if the kernel skips interrupts. There are some tools to improve software clock accuracy:<br />
<br />
* See [[#Time synchronization]].<br />
<br />
== Time synchronization ==<br />
<br />
The [[Wikipedia:Network Time Protocol|Network Time Protocol]] (NTP) is a protocol for synchronizing the clocks of computer systems over packet-switched, variable-latency data networks. The following are implementations of NTP available for Arch Linux:<br />
<br />
* {{App|[[Chrony]]|A client and server that is roaming friendly and designed specifically for systems that are not online all the time.|https://chrony.tuxfamily.org/|{{Pkg|chrony}}}}<br />
* {{App|[[ConnMan]]|A lightweight network manager with NTP support.|[https://web.archive.org/web/20210224075615/https://01.org/connman https://01.org/connman (waybackmachine)]|{{Pkg|connman}}}}<br />
* {{App|[[Network Time Protocol daemon]]|The [[Wikipedia:reference implementation|reference implementation]] of the protocol, especially recommended to be used on time servers. It can also adjust the interrupt frequency and the number of ticks per second to decrease system clock drift, and will cause the hardware clock to be re-synchronised every 11 minutes.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|ntpclient|A simple command-line NTP client.|http://doolittle.icarus.com/ntpclient/|{{Aur|ntpclient}}}}<br />
* {{App|[[NTPsec]]|A fork of NTPd, focused on security.|https://ntpsec.org/|{{AUR|ntpsec}}}}<br />
* {{App|[[OpenNTPD]]|Part of the OpenBSD project and implements both a client and a server.|https://www.openntpd.org/|{{Pkg|openntpd}}}}<br />
* {{App|sntp|An [[wikipedia:Network Time Protocol#SNTP|SNTP]] client that comes with NTPd. It supersedes ''ntpdate'' and is recommended in non-server environments.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|[[systemd-timesyncd]]|A simple [[wikipedia:Network Time Protocol#SNTP|SNTP]] daemon that only implements a client side, focusing only on querying time from one remote server. It should be more than appropriate for most installations.|https://www.freedesktop.org/wiki/Software/systemd/|{{Pkg|systemd}}}}<br />
<br />
== Per-user/session or temporary settings ==<br />
<br />
For some use cases it may be useful to change the time settings without touching the global system values. For example to test applications relying on the time during development or adjusting the system time zone when logging into a server remotely from another zone. <br />
<br />
To make an application "see" a different date/time than the system one, you can use the ''{{man|1|faketime}}'' (from {{Pkg|libfaketime}}) utility.<br />
<br />
If instead you want an application to "see" a different time zone than the system one, set the {{ic|TZ}} [[environment variable]], for example: <br />
<br />
{{hc|1=$ date && export TZ=":/usr/share/zoneinfo/Pacific/Fiji" && date|2=<br />
Tue Nov 1 14:34:51 CET 2016<br />
Wed Nov 2 01:34:51 FJT 2016<br />
}}<br />
<br />
This is different than just setting the time, as for example it allows to test the behavior of a program with positive or negative UTC offset values, or the effects of DST changes when developing on systems in a non-DST time zone.<br />
<br />
Another use case is having different time zones set for different users of the same system: this can be accomplished by setting the {{ic|TZ}} variable in the shell's configuration file, see [[Environment variables#Defining variables]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Clock shows a value that is neither UTC nor local time ===<br />
<br />
This might be caused by a number of reasons. For example, if your hardware clock is running on local time, but {{ic|timedatectl}} is set to assume it is in UTC, the result would be that your timezone's offset to UTC effectively gets applied twice, resulting in wrong values for your local time and UTC.<br />
<br />
To force your clock to the correct time, and to also write the correct UTC to your hardware clock, follow these steps:<br />
<br />
* Setup [[ntpd]] (enabling it as a service is not necessary).<br />
* Set your [[#Time zone|time zone]] correctly.<br />
* Run {{ic|ntpd -qg}} to manually synchronize your clock with the network, ignoring large deviations between local UTC and network UTC.<br />
* Run {{ic|hwclock --systohc}} to write the current software UTC time to the hardware clock.<br />
<br />
== Tips and tricks ==<br />
<br />
=== fake-hwclock ===<br />
<br />
[https://github.com/xanmanning/alarm-fake-hwclock alarm-fake-hwclock] designed especially for system without battery backed up RTC, it includes a systemd service which on shutdown saves the current time and on startup restores the saved time, thus avoiding strange time travel errors. <br />
<br />
[[Install]] {{AUR|fake-hwclock-git}}, [[Systemd#Using_units|start and enable]] the service {{ic|fake-hwclock.service}}.<br />
<br />
== See also ==<br />
<br />
* [http://sunnyan.tistory.com/entry/Linux-Clocks-and-Time Linux Tips - Linux, Clocks, and Time]<br />
* [https://opensource.com/article/17/6/timekeeping-linux-vms An introduction to timekeeping in Linux VMs]<br />
* [https://data.iana.org/time-zones/tz-link.html Sources for Time Zone and Daylight Saving Time Data] for {{Pkg|tzdata}}<br />
* [https://www.ucolick.org/~sla/leapsecs/timescales.html Time Scales]<br />
* [[Gentoo: System time]]<br />
* [[Wikipedia:Time]]</div>PXfhttps://wiki.archlinux.org/index.php?title=System_time&diff=693556System time2021-08-31T06:55:00Z<p>PXf: /* Time standard */ +wikilink, hint on using systemd-nspawn instead of chroot if dbus is required</p>
<hr />
<div>[[Category:Mainboards and BIOS]]<br />
[[Category:System administration]]<br />
[[es:System time]]<br />
[[fa:زمان]]<br />
[[fr:System time]]<br />
[[ja:時刻]]<br />
[[zh-hans:System time]]<br />
[[zh-hant:System time]]<br />
{{Related articles start}}<br />
{{Related|Network Time Protocol daemon}}<br />
{{Related|OpenNTPD}}<br />
{{Related|Chrony}}<br />
{{Related|systemd-timesyncd}}<br />
{{Related articles end}}<br />
{{Expansion|This article mostly documents [[systemd]] ''timedatectl''; explain basic commands like ''date'' and ''hwclock'' first}}<br />
In an operating system, the time (clock) is determined by three parts: time value, whether it is local time or UTC or something else, time zone, and Daylight Saving Time ''(DST)'' if applicable. This article explains what they are and how to read/set them. Two clocks are present on systems: a hardware clock and a system clock which are also detailed in this article.<br />
<br />
Standard behavior of most operating systems is:<br />
<br />
* Set the system clock from the hardware clock on boot.<br />
* Keep accurate time of the system clock, see [[#Time synchronization]].<br />
* Set the hardware clock from the system clock on shutdown.<br />
<br />
== Hardware clock ==<br />
<br />
The '''hardware clock''' (a.k.a. the Real Time Clock (RTC) or CMOS clock) stores the values of: Year, Month, Day, Hour, Minute, and Seconds. Only 2016, or later, [[UEFI]] firmware has the ability to store the timezone, and whether DST is used.<br />
<br />
=== Read hardware clock ===<br />
<br />
# hwclock --show<br />
<br />
=== Set hardware clock from system clock ===<br />
<br />
The following sets the hardware clock from the system clock. Additionally it updates {{ic|/etc/adjtime}} or creates it if not present. See {{man|8|hwclock}} section "The Adjtime File" for more information on this file as well as the [[#Time skew]] section.<br />
<br />
# hwclock --systohc<br />
<br />
== System clock ==<br />
<br />
The '''system clock''' (a.k.a. the software clock) keeps track of: time, time zone, and DST if applicable. It is calculated by the Linux kernel as the number of seconds since midnight January 1st 1970, UTC. The initial value of the system clock is calculated from the hardware clock, dependent on the contents of {{ic|/etc/adjtime}}. After boot-up has completed, the system clock runs independently of the hardware clock. The Linux kernel keeps track of the system clock by counting timer interrupts.<br />
<br />
=== Read clock ===<br />
<br />
To check the current system clock time (presented both in local time and UTC) as well as the RTC (hardware clock):<br />
<br />
$ timedatectl<br />
<br />
=== Set system clock ===<br />
<br />
To set the local time of the system clock directly:<br />
# timedatectl set-time "yyyy-MM-dd hh:mm:ss"<br />
<br />
For example:<br />
# timedatectl set-time "2014-05-26 11:13:54"<br />
sets the time to May 26th, year 2014, 11:13 and 54 seconds.<br />
<br />
== Time standard ==<br />
<br />
There are two time standards: '''localtime''' and [[Wikipedia:Coordinated Universal Time|Coordinated Universal Time]] ('''UTC'''). The localtime standard is dependent on the current ''time zone'', while UTC is the ''global'' time standard and is independent of time zone values. Though conceptually different, UTC is also known as GMT (Greenwich Mean Time).<br />
<br />
The standard used by the hardware clock (CMOS clock, the BIOS time) is set by the operating system. By default, ''Windows'' uses localtime, ''macOS'' uses UTC, and other ''UNIX-like'' systems vary. An OS that uses the UTC standard will generally consider the hardware clock as UTC and make an adjustment to it to set the OS time at boot according to the time zone.<br />
<br />
If multiple operating systems are installed on a machine, they will all derive the current time from the same hardware clock: it is recommended to adopt a unique standard for the hardware clock to avoid conflicts across systems and set it to UTC. Otherwise, if the hardware clock is set to ''localtime'', more than one operating system may adjust it after a [[Wikipedia:Daylight_saving_time|DST]] change for example, thus resulting in an over-correction; problems may also arise when traveling between different time zones and using one of the operating systems to reset the system/hardware clock.<br />
<br />
The hardware clock can be queried and set with the {{ic|timedatectl}} command. <br />
You can see the current hardware clock time standard of the Arch system using:<br />
<br />
{{hc|$ timedatectl {{!}} grep local|RTC in local TZ: no}}<br />
<br />
To change the hardware clock time standard to localtime, use:<br />
<br />
# timedatectl set-local-rtc '''1'''<br />
<br />
To revert to the hardware clock being in UTC, type:<br />
<br />
# timedatectl set-local-rtc '''0'''<br />
<br />
These generate {{ic|/etc/adjtime}} automatically and update the RTC accordingly; no further configuration is required.<br />
<br />
During kernel startup, at the point when the RTC driver is loaded, the system clock may be set from the hardware clock. Whether this occurs depends on the hardware platform, the version of the kernel and kernel build options. If this does occur, at this point in the boot sequence, the hardware clock time is assumed to be UTC and the value of {{ic|/sys/class/rtc/rtc''N''/hctosys}} (N=0,1,2,..) will be set to 1. <br />
<br />
Later, the system clock is set again from the hardware clock by systemd, dependent on values in {{ic|/etc/adjtime}}. Hence, having the hardware clock using localtime may cause some unexpected behavior during the boot sequence; e.g system time going backwards, which is always a bad idea ([https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html there is a lot more to it]). To avoid it systemd [https://mailman.archlinux.org/pipermail/arch-dev-public/2014-August/026577.html will only synchronize back], if the hardware clock is set to UTC and keep the kernel uninformed about the local timezone. As a consequence timestamps on a FAT filesystem touched by the Linux system will be in UTC. <br />
<br />
{{Note|<br />
* The use of {{ic|timedatectl}} requires an active [[D-Bus|dbus]]. Therefore, it may not be possible to use this command under a [[chroot]] (such as during installation). In these cases, you can revert back to the hwclock command, or use [[systemd-nspawn]] instead of chroot.<br />
* If {{ic|/etc/adjtime}} is not present, [[systemd]] assumes the hardware clock is set to UTC.<br />
}}<br />
<br />
=== UTC in Microsoft Windows ===<br />
<br />
To [[dual boot with Windows]] it is recommended to configure Windows to use UTC, rather than Linux to use localtime. (Windows by default uses localtime [https://devblogs.microsoft.com/oldnewthing/20040902-00/?p=37983].)<br />
<br />
It can be done by a simple registry fix: Open {{ic|regedit}} and add a {{ic|DWORD}} value with hexadecimal value {{ic|1}} to the registry:<br />
<br />
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\RealTimeIsUniversal<br />
<br />
You can do this from an Administrator Command Prompt running:<br />
<br />
reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /d 1 /t REG_DWORD /f<br />
<br />
<br />
Alternatively, create a {{ic|*.reg}} file (on the desktop) with the following content and double-click it to import it into registry:<br />
<br />
Windows Registry Editor Version 5.00<br />
<br />
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation]<br />
"RealTimeIsUniversal"=dword:00000001<br />
<br />
<br />
Should Windows ask to update the clock due to DST changes, let it. It will leave the clock in UTC as expected, only correcting the displayed time.<br />
<br />
The [[#Hardware clock]] and [[#System clock]] time may need to be updated after setting this value.<br />
<br />
If you are having issues with the offset of the time, try reinstalling {{Pkg|tzdata}} and then setting your time zone again:<br />
<br />
# timedatectl set-timezone America/Los_Angeles<br />
<br />
==== Historical notes ====<br />
<br />
For ''really old'' Windows, the above method fails, due to Windows bugs. More precisely,<br />
<br />
* For 64-bit versions of Windows 7 and older builds of Windows 10, there was a bug that made it necessary to have a {{ic|QWORD}} value with hexadecimal value of {{ic|1}} instead of a {{ic|DWORD}} value. This bug has been fixed in newer builds and now only {{ic|DWORD}} works.<br />
* Before Vista SP2, there is a bug that resets the clock to ''localtime'' after resuming from the suspend/hibernation state.<br />
* For XP and older, there is a bug related to the daylight saving time. See [https://mskb.pkisolutions.com/kb/2687252] for details.<br />
* For ''even older'' versions of Windows, you might want to read https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html - the functionality was not even documented nor officially supported then.<br />
<br />
For these operating systems, it is recommended to use ''localtime''.<br />
<br />
=== UTC in Ubuntu ===<br />
<br />
Ubuntu and its derivatives have the hardware clock set to be interpreted as in "localtime" if Windows was detected on any disk during Ubuntu installation. This is apparently done deliberately to allow new Linux users to try out Ubuntu on their Windows computers without editing the registry.<br />
<br />
For changing this behavior, see above.<br />
<br />
== Time zone ==<br />
<br />
To check the current zone defined for the system:<br />
<br />
$ timedatectl status<br />
<br />
To list available zones:<br />
<br />
$ timedatectl list-timezones<br />
<br />
To set your time zone:<br />
<br />
# timedatectl set-timezone ''Zone''/''SubZone''<br />
<br />
Example:<br />
<br />
# timedatectl set-timezone Canada/Eastern<br />
<br />
This will create an {{ic|/etc/localtime}} symlink that points to a zoneinfo file under {{ic|/usr/share/zoneinfo/}}. In case you choose to create the link manually (for example during [[chroot]] where {{ic|timedatectl}} will not work), keep in mind that it must be a symbolic link, as specified in {{man|7|archlinux}}{{Dead link|2021|02|08}}:<br />
<br />
# ln -sf /usr/share/zoneinfo/''Zone''/''SubZone'' /etc/localtime<br />
<br />
{{Tip|The time zone can also be selected interactively with ''tzselect''.}}<br />
<br />
See {{man|1|timedatectl}}, {{man|5|localtime}} and {{man|7|archlinux}}{{Dead link|2021|02|08}} for details.<br />
<br />
=== Setting based on geolocation ===<br />
<br />
{{Note|Some desktop environments have support for automatic time zone selection (e.g. see [[GNOME#Date & time]]).}}<br />
<br />
To set the timezone automatically based on the IP address location, one can use a geolocation API to retrieve the timezone, for example {{ic|curl <nowiki>https://ipapi.co/timezone</nowiki>}}, and pass the output to {{ic|timedatectl set-timezone}} for automatic setting. Some geo-IP APIs that provide free or partly free services are listed below:<br />
<br />
* [https://www.abstractapi.com/ip-geolocation-api Abstract IP geolocation API]<br />
* [https://freegeoip.app FreegeoIP]<br />
* [https://ip-api.com/ IP-api]<br />
* [https://ipapi.co/ IPAPI]<br />
* [https://ipdata.co Ipdata]<br />
* [https://ipstack.com/ Ipstack]<br />
* [https://timezoneapi.io/ TimezoneApi]<br />
<br />
==== Update timezone every time NetworkManager connects to a network ====<br />
<br />
Create a [[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|<br />
#!/bin/sh<br />
case "$2" in<br />
up)<br />
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"<br />
;;<br />
esac<br />
}}<br />
<br />
Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.<br />
<br />
== Time skew ==<br />
<br />
Every clock has a value that differs from ''real time'' (the best representation of which being [[Wikipedia:International Atomic Time|International Atomic Time]]); no clock is perfect. A quartz-based electronic clock keeps imperfect time, but maintains a consistent inaccuracy. This base 'inaccuracy' is known as 'time skew' or 'time drift'.<br />
<br />
When the hardware clock is set with {{ic|hwclock}}, a new drift value is calculated in seconds per day. The drift value is calculated by using the difference between the new value set and the hardware clock value just before the set, taking into account the value of the previous drift value and the last time the hardware clock was set. The new drift value and the time when the clock was set is written to the file {{ic|/etc/adjtime}} overwriting the previous values. The hardware clock can therefore be adjusted for drift when the command {{ic|hwclock --adjust}} is run; this also occurs on shutdown but only if the {{ic|hwclock}} daemon is enabled, hence for Arch systems which use systemd, this does not happen.<br />
<br />
{{Note|If the hwclock has been set again less than 24 hours after a previous set, the drift is not recalculated as {{ic|hwclock}} considers the elapsed time period too short to accurately calculate the drift.}}<br />
<br />
If the hardware clock keeps losing or gaining time in large increments, it is possible that an invalid drift has been recorded (but only applicable, if the hwclock daemon is running). This can happen if you have set the hardware clock time incorrectly or your [[#Time standard|time standard]] is not synchronized with a Windows or macOS install. The drift value can be removed by first removing the file {{ic|/etc/adjtime}}, then setting the correct hardware clock and system clock time. You should then check if your time standard is correct.<br />
<br />
{{Note|If you wish to make use of the drift value stored in {{ic|/etc/adjtime}} even when using systemd, (e.g. you cannot or do not want to use NTP), you must call {{ic|hwclock --adjust}} on a regular basis, perhaps by creating a [[cron]] job.}}<br />
<br />
The software clock is very accurate but like most clocks is not perfectly accurate and will drift as well. Though rarely, the system clock can lose accuracy if the kernel skips interrupts. There are some tools to improve software clock accuracy:<br />
<br />
* See [[#Time synchronization]].<br />
<br />
== Time synchronization ==<br />
<br />
The [[Wikipedia:Network Time Protocol|Network Time Protocol]] (NTP) is a protocol for synchronizing the clocks of computer systems over packet-switched, variable-latency data networks. The following are implementations of NTP available for Arch Linux:<br />
<br />
* {{App|[[Chrony]]|A client and server that is roaming friendly and designed specifically for systems that are not online all the time.|https://chrony.tuxfamily.org/|{{Pkg|chrony}}}}<br />
* {{App|[[ConnMan]]|A lightweight network manager with NTP support.|[https://web.archive.org/web/20210224075615/https://01.org/connman https://01.org/connman (waybackmachine)]|{{Pkg|connman}}}}<br />
* {{App|[[Network Time Protocol daemon]]|The [[Wikipedia:reference implementation|reference implementation]] of the protocol, especially recommended to be used on time servers. It can also adjust the interrupt frequency and the number of ticks per second to decrease system clock drift, and will cause the hardware clock to be re-synchronised every 11 minutes.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|ntpclient|A simple command-line NTP client.|http://doolittle.icarus.com/ntpclient/|{{Aur|ntpclient}}}}<br />
* {{App|[[NTPsec]]|A fork of NTPd, focused on security.|https://ntpsec.org/|{{AUR|ntpsec}}}}<br />
* {{App|[[OpenNTPD]]|Part of the OpenBSD project and implements both a client and a server.|https://www.openntpd.org/|{{Pkg|openntpd}}}}<br />
* {{App|sntp|An [[wikipedia:Network Time Protocol#SNTP|SNTP]] client that comes with NTPd. It supersedes ''ntpdate'' and is recommended in non-server environments.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|[[systemd-timesyncd]]|A simple [[wikipedia:Network Time Protocol#SNTP|SNTP]] daemon that only implements a client side, focusing only on querying time from one remote server. It should be more than appropriate for most installations.|https://www.freedesktop.org/wiki/Software/systemd/|{{Pkg|systemd}}}}<br />
<br />
== Per-user/session or temporary settings ==<br />
<br />
For some use cases it may be useful to change the time settings without touching the global system values. For example to test applications relying on the time during development or adjusting the system time zone when logging into a server remotely from another zone. <br />
<br />
To make an application "see" a different date/time than the system one, you can use the ''faketime'' (from {{Pkg|libfaketime}}) utility.<br />
<br />
If instead you want an application to "see" a different time zone than the system one, set the {{ic|TZ}} [[environment variable]], for example: <br />
<br />
{{hc|1=$ date && export TZ=":/usr/share/zoneinfo/Pacific/Fiji" && date|2=<br />
Tue Nov 1 14:34:51 CET 2016<br />
Wed Nov 2 01:34:51 FJT 2016<br />
}}<br />
<br />
This is different than just setting the time, as for example it allows to test the behavior of a program with positive or negative UTC offset values, or the effects of DST changes when developing on systems in a non-DST time zone.<br />
<br />
Another use case is having different time zones set for different users of the same system: this can be accomplished by setting the {{ic|TZ}} variable in the shell's configuration file, see [[Environment variables#Defining variables]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Clock shows a value that is neither UTC nor local time ===<br />
<br />
This might be caused by a number of reasons. For example, if your hardware clock is running on local time, but {{ic|timedatectl}} is set to assume it is in UTC, the result would be that your timezone's offset to UTC effectively gets applied twice, resulting in wrong values for your local time and UTC.<br />
<br />
To force your clock to the correct time, and to also write the correct UTC to your hardware clock, follow these steps:<br />
<br />
* Setup [[ntpd]] (enabling it as a service is not necessary).<br />
* Set your [[#Time zone|time zone]] correctly.<br />
* Run {{ic|ntpd -qg}} to manually synchronize your clock with the network, ignoring large deviations between local UTC and network UTC.<br />
* Run {{ic|hwclock --systohc}} to write the current software UTC time to the hardware clock.<br />
<br />
== Tips and tricks ==<br />
<br />
=== fake-hwclock ===<br />
<br />
[https://github.com/xanmanning/alarm-fake-hwclock alarm-fake-hwclock] designed especially for system without battery backed up RTC, it includes a systemd service which on shutdown saves the current time and on startup restores the saved time, thus avoiding strange time travel errors. <br />
<br />
[[Install]] {{AUR|fake-hwclock-git}}, [[Systemd#Using_units|start and enable]] the service {{ic|fake-hwclock.service}}.<br />
<br />
== See also ==<br />
<br />
* [http://sunnyan.tistory.com/entry/Linux-Clocks-and-Time Linux Tips - Linux, Clocks, and Time]<br />
* [https://opensource.com/article/17/6/timekeeping-linux-vms An introduction to timekeeping in Linux VMs]<br />
* [https://data.iana.org/time-zones/tz-link.html Sources for Time Zone and Daylight Saving Time Data] for {{Pkg|tzdata}}<br />
* [https://www.ucolick.org/~sla/leapsecs/timescales.html Time Scales]<br />
* [[Gentoo: System time]]<br />
* [[Wikipedia:Time]]</div>PXfhttps://wiki.archlinux.org/index.php?title=System_time&diff=693552System time2021-08-31T06:12:34Z<p>PXf: /* Time standard */ macOS is perhaps not UNIX, but at least UNIX-like</p>
<hr />
<div>[[Category:Mainboards and BIOS]]<br />
[[Category:System administration]]<br />
[[es:System time]]<br />
[[fa:زمان]]<br />
[[fr:System time]]<br />
[[ja:時刻]]<br />
[[zh-hans:System time]]<br />
[[zh-hant:System time]]<br />
{{Related articles start}}<br />
{{Related|Network Time Protocol daemon}}<br />
{{Related|OpenNTPD}}<br />
{{Related|Chrony}}<br />
{{Related|systemd-timesyncd}}<br />
{{Related articles end}}<br />
{{Expansion|This article mostly documents [[systemd]] ''timedatectl''; explain basic commands like ''date'' and ''hwclock'' first}}<br />
In an operating system, the time (clock) is determined by three parts: time value, whether it is local time or UTC or something else, time zone, and Daylight Saving Time ''(DST)'' if applicable. This article explains what they are and how to read/set them. Two clocks are present on systems: a hardware clock and a system clock which are also detailed in this article.<br />
<br />
Standard behavior of most operating systems is:<br />
<br />
* Set the system clock from the hardware clock on boot.<br />
* Keep accurate time of the system clock, see [[#Time synchronization]].<br />
* Set the hardware clock from the system clock on shutdown.<br />
<br />
== Hardware clock ==<br />
<br />
The '''hardware clock''' (a.k.a. the Real Time Clock (RTC) or CMOS clock) stores the values of: Year, Month, Day, Hour, Minute, and Seconds. Only 2016, or later, [[UEFI]] firmware has the ability to store the timezone, and whether DST is used.<br />
<br />
=== Read hardware clock ===<br />
<br />
# hwclock --show<br />
<br />
=== Set hardware clock from system clock ===<br />
<br />
The following sets the hardware clock from the system clock. Additionally it updates {{ic|/etc/adjtime}} or creates it if not present. See {{man|8|hwclock}} section "The Adjtime File" for more information on this file as well as the [[#Time skew]] section.<br />
<br />
# hwclock --systohc<br />
<br />
== System clock ==<br />
<br />
The '''system clock''' (a.k.a. the software clock) keeps track of: time, time zone, and DST if applicable. It is calculated by the Linux kernel as the number of seconds since midnight January 1st 1970, UTC. The initial value of the system clock is calculated from the hardware clock, dependent on the contents of {{ic|/etc/adjtime}}. After boot-up has completed, the system clock runs independently of the hardware clock. The Linux kernel keeps track of the system clock by counting timer interrupts.<br />
<br />
=== Read clock ===<br />
<br />
To check the current system clock time (presented both in local time and UTC) as well as the RTC (hardware clock):<br />
<br />
$ timedatectl<br />
<br />
=== Set system clock ===<br />
<br />
To set the local time of the system clock directly:<br />
# timedatectl set-time "yyyy-MM-dd hh:mm:ss"<br />
<br />
For example:<br />
# timedatectl set-time "2014-05-26 11:13:54"<br />
sets the time to May 26th, year 2014, 11:13 and 54 seconds.<br />
<br />
== Time standard ==<br />
<br />
There are two time standards: '''localtime''' and [[Wikipedia:Coordinated Universal Time|Coordinated Universal Time]] ('''UTC'''). The localtime standard is dependent on the current ''time zone'', while UTC is the ''global'' time standard and is independent of time zone values. Though conceptually different, UTC is also known as GMT (Greenwich Mean Time).<br />
<br />
The standard used by the hardware clock (CMOS clock, the BIOS time) is set by the operating system. By default, ''Windows'' uses localtime, ''macOS'' uses UTC, and other ''UNIX-like'' systems vary. An OS that uses the UTC standard will generally consider the hardware clock as UTC and make an adjustment to it to set the OS time at boot according to the time zone.<br />
<br />
If multiple operating systems are installed on a machine, they will all derive the current time from the same hardware clock: it is recommended to adopt a unique standard for the hardware clock to avoid conflicts across systems and set it to UTC. Otherwise, if the hardware clock is set to ''localtime'', more than one operating system may adjust it after a [[Wikipedia:Daylight_saving_time|DST]] change for example, thus resulting in an over-correction; problems may also arise when traveling between different time zones and using one of the operating systems to reset the system/hardware clock.<br />
<br />
The hardware clock can be queried and set with the {{ic|timedatectl}} command. <br />
You can see the current hardware clock time standard of the Arch system using:<br />
<br />
{{hc|$ timedatectl {{!}} grep local|RTC in local TZ: no}}<br />
<br />
To change the hardware clock time standard to localtime, use:<br />
<br />
# timedatectl set-local-rtc '''1'''<br />
<br />
To revert to the hardware clock being in UTC, type:<br />
<br />
# timedatectl set-local-rtc '''0'''<br />
<br />
These generate {{ic|/etc/adjtime}} automatically and update the RTC accordingly; no further configuration is required.<br />
<br />
During kernel startup, at the point when the RTC driver is loaded, the system clock may be set from the hardware clock. Whether this occurs depends on the hardware platform, the version of the kernel and kernel build options. If this does occur, at this point in the boot sequence, the hardware clock time is assumed to be UTC and the value of {{ic|/sys/class/rtc/rtc''N''/hctosys}} (N=0,1,2,..) will be set to 1. <br />
<br />
Later, the system clock is set again from the hardware clock by systemd, dependent on values in {{ic|/etc/adjtime}}. Hence, having the hardware clock using localtime may cause some unexpected behavior during the boot sequence; e.g system time going backwards, which is always a bad idea ([https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html there is a lot more to it]). To avoid it systemd [https://mailman.archlinux.org/pipermail/arch-dev-public/2014-August/026577.html will only synchronize back], if the hardware clock is set to UTC and keep the kernel uninformed about the local timezone. As a consequence timestamps on a FAT filesystem touched by the Linux system will be in UTC. <br />
<br />
{{Note|<br />
* The use of {{ic|timedatectl}} requires an active dbus. Therefore, it may not be possible to use this command under a chroot (such as during installation). In these cases, you can revert back to the hwclock command.<br />
* If {{ic|/etc/adjtime}} is not present, [[systemd]] assumes the hardware clock is set to UTC.<br />
}}<br />
<br />
=== UTC in Microsoft Windows ===<br />
<br />
To [[dual boot with Windows]] it is recommended to configure Windows to use UTC, rather than Linux to use localtime. (Windows by default uses localtime [https://devblogs.microsoft.com/oldnewthing/20040902-00/?p=37983].)<br />
<br />
It can be done by a simple registry fix: Open {{ic|regedit}} and add a {{ic|DWORD}} value with hexadecimal value {{ic|1}} to the registry:<br />
<br />
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\RealTimeIsUniversal<br />
<br />
You can do this from an Administrator Command Prompt running:<br />
<br />
reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /d 1 /t REG_DWORD /f<br />
<br />
<br />
Alternatively, create a {{ic|*.reg}} file (on the desktop) with the following content and double-click it to import it into registry:<br />
<br />
Windows Registry Editor Version 5.00<br />
<br />
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation]<br />
"RealTimeIsUniversal"=dword:00000001<br />
<br />
<br />
Should Windows ask to update the clock due to DST changes, let it. It will leave the clock in UTC as expected, only correcting the displayed time.<br />
<br />
The [[#Hardware clock]] and [[#System clock]] time may need to be updated after setting this value.<br />
<br />
If you are having issues with the offset of the time, try reinstalling {{Pkg|tzdata}} and then setting your time zone again:<br />
<br />
# timedatectl set-timezone America/Los_Angeles<br />
<br />
==== Historical notes ====<br />
<br />
For ''really old'' Windows, the above method fails, due to Windows bugs. More precisely,<br />
<br />
* For 64-bit versions of Windows 7 and older builds of Windows 10, there was a bug that made it necessary to have a {{ic|QWORD}} value with hexadecimal value of {{ic|1}} instead of a {{ic|DWORD}} value. This bug has been fixed in newer builds and now only {{ic|DWORD}} works.<br />
* Before Vista SP2, there is a bug that resets the clock to ''localtime'' after resuming from the suspend/hibernation state.<br />
* For XP and older, there is a bug related to the daylight saving time. See [https://mskb.pkisolutions.com/kb/2687252] for details.<br />
* For ''even older'' versions of Windows, you might want to read https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html - the functionality was not even documented nor officially supported then.<br />
<br />
For these operating systems, it is recommended to use ''localtime''.<br />
<br />
=== UTC in Ubuntu ===<br />
<br />
Ubuntu and its derivatives have the hardware clock set to be interpreted as in "localtime" if Windows was detected on any disk during Ubuntu installation. This is apparently done deliberately to allow new Linux users to try out Ubuntu on their Windows computers without editing the registry.<br />
<br />
For changing this behavior, see above.<br />
<br />
== Time zone ==<br />
<br />
To check the current zone defined for the system:<br />
<br />
$ timedatectl status<br />
<br />
To list available zones:<br />
<br />
$ timedatectl list-timezones<br />
<br />
To set your time zone:<br />
<br />
# timedatectl set-timezone ''Zone''/''SubZone''<br />
<br />
Example:<br />
<br />
# timedatectl set-timezone Canada/Eastern<br />
<br />
This will create an {{ic|/etc/localtime}} symlink that points to a zoneinfo file under {{ic|/usr/share/zoneinfo/}}. In case you choose to create the link manually (for example during [[chroot]] where {{ic|timedatectl}} will not work), keep in mind that it must be a symbolic link, as specified in {{man|7|archlinux}}{{Dead link|2021|02|08}}:<br />
<br />
# ln -sf /usr/share/zoneinfo/''Zone''/''SubZone'' /etc/localtime<br />
<br />
{{Tip|The time zone can also be selected interactively with ''tzselect''.}}<br />
<br />
See {{man|1|timedatectl}}, {{man|5|localtime}} and {{man|7|archlinux}}{{Dead link|2021|02|08}} for details.<br />
<br />
=== Setting based on geolocation ===<br />
<br />
{{Note|Some desktop environments have support for automatic time zone selection (e.g. see [[GNOME#Date & time]]).}}<br />
<br />
To set the timezone automatically based on the IP address location, one can use a geolocation API to retrieve the timezone, for example {{ic|curl <nowiki>https://ipapi.co/timezone</nowiki>}}, and pass the output to {{ic|timedatectl set-timezone}} for automatic setting. Some geo-IP APIs that provide free or partly free services are listed below:<br />
<br />
* [https://www.abstractapi.com/ip-geolocation-api Abstract IP geolocation API]<br />
* [https://freegeoip.app FreegeoIP]<br />
* [https://ip-api.com/ IP-api]<br />
* [https://ipapi.co/ IPAPI]<br />
* [https://ipdata.co Ipdata]<br />
* [https://ipstack.com/ Ipstack]<br />
* [https://timezoneapi.io/ TimezoneApi]<br />
<br />
==== Update timezone every time NetworkManager connects to a network ====<br />
<br />
Create a [[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|<br />
#!/bin/sh<br />
case "$2" in<br />
up)<br />
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"<br />
;;<br />
esac<br />
}}<br />
<br />
Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.<br />
<br />
== Time skew ==<br />
<br />
Every clock has a value that differs from ''real time'' (the best representation of which being [[Wikipedia:International Atomic Time|International Atomic Time]]); no clock is perfect. A quartz-based electronic clock keeps imperfect time, but maintains a consistent inaccuracy. This base 'inaccuracy' is known as 'time skew' or 'time drift'.<br />
<br />
When the hardware clock is set with {{ic|hwclock}}, a new drift value is calculated in seconds per day. The drift value is calculated by using the difference between the new value set and the hardware clock value just before the set, taking into account the value of the previous drift value and the last time the hardware clock was set. The new drift value and the time when the clock was set is written to the file {{ic|/etc/adjtime}} overwriting the previous values. The hardware clock can therefore be adjusted for drift when the command {{ic|hwclock --adjust}} is run; this also occurs on shutdown but only if the {{ic|hwclock}} daemon is enabled, hence for Arch systems which use systemd, this does not happen.<br />
<br />
{{Note|If the hwclock has been set again less than 24 hours after a previous set, the drift is not recalculated as {{ic|hwclock}} considers the elapsed time period too short to accurately calculate the drift.}}<br />
<br />
If the hardware clock keeps losing or gaining time in large increments, it is possible that an invalid drift has been recorded (but only applicable, if the hwclock daemon is running). This can happen if you have set the hardware clock time incorrectly or your [[#Time standard|time standard]] is not synchronized with a Windows or macOS install. The drift value can be removed by first removing the file {{ic|/etc/adjtime}}, then setting the correct hardware clock and system clock time. You should then check if your time standard is correct.<br />
<br />
{{Note|If you wish to make use of the drift value stored in {{ic|/etc/adjtime}} even when using systemd, (e.g. you cannot or do not want to use NTP), you must call {{ic|hwclock --adjust}} on a regular basis, perhaps by creating a [[cron]] job.}}<br />
<br />
The software clock is very accurate but like most clocks is not perfectly accurate and will drift as well. Though rarely, the system clock can lose accuracy if the kernel skips interrupts. There are some tools to improve software clock accuracy:<br />
<br />
* See [[#Time synchronization]].<br />
<br />
== Time synchronization ==<br />
<br />
The [[Wikipedia:Network Time Protocol|Network Time Protocol]] (NTP) is a protocol for synchronizing the clocks of computer systems over packet-switched, variable-latency data networks. The following are implementations of NTP available for Arch Linux:<br />
<br />
* {{App|[[Chrony]]|A client and server that is roaming friendly and designed specifically for systems that are not online all the time.|https://chrony.tuxfamily.org/|{{Pkg|chrony}}}}<br />
* {{App|[[ConnMan]]|A lightweight network manager with NTP support.|[https://web.archive.org/web/20210224075615/https://01.org/connman https://01.org/connman (waybackmachine)]|{{Pkg|connman}}}}<br />
* {{App|[[Network Time Protocol daemon]]|The [[Wikipedia:reference implementation|reference implementation]] of the protocol, especially recommended to be used on time servers. It can also adjust the interrupt frequency and the number of ticks per second to decrease system clock drift, and will cause the hardware clock to be re-synchronised every 11 minutes.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|ntpclient|A simple command-line NTP client.|http://doolittle.icarus.com/ntpclient/|{{Aur|ntpclient}}}}<br />
* {{App|[[NTPsec]]|A fork of NTPd, focused on security.|https://ntpsec.org/|{{AUR|ntpsec}}}}<br />
* {{App|[[OpenNTPD]]|Part of the OpenBSD project and implements both a client and a server.|https://www.openntpd.org/|{{Pkg|openntpd}}}}<br />
* {{App|sntp|An [[wikipedia:Network Time Protocol#SNTP|SNTP]] client that comes with NTPd. It supersedes ''ntpdate'' and is recommended in non-server environments.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|[[systemd-timesyncd]]|A simple [[wikipedia:Network Time Protocol#SNTP|SNTP]] daemon that only implements a client side, focusing only on querying time from one remote server. It should be more than appropriate for most installations.|https://www.freedesktop.org/wiki/Software/systemd/|{{Pkg|systemd}}}}<br />
<br />
== Per-user/session or temporary settings ==<br />
<br />
For some use cases it may be useful to change the time settings without touching the global system values. For example to test applications relying on the time during development or adjusting the system time zone when logging into a server remotely from another zone. <br />
<br />
To make an application "see" a different date/time than the system one, you can use the ''faketime'' (from {{Pkg|libfaketime}}) utility.<br />
<br />
If instead you want an application to "see" a different time zone than the system one, set the {{ic|TZ}} [[environment variable]], for example: <br />
<br />
{{hc|1=$ date && export TZ=":/usr/share/zoneinfo/Pacific/Fiji" && date|2=<br />
Tue Nov 1 14:34:51 CET 2016<br />
Wed Nov 2 01:34:51 FJT 2016<br />
}}<br />
<br />
This is different than just setting the time, as for example it allows to test the behavior of a program with positive or negative UTC offset values, or the effects of DST changes when developing on systems in a non-DST time zone.<br />
<br />
Another use case is having different time zones set for different users of the same system: this can be accomplished by setting the {{ic|TZ}} variable in the shell's configuration file, see [[Environment variables#Defining variables]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Clock shows a value that is neither UTC nor local time ===<br />
<br />
This might be caused by a number of reasons. For example, if your hardware clock is running on local time, but {{ic|timedatectl}} is set to assume it is in UTC, the result would be that your timezone's offset to UTC effectively gets applied twice, resulting in wrong values for your local time and UTC.<br />
<br />
To force your clock to the correct time, and to also write the correct UTC to your hardware clock, follow these steps:<br />
<br />
* Setup [[ntpd]] (enabling it as a service is not necessary).<br />
* Set your [[#Time zone|time zone]] correctly.<br />
* Run {{ic|ntpd -qg}} to manually synchronize your clock with the network, ignoring large deviations between local UTC and network UTC.<br />
* Run {{ic|hwclock --systohc}} to write the current software UTC time to the hardware clock.<br />
<br />
== Tips and tricks ==<br />
<br />
=== fake-hwclock ===<br />
<br />
[https://github.com/xanmanning/alarm-fake-hwclock alarm-fake-hwclock] designed especially for system without battery backed up RTC, it includes a systemd service which on shutdown saves the current time and on startup restores the saved time, thus avoiding strange time travel errors. <br />
<br />
[[Install]] {{AUR|fake-hwclock-git}}, [[Systemd#Using_units|start and enable]] the service {{ic|fake-hwclock.service}}.<br />
<br />
== See also ==<br />
<br />
* [http://sunnyan.tistory.com/entry/Linux-Clocks-and-Time Linux Tips - Linux, Clocks, and Time]<br />
* [https://opensource.com/article/17/6/timekeeping-linux-vms An introduction to timekeeping in Linux VMs]<br />
* [https://data.iana.org/time-zones/tz-link.html Sources for Time Zone and Daylight Saving Time Data] for {{Pkg|tzdata}}<br />
* [https://www.ucolick.org/~sla/leapsecs/timescales.html Time Scales]<br />
* [[Gentoo: System time]]<br />
* [[Wikipedia:Time]]</div>PXfhttps://wiki.archlinux.org/index.php?title=System_time&diff=693551System time2021-08-31T05:41:33Z<p>PXf: val, TZ, DST, where is the fourth part?</p>
<hr />
<div>[[Category:Mainboards and BIOS]]<br />
[[Category:System administration]]<br />
[[es:System time]]<br />
[[fa:زمان]]<br />
[[fr:System time]]<br />
[[ja:時刻]]<br />
[[zh-hans:System time]]<br />
[[zh-hant:System time]]<br />
{{Related articles start}}<br />
{{Related|Network Time Protocol daemon}}<br />
{{Related|OpenNTPD}}<br />
{{Related|Chrony}}<br />
{{Related|systemd-timesyncd}}<br />
{{Related articles end}}<br />
{{Expansion|This article mostly documents [[systemd]] ''timedatectl''; explain basic commands like ''date'' and ''hwclock'' first}}<br />
In an operating system, the time (clock) is determined by three parts: time value, whether it is local time or UTC or something else, time zone, and Daylight Saving Time ''(DST)'' if applicable. This article explains what they are and how to read/set them. Two clocks are present on systems: a hardware clock and a system clock which are also detailed in this article.<br />
<br />
Standard behavior of most operating systems is:<br />
<br />
* Set the system clock from the hardware clock on boot.<br />
* Keep accurate time of the system clock, see [[#Time synchronization]].<br />
* Set the hardware clock from the system clock on shutdown.<br />
<br />
== Hardware clock ==<br />
<br />
The '''hardware clock''' (a.k.a. the Real Time Clock (RTC) or CMOS clock) stores the values of: Year, Month, Day, Hour, Minute, and Seconds. Only 2016, or later, [[UEFI]] firmware has the ability to store the timezone, and whether DST is used.<br />
<br />
=== Read hardware clock ===<br />
<br />
# hwclock --show<br />
<br />
=== Set hardware clock from system clock ===<br />
<br />
The following sets the hardware clock from the system clock. Additionally it updates {{ic|/etc/adjtime}} or creates it if not present. See {{man|8|hwclock}} section "The Adjtime File" for more information on this file as well as the [[#Time skew]] section.<br />
<br />
# hwclock --systohc<br />
<br />
== System clock ==<br />
<br />
The '''system clock''' (a.k.a. the software clock) keeps track of: time, time zone, and DST if applicable. It is calculated by the Linux kernel as the number of seconds since midnight January 1st 1970, UTC. The initial value of the system clock is calculated from the hardware clock, dependent on the contents of {{ic|/etc/adjtime}}. After boot-up has completed, the system clock runs independently of the hardware clock. The Linux kernel keeps track of the system clock by counting timer interrupts.<br />
<br />
=== Read clock ===<br />
<br />
To check the current system clock time (presented both in local time and UTC) as well as the RTC (hardware clock):<br />
<br />
$ timedatectl<br />
<br />
=== Set system clock ===<br />
<br />
To set the local time of the system clock directly:<br />
# timedatectl set-time "yyyy-MM-dd hh:mm:ss"<br />
<br />
For example:<br />
# timedatectl set-time "2014-05-26 11:13:54"<br />
sets the time to May 26th, year 2014, 11:13 and 54 seconds.<br />
<br />
== Time standard ==<br />
<br />
There are two time standards: '''localtime''' and [[Wikipedia:Coordinated Universal Time|Coordinated Universal Time]] ('''UTC'''). The localtime standard is dependent on the current ''time zone'', while UTC is the ''global'' time standard and is independent of time zone values. Though conceptually different, UTC is also known as GMT (Greenwich Mean Time).<br />
<br />
The standard used by the hardware clock (CMOS clock, the BIOS time) is set by the operating system. By default, ''Windows'' uses localtime, ''macOS'' uses UTC, and ''UNIX-like'' systems vary. An OS that uses the UTC standard will generally consider the hardware clock as UTC and make an adjustment to it to set the OS time at boot according to the time zone.<br />
<br />
If multiple operating systems are installed on a machine, they will all derive the current time from the same hardware clock: it is recommended to adopt a unique standard for the hardware clock to avoid conflicts across systems and set it to UTC. Otherwise, if the hardware clock is set to ''localtime'', more than one operating system may adjust it after a [[Wikipedia:Daylight_saving_time|DST]] change for example, thus resulting in an over-correction; problems may also arise when traveling between different time zones and using one of the operating systems to reset the system/hardware clock.<br />
<br />
The hardware clock can be queried and set with the {{ic|timedatectl}} command. <br />
You can see the current hardware clock time standard of the Arch system using:<br />
<br />
{{hc|$ timedatectl {{!}} grep local|RTC in local TZ: no}}<br />
<br />
To change the hardware clock time standard to localtime, use:<br />
<br />
# timedatectl set-local-rtc '''1'''<br />
<br />
To revert to the hardware clock being in UTC, type:<br />
<br />
# timedatectl set-local-rtc '''0'''<br />
<br />
These generate {{ic|/etc/adjtime}} automatically and update the RTC accordingly; no further configuration is required.<br />
<br />
During kernel startup, at the point when the RTC driver is loaded, the system clock may be set from the hardware clock. Whether this occurs depends on the hardware platform, the version of the kernel and kernel build options. If this does occur, at this point in the boot sequence, the hardware clock time is assumed to be UTC and the value of {{ic|/sys/class/rtc/rtc''N''/hctosys}} (N=0,1,2,..) will be set to 1. <br />
<br />
Later, the system clock is set again from the hardware clock by systemd, dependent on values in {{ic|/etc/adjtime}}. Hence, having the hardware clock using localtime may cause some unexpected behavior during the boot sequence; e.g system time going backwards, which is always a bad idea ([https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html there is a lot more to it]). To avoid it systemd [https://mailman.archlinux.org/pipermail/arch-dev-public/2014-August/026577.html will only synchronize back], if the hardware clock is set to UTC and keep the kernel uninformed about the local timezone. As a consequence timestamps on a FAT filesystem touched by the Linux system will be in UTC. <br />
<br />
{{Note|<br />
* The use of {{ic|timedatectl}} requires an active dbus. Therefore, it may not be possible to use this command under a chroot (such as during installation). In these cases, you can revert back to the hwclock command.<br />
* If {{ic|/etc/adjtime}} is not present, [[systemd]] assumes the hardware clock is set to UTC.<br />
}}<br />
<br />
=== UTC in Microsoft Windows ===<br />
<br />
To [[dual boot with Windows]] it is recommended to configure Windows to use UTC, rather than Linux to use localtime. (Windows by default uses localtime [https://devblogs.microsoft.com/oldnewthing/20040902-00/?p=37983].)<br />
<br />
It can be done by a simple registry fix: Open {{ic|regedit}} and add a {{ic|DWORD}} value with hexadecimal value {{ic|1}} to the registry:<br />
<br />
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\RealTimeIsUniversal<br />
<br />
You can do this from an Administrator Command Prompt running:<br />
<br />
reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /d 1 /t REG_DWORD /f<br />
<br />
<br />
Alternatively, create a {{ic|*.reg}} file (on the desktop) with the following content and double-click it to import it into registry:<br />
<br />
Windows Registry Editor Version 5.00<br />
<br />
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation]<br />
"RealTimeIsUniversal"=dword:00000001<br />
<br />
<br />
Should Windows ask to update the clock due to DST changes, let it. It will leave the clock in UTC as expected, only correcting the displayed time.<br />
<br />
The [[#Hardware clock]] and [[#System clock]] time may need to be updated after setting this value.<br />
<br />
If you are having issues with the offset of the time, try reinstalling {{Pkg|tzdata}} and then setting your time zone again:<br />
<br />
# timedatectl set-timezone America/Los_Angeles<br />
<br />
==== Historical notes ====<br />
<br />
For ''really old'' Windows, the above method fails, due to Windows bugs. More precisely,<br />
<br />
* For 64-bit versions of Windows 7 and older builds of Windows 10, there was a bug that made it necessary to have a {{ic|QWORD}} value with hexadecimal value of {{ic|1}} instead of a {{ic|DWORD}} value. This bug has been fixed in newer builds and now only {{ic|DWORD}} works.<br />
* Before Vista SP2, there is a bug that resets the clock to ''localtime'' after resuming from the suspend/hibernation state.<br />
* For XP and older, there is a bug related to the daylight saving time. See [https://mskb.pkisolutions.com/kb/2687252] for details.<br />
* For ''even older'' versions of Windows, you might want to read https://www.cl.cam.ac.uk/~mgk25/mswish/ut-rtc.html - the functionality was not even documented nor officially supported then.<br />
<br />
For these operating systems, it is recommended to use ''localtime''.<br />
<br />
=== UTC in Ubuntu ===<br />
<br />
Ubuntu and its derivatives have the hardware clock set to be interpreted as in "localtime" if Windows was detected on any disk during Ubuntu installation. This is apparently done deliberately to allow new Linux users to try out Ubuntu on their Windows computers without editing the registry.<br />
<br />
For changing this behavior, see above.<br />
<br />
== Time zone ==<br />
<br />
To check the current zone defined for the system:<br />
<br />
$ timedatectl status<br />
<br />
To list available zones:<br />
<br />
$ timedatectl list-timezones<br />
<br />
To set your time zone:<br />
<br />
# timedatectl set-timezone ''Zone''/''SubZone''<br />
<br />
Example:<br />
<br />
# timedatectl set-timezone Canada/Eastern<br />
<br />
This will create an {{ic|/etc/localtime}} symlink that points to a zoneinfo file under {{ic|/usr/share/zoneinfo/}}. In case you choose to create the link manually (for example during [[chroot]] where {{ic|timedatectl}} will not work), keep in mind that it must be a symbolic link, as specified in {{man|7|archlinux}}{{Dead link|2021|02|08}}:<br />
<br />
# ln -sf /usr/share/zoneinfo/''Zone''/''SubZone'' /etc/localtime<br />
<br />
{{Tip|The time zone can also be selected interactively with ''tzselect''.}}<br />
<br />
See {{man|1|timedatectl}}, {{man|5|localtime}} and {{man|7|archlinux}}{{Dead link|2021|02|08}} for details.<br />
<br />
=== Setting based on geolocation ===<br />
<br />
{{Note|Some desktop environments have support for automatic time zone selection (e.g. see [[GNOME#Date & time]]).}}<br />
<br />
To set the timezone automatically based on the IP address location, one can use a geolocation API to retrieve the timezone, for example {{ic|curl <nowiki>https://ipapi.co/timezone</nowiki>}}, and pass the output to {{ic|timedatectl set-timezone}} for automatic setting. Some geo-IP APIs that provide free or partly free services are listed below:<br />
<br />
* [https://www.abstractapi.com/ip-geolocation-api Abstract IP geolocation API]<br />
* [https://freegeoip.app FreegeoIP]<br />
* [https://ip-api.com/ IP-api]<br />
* [https://ipapi.co/ IPAPI]<br />
* [https://ipdata.co Ipdata]<br />
* [https://ipstack.com/ Ipstack]<br />
* [https://timezoneapi.io/ TimezoneApi]<br />
<br />
==== Update timezone every time NetworkManager connects to a network ====<br />
<br />
Create a [[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|<br />
#!/bin/sh<br />
case "$2" in<br />
up)<br />
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"<br />
;;<br />
esac<br />
}}<br />
<br />
Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.<br />
<br />
== Time skew ==<br />
<br />
Every clock has a value that differs from ''real time'' (the best representation of which being [[Wikipedia:International Atomic Time|International Atomic Time]]); no clock is perfect. A quartz-based electronic clock keeps imperfect time, but maintains a consistent inaccuracy. This base 'inaccuracy' is known as 'time skew' or 'time drift'.<br />
<br />
When the hardware clock is set with {{ic|hwclock}}, a new drift value is calculated in seconds per day. The drift value is calculated by using the difference between the new value set and the hardware clock value just before the set, taking into account the value of the previous drift value and the last time the hardware clock was set. The new drift value and the time when the clock was set is written to the file {{ic|/etc/adjtime}} overwriting the previous values. The hardware clock can therefore be adjusted for drift when the command {{ic|hwclock --adjust}} is run; this also occurs on shutdown but only if the {{ic|hwclock}} daemon is enabled, hence for Arch systems which use systemd, this does not happen.<br />
<br />
{{Note|If the hwclock has been set again less than 24 hours after a previous set, the drift is not recalculated as {{ic|hwclock}} considers the elapsed time period too short to accurately calculate the drift.}}<br />
<br />
If the hardware clock keeps losing or gaining time in large increments, it is possible that an invalid drift has been recorded (but only applicable, if the hwclock daemon is running). This can happen if you have set the hardware clock time incorrectly or your [[#Time standard|time standard]] is not synchronized with a Windows or macOS install. The drift value can be removed by first removing the file {{ic|/etc/adjtime}}, then setting the correct hardware clock and system clock time. You should then check if your time standard is correct.<br />
<br />
{{Note|If you wish to make use of the drift value stored in {{ic|/etc/adjtime}} even when using systemd, (e.g. you cannot or do not want to use NTP), you must call {{ic|hwclock --adjust}} on a regular basis, perhaps by creating a [[cron]] job.}}<br />
<br />
The software clock is very accurate but like most clocks is not perfectly accurate and will drift as well. Though rarely, the system clock can lose accuracy if the kernel skips interrupts. There are some tools to improve software clock accuracy:<br />
<br />
* See [[#Time synchronization]].<br />
<br />
== Time synchronization ==<br />
<br />
The [[Wikipedia:Network Time Protocol|Network Time Protocol]] (NTP) is a protocol for synchronizing the clocks of computer systems over packet-switched, variable-latency data networks. The following are implementations of NTP available for Arch Linux:<br />
<br />
* {{App|[[Chrony]]|A client and server that is roaming friendly and designed specifically for systems that are not online all the time.|https://chrony.tuxfamily.org/|{{Pkg|chrony}}}}<br />
* {{App|[[ConnMan]]|A lightweight network manager with NTP support.|[https://web.archive.org/web/20210224075615/https://01.org/connman https://01.org/connman (waybackmachine)]|{{Pkg|connman}}}}<br />
* {{App|[[Network Time Protocol daemon]]|The [[Wikipedia:reference implementation|reference implementation]] of the protocol, especially recommended to be used on time servers. It can also adjust the interrupt frequency and the number of ticks per second to decrease system clock drift, and will cause the hardware clock to be re-synchronised every 11 minutes.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|ntpclient|A simple command-line NTP client.|http://doolittle.icarus.com/ntpclient/|{{Aur|ntpclient}}}}<br />
* {{App|[[NTPsec]]|A fork of NTPd, focused on security.|https://ntpsec.org/|{{AUR|ntpsec}}}}<br />
* {{App|[[OpenNTPD]]|Part of the OpenBSD project and implements both a client and a server.|https://www.openntpd.org/|{{Pkg|openntpd}}}}<br />
* {{App|sntp|An [[wikipedia:Network Time Protocol#SNTP|SNTP]] client that comes with NTPd. It supersedes ''ntpdate'' and is recommended in non-server environments.|https://www.ntp.org/|{{Pkg|ntp}}}}<br />
* {{App|[[systemd-timesyncd]]|A simple [[wikipedia:Network Time Protocol#SNTP|SNTP]] daemon that only implements a client side, focusing only on querying time from one remote server. It should be more than appropriate for most installations.|https://www.freedesktop.org/wiki/Software/systemd/|{{Pkg|systemd}}}}<br />
<br />
== Per-user/session or temporary settings ==<br />
<br />
For some use cases it may be useful to change the time settings without touching the global system values. For example to test applications relying on the time during development or adjusting the system time zone when logging into a server remotely from another zone. <br />
<br />
To make an application "see" a different date/time than the system one, you can use the ''faketime'' (from {{Pkg|libfaketime}}) utility.<br />
<br />
If instead you want an application to "see" a different time zone than the system one, set the {{ic|TZ}} [[environment variable]], for example: <br />
<br />
{{hc|1=$ date && export TZ=":/usr/share/zoneinfo/Pacific/Fiji" && date|2=<br />
Tue Nov 1 14:34:51 CET 2016<br />
Wed Nov 2 01:34:51 FJT 2016<br />
}}<br />
<br />
This is different than just setting the time, as for example it allows to test the behavior of a program with positive or negative UTC offset values, or the effects of DST changes when developing on systems in a non-DST time zone.<br />
<br />
Another use case is having different time zones set for different users of the same system: this can be accomplished by setting the {{ic|TZ}} variable in the shell's configuration file, see [[Environment variables#Defining variables]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Clock shows a value that is neither UTC nor local time ===<br />
<br />
This might be caused by a number of reasons. For example, if your hardware clock is running on local time, but {{ic|timedatectl}} is set to assume it is in UTC, the result would be that your timezone's offset to UTC effectively gets applied twice, resulting in wrong values for your local time and UTC.<br />
<br />
To force your clock to the correct time, and to also write the correct UTC to your hardware clock, follow these steps:<br />
<br />
* Setup [[ntpd]] (enabling it as a service is not necessary).<br />
* Set your [[#Time zone|time zone]] correctly.<br />
* Run {{ic|ntpd -qg}} to manually synchronize your clock with the network, ignoring large deviations between local UTC and network UTC.<br />
* Run {{ic|hwclock --systohc}} to write the current software UTC time to the hardware clock.<br />
<br />
== Tips and tricks ==<br />
<br />
=== fake-hwclock ===<br />
<br />
[https://github.com/xanmanning/alarm-fake-hwclock alarm-fake-hwclock] designed especially for system without battery backed up RTC, it includes a systemd service which on shutdown saves the current time and on startup restores the saved time, thus avoiding strange time travel errors. <br />
<br />
[[Install]] {{AUR|fake-hwclock-git}}, [[Systemd#Using_units|start and enable]] the service {{ic|fake-hwclock.service}}.<br />
<br />
== See also ==<br />
<br />
* [http://sunnyan.tistory.com/entry/Linux-Clocks-and-Time Linux Tips - Linux, Clocks, and Time]<br />
* [https://opensource.com/article/17/6/timekeeping-linux-vms An introduction to timekeeping in Linux VMs]<br />
* [https://data.iana.org/time-zones/tz-link.html Sources for Time Zone and Daylight Saving Time Data] for {{Pkg|tzdata}}<br />
* [https://www.ucolick.org/~sla/leapsecs/timescales.html Time Scales]<br />
* [[Gentoo: System time]]<br />
* [[Wikipedia:Time]]</div>PXfhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=693522Network configuration/Wireless2021-08-30T16:31:04Z<p>PXf: /* Cause #5 */ It ain't a solution. It's a workaround.</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Network configuration (Čeština)/Wireless]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Network configuration (Ελληνικά)/Wireless]]<br />
[[es:Network configuration (Español)/Wireless]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Network configuration (Français)/Wireless]]<br />
[[it:Network configuration (Italiano)/Wireless]]<br />
[[ja:ワイヤレス設定]]<br />
[[pt:Network configuration (Português)/Wireless]]<br />
[[ru:Network configuration (Русский)/Wireless]]<br />
[[zh-hans:Network configuration (简体中文)/Wireless]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package; however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} as root should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
{{Note|<br />
* If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.<br />
* If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
}}<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|# dmesg {{!}} grep firmware|<br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|# dmesg {{!}} grep iwlwifi|2=<br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [https://web.archive.org/web/20110711100256/http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List] (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64]<br />
|-<br />
| [https://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{Pkg|wireless_tools}} || {{Yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.wiki.kernel.org/en/users/documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[wpa_supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [https://wireless.wiki.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iw list''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [https://wireless.wiki.kernel.org/en/users/documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== Authentication ==<br />
<br />
{{Expansion|Add [[Wikipedia:WPA3|WPA3 Enterprise]] ({{Bug|65314}}) and [[Wikipedia:Opportunistic Wireless Encryption|Opportunistic Wireless Encryption (OWE) a.k.a. Enhanced Open]]. Warn against WEP and open networks.}}<br />
<br />
=== WPA2 Personal ===<br />
<br />
WPA2 Personal, a.k.a. WPA2-PSK, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
You can authenticate to WPA2 Personal networks using [[wpa_supplicant]] or [[iwd]], or connect using a [[network manager]]. If you only authenticated to the network, then to have a fully functional connection you will still need to assign the IP address(es) and routes either [[Network configuration#Static IP address|manually]] or using a [[DHCP]] client.<br />
<br />
=== WPA2 Enterprise ===<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option.<br />
<br />
==== eduroam ====<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
==== Manual/automatic setup ====<br />
<br />
* [[wpa_supplicant#Advanced usage|wpa_supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
* [[iwd#WPA Enterprise]]<br />
* [[NetworkManager]] can create WPA2 Enterprise profiles with ''nmcli'' or the [[NetworkManager#Front-ends|graphical front ends]]. ''nmtui'' does not support this ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/376 NetworkManager issue 376]), but may use existing profiles.<br />
* [[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting to eduroam (802.1X)]] for details.<br />
* [[netctl]] supports wpa_supplicant configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
: {{Note|Special quoting rules apply: see {{man|5|netctl.profile|SPECIAL QUOTING RULES}}.}}<br />
: {{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== WPA3 Personal ===<br />
<br />
WPA3 Personal, a.k.a. WPA3-SAE, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
[[wpa_supplicant]] supports WPA3 Personal ({{ic|CONFIG_SAE}} is enabled in {{Pkg|wpa_supplicant}} since version 2:2.9-4).<br />
<br />
[[iwd]] supports WPA3 since at least [https://iwd.wiki.kernel.org/networkmanager version 1.0].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dBm-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [https://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
# dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|<br />
* Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.<br />
* If compiling a custom kernel, {{ic|CONFIG_CFG80211_INTERNAL_REGDB}} can be enabled as an alternative to {{ic|crda}}. Once enabled, you need to place [https://git.kernel.org/pub/scm/linux/kernel/git/sforshee/wireless-regdb.git/tree/db.txt db.txt] into {{ic|net/wireless/db.txt}}. For further details and caveats see [https://wireless.wiki.kernel.org/en/developers/regulatory/crda].<br />
}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [https://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
# dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[wpa_supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [https://wireless.wiki.kernel.org/en/developers/documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=JP}} as [[Kernel_modules#Setting module options|module options]]. The module option is inherited from the [https://wireless.wiki.kernel.org/en/developers/regulatory#the_ieee80211_regdom_module_parameter old regulatory implementation] and in modern kernels act as a userspace regulatory hint as if it came through {{ic|nl80211}} through utilities like {{ic|iw}} and {{ic|wpa_supplicant}}.<br />
<br />
For further information, read the [https://wireless.wiki.kernel.org/en/developers/regulatory kernel.org regulatory documentation].<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [https://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Observing logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
<br />
# dmesg -w<br />
<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
<br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
<br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[Domain name resolution#Resolve a domain name using NSS|check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If [[dmesg]] says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card. Try disabling the wireless card's [[Power_management#Network_interfaces|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and ''dmesg'' shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Change the router's 5 GHz channel(s) to a [[Wikipedia:List_of_WLAN_channels#5_GHz_(802.11a/h/j/n/ac/ax)|non-DFS (Dynamic Frequency Selection) channel]]. Connections on such channels [https://wifinigel.blogspot.com/2018/05/the-5ghz-problem-for-wi-fi-networks-dfs.html may be dropped or suddenly switched] due to interference from nearby weather radar.<br />
* Disable {{ic|40MHz}} channel bandwidth (lower throughput but less likely collisions) with {{ic|1=cfg80211.cfg80211_disable_40mhz_24ghz=1}}<br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
==== Cause #5 ====<br />
<br />
On some wireless network adapters (e.g. Qualcomm Atheros AR9485), random disconnects can happen with a DMA error:<br />
<br />
{{hc|# journalctl -xb|2=<br />
ath: phy0: DMA failed to stop in 10 ms AR_CR=0x00000024 AR_DIAG_SW=0x02000020 DMADBG_7=0x0000a400<br />
wlp1s0: authenticate with 56:e7:ee:7b:55:bc<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 1/3)<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 2/3)<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 3/3)<br />
wlp1s0: authentication with 56:e7:ee:7b:55:bc timed out<br />
}}<br />
<br />
A possible workaround is to disable the [https://www.kernel.org/doc/html/latest/x86/intel-iommu.html Intel IOMMU driver (DMA)], adding {{ic|1=intel_iommu=off}} to the [[kernel parameters]] [https://bbs.archlinux.org/viewtopic.php?pid=1907446#p1907446].<br />
<br />
{{Note|The Intel IOMMU driver is needed for some advanced virtual machine features, like PCI pass-through.}}<br />
<br />
==== Cause #6 ====<br />
<br />
If you're using a device with iwlwifi and iwlmvm for wireless connectivity, and your Wi-Fi card appears to disappear when on battery power (perhaps after a reboot or resuming from suspend), this can be fixed by configuring power saving settings in iwlmvm.<br />
<br />
Create the file {{ic|/etc/modprobe.d/iwlmvm.conf}} if it doesn't exist already, then add the following line to it:<br />
<br />
{{hc|/etc/modprobe.d/iwlmvm.conf|2=<br />
options iwlmvm power_scheme=1<br />
}}<br />
<br />
A {{ic|power_scheme}} of 1 sets iwlmvm to "Always Active." Available options are:<br />
<br />
{| class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 1 || Always Active<br />
|-<br />
| 2 || Balanced<br />
|-<br />
| 3 || Low-power<br />
|}<br />
<br />
This fix was discovered at [http://forums.debian.net/viewtopic.php?t=121696#p576208].<br />
<br />
==== Cause #7 ====<br />
<br />
If your device undergoes long periods of inactivity (e.g. a file server) the disconnection may be due to power saving, which will block incoming traffic and prevent connections. Try disabling power saving for the interface:<br />
<br />
# iw dev ''interface'' set power_save off<br />
<br />
You can create a udev rule to do this on boot, see [[Power management#Network interfaces]].<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, some in-range Wi-Fi networks might be invisible, because they use wireless channels that are not allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}} [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3].<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [https://web.archive.org/web/20111105120212/http://web.ralinktech.com:80/ralink/Home/Support/Linux.html source tarballs] available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]. As of kernel 5.5 it should be supported by the included {{ic|mt76}} driver.<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} as root or {{ic|journalctl -f}} as root and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection. See [[Kernel module#Setting module options]].<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au, rtl8812au, rtl8814au and rtl8821au designed for various USB adapters ranging from AC600 to AC1900. Several packages provide various kernel drivers, these require [[DKMS]] (the {{Pkg|dkms}} package and the kernel headers installed):<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8821au || 5.6.4.2 || {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au and 8821au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8814au || 5.8.5.1 || {{AUR|rtl8814au-aircrack-dkms-git}} || Aircrack-ng kernel module for 8814au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8812au || 5.9.3.2 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au '''only'''.<br />
|-<br />
| rtl8811au, rtl8821au || 5.8.2.3 || {{AUR|rtl8821au-dkms-git}} || Newer driver version for rtl8821au.<br />
|-<br />
| rtl8814au || 5.8.5.1 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too. Seems to be deprecated in favor of {{AUR|rtl8814au-aircrack-dkms-git}}<br />
|}<br />
<br />
==== rtl8811cu/rtl8821cu ====<br />
<br />
{{AUR|rtl8821cu-dkms-git}} provides a kernel module for the Realtek 8811cu and 8821cu chipset.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
If no wireless interface shows up even though the {{ic|8821cu}} module is loaded, you may need to manually specify the {{ic|rtw_RFE_type}} option [https://forums.linuxmint.com/viewtopic.php?p=1913190&sid=68f2d6eff91cd47e184ae5a56385dc02#p1913190][https://github.com/brektrou/rtl8821CU/issues/83]. Try e.g. {{ic|1=rtw_RFE_type=0x26}}, other values might also work. See [[Kernel module#Setting module options]] for details.<br />
<br />
==== rtl8821ce ====<br />
<br />
{{AUR|rtl8821ce-dkms-git}} provides a kernel module for the Realtek 8821ce chipset found in the Asus X543UA.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} or {{AUR|rtl88x2bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3, Asus AC53 Nano USB 802.11ac and TP-Link Archer T3U adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [https://wireless.wiki.kernel.org/en/users/Drivers/Atheros#pcipci-eahb_driversrs Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath5k<br />
* [[Debian:ath5k]]<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath9k<br />
* [[Debian:ath9k]]<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by setting the {{ic|1=nohwcrypt=1}} option for the {{ic|ath9k}} module. See [[Kernel module#Setting module options]].<br />
<br />
{{Note|Use the command {{ic|lsmod}} to see what modules are in use and change {{ic|ath9k}} if it is named differently (e.g. {{ic|ath9k_htc}}).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [https://web.archive.org/web/20201118232556/http://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list] exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [https://wireless.wiki.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module, see [[Kernel module#Setting module options]].<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi#supported_devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{AUR|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[https://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[https://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [https://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
If you have an 802.11ax (WiFi 6) access point and have problems detecting the beacons or an unreliable connection, review [https://www.intel.com/content/www/us/en/support/articles/000054799/network-and-i-o/wireless.html Intel Article 54799].<br />
<br />
{{Note|Using {{ic|1=11n_disable=0}} will also prevent 802.11ac and only allow connection with slower protocols (802.11a in the 5GHz band or 802.11b/g in the 2.4 GHz band).}}<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wi-fibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
===== Firmware stack traces =====<br />
<br />
{{Accuracy|What is the last note about ignored packages trying to say?}}<br />
<br />
You may have some issue where the driver outputs stack traces & errors, which can cause some stuttering.<br />
<br />
{{hc|# dmesg|2=<br />
Microcode SW error detected. Restarting 0x2000000.<br />
}}<br />
<br />
To fix those errors, you may downgrade the package {{Pkg|linux-firmware}} or rename the last version of the firmware used by your device so that an older version is loaded (which keeps it out of pacman's ignored packages).<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [https://wireless.wiki.kernel.org/en/users/drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [https://sourceforge.net/projects/acx100/ official page] for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[https://sourceforge.net/projects/zd1211/ zd1211rw] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [https://wireless.wiki.kernel.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[https://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{Pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[https://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [https://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [https://wireless.wiki.kernel.org/ The Linux Wireless project]<br />
* [https://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]<br />
* [https://wikidevi.wi-cat.ru Wireless Device Database Wiki] (This fork is hosted by wi-cat.ru since the original wiki has shut down. There are two less complete versions available: [http://en.techinfodepot.shoutwiki.com TechInfoDepot], [https://deviwiki.com/ deviwiki])</div>PXfhttps://wiki.archlinux.org/index.php?title=Systemd-timesyncd&diff=693514Systemd-timesyncd2021-08-30T16:20:12Z<p>PXf: /* See also */ "Branch master was renamed to main."</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network Time Protocol]]<br />
[[de:Systemd/systemd-timesyncd]]<br />
[[es:Systemd-timesyncd]]<br />
[[fr:Systemd-timesyncd]]<br />
[[ja:Systemd-timesyncd]]<br />
[[pl:Systemd-timesyncd]]<br />
[[zh-hans:Systemd-timesyncd]]<br />
{{Related articles start}}<br />
{{Related|systemd-networkd}}<br />
{{Related|systemd}}<br />
{{Related|System time}}<br />
{{Related articles end}}<br />
From the [https://lists.freedesktop.org/archives/systemd-devel/2014-May/019537.html systemd mailing list]:<br />
<br />
:''systemd-timesyncd'' is a daemon that has been added for synchronizing the system clock across the network. It implements an SNTP client. In contrast to NTP implementations such as [[chrony]] or the NTP reference server this only implements a client side, and does not bother with the full NTP complexity, focusing only on querying time from one remote server and synchronizing the local clock to it. Unless you intend to serve NTP to networked clients or want to connect to local hardware clocks this simple NTP client should be more than appropriate for most installations. The daemon runs with minimal privileges, and has been hooked up with networkd to only operate when network connectivity is available. The daemon saves the current clock to disk every time a new NTP sync has been acquired, and uses this to possibly correct the system clock early at bootup, in order to accommodate for systems that lack an RTC such as the Raspberry Pi and embedded devices, and make sure that time monotonically progresses on these systems, even if it is not always correct. To make use of this daemon a new system user and group "systemd-timesync" needs to be created on installation of systemd.<br />
<br />
== Configuration ==<br />
<br />
[[Start/enable]] {{ic|systemd-timesyncd.service}} which is available with {{Pkg|systemd}}.<br />
<br />
When starting, ''systemd-timesyncd'' will read the configuration file from {{ic|/etc/systemd/timesyncd.conf}}, which looks like this:<br />
<br />
{{hc|/etc/systemd/timesyncd.conf|2=<br />
[Time]<br />
#NTP=<br />
#FallbackNTP=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org<br />
#RootDistanceMaxSec=5<br />
#PollIntervalMinSec=32<br />
#PollIntervalMaxSec=2048<br />
}}<br />
<br />
To add [[Network Time Protocol daemon#Connection to NTP servers|time servers]] or change the provided ones, uncomment the relevant line and list their host name or IP separated by a space. For example, you can use any servers provided by [https://www.pool.ntp.org/ the NTP pool project] or use [https://github.com/archlinux/svntogit-packages/commit/1b485f87c9e1384eaf069d031e415515e8ead92d the default Arch ones] (also provided by the NTP pool project):<br />
<br />
{{hc|/etc/systemd/timesyncd.conf|2=<br />
[Time]<br />
NTP=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org<br />
FallbackNTP=0.pool.ntp.org 1.pool.ntp.org 0.fr.pool.ntp.org<br />
}}<br />
<br />
To verify your configuration, use {{ic|timedatectl show-timesync --all}}:<br />
<br />
{{hc|$ timedatectl show-timesync --all|2=<br />
LinkNTPServers=<br />
SystemNTPServers=<br />
FallbackNTPServers=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org<br />
ServerName=0.arch.pool.ntp.org<br />
ServerAddress=103.47.76.177<br />
RootDistanceMaxUSec=5s<br />
PollIntervalMinUSec=32s<br />
PollIntervalMaxUSec=34min 8s<br />
PollIntervalUSec=1min 4s<br />
NTPMessage={ Leap=0, Version=4, Mode=4, Stratum=2, Precision=-21, RootDelay=177.398ms, RootDispersion=142.196ms, Reference=C342F10A, OriginateTimestamp=Mon 2018-07-16 13:53:43 +08, ReceiveTimestamp=Mon 2018-07-16 13:53:43 +08, TransmitTimestamp=Mon 2018-07-16 13:53:43 +08, DestinationTimestamp=Mon 2018-07-16 13:53:43 +08, Ignored=no PacketCount=1, Jitter=0 }<br />
Frequency=22520548<br />
}}<br />
<br />
Further to the daemon configuration, NTP servers may also be provided via a [[Systemd-networkd#%5BNetDev%5D section|systemd-networkd]] configuration with a {{ic|1=NTP=}} option or, dynamically, via a DHCP server. <br />
<br />
The NTP server to be used will be determined using the following rules:<br />
<br />
* Any per-interface NTP servers obtained from {{ic|systemd-networkd.service(8)}} configuration or via DHCP take precedence.<br />
* The NTP servers defined in {{ic|/etc/systemd/timesyncd.conf}} will be appended to the per-interface list at runtime and the daemon will contact the servers in turn until one is found that responds.<br />
* If no NTP server information is acquired after completing those steps, the NTP server host names or IP addresses defined in {{ic|1=FallbackNTP=}} will be used.<br />
<br />
{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization. This location is hard-coded and cannot be changed. This may be problematic for running off read-only root partition or trying to minimize writes to an SD card.}}<br />
<br />
== Usage ==<br />
<br />
To enable and start it, simply run:<br />
<br />
# timedatectl set-ntp true <br />
<br />
The synchronization process might be noticeably slow. This is expected, one should wait a while before determining there is a problem. To check the service status, use {{ic|timedatectl status}}:<br />
<br />
{{hc|$ timedatectl status|<br />
Local time: Thu 2015-07-09 18:21:33 CEST<br />
Universal time: Thu 2015-07-09 16:21:33 UTC<br />
RTC time: Thu 2015-07-09 16:21:33<br />
Time zone: Europe/Amsterdam (CEST, +0200)<br />
System clock synchronized: yes<br />
NTP service: active<br />
RTC in local TZ: no<br />
}}<br />
<br />
To see verbose service information, use {{ic|timedatectl timesync-status}}:<br />
<br />
{{hc|$ timedatectl timesync-status|<br />
Server: 103.47.76.177 (0.arch.pool.ntp.org)<br />
Poll interval: 2min 8s (min: 32s; max 34min 8s)<br />
Leap: normal<br />
Version: 4<br />
Stratum: 2<br />
Reference: C342F10A<br />
Precision: 1us (-21)<br />
Root distance: 231.856ms (max: 5s)<br />
Offset: -19.428ms<br />
Delay: 36.717ms<br />
Jitter: 7.343ms<br />
Packet count: 2<br />
Frequency: +267.747ppm<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Dynamically set NTP servers received via DHCP ===<br />
<br />
{{Style|Written like a blog post. See [[Help:Style#Language register]].}}<br />
<br />
{{Move|NetworkManager#Dispatcher examples|Belongs on the [[NetworkManager]] page, not in this troubleshooting section.}}<br />
<br />
Presupposition:<br />
<br />
* Your system clock is synchonized with NTP servers by systemd-timesyncd.<br />
<br />
* Your networks are configured by NetworkManager.<br />
<br />
If you roam between different networks (e.g. you company's LAN, your wifi at home, various other wifis now and then) you might want to set the NTP server(s) used by timesyncd to those provided by DHCP. However, NetworkManager itself not capable to communicate with systemd-timesyncd to set the NTP server(s).<br />
<br />
NetworkManager dispatcher to the rescue! (All following actions have to be performed as root. So either spin up a root shell with {{ic|sudo -i}} or prepend all commands with {{ic|sudo}}.)<br />
<br />
If not already existing create the overlay directory for your systemd-timesyncd configuration {{ic|/etc/systemd/timesyncd.conf.d}}. Also if not already existing create the directory {{ic|/etc/NetworkManager/dispatcher.d}}. Put the following dispatcher script there<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-update-timesyncd|<nowiki><br />
#! /usr/bin/bash<br />
<br />
[ -n "$CONNECTION_UUID" ] || exit<br />
<br />
INTERFACE=$1<br />
ACTION=$2<br />
<br />
case $ACTION in<br />
up | dhcp4-change | dhcp6-change)<br />
[ -n "$DHCP4_NTP_SERVERS" ] || exit<br />
exec > /etc/systemd/timesyncd.conf.d/$CONNECTION_UUID.conf<br />
echo "[Time]"<br />
echo "NTP=$DHCP4_NTP_SERVERS"<br />
systemctl restart systemd-timesyncd<br />
;;<br />
down)<br />
rm -f /etc/systemd/timesyncd.conf.d/$CONNECTION_UUID.conf<br />
systemctl restart systemd-timesyncd<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
Make this script executable by root only with {{ic|chmod 700 10-update-timesync}}. Finally make sure NetworkManager dispatcher is enabled and started.<br />
<br />
So what happens here? Every time NetworkManager sets up a new network connection ({{ic|1=ACTION=up}}) or gets some update for an existing connection ({{ic|1=ACTION=dhcp4-change}} or {{ic|1=ACTION=dhcp6-change}}) and the provided connection data contains information about NTP server(s) ({{ic|DHCP4_NTP_SERVERS}}) then a connection specific overlay configuration file is written to {{ic|/etc/systemd/timesyncd.conf.d}} containing the provided NTP server(s). Whenever a connection is taken down ({{ic|1=ACTION=down}}) the connection specific overlay file is removed again. After each change to the configuration of systemd-timesyncd this service is restarted to pick up the updated configuration.The use of connection specific config files is intentional so that when two or more connections are managed by NetworkManager in parallel the different NTP server names in the config are not overwritten as {{ic|up}}, {{ic|dhcp4-change}}, {{ic|dhcp6-change}} and {{ic|down}} actions might come in in an arbitrary order.<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=182600 Forum: systemd-timesyncd is not syncing time]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=182172 Forum: Using systemd-timesync instead of NTP]<br />
* [https://github.com/systemd/systemd/blob/main/src/timesync/timesyncd.c Git Sourcecode of timesyncd]<br />
* {{man|8|systemd-timesyncd}}<br />
* {{man|5|timesyncd.conf}}</div>PXfhttps://wiki.archlinux.org/index.php?title=Systemd-timesyncd&diff=693512Systemd-timesyncd2021-08-30T16:19:00Z<p>PXf: /* Dynamically set NTP servers received via DHCP */ reword</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network Time Protocol]]<br />
[[de:Systemd/systemd-timesyncd]]<br />
[[es:Systemd-timesyncd]]<br />
[[fr:Systemd-timesyncd]]<br />
[[ja:Systemd-timesyncd]]<br />
[[pl:Systemd-timesyncd]]<br />
[[zh-hans:Systemd-timesyncd]]<br />
{{Related articles start}}<br />
{{Related|systemd-networkd}}<br />
{{Related|systemd}}<br />
{{Related|System time}}<br />
{{Related articles end}}<br />
From the [https://lists.freedesktop.org/archives/systemd-devel/2014-May/019537.html systemd mailing list]:<br />
<br />
:''systemd-timesyncd'' is a daemon that has been added for synchronizing the system clock across the network. It implements an SNTP client. In contrast to NTP implementations such as [[chrony]] or the NTP reference server this only implements a client side, and does not bother with the full NTP complexity, focusing only on querying time from one remote server and synchronizing the local clock to it. Unless you intend to serve NTP to networked clients or want to connect to local hardware clocks this simple NTP client should be more than appropriate for most installations. The daemon runs with minimal privileges, and has been hooked up with networkd to only operate when network connectivity is available. The daemon saves the current clock to disk every time a new NTP sync has been acquired, and uses this to possibly correct the system clock early at bootup, in order to accommodate for systems that lack an RTC such as the Raspberry Pi and embedded devices, and make sure that time monotonically progresses on these systems, even if it is not always correct. To make use of this daemon a new system user and group "systemd-timesync" needs to be created on installation of systemd.<br />
<br />
== Configuration ==<br />
<br />
[[Start/enable]] {{ic|systemd-timesyncd.service}} which is available with {{Pkg|systemd}}.<br />
<br />
When starting, ''systemd-timesyncd'' will read the configuration file from {{ic|/etc/systemd/timesyncd.conf}}, which looks like this:<br />
<br />
{{hc|/etc/systemd/timesyncd.conf|2=<br />
[Time]<br />
#NTP=<br />
#FallbackNTP=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org<br />
#RootDistanceMaxSec=5<br />
#PollIntervalMinSec=32<br />
#PollIntervalMaxSec=2048<br />
}}<br />
<br />
To add [[Network Time Protocol daemon#Connection to NTP servers|time servers]] or change the provided ones, uncomment the relevant line and list their host name or IP separated by a space. For example, you can use any servers provided by [https://www.pool.ntp.org/ the NTP pool project] or use [https://github.com/archlinux/svntogit-packages/commit/1b485f87c9e1384eaf069d031e415515e8ead92d the default Arch ones] (also provided by the NTP pool project):<br />
<br />
{{hc|/etc/systemd/timesyncd.conf|2=<br />
[Time]<br />
NTP=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org<br />
FallbackNTP=0.pool.ntp.org 1.pool.ntp.org 0.fr.pool.ntp.org<br />
}}<br />
<br />
To verify your configuration, use {{ic|timedatectl show-timesync --all}}:<br />
<br />
{{hc|$ timedatectl show-timesync --all|2=<br />
LinkNTPServers=<br />
SystemNTPServers=<br />
FallbackNTPServers=0.arch.pool.ntp.org 1.arch.pool.ntp.org 2.arch.pool.ntp.org 3.arch.pool.ntp.org<br />
ServerName=0.arch.pool.ntp.org<br />
ServerAddress=103.47.76.177<br />
RootDistanceMaxUSec=5s<br />
PollIntervalMinUSec=32s<br />
PollIntervalMaxUSec=34min 8s<br />
PollIntervalUSec=1min 4s<br />
NTPMessage={ Leap=0, Version=4, Mode=4, Stratum=2, Precision=-21, RootDelay=177.398ms, RootDispersion=142.196ms, Reference=C342F10A, OriginateTimestamp=Mon 2018-07-16 13:53:43 +08, ReceiveTimestamp=Mon 2018-07-16 13:53:43 +08, TransmitTimestamp=Mon 2018-07-16 13:53:43 +08, DestinationTimestamp=Mon 2018-07-16 13:53:43 +08, Ignored=no PacketCount=1, Jitter=0 }<br />
Frequency=22520548<br />
}}<br />
<br />
Further to the daemon configuration, NTP servers may also be provided via a [[Systemd-networkd#%5BNetDev%5D section|systemd-networkd]] configuration with a {{ic|1=NTP=}} option or, dynamically, via a DHCP server. <br />
<br />
The NTP server to be used will be determined using the following rules:<br />
<br />
* Any per-interface NTP servers obtained from {{ic|systemd-networkd.service(8)}} configuration or via DHCP take precedence.<br />
* The NTP servers defined in {{ic|/etc/systemd/timesyncd.conf}} will be appended to the per-interface list at runtime and the daemon will contact the servers in turn until one is found that responds.<br />
* If no NTP server information is acquired after completing those steps, the NTP server host names or IP addresses defined in {{ic|1=FallbackNTP=}} will be used.<br />
<br />
{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization. This location is hard-coded and cannot be changed. This may be problematic for running off read-only root partition or trying to minimize writes to an SD card.}}<br />
<br />
== Usage ==<br />
<br />
To enable and start it, simply run:<br />
<br />
# timedatectl set-ntp true <br />
<br />
The synchronization process might be noticeably slow. This is expected, one should wait a while before determining there is a problem. To check the service status, use {{ic|timedatectl status}}:<br />
<br />
{{hc|$ timedatectl status|<br />
Local time: Thu 2015-07-09 18:21:33 CEST<br />
Universal time: Thu 2015-07-09 16:21:33 UTC<br />
RTC time: Thu 2015-07-09 16:21:33<br />
Time zone: Europe/Amsterdam (CEST, +0200)<br />
System clock synchronized: yes<br />
NTP service: active<br />
RTC in local TZ: no<br />
}}<br />
<br />
To see verbose service information, use {{ic|timedatectl timesync-status}}:<br />
<br />
{{hc|$ timedatectl timesync-status|<br />
Server: 103.47.76.177 (0.arch.pool.ntp.org)<br />
Poll interval: 2min 8s (min: 32s; max 34min 8s)<br />
Leap: normal<br />
Version: 4<br />
Stratum: 2<br />
Reference: C342F10A<br />
Precision: 1us (-21)<br />
Root distance: 231.856ms (max: 5s)<br />
Offset: -19.428ms<br />
Delay: 36.717ms<br />
Jitter: 7.343ms<br />
Packet count: 2<br />
Frequency: +267.747ppm<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Dynamically set NTP servers received via DHCP ===<br />
<br />
{{Style|Written like a blog post. See [[Help:Style#Language register]].}}<br />
<br />
{{Move|NetworkManager#Dispatcher examples|Belongs on the [[NetworkManager]] page, not in this troubleshooting section.}}<br />
<br />
Presupposition:<br />
<br />
* Your system clock is synchonized with NTP servers by systemd-timesyncd.<br />
<br />
* Your networks are configured by NetworkManager.<br />
<br />
If you roam between different networks (e.g. you company's LAN, your wifi at home, various other wifis now and then) you might want to set the NTP server(s) used by timesyncd to those provided by DHCP. However, NetworkManager itself not capable to communicate with systemd-timesyncd to set the NTP server(s).<br />
<br />
NetworkManager dispatcher to the rescue! (All following actions have to be performed as root. So either spin up a root shell with {{ic|sudo -i}} or prepend all commands with {{ic|sudo}}.)<br />
<br />
If not already existing create the overlay directory for your systemd-timesyncd configuration {{ic|/etc/systemd/timesyncd.conf.d}}. Also if not already existing create the directory {{ic|/etc/NetworkManager/dispatcher.d}}. Put the following dispatcher script there<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-update-timesyncd|<nowiki><br />
#! /usr/bin/bash<br />
<br />
[ -n "$CONNECTION_UUID" ] || exit<br />
<br />
INTERFACE=$1<br />
ACTION=$2<br />
<br />
case $ACTION in<br />
up | dhcp4-change | dhcp6-change)<br />
[ -n "$DHCP4_NTP_SERVERS" ] || exit<br />
exec > /etc/systemd/timesyncd.conf.d/$CONNECTION_UUID.conf<br />
echo "[Time]"<br />
echo "NTP=$DHCP4_NTP_SERVERS"<br />
systemctl restart systemd-timesyncd<br />
;;<br />
down)<br />
rm -f /etc/systemd/timesyncd.conf.d/$CONNECTION_UUID.conf<br />
systemctl restart systemd-timesyncd<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
Make this script executable by root only with {{ic|chmod 700 10-update-timesync}}. Finally make sure NetworkManager dispatcher is enabled and started.<br />
<br />
So what happens here? Every time NetworkManager sets up a new network connection ({{ic|1=ACTION=up}}) or gets some update for an existing connection ({{ic|1=ACTION=dhcp4-change}} or {{ic|1=ACTION=dhcp6-change}}) and the provided connection data contains information about NTP server(s) ({{ic|DHCP4_NTP_SERVERS}}) then a connection specific overlay configuration file is written to {{ic|/etc/systemd/timesyncd.conf.d}} containing the provided NTP server(s). Whenever a connection is taken down ({{ic|1=ACTION=down}}) the connection specific overlay file is removed again. After each change to the configuration of systemd-timesyncd this service is restarted to pick up the updated configuration.The use of connection specific config files is intentional so that when two or more connections are managed by NetworkManager in parallel the different NTP server names in the config are not overwritten as {{ic|up}}, {{ic|dhcp4-change}}, {{ic|dhcp6-change}} and {{ic|down}} actions might come in in an arbitrary order.<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=182600 Forum: systemd-timesyncd is not syncing time]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=182172 Forum: Using systemd-timesync instead of NTP]<br />
* [https://github.com/systemd/systemd/blob/master/src/timesync/timesyncd.c Git Sourcecode of timesyncd]<br />
* {{man|8|systemd-timesyncd}}<br />
* {{man|5|timesyncd.conf}}</div>PXfhttps://wiki.archlinux.org/index.php?title=Map_scancodes_to_keycodes&diff=693119Map scancodes to keycodes2021-08-27T19:35:53Z<p>PXf: /* Using udev */ + man page link evemu-describe(1)</p>
<hr />
<div>[[Category:Keyboard configuration]]<br />
[[ja:スキャンコードをキーコードにマップ]]<br />
[[zh-hans:Map scancodes to keycodes]]<br />
This page assumes that you have read [[Keyboard input]], which provides wider context.<br />
<br />
Mapping ''scancodes'' to ''keycodes'' is achieved in a layer lower than Xorg and Linux console, which means that changes to this mapping will be effective in both. [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/input-event-codes.h#n64][https://elixir.bootlin.com/linux/latest/A/ident/hid_keyboard][https://elixir.bootlin.com/linux/latest/A/ident/atkbd_set2_keycode]<br />
<br />
There are two ways of mapping ''scancodes'' to ''keycodes'':<br />
* Using [[udev]]<br />
* Using {{man|8|setkeycodes}}<br />
<br />
The preferred method is to use ''udev'' because it uses hardware information (which is a quite reliable source) to choose the keyboard model in a database. It means that if your keyboard model has been found in the database, your keys are recognized ''out of the box''.<br />
<br />
== Identifying scancodes ==<br />
<br />
You need to know the ''scancodes'' of keys you wish to remap. See [[Keyboard input#Identifying scancodes]] for details.<br />
<br />
== Using udev ==<br />
<br />
[[udev]] provides a builtin function called ''hwdb'' to maintain the hardware database index in {{ic|/etc/udev/hwdb.bin}}. The database is compiled from files with ''.hwdb'' extension located in directories {{ic|/usr/lib/udev/hwdb.d/}}, {{ic|/run/udev/hwdb.d/}} and {{ic|/etc/udev/hwdb.d/}}. The default ''scancodes-to-keycodes'' mapping file is {{ic|/usr/lib/udev/hwdb.d/60-keyboard.hwdb}}. See {{man|7|hwdb}} for details.<br />
<br />
The ''.hwdb'' file can apply key mappings to one or more keyboards based on hardware ID glob patterns. You may obtain device identification info by running {{man|1|evemu-describe}} as the root user. This command is provided by the {{pkg|evemu}} package.<br />
<br />
The {{ic|evdev:}} prefix is used to match hardware against a block of mappings. The following hardware matches are supported:<br />
<br />
* Generic input devices (also USB keyboards) identified by the usb kernel modalias: {{bc|evdev:input:b''<bus_id>''v''<vendor_id>''p''<product_id>''e''<version_id>''-''<modalias>''}} where {{ic|''<vendor_id>''}}, {{ic|''<product_id>''}} and {{ic|''<version_id>''}} are the 4-digit hex uppercase vendor, product and version IDs (you can find those by running the {{ic|lsusb}} command) and {{ic|''<modalias>''}} is an arbitrary length input-modalias describing the device capabilities. {{ic|''<bus_id>''}} is the 4-digit hex bus id and should be 0003 for usb devices. The possible {{ic|''<bus_id>''}} values are defined in {{ic|/usr/include/linux/input.h}} (you can run {{ic|awk '/BUS_/ {print $2, $3}' /usr/include/linux/input.h}} to get a list).<br />
* AT keyboard DMI data matches: {{bc|evdev:atkbd:dmi:bvn*:bvr*:bd*:svn''<vendor>'':pn''<product>'':pvr*}} where {{ic|''<vendor>''}} and {{ic|''<product>''}} are the firmware-provided strings exported by the kernel DMI modalias.<br />
* Input driver device name and DMI data match: {{bc|evdev:name:''<input device name>'':dmi:bvn*:bvr*:bd*:svn''<vendor>'':pn*}} where {{ic|''<input_device_name>''}} is the name device specified by the driver and {{ic|''<vendor>''}} is the firmware-provided string exported by the kernel DMI modalias.<br />
<br />
The format of each line in the block body is {{ic|1=KEYBOARD_KEY_''<scancode>''=''<keycode>''}}. The value of {{ic|''<scancode>''}} is hexadecimal, but without the leading {{ic|0x}} (i.e. specify {{ic|a0}} instead of {{ic|0xa0}}), whereas the value of {{ic|''<keycode>''}} is the lower-case keycode name string as listed in {{ic|/usr/include/linux/input-event-codes.h}} (see the {{ic|KEY_''<KEYCODE>''}} variables), a sorted list is available at [https://hal.freedesktop.org/quirk/quirk-keymap-list.txt]. It is not possible to specify decimal value in {{ic|''<keycode>''}}.<br />
<br />
=== Example for custom hwdb ===<br />
<br />
The example hwdb file will match all AT keyboards:<br />
<br />
{{hc|/etc/udev/hwdb.d/90-custom-keyboard.hwdb|<nowiki><br />
evdev:atkbd:dmi:bvn*:bvr*:bd*:svn*:pn*:pvr*<br />
KEYBOARD_KEY_10=suspend<br />
KEYBOARD_KEY_a0=search<br />
</nowiki>}}<br />
<br />
Here is an example of rebinding modifiers on a laptop and USB keyboard:<br />
<br />
{{hc|/etc/udev/hwdb.d/10-my-modifiers.hwdb|<nowiki><br />
evdev:input:b0003v05AFp8277* # was tested on Kensington Slim Type USB (with old ABI)<br />
KEYBOARD_KEY_70039=leftalt # bind capslock to leftalt<br />
KEYBOARD_KEY_700e2=leftctrl # bind leftalt to leftctrl<br />
<br />
evdev:atkbd:dmi:* # built-in keyboard: match all AT keyboards for now<br />
KEYBOARD_KEY_3a=leftalt # bind capslock to leftalt<br />
KEYBOARD_KEY_38=leftctrl # bind leftalt to leftctrl<br />
</nowiki>}}<br />
<br />
To block the {{ic|Sleep}} key, bind it to the "reserved" keyword. Alternatively, you can use "unknown" to map it to the {{ic|NoSymbol}} key. For example:<br />
<br />
{{hc|/etc/udev/hwdb.d/90-block-sleep.hwdb|2=<br />
evdev:input:b0003v03F0p020C* # hp 5308 keyboard controller<br />
KEYBOARD_KEY_10082=reserved<br />
}}<br />
<br />
=== Updating the Hardware Database Index ===<br />
<br />
After changing the configuration files, the hardware database index, {{ic|hwdb.bin}}, needs to be rebuilt. <br />
<br />
* Update {{ic|hwdb.bin}} manually by running<br />
# systemd-hwdb update<br />
<br />
{{Out of date|{{ic|1=ConditionNeedsUpdate=/etc}} seems to be commented out by default in {{ic|systemd-hwdb-update.service}} (checked in {{pkg|systemd}} 232).}}<br />
{{Accuracy|Do not edit in {{ic|/usr/lib/}}, use [[Systemd#Editing_provided_units|systemctl edit]].}}<br />
<br />
* Update automatically on each reboot by commenting out {{ic|ConditionNeedsUpdate}} in {{ic|systemd-hwdb-update.service}}.<br />
<br />
{{hc|/usr/lib/systemd/system/systemd-hwdb-update.service|<nowiki><br />
# This file is part of systemd.<br />
.<br />
.<br />
#ConditionNeedsUpdate=/etc<br />
.<br />
.<br />
</nowiki>}}<br />
<br />
After {{ic|systemd-hwdb-update.service}} finished loading {{ic|systemd-trigger.service}} will reload the changes from <br />
{{ic|hwdb.bin}}.<br />
<br />
* Automatically after [[Systemd]] upgrade.<br />
<br />
On each upgrade of [[Systemd]], the installation script rebuilds {{ic|hwdb.bin}} by running {{ic|udevadm hwdb --update}} as the root user, so we do not need to care about it.<br />
<br />
=== Reloading the Hardware Database Index ===<br />
<br />
The kernel loads {{ic|hwdb.bin}} as part of the boot process, rebooting the system will promise the loading of the updated {{ic|hwdb.bin}}.<br />
<br />
With {{ic|udevadm}} it is possible to load new key mapping from the updated {{ic|hwdb.bin}} by running<br />
# udevadm trigger<br />
Be aware that with {{ic|udevadm}} only added or changed key mapping are loaded so if we delete a mapping from the config file, rebuild {{ic|hwdb.bin}} and run {{ic|udevadm trigger}} as the root user, then the deleted mapping still kept by the kernel, at least until a reboot.<br />
<br />
=== Querying the database ===<br />
<br />
You can check that your configuration was loaded either by pressing keys, or by running {{ic|udevadm info}}. For the USB keyboard in the above example, this outputs the mapping we configured as follows:<br />
<br />
# udevadm info /dev/input/by-path/*-usb-*-kbd | grep KEYBOARD_KEY<br />
E: KEYBOARD_KEY_70039=leftalt<br />
E: KEYBOARD_KEY_700e2=leftctrl<br />
<br />
== Using setkeycodes ==<br />
<br />
''setkeycodes'' is a tool to load ''scancodes''-to-''keycodes'' mapping table into Linux kernel. Its usage is:<br />
<br />
# setkeycodes ''scancode'' ''keycode'' ...<br />
<br />
It is possible to specify multiple pairs at once. ''Scancodes'' are given in hexadecimal, ''keycodes'' in decimal.<br />
<br />
{{Note|Apparently ''setkeycodes'' does not work with USB keyboards (Linux 3.14.44-1-lts):<br />
<br />
# setkeycodes 45 30 # bind NumLock (0x45) to KEY_A (30) on AT keyboard<br />
(successful)<br />
# setkeycodes 70053 30 # bind NumLock (0x70053) to KEY_A (30) on USB keyboard<br />
KDSETKEYCODE: Invalid argument<br />
failed to set scancode 620d3 to keycode 31<br />
}}</div>PXfhttps://wiki.archlinux.org/index.php?title=Archiso&diff=692981Archiso2021-08-26T10:44:02Z<p>PXf: dedup</p>
<hr />
<div>[[Category:Live Arch systems]]<br />
[[Category:Installation process]]<br />
[[Category:Arch projects]]<br />
[[ar:Archiso]]<br />
[[el:Archiso]]<br />
[[es:Archiso]]<br />
[[fr:Archiso]]<br />
[[it:Archiso]]<br />
[[ja:Archiso]]<br />
[[nl:Archiso]]<br />
[[pt:Archiso]]<br />
[[ru:Archiso]]<br />
[[sk:Archiso]]<br />
[[zh-hans:Archiso]]<br />
{{Related articles start}}<br />
{{Related|Archiso as pxe server}}<br />
{{Related|Archboot}}<br />
{{Related|Offline installation}}<br />
{{Related articles end}} <br />
[https://gitlab.archlinux.org/archlinux/archiso Archiso] is a highly-customizable tool for building Arch Linux live CD/USB ISO images. The [https://archlinux.org/download/ official images] are built with Archiso. It can be used as the basis for rescue systems, linux installers or other systems. This wiki article explains how to install Archiso, and how to configure it to control aspects of the resulting ISO image such as included packages and files. Technical requirements and build steps can be found in the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs official project documentation]. Archiso is implemented with a number of bash scripts. The core component of Archiso is the ''mkarchiso'' command. Its options are documented in ''mkarchiso -h'' and not covered here.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package.<br />
<br />
== Prepare a custom profile ==<br />
<br />
Archiso comes with two profiles, '''releng''' and '''baseline'''.<br />
<br />
* '''releng''' is used to create the official monthly installation ISO. It can be used as a starting point for creating a customized ISO image.<br />
* '''baseline''' is a minimalistic configuration, that includes only the bare minimum packages required to boot the live environment from the medium.<br />
<br />
To build an unmodified version of the profiles, skip to [[#Build the ISO]]. Otherwise, if you wish to adapt or customize one of archiso's shipped profiles, copy it from {{ic|/usr/share/archiso/configs/''profile-name''/}} to a writable directory with a name of your choice. For example:<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile''/ ''archlive''<br />
<br />
Proceed to the following sections to customize and build the custom profile.<br />
<br />
=== Profile structure ===<br />
<br />
An archiso profile contains configuration that defines the resulting ISO image. The profile structure is documented in {{ic|/usr/share/doc/archiso/README.profile.rst}}[https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst].<br />
<br />
=== Selecting packages ===<br />
<br />
Edit {{ic|packages.x86_64}} to select which packages are to be installed on the live system image, listing packages line by line.<br />
<br />
==== Custom local repository ====<br />
<br />
To add packages not located in standard Arch repositories (e.g. custom packages or packages from [[AUR]]/[[ABS]]), set up a [[custom local repository]] and add your custom packages to it. Then add your repository to {{ic|pacman.conf}} as follows: <br />
<br />
{{hc|''archlive''/pacman.conf|2=<br />
...<br />
[''customrepo'']<br />
SigLevel = Optional TrustAll<br />
Server = file://''/path/to/customrepo''<br />
...<br />
}}<br />
<br />
{{Note|The ordering within {{ic|pacman.conf}} matters. To give top priority to your custom repository, place it above the other repository entries.}}<br />
<br />
==== Packages from multilib ====<br />
<br />
To install packages from the [[multilib]] repository, simply uncomment that repository in {{ic|pacman.conf}}.<br />
<br />
=== Adding files to image ===<br />
<br />
The airootfs directory is used as the starting point for the [[Wikipedia:Root directory|root directory]] ({{ic|/}}) of the live system on the image. All its contents will be copied over to the working directory before packages are installed.<br />
<br />
Place any custom files and/or directories in the desired location under {{ic|airootfs/}}. For example, if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:<br />
<br />
$ cp -r /etc/iptables ''archlive''/airootfs/etc<br />
<br />
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. Missing parts of the directory structure can be simply created with {{man|1|mkdir}}.<br />
<br />
{{Tip|To add a file to the install user's home directory, place it in {{ic|''archlive''/airootfs/root/}}. To add a file to all other users home directories, place it in {{ic|''archlive''/airootfs/etc/skel/}}.}}<br />
<br />
{{Note|Custom files that conflict with those provided by packages will be overwritten unless a package specifies them as [[pacman/Pacnew and Pacsave#Package backup files|backup files]].}}<br />
<br />
By default, [[permissions]] will be {{ic|644}} for files and {{ic|755}} for directories. All of them will be owned by the root user. To set different permissions or ownership for specific files and/or folders, use the {{ic|file_permissions}} associative array in {{ic|profiledef.sh}}. See [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst README.profile.rst] for details.<br />
<br />
=== Kernel ===<br />
<br />
Although both archiso's included profiles only have {{Pkg|linux}}, ISOs can be made to include other or even multiple [[kernels]].<br />
<br />
First, edit {{ic|packages.x86_64}} to include kernel package names that you want. When ''mkarchiso'' runs, it will include all {{ic|''work_dir''/airootfs/boot/vmlinuz-*}} and {{ic|''work_dir''/boot/initramfs-*.img}} files in the ISO (and additionally in the FAT image used for UEFI booting).<br />
<br />
[[mkinitcpio]] presets by default will build fallback initramfs images. For an ISO, the main initramfs image would not typically include the {{ic|autodetect}} hook, thus making an additional fallback image unnecessary. To prevent the creation of an fallback initramfs image, so that it does not take up space or slow down the build process, place a custom preset in {{ic|''archlive''/airootfs/etc/mkinitcpio.d/''pkgbase''.preset}}. For example, for {{Pkg|linux-lts}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/mkinitcpio.d/linux-lts.preset|2=<br />
PRESETS=('archiso')<br />
<br />
ALL_kver='/boot/vmlinuz-linux-lts'<br />
ALL_config='/etc/mkinitcpio.conf'<br />
<br />
archiso_image="/boot/initramfs-linux-lts.img"<br />
}}<br />
<br />
Finally create [[#Boot loader|boot loader configuration]] to allow booting the kernel(s).<br />
<br />
=== Boot loader ===<br />
<br />
Archiso supports [[syslinux]] for BIOS booting and [[systemd-boot]] for UEFI booting. Refer to the articles of the boot loaders for information on their configuration syntax.<br />
<br />
{{Tip|1=<nowiki></nowiki><br />
* The '''releng''' profile by default builds into an ISO that supports both BIOS and UEFI booting when burned to an optical disc using El Torito, or when written to a hard disk (or USB flash drive, or similar) using [https://wiki.syslinux.org/wiki/index.php?title=Isohybrid Isohybrid].<br />
* Due to the modular nature of isolinux, you are able to use lots of addons since all ''.c32'' files are copied and available to you. Take a look at the [https://wiki.syslinux.org/wiki/index.php/SYSLINUX official syslinux site] and the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/configs/releng/syslinux archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [https://wiki.syslinux.org/wiki/index.php/Comboot/menu.c32].<br />
}}<br />
<br />
mkarchiso expects that [[systemd-boot]] configuration is in the {{ic|efiboot}} directory, and [[syslinux]] configuration in {{ic|syslinux}} and {{ic|isolinux}} directories.<br />
<br />
==== UEFI Secure Boot ====<br />
<br />
If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed boot loader. You can follow the instructions on [[Secure Boot#Booting an installation medium]].<br />
<br />
=== systemd units ===<br />
<br />
To [[enable]] systemd services/sockets/timers for the live environment, you need to manually create the symbolic links just as {{ic|systemctl enable}} does it.<br />
<br />
For example, to enable {{ic|gpm.service}}, which contains {{ic|1=WantedBy=multi-user.target}}, run:<br />
<br />
$ mkdir -p ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants<br />
$ ln -s /usr/lib/systemd/system/gpm.service ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants/<br />
<br />
The required symlinks can be found out by reading the systemd unit, or if you have the service installed, by [[enabling]] it and observing the systemctl output.<br />
<br />
==== Login manager ====<br />
<br />
Starting X at boot is done by enabling your login manager's [[systemd]] service. If you do not know which ''.service'' enable, you can easily find out in case you are using the same program on the system you build your ISO on. Just use:<br />
<br />
$ ls -l /etc/systemd/system/display-manager.service<br />
<br />
Now create the same symlink in {{ic|''archlive''/airootfs/etc/systemd/system/}}. For LXDM:<br />
<br />
$ ln -s /usr/lib/systemd/system/lxdm.service ''archlive''/airootfs/etc/systemd/system/display-manager.service<br />
<br />
This will enable LXDM at system start on your live system.<br />
<br />
==== Changing automatic login ====<br />
<br />
The configuration for getty's automatic login is located under {{ic|airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf}}.<br />
<br />
You can modify this file to change the auto login user:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty --autologin '''''username''''' --noclear %I 38400 linux<br />
<br />
Or remove it altogether to disable auto login.<br />
<br />
=== Users and passwords ===<br />
<br />
To create a [[user]] which will be available in the live environment, you must manually edit {{ic|''archlive''/airootfs/etc/passwd}}, {{ic|''archlive''/airootfs/etc/shadow}}, {{ic|''archlive''/airootfs/etc/group}} and {{ic|''archlive''/airootfs/etc/gshadow}}.<br />
<br />
{{Note|If these files exist, they must contain the root user and group.}}<br />
<br />
For example, to add a user {{ic|archie}}. Add them to {{ic|''archlive''/airootfs/etc/passwd}} following the {{man|5|passwd}} syntax:<br />
<br />
{{hc|''archlive''/airootfs/etc/passwd|<br />
root:x:0:0:root:/root:/usr/bin/zsh<br />
archie:x:1000:1000::/home/archie:/usr/bin/zsh<br />
}}<br />
<br />
Generate a password hash with {{ic|openssl passwd -6}} and add it to {{ic|''archlive''/airootfs/etc/shadow}} following the syntax of {{man|5|shadow}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/shadow|2=<br />
root::14871::::::<br />
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::<br />
}}<br />
<br />
Add the user's group and the groups which they will part of to {{ic|''archlive''/airootfs/etc/group}} according to {{man|5|group}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/group|2=<br />
root:x:0:root<br />
adm:x:4:archie<br />
wheel:x:10:archie<br />
uucp:x:14:archie<br />
archie:x:1000:<br />
}}<br />
<br />
Create the appropriate {{ic|''archlive''/airootfs/etc/gshadow}} according to {{man|5|gshadow}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/gshadow|2=<br />
root:!*::root<br />
archie:!*::<br />
}}<br />
<br />
Make sure {{ic|/etc/shadow}} and {{ic|/etc/gshadow}} have the correct permissions:<br />
<br />
{{hc|''archlive''/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/etc/shadow"]="0:0:0400"<br />
["/etc/gshadow"]="0:0:0400"<br />
)<br />
}}<br />
<br />
After package installation, ''mkarchiso'' will create all specified home directories for users listed in {{ic|''archlive''/airootfs/etc/passwd}} and copy {{ic|''work_directory''/x86_64/airootfs/etc/skel/*}} to them. The copied files will have proper user and group ownership.<br />
<br />
== Build the ISO ==<br />
<br />
Build an ISO which you can then burn to CD or USB by running:<br />
<br />
# mkarchiso -v -w ''/path/to/work_dir'' -o ''/path/to/out_dir'' ''/path/to/profile/''<br />
<br />
* {{ic|-w}} specifies the working directory. If the option is not specified, it will default to {{ic|work}} in the current directory.<br />
* {{ic|-o}} specifies the directory where the built ISO image will be placed. If the option is not specified, it will default to {{ic|out}} in the current directory.<br />
* It should be noted the profile file {{ic|profiledef.sh}} cannot be specified when running mkarchiso, only the path to the file<br />
<br />
Replace {{ic|''/path/to/profile/''}} with the path to your custom profile, or with {{ic|/usr/share/archiso/configs/releng/}} if you are building an unmodified profile.<br />
<br />
{{Tip|If memory allows, it is preferred to place the working directory on [[tmpfs]]. E.g.:<br />
<br />
# mkarchiso -v -w /tmp/archiso-tmp ''/path/to/profile/''<br />
<br />
}}<br />
<br />
When run, the script will download and install the packages you specified to {{ic|''work_directory''/x86_64/airootfs}}, create the kernel and init images, apply your customizations and finally build the ISO into the output directory.<br />
<br />
=== Removal of work directory ===<br />
<br />
{{Warning|If ''mkarchiso'' is interrupted, run {{man|8|findmnt}} to make sure there are no mount binds before deleting it - otherwise, '''you may lose data''' (e.g. an external device mounted at {{ic|/run/media/''user''/''label''}} gets bound within {{ic|work/x86_64/airootfs/run/media/''user''/''label''}} during the build process).}}<br />
<br />
The temporary files are copied into work directory. After successfully building the ISO , the work directory and its contents can be deleted. E.g.:<br />
<br />
# rm -rf ''/path/to/work_dir''<br />
<br />
== Using the ISO ==<br />
<br />
See [[Installation guide#Prepare an installation medium]] for various options.<br />
<br />
== Test the ISO in QEMU ==<br />
<br />
[[Install]] the optional dependencies {{pkg|qemu}} and {{pkg|edk2-ovmf}}.<br />
<br />
Use the convenience script {{ic|run_archiso}} to run a built image using [[QEMU]].<br />
<br />
$ run_archiso -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
The virtual machine can also be run using UEFI emulation:<br />
<br />
$ run_archiso -u -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
== Tips and tricks ==<br />
<br />
=== Prepare an ISO for an installation via SSH ===<br />
<br />
{{Remove|Since {{ic|archlinux-2021.02.01-x86_64.iso}}, there is [[cloud-init]] support and {{ic|sshd.service}} is enabled by default. [[Install Arch Linux via SSH#Installation on a headless server]] is updated to reflect the changes..}}<br />
<br />
To [[install Arch Linux via SSH]] without any interaction with the system, the installation ISO must have {{Pkg|openssh}} installed, {{ic|sshd.service}} enabled and a public SSH key must be placed in {{ic|authorized_keys}}.<br />
<br />
Adding the SSH key can either be done manually (explained here), or by using [[cloud-init]].<br />
<br />
First [[#Prepare a custom profile|copy Archiso's releng profile]] to writable directory. The following examples will use {{ic|archlive}}.<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile/'' archlive<br />
<br />
As described in [[#systemd units]], systemd services in the live environment are enabled by creating the correct symbolic links. Use the following commands to enable {{ic|sshd.service}} so that it gets started when the live environment boots:<br />
<br />
$ mkdir -p archlive/airootfs/etc/systemd/system/multi-user.target.wants<br />
$ ln -s /usr/lib/systemd/system/sshd.service archlive/airootfs/etc/systemd/system/multi-user.target.wants/<br />
<br />
Create a {{ic|.ssh}} directory in the home directory of the user which will be used to log in. The following examples will be using the root user.<br />
<br />
$ mkdir archlive/airootfs/root/.ssh<br />
<br />
Add the public SSH key(s), which will be used to log in, to {{ic|authorized_keys}}:<br />
<br />
$ cat ~/.ssh/id_ed25519.pub >> archlive/airootfs/root/.ssh/authorized_keys<br />
<br />
Set the correct [[permissions]] and ownership for the {{ic|.ssh}} directory and the {{ic|authorized_keys}} file:<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/root"]="0:0:0750"<br />
["/root/.ssh"]="0:0:0700"<br />
["/root/.ssh/authorized_keys"]="0:0:0600"<br />
)<br />
}}<br />
<br />
Finally [[#Build the ISO|build the ISO]]. Upon booting the ISO, [[OpenSSH]] will start and it will be possible to log in using the SSH key.<br />
<br />
=== Automatically connect to a Wi-Fi network using iwd ===<br />
<br />
Create {{ic|/var/lib/iwd/}} inside the profile's {{ic|airootfs}} directory and set the correct permissions:<br />
<br />
$ mkdir -p ''archlive''/airootfs/var/lib/iwd<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/var/lib/iwd"]="0:0:0700"<br />
)<br />
}}<br />
<br />
Follow the instructions in [[iwd#Network configuration]] and {{man|5|iwd.network}} to create a network configuration file for your Wi-Fi network.<br />
<br />
Save the configuration file inside {{ic|''archlive''/airootfs/var/lib/iwd/}}.<br />
<br />
=== Adjusting the size of root partition on the fly ===<br />
<br />
<!-- {{Accuracy|Explaining ''how'' but omitting the ''why'' renders the whole section useless.}} --><br />
<br />
If you get the following error message when downloading files or installing packages in the booted ISO environment, you may need to shutdown and adjust the size of the root partition while booting the Archiso again.<br />
<br />
error: partition / too full: 63256 blocks needed, 61450 blocks free<br />
error: not enough free disk space<br />
error: failed to commit transaction (not enough free disk space) <br />
Errors occurred: no packages were upgraded.<br />
<br />
To adjust the size of the root partition on the live Archlinux system, hit the TAB key to edit the kernel parameters.<br />
Append {{ic|1=cow_spacesize=2G}} at the end to get 2G size for the root partition.<br />
Press Enter to continue booting into the live system.<br />
You can check the size of the filesystems by running:<br />
$ df -h<br />
<br />
You can also adjust the root partition size on the fly by running this command:<br />
# mount -o remount,size=2G /run/archiso/cowspace<br />
<br />
See more boot parameters [https://gitlab.archlinux.org/mkinitcpio/mkinitcpio-archiso/blob/master/docs/README.bootparams here]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Window manager freezes ===<br />
<br />
If you want to use a [[window manager]] in the Live CD then you must add the necessary and correct [[video drivers]], or the WM may freeze on loading.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.archlinux.org/archlinux/archiso Archiso project page]<br />
* [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs Official documentation]<br />
* [https://lists.archlinux.org/listinfo/arch-releng Arch Linux Release Engineering mailing list]<br />
* [ircs://irc.libera.chat/archlinux-releng #archlinux-releng — Arch Linux Release Engineering IRC channel]<br />
* [https://github.com/pierres/archiso-manager archiso-manager — the tool used for building the official monthly ISOs]</div>PXfhttps://wiki.archlinux.org/index.php?title=Archiso&diff=692980Archiso2021-08-26T10:37:37Z<p>PXf: /* Adjusting the size of root partition on the fly */ add the "why" part</p>
<hr />
<div>[[Category:Live Arch systems]]<br />
[[Category:Installation process]]<br />
[[Category:Arch projects]]<br />
[[ar:Archiso]]<br />
[[el:Archiso]]<br />
[[es:Archiso]]<br />
[[fr:Archiso]]<br />
[[it:Archiso]]<br />
[[ja:Archiso]]<br />
[[nl:Archiso]]<br />
[[pt:Archiso]]<br />
[[ru:Archiso]]<br />
[[sk:Archiso]]<br />
[[zh-hans:Archiso]]<br />
{{Related articles start}}<br />
{{Related|Archiso as pxe server}}<br />
{{Related|Archboot}}<br />
{{Related|Offline installation}}<br />
{{Related articles end}} <br />
[https://gitlab.archlinux.org/archlinux/archiso Archiso] is a tool for building Arch Linux live CD ISO images. The [https://archlinux.org/download/ official images] are built with Archiso. Archiso is configurable and can be used as the basis for different systems, for example rescue systems, or linux installers. This wiki article explains how to install Archiso, and how to configure it to control aspects of the resulting ISO image such as included packages and files. Technical requirements and build steps can be found in the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs official project documentation]. Archiso is implemented with a number of bash scripts. The core component of Archiso is the ''mkarchiso'' command. Its options are documented in its usage output and not covered here.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package.<br />
<br />
== Prepare a custom profile ==<br />
<br />
Archiso comes with two profiles, '''releng''' and '''baseline'''.<br />
<br />
* '''releng''' is used to create the official monthly installation ISO. It can be used as a starting point for creating a customized ISO image.<br />
* '''baseline''' is a minimalistic configuration, that includes only the bare minimum packages required to boot the live environment from the medium.<br />
<br />
To build an unmodified version of the profiles, skip to [[#Build the ISO]]. Otherwise, if you wish to adapt or customize one of archiso's shipped profiles, copy it from {{ic|/usr/share/archiso/configs/''profile-name''/}} to a writable directory with a name of your choice. For example:<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile''/ ''archlive''<br />
<br />
Proceed to the following sections to customize and build the custom profile.<br />
<br />
=== Profile structure ===<br />
<br />
An archiso profile contains configuration that defines the resulting ISO image. The profile structure is documented in {{ic|/usr/share/doc/archiso/README.profile.rst}}[https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst].<br />
<br />
=== Selecting packages ===<br />
<br />
Edit {{ic|packages.x86_64}} to select which packages are to be installed on the live system image, listing packages line by line.<br />
<br />
==== Custom local repository ====<br />
<br />
To add packages not located in standard Arch repositories (e.g. custom packages or packages from [[AUR]]/[[ABS]]), set up a [[custom local repository]] and add your custom packages to it. Then add your repository to {{ic|pacman.conf}} as follows: <br />
<br />
{{hc|''archlive''/pacman.conf|2=<br />
...<br />
[''customrepo'']<br />
SigLevel = Optional TrustAll<br />
Server = file://''/path/to/customrepo''<br />
...<br />
}}<br />
<br />
{{Note|The ordering within {{ic|pacman.conf}} matters. To give top priority to your custom repository, place it above the other repository entries.}}<br />
<br />
==== Packages from multilib ====<br />
<br />
To install packages from the [[multilib]] repository, simply uncomment that repository in {{ic|pacman.conf}}.<br />
<br />
=== Adding files to image ===<br />
<br />
The airootfs directory is used as the starting point for the [[Wikipedia:Root directory|root directory]] ({{ic|/}}) of the live system on the image. All its contents will be copied over to the working directory before packages are installed.<br />
<br />
Place any custom files and/or directories in the desired location under {{ic|airootfs/}}. For example, if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:<br />
<br />
$ cp -r /etc/iptables ''archlive''/airootfs/etc<br />
<br />
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. Missing parts of the directory structure can be simply created with {{man|1|mkdir}}.<br />
<br />
{{Tip|To add a file to the install user's home directory, place it in {{ic|''archlive''/airootfs/root/}}. To add a file to all other users home directories, place it in {{ic|''archlive''/airootfs/etc/skel/}}.}}<br />
<br />
{{Note|Custom files that conflict with those provided by packages will be overwritten unless a package specifies them as [[pacman/Pacnew and Pacsave#Package backup files|backup files]].}}<br />
<br />
By default, [[permissions]] will be {{ic|644}} for files and {{ic|755}} for directories. All of them will be owned by the root user. To set different permissions or ownership for specific files and/or folders, use the {{ic|file_permissions}} associative array in {{ic|profiledef.sh}}. See [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.profile.rst README.profile.rst] for details.<br />
<br />
=== Kernel ===<br />
<br />
Although both archiso's included profiles only have {{Pkg|linux}}, ISOs can be made to include other or even multiple [[kernels]].<br />
<br />
First, edit {{ic|packages.x86_64}} to include kernel package names that you want. When ''mkarchiso'' runs, it will include all {{ic|''work_dir''/airootfs/boot/vmlinuz-*}} and {{ic|''work_dir''/boot/initramfs-*.img}} files in the ISO (and additionally in the FAT image used for UEFI booting).<br />
<br />
[[mkinitcpio]] presets by default will build fallback initramfs images. For an ISO, the main initramfs image would not typically include the {{ic|autodetect}} hook, thus making an additional fallback image unnecessary. To prevent the creation of an fallback initramfs image, so that it does not take up space or slow down the build process, place a custom preset in {{ic|''archlive''/airootfs/etc/mkinitcpio.d/''pkgbase''.preset}}. For example, for {{Pkg|linux-lts}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/mkinitcpio.d/linux-lts.preset|2=<br />
PRESETS=('archiso')<br />
<br />
ALL_kver='/boot/vmlinuz-linux-lts'<br />
ALL_config='/etc/mkinitcpio.conf'<br />
<br />
archiso_image="/boot/initramfs-linux-lts.img"<br />
}}<br />
<br />
Finally create [[#Boot loader|boot loader configuration]] to allow booting the kernel(s).<br />
<br />
=== Boot loader ===<br />
<br />
Archiso supports [[syslinux]] for BIOS booting and [[systemd-boot]] for UEFI booting. Refer to the articles of the boot loaders for information on their configuration syntax.<br />
<br />
{{Tip|1=<nowiki></nowiki><br />
* The '''releng''' profile by default builds into an ISO that supports both BIOS and UEFI booting when burned to an optical disc using El Torito, or when written to a hard disk (or USB flash drive, or similar) using [https://wiki.syslinux.org/wiki/index.php?title=Isohybrid Isohybrid].<br />
* Due to the modular nature of isolinux, you are able to use lots of addons since all ''.c32'' files are copied and available to you. Take a look at the [https://wiki.syslinux.org/wiki/index.php/SYSLINUX official syslinux site] and the [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/configs/releng/syslinux archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [https://wiki.syslinux.org/wiki/index.php/Comboot/menu.c32].<br />
}}<br />
<br />
mkarchiso expects that [[systemd-boot]] configuration is in the {{ic|efiboot}} directory, and [[syslinux]] configuration in {{ic|syslinux}} and {{ic|isolinux}} directories.<br />
<br />
==== UEFI Secure Boot ====<br />
<br />
If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed boot loader. You can follow the instructions on [[Secure Boot#Booting an installation medium]].<br />
<br />
=== systemd units ===<br />
<br />
To [[enable]] systemd services/sockets/timers for the live environment, you need to manually create the symbolic links just as {{ic|systemctl enable}} does it.<br />
<br />
For example, to enable {{ic|gpm.service}}, which contains {{ic|1=WantedBy=multi-user.target}}, run:<br />
<br />
$ mkdir -p ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants<br />
$ ln -s /usr/lib/systemd/system/gpm.service ''archlive''/airootfs/etc/systemd/system/multi-user.target.wants/<br />
<br />
The required symlinks can be found out by reading the systemd unit, or if you have the service installed, by [[enabling]] it and observing the systemctl output.<br />
<br />
==== Login manager ====<br />
<br />
Starting X at boot is done by enabling your login manager's [[systemd]] service. If you do not know which ''.service'' enable, you can easily find out in case you are using the same program on the system you build your ISO on. Just use:<br />
<br />
$ ls -l /etc/systemd/system/display-manager.service<br />
<br />
Now create the same symlink in {{ic|''archlive''/airootfs/etc/systemd/system/}}. For LXDM:<br />
<br />
$ ln -s /usr/lib/systemd/system/lxdm.service ''archlive''/airootfs/etc/systemd/system/display-manager.service<br />
<br />
This will enable LXDM at system start on your live system.<br />
<br />
==== Changing automatic login ====<br />
<br />
The configuration for getty's automatic login is located under {{ic|airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf}}.<br />
<br />
You can modify this file to change the auto login user:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty --autologin '''''username''''' --noclear %I 38400 linux<br />
<br />
Or remove it altogether to disable auto login.<br />
<br />
=== Users and passwords ===<br />
<br />
To create a [[user]] which will be available in the live environment, you must manually edit {{ic|''archlive''/airootfs/etc/passwd}}, {{ic|''archlive''/airootfs/etc/shadow}}, {{ic|''archlive''/airootfs/etc/group}} and {{ic|''archlive''/airootfs/etc/gshadow}}.<br />
<br />
{{Note|If these files exist, they must contain the root user and group.}}<br />
<br />
For example, to add a user {{ic|archie}}. Add them to {{ic|''archlive''/airootfs/etc/passwd}} following the {{man|5|passwd}} syntax:<br />
<br />
{{hc|''archlive''/airootfs/etc/passwd|<br />
root:x:0:0:root:/root:/usr/bin/zsh<br />
archie:x:1000:1000::/home/archie:/usr/bin/zsh<br />
}}<br />
<br />
Generate a password hash with {{ic|openssl passwd -6}} and add it to {{ic|''archlive''/airootfs/etc/shadow}} following the syntax of {{man|5|shadow}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/shadow|2=<br />
root::14871::::::<br />
archie:$6$randomsalt$cij4/pJREFQV/NgAgh9YyBIoCRRNq2jp5l8lbnE5aLggJnzIRmNVlogAg8N6hEEecLwXHtMQIl2NX2HlDqhCU1:14871::::::<br />
}}<br />
<br />
Add the user's group and the groups which they will part of to {{ic|''archlive''/airootfs/etc/group}} according to {{man|5|group}}. For example:<br />
<br />
{{hc|''archlive''/airootfs/etc/group|2=<br />
root:x:0:root<br />
adm:x:4:archie<br />
wheel:x:10:archie<br />
uucp:x:14:archie<br />
archie:x:1000:<br />
}}<br />
<br />
Create the appropriate {{ic|''archlive''/airootfs/etc/gshadow}} according to {{man|5|gshadow}}:<br />
<br />
{{hc|''archlive''/airootfs/etc/gshadow|2=<br />
root:!*::root<br />
archie:!*::<br />
}}<br />
<br />
Make sure {{ic|/etc/shadow}} and {{ic|/etc/gshadow}} have the correct permissions:<br />
<br />
{{hc|''archlive''/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/etc/shadow"]="0:0:0400"<br />
["/etc/gshadow"]="0:0:0400"<br />
)<br />
}}<br />
<br />
After package installation, ''mkarchiso'' will create all specified home directories for users listed in {{ic|''archlive''/airootfs/etc/passwd}} and copy {{ic|''work_directory''/x86_64/airootfs/etc/skel/*}} to them. The copied files will have proper user and group ownership.<br />
<br />
== Build the ISO ==<br />
<br />
Build an ISO which you can then burn to CD or USB by running:<br />
<br />
# mkarchiso -v -w ''/path/to/work_dir'' -o ''/path/to/out_dir'' ''/path/to/profile/''<br />
<br />
* {{ic|-w}} specifies the working directory. If the option is not specified, it will default to {{ic|work}} in the current directory.<br />
* {{ic|-o}} specifies the directory where the built ISO image will be placed. If the option is not specified, it will default to {{ic|out}} in the current directory.<br />
* It should be noted the profile file {{ic|profiledef.sh}} cannot be specified when running mkarchiso, only the path to the file<br />
<br />
Replace {{ic|''/path/to/profile/''}} with the path to your custom profile, or with {{ic|/usr/share/archiso/configs/releng/}} if you are building an unmodified profile.<br />
<br />
{{Tip|If memory allows, it is preferred to place the working directory on [[tmpfs]]. E.g.:<br />
<br />
# mkarchiso -v -w /tmp/archiso-tmp ''/path/to/profile/''<br />
<br />
}}<br />
<br />
When run, the script will download and install the packages you specified to {{ic|''work_directory''/x86_64/airootfs}}, create the kernel and init images, apply your customizations and finally build the ISO into the output directory.<br />
<br />
=== Removal of work directory ===<br />
<br />
{{Warning|If ''mkarchiso'' is interrupted, run {{man|8|findmnt}} to make sure there are no mount binds before deleting it - otherwise, '''you may lose data''' (e.g. an external device mounted at {{ic|/run/media/''user''/''label''}} gets bound within {{ic|work/x86_64/airootfs/run/media/''user''/''label''}} during the build process).}}<br />
<br />
The temporary files are copied into work directory. After successfully building the ISO , the work directory and its contents can be deleted. E.g.:<br />
<br />
# rm -rf ''/path/to/work_dir''<br />
<br />
== Using the ISO ==<br />
<br />
See [[Installation guide#Prepare an installation medium]] for various options.<br />
<br />
== Test the ISO in QEMU ==<br />
<br />
[[Install]] the optional dependencies {{pkg|qemu}} and {{pkg|edk2-ovmf}}.<br />
<br />
Use the convenience script {{ic|run_archiso}} to run a built image using [[QEMU]].<br />
<br />
$ run_archiso -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
The virtual machine can also be run using UEFI emulation:<br />
<br />
$ run_archiso -u -i ''/path/to/''archlinux-''yyyy.mm.dd''-x86_64.iso<br />
<br />
== Tips and tricks ==<br />
<br />
=== Prepare an ISO for an installation via SSH ===<br />
<br />
{{Remove|Since {{ic|archlinux-2021.02.01-x86_64.iso}}, there is [[cloud-init]] support and {{ic|sshd.service}} is enabled by default. [[Install Arch Linux via SSH#Installation on a headless server]] is updated to reflect the changes..}}<br />
<br />
To [[install Arch Linux via SSH]] without any interaction with the system, the installation ISO must have {{Pkg|openssh}} installed, {{ic|sshd.service}} enabled and a public SSH key must be placed in {{ic|authorized_keys}}.<br />
<br />
Adding the SSH key can either be done manually (explained here), or by using [[cloud-init]].<br />
<br />
First [[#Prepare a custom profile|copy Archiso's releng profile]] to writable directory. The following examples will use {{ic|archlive}}.<br />
<br />
$ cp -r /usr/share/archiso/configs/''profile/'' archlive<br />
<br />
As described in [[#systemd units]], systemd services in the live environment are enabled by creating the correct symbolic links. Use the following commands to enable {{ic|sshd.service}} so that it gets started when the live environment boots:<br />
<br />
$ mkdir -p archlive/airootfs/etc/systemd/system/multi-user.target.wants<br />
$ ln -s /usr/lib/systemd/system/sshd.service archlive/airootfs/etc/systemd/system/multi-user.target.wants/<br />
<br />
Create a {{ic|.ssh}} directory in the home directory of the user which will be used to log in. The following examples will be using the root user.<br />
<br />
$ mkdir archlive/airootfs/root/.ssh<br />
<br />
Add the public SSH key(s), which will be used to log in, to {{ic|authorized_keys}}:<br />
<br />
$ cat ~/.ssh/id_ed25519.pub >> archlive/airootfs/root/.ssh/authorized_keys<br />
<br />
Set the correct [[permissions]] and ownership for the {{ic|.ssh}} directory and the {{ic|authorized_keys}} file:<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/root"]="0:0:0750"<br />
["/root/.ssh"]="0:0:0700"<br />
["/root/.ssh/authorized_keys"]="0:0:0600"<br />
)<br />
}}<br />
<br />
Finally [[#Build the ISO|build the ISO]]. Upon booting the ISO, [[OpenSSH]] will start and it will be possible to log in using the SSH key.<br />
<br />
=== Automatically connect to a Wi-Fi network using iwd ===<br />
<br />
Create {{ic|/var/lib/iwd/}} inside the profile's {{ic|airootfs}} directory and set the correct permissions:<br />
<br />
$ mkdir -p ''archlive''/airootfs/var/lib/iwd<br />
<br />
{{hc|archlive/profiledef.sh|2=<br />
...<br />
file_permissions=(<br />
...<br />
["/var/lib/iwd"]="0:0:0700"<br />
)<br />
}}<br />
<br />
Follow the instructions in [[iwd#Network configuration]] and {{man|5|iwd.network}} to create a network configuration file for your Wi-Fi network.<br />
<br />
Save the configuration file inside {{ic|''archlive''/airootfs/var/lib/iwd/}}.<br />
<br />
=== Adjusting the size of root partition on the fly ===<br />
<br />
<!-- {{Accuracy|Explaining ''how'' but omitting the ''why'' renders the whole section useless.}} --><br />
<br />
If you get the following error message when downloading files or installing packages in the booted ISO environment, you may need to shutdown and adjust the size of the root partition while booting the Archiso again.<br />
<br />
error: partition / too full: 63256 blocks needed, 61450 blocks free<br />
error: not enough free disk space<br />
error: failed to commit transaction (not enough free disk space) <br />
Errors occurred: no packages were upgraded.<br />
<br />
To adjust the size of the root partition on the live Archlinux system, hit the TAB key to edit the kernel parameters.<br />
Append {{ic|1=cow_spacesize=2G}} at the end to get 2G size for the root partition.<br />
Press Enter to continue booting into the live system.<br />
You can check the size of the filesystems by running:<br />
$ df -h<br />
<br />
You can also adjust the root partition size on the fly by running this command:<br />
# mount -o remount,size=2G /run/archiso/cowspace<br />
<br />
See more boot parameters [https://gitlab.archlinux.org/mkinitcpio/mkinitcpio-archiso/blob/master/docs/README.bootparams here]<br />
<br />
== Troubleshooting ==<br />
<br />
=== Window manager freezes ===<br />
<br />
If you want to use a [[window manager]] in the Live CD then you must add the necessary and correct [[video drivers]], or the WM may freeze on loading.<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.archlinux.org/archlinux/archiso Archiso project page]<br />
* [https://gitlab.archlinux.org/archlinux/archiso/-/tree/master/docs Official documentation]<br />
* [https://lists.archlinux.org/listinfo/arch-releng Arch Linux Release Engineering mailing list]<br />
* [ircs://irc.libera.chat/archlinux-releng #archlinux-releng — Arch Linux Release Engineering IRC channel]<br />
* [https://github.com/pierres/archiso-manager archiso-manager — the tool used for building the official monthly ISOs]</div>PXfhttps://wiki.archlinux.org/index.php?title=NFS&diff=692066NFS2021-08-18T09:44:41Z<p>PXf: /* Enabling NFSv4 idmapping */ boldface "not"</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Network sharing]]<br />
[[Category:Servers]]<br />
[[ar:NFS]]<br />
[[de:Network File System]]<br />
[[es:NFS]]<br />
[[fr:NFS]]<br />
[[it:NFS]]<br />
[[ja:NFS]]<br />
[[zh-hans:NFS]]<br />
{{Related articles start}}<br />
{{Related|NFS/Troubleshooting}}<br />
{{Related articles end}}<br />
From [[Wikipedia: Network File System|Wikipedia]]: <br />
:Network File System (NFS) is a distributed file system protocol originally developed by Sun Microsystems in 1984, allowing a user on a client computer to access files over a network in a manner similar to how local storage is accessed.<br />
<br />
{{Note|<br />
* NFS is not encrypted. Tunnel NFS through an encrypted protocol like [[Kerberos]] or (secure) [[VPN]] when dealing with sensitive data.<br />
* Unlike [[Samba]], NFS does not have any user authentication by default, client access is restricted by their IP-address/[[hostname]].<br />
* NFS expects the [[user]] and/or [[user group]] ID's are the same on both the client and server. [[#Enabling NFSv4 idmapping|Enable NFSv4 idmapping]] or overrule the UID/GID manually by using {{ic|anonuid}}/{{ic|anongid}} together with {{ic|all_squash}} in {{ic|/etc/exports}}.<br />
}}<br />
<br />
== Installation ==<br />
<br />
Both client and server only require the [[install|installation]] of the {{Pkg|nfs-utils}} package.<br />
<br />
It is '''highly''' recommended to use a [[time synchronization]] daemon to keep client/server clocks in sync. Without accurate clocks on all nodes, NFS can introduce unwanted delays.<br />
<br />
== Configuration ==<br />
<br />
=== Server ===<br />
<br />
Global configuration options are set in {{ic|/etc/nfs.conf}}. Users of simple configurations should not need to edit this file.<br />
<br />
The NFS server needs a list of exports (see {{man|5|exports}} for details) which are defined in {{ic|/etc/exports}} or {{ic|/etc/exports.d/*.exports}}. These shares are relative to the so-called NFS root. A good security practice is to define a NFS root in a discrete directory tree which will keep users limited to that mount point. Bind mounts are used to link the share mount point to the actual directory elsewhere on the [[filesystem]].<br />
<br />
Consider this following example wherein:<br />
<br />
# The NFS root is {{ic|/srv/nfs}}.<br />
# The export is {{ic|/srv/nfs/music}} via a bind mount to the actual target {{ic|/mnt/music}}.<br />
<br />
# mkdir -p /srv/nfs/music /mnt/music<br />
# mount --bind /mnt/music /srv/nfs/music<br />
<br />
{{Note|[[ZFS]] filesystems require special handling of bindmounts, see [[ZFS#Bind mount]].}}<br />
<br />
To make the bind mount persistent across reboots, add it to [[fstab]]:<br />
<br />
{{hc|/etc/fstab|<br />
/mnt/music /srv/nfs/music none bind 0 0<br />
}}<br />
<br />
Add directories to be shared and limit them to a range of addresses via a CIDR or hostname(s) of client machines that will be allowed to mount them in {{ic|/etc/exports}}, e.g.:<br />
<br />
{{hc|/etc/exports|2=<br />
/srv/nfs 192.168.1.0/24(rw,sync,crossmnt,fsid=0)<br />
/srv/nfs/music 192.168.1.0/24(rw,sync)<br />
/srv/nfs/home 192.168.1.0/24(rw,sync,nohide)<br />
/srv/nfs/public 192.168.1.0/24(ro,all_squash,insecure) desktop(rw,sync,all_squash,anonuid=99,anongid=99) # map to user/group - in this case ''nobody''<br />
}}<br />
<br />
{{Note|When using NFSv4, the nfs root directory is specified by the entry denoted by {{ic|1=fsid=0}}, other directories must be below it. The {{ic|rootdir}} option in the {{ic|/etc/nfs.conf}} file has no effect on this.}}<br />
<br />
{{Tip|<br />
* The {{ic|crossmnt}} option makes it possible for clients to access '''all''' filesystems mounted on a filesystem marked with {{ic|crossmnt}} and clients will not be required to mount every child export separately. Note this may not be desirable if a child is shared with a different range of addresses.<br />
* Instead of {{ic|crossmnt}}, one can also use the {{ic|nohide}} option on child exports so that they can be automatically mounted when a client mounts the root export. Being different from {{ic|crossmnt}}, {{ic|nohide}} still respects address ranges of child exports.<br />
* Use an asterisk (*) to allow access from any interface.}}<br />
<br />
It should be noted that modifying {{ic|/etc/exports}} while the server is running will require a re-export for changes to take effect:<br />
<br />
# exportfs -arv<br />
<br />
To view the current loaded exports state in more detail, use:<br />
<br />
# exportfs -v<br />
<br />
For more information about all available options see {{man|5|exports}}.<br />
<br />
{{Tip|[https://ip2cidr.com/ ip2cidr] is a tool to convert an IP ranges to correctly structured CIDR specification.}}<br />
<br />
{{Note|If the target export is a [[tmpfs]] filesystem, the {{ic|1=fsid=1}} option is required.}}<br />
<br />
==== Starting the server ====<br />
<br />
[[Start]] and [[enable]] {{ic|nfs-server.service}}.<br />
<br />
{{Warning|A hard dependency of serving NFS ({{ic|rpc-gssd.service}}) will wait until the [[random number generator]] pool is sufficiently initialized possibly delaying the boot process. This is particularly prevalent on headless servers. It is ''highly'' recommended to populate the entropy pool using a utility such as [[Rng-tools]] (if [[TPM]] is supported) or [[Haveged]] in these scenarios.}}<br />
<br />
{{Note|If exporting ZFS shares, also [[start]]/[[enable]] {{ic|zfs-share.service}}. Without this, ZFS shares will no longer be exported after a reboot. See [[ZFS#NFS]].}}<br />
<br />
==== Restricting NFS to interfaces/IPs ====<br />
<br />
By default, starting {{ic|nfs-server.service}} will listen for connections on all network interfaces, regardless of {{ic|/etc/exports}}. This can be changed by defining which IPs and/or hostnames to listen on.<br />
<br />
{{hc|/etc/nfs.conf|2=<br />
[nfsd]<br />
host=192.168.1.123<br />
# Alternatively, use the hostname.<br />
# host=myhostname<br />
}}<br />
<br />
[[Restart]] {{ic|nfs-server.service}} to apply the changes immediately.<br />
<br />
==== Firewall configuration ====<br />
<br />
To enable access through a [[firewall]], TCP and UDP ports {{ic|111}}, {{ic|2049}}, and {{ic|20048}} may need to be opened when using the default configuration; use {{ic|rpcinfo -p}} to examine the exact ports in use on the server:<br />
<br />
{{hc|$ rpcinfo -p {{!}} grep nfs|<br />
100003 3 tcp 2049 nfs<br />
100003 4 tcp 2049 nfs<br />
100227 3 tcp 2049 nfs_acl<br />
}}<br />
<br />
When using NFSv4, make sure TCP port {{ic|2049}} is open. No other port opening should be required:<br />
<br />
{{hc|/etc/iptables/iptables.rules|2=<br />
-A INPUT -p tcp -m tcp --dport 2049 -j ACCEPT<br />
}}<br />
<br />
When using an older NFS version, make sure other ports are open:<br />
<br />
# iptables -A INPUT -p tcp -m tcp --dport 111 -j ACCEPT<br />
# iptables -A INPUT -p tcp -m tcp --dport 2049 -j ACCEPT<br />
# iptables -A INPUT -p tcp -m tcp --dport 20048 -j ACCEPT<br />
# iptables -A INPUT -p udp -m udp --dport 111 -j ACCEPT<br />
# iptables -A INPUT -p udp -m udp --dport 2049 -j ACCEPT<br />
# iptables -A INPUT -p udp -m udp --dport 20048 -j ACCEPT<br />
<br />
To have this configuration load on every system start, edit {{ic|/etc/iptables/iptables.rules}} to include the following lines:<br />
<br />
{{hc|/etc/iptables/iptables.rules|2=<br />
-A INPUT -p tcp -m tcp --dport 111 -j ACCEPT<br />
-A INPUT -p tcp -m tcp --dport 2049 -j ACCEPT<br />
-A INPUT -p tcp -m tcp --dport 20048 -j ACCEPT<br />
-A INPUT -p udp -m udp --dport 111 -j ACCEPT<br />
-A INPUT -p udp -m udp --dport 2049 -j ACCEPT<br />
-A INPUT -p udp -m udp --dport 20048 -j ACCEPT<br />
}}<br />
<br />
The previous commands can be saved by executing:<br />
<br />
# iptables-save > /etc/iptables/iptables.rules<br />
<br />
{{Warning|This command will '''override''' the current iptables start configuration with the current iptables configuration!}}<br />
<br />
If using NFSv3 and the above listed static ports for {{ic|rpc.statd}} and {{ic|lockd}} the following ports may also need to be added to the configuration:<br />
<br />
{{hc|/etc/iptables/iptables.rules|2=<br />
-A INPUT -p tcp -m tcp --dport 32765 -j ACCEPT<br />
-A INPUT -p tcp -m tcp --dport 32803 -j ACCEPT<br />
-A INPUT -p udp -m udp --dport 32765 -j ACCEPT<br />
-A INPUT -p udp -m udp --dport 32803 -j ACCEPT<br />
}}<br />
<br />
To apply changes, [[Restart]] {{ic|iptables.service}}.<br />
<br />
==== Enabling NFSv4 idmapping ====<br />
<br />
{{Expansion|Missing lookup information, static binding examples, etc.}}<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* NFSv4 idmapping does not work with the default {{ic|1=sec=sys}} mount option. [https://dfusion.com.au/wiki/tiki-index.php?page=Why+NFSv4+UID+mapping+breaks+with+AUTH_UNIX]<br />
* NFSv4 idmapping needs to be enabled on '''both''' the client and server.<br />
* Another option is to make sure the user and group IDs (UID and GID) match on both the client and server.<br />
* [[Enabling]]/[[starting]] {{ic|nfs-idmapd.service}} should '''not''' be needed as it has been replaced with a new id mapper:<br />
{{hc|# dmesg &#124; grep id_resolver|<br />
[ 3238.356001] NFS: Registering the id_resolver key type<br />
[ 3238.356009] Key type id_resolver registered<br />
}}}}<br />
<br />
The NFSv4 protocol represents the local system's UID and GID values on the wire as strings of the form {{ic|user@domain}}. The process of translating from UID to string and string to UID is referred to as ''ID mapping''. See {{man|8|nfsidmap}} for details.<br />
<br />
Even though idmapd may be running, it may not be fully enabled. If {{ic|/sys/module/nfs/parameters/nfs4_disable_idmapping}} or {{ic|/sys/module/nfsd/parameters/nfs4_disable_idmapping}} returns {{ic|Y}} on a client/server, enable it by:<br />
<br />
{{Note|The kernel modules {{ic|nfs4}} and {{ic|nfsd}} need to be loaded (respectively) for the following paths to be available.<br />
}}<br />
<br />
On the client:<br />
# echo "N" | tee /sys/module/nfs/parameters/nfs4_disable_idmapping<br />
On the server:<br />
# echo "N" | tee /sys/module/nfsd/parameters/nfs4_disable_idmapping<br />
<br />
Set as [[Kernel modules#Setting module options|module option]] to make this change permanent, i.e.:<br />
<br />
{{hc|/etc/modprobe.d/nfsd.conf|2=<br />
options nfs nfs4_disable_idmapping=0<br />
options nfsd nfs4_disable_idmapping=0<br />
}}<br />
<br />
To fully use ''idmapping'', make sure the domain is configured in {{ic|/etc/idmapd.conf}} on '''both''' the server and the client: <br />
<br />
{{hc|/etc/idmapd.conf|2=<br />
# The following should be set to the local NFSv4 domain name<br />
# The default is the host's DNS domain name.<br />
Domain = ''domain.tld''<br />
}}<br />
<br />
See [https://unix.stackexchange.com/a/464950] for details.<br />
<br />
=== Client ===<br />
<br />
Users intending to use NFS4 with [[Kerberos]] need to [[start]] and [[enable]] {{ic|nfs-client.target}}.<br />
<br />
==== Manual mounting ====<br />
<br />
For NFSv3 use this command to show the server's exported file systems:<br />
<br />
$ showmount -e servername<br />
<br />
For NFSv4 mount the root NFS directory and look around for available mounts:<br />
<br />
# mount server:/ /mountpoint/on/client<br />
<br />
Then mount omitting the server's NFS export root: <br />
<br />
# mount -t nfs -o vers=4 servername:/music /mountpoint/on/client<br />
<br />
If mount fails try including the server's export root (required for Debian/RHEL/SLES, some distributions need {{ic|-t nfs4}} instead of {{ic|-t nfs}}):<br />
<br />
# mount -t nfs -o vers=4 servername:/srv/nfs/music /mountpoint/on/client<br />
<br />
{{Note|Server name needs to be a valid hostname (not just IP address). Otherwise mounting of remote share will hang.}}<br />
<br />
==== Mount using /etc/fstab ====<br />
<br />
Using [[fstab]] is useful for a server which is always on, and the NFS shares are available whenever the client boots up. Edit {{ic|/etc/fstab}} file, and add an appropriate line reflecting the setup. Again, the server's NFS export root is omitted.<br />
<br />
{{hc|/etc/fstab|2=<br />
servername:/music /mountpoint/on/client nfs defaults,timeo=900,retrans=5,_netdev 0 0<br />
}}<br />
<br />
{{Note|Consult {{man|5|nfs}} and {{man|8|mount}} for more mount options.}}<br />
<br />
Some additional mount options to consider:<br />
<br />
; rsize and wsize: The {{ic|rsize}} value is the number of bytes used when reading from the server. The {{ic|wsize}} value is the number of bytes used when writing to the server. By default, if these options are not specified, the client and server negotiate the largest values they can both support (see {{man|5|nfs}} for details). After changing these values, it is recommended to test the performance (see [[#Performance tuning]]).<br />
<br />
; soft or hard: Determines the recovery behaviour of the NFS client after an NFS request times out. If neither option is specified (or if the {{ic|hard}} option is specified), NFS requests are retried indefinitely. If the {{ic|soft}} option is specified, then the NFS client fails a NFS request after ''retrans'' retransmissions have been sent, causing the NFS client to return an error to the calling application.<br />
<br />
{{Warning|A so-called {{ic|soft}} timeout can cause silent data corruption in certain cases. As such, use the {{ic|soft}} option only when client responsiveness is more important than data integrity. Using NFS over TCP or increasing the value of the {{ic|retrans}} option may mitigate some of the risks of using the {{ic|soft}} option.}}<br />
<br />
; timeo: The {{ic|timeo}} value is the amount of time, in tenths of a second, to wait before resending a transmission after an RPC timeout. The default value for NFS over TCP is 600 (60 seconds). After the first timeout, the timeout value is doubled for each retry for a maximum of 60 seconds or until a major timeout occurs. If connecting to a slow server or over a busy network, better stability can be achieved by increasing this timeout value.<br />
<br />
; retrans: The number of times the NFS client retries a request before it attempts further recovery action. If the {{ic|retrans}} option is not specified, the NFS client tries each request three times. The NFS client generates a "server not responding" message after ''retrans'' retries, then attempts further recovery (depending on whether the hard mount option is in effect). <br />
<br />
; _netdev: The {{ic|_netdev}} option tells the system to wait until the network is up before trying to mount the share - [[systemd]] assumes this for NFS. <br />
<br />
{{Note|Setting the sixth field ({{ic|fs_passno}}) to a nonzero value may lead to unexpected behaviour, e.g. hangs when the systemd automount waits for a check which will never happen.}}<br />
<br />
==== Mount using /etc/fstab with systemd ====<br />
<br />
Another method is using the [[Fstab#Remote filesystem|x-systemd.automount]] option which mounts the filesystem upon access:<br />
<br />
{{hc|1=/etc/fstab|2=<br />
servername:/home ''/mountpoint/on/client'' nfs _netdev,noauto,x-systemd.automount,x-systemd.mount-timeout=10,timeo=14,x-systemd.idle-timeout=1min 0 0 <br />
}}<br />
<br />
To make systemd aware of the changes to fstab, [[reload]] systemd and restart {{ic|remote-fs.target}} [https://bbs.archlinux.org/viewtopic.php?pid=1515377#p1515377].<br />
<br />
{{Accuracy|Not everyone uses NetworkManager. Refer to [[Systemd#Running services after the network is up]] instead?}}<br />
<br />
{{Tip|<br />
* The {{ic|noauto}} mount option will not mount the NFS share until it is accessed: use {{ic|auto}} for it to be available immediately. <br> If experiencing any issues with the mount failing due to the network not being up/available, [[enable]] {{ic|NetworkManager-wait-online.service}}. It will ensure that {{ic|network.target}} has all the links available prior to being active.<br />
* The {{ic|users}} mount option would allow user mounts, but be aware it implies further options as {{ic|noexec}} for example.<br />
* The {{ic|1=x-systemd.idle-timeout=1min}} option will unmount the NFS share automatically after 1 minute of non-use. Good for laptops which might suddenly disconnect from the network.<br />
* If shutdown/reboot holds too long because of NFS, [[enable]] {{ic|NetworkManager-wait-online.service}} to ensure that NetworkManager is not exited before the NFS volumes are unmounted. <br />
* Do not add the {{ic|1=x-systemd.requires=network-online.target}} mount option as this can lead to ordering cycles within systemd [https://github.com/systemd/systemd-stable/issues/69]. systemd adds the {{ic|network-online.target}} dependency to the unit for {{ic|_netdev}} mount automatically. <br />
* Using the {{ic|nocto}} option may improve performance for read-only mounts, but should be used only if the data on the server changes only occasionally.<br />
}}<br />
<br />
==== As systemd unit ====<br />
<br />
Create a new {{ic|.mount}} file inside {{ic|/etc/systemd/system}}, e.g. {{ic|mnt-myshare.mount}}. See {{man|5|systemd.mount}} for details.<br />
<br />
{{Note|Make sure the filename corresponds to the mountpoint you want to use.<br />
E.g. the unit name {{ic|mnt-myshare.mount}} can only be used if you are going to mount the share under {{ic|/mnt/myshare}}. Otherwise the following error might occur: {{ic|1=systemd[1]: mnt-myshare.mount: Where= setting does not match unit name. Refusing.}}.}}<br />
<br />
{{ic|1=What=}} path to share<br />
<br />
{{ic|1=Where=}} path to mount the share<br />
<br />
{{ic|1=Options=}} share mounting options<br />
<br />
{{Note|<br />
* Network mount units automatically acquire {{ic|After}} dependencies on {{ic|remote-fs-pre.target}}, {{ic|network.target}} and {{ic|network-online.target}}, and gain a {{ic|Before}} dependency on {{ic|remote-fs.target}} unless {{ic|nofail}} mount option is set. Towards the latter a {{ic|Wants}} unit is added as well.<br />
* [[Append]] {{ic|noauto}} to {{ic|Options}} preventing automatically mount during boot (unless it is pulled in by some other unit).<br />
* If you want to use a hostname for the server you want to share (instead of an IP address), add {{ic|1=nss-lookup.target}} to {{ic|1=After}}. This might avoid mount errors at boot time that do not arise when testing the unit.<br />
}} <br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.mount|2=<br />
[Unit]<br />
Description=Mount Share at boot<br />
<br />
[Mount]<br />
What=172.16.24.192:/mnt/myshare<br />
Where=/mnt/myshare<br />
Options=<br />
Type=nfs<br />
TimeoutSec=30<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Tip|In case of an unreachable system, [[append]] {{ic|1=ForceUnmount=true}} to {{ic|[Mount]}}, allowing the share to be (force-)unmounted.}}<br />
<br />
To use {{ic|mnt-myshare.mount}}, [[start]] the unit and [[enable]] it to run on system boot.<br />
<br />
===== automount =====<br />
<br />
To automatically mount a share, one may use the following automount unit:<br />
<br />
{{hc|/etc/systemd/system/mnt-myshare.automount|2=<br />
[Unit]<br />
Description=Automount myshare<br />
<br />
[Automount]<br />
Where=/mnt/myshare<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
[[Disable]]/[[stop]] the {{ic|mnt-myshare.mount}} unit, and [[enable]]/[[start]] {{ic|mnt-myshare.automount}} to automount the share when the mount path is being accessed.<br />
<br />
{{Tip|[[Append]] {{ic|TimeoutIdleSec}} to enable auto unmount. See {{man|5|systemd.automount}} for details.}}<br />
<br />
==== Mount using autofs ====<br />
<br />
Using [[autofs]] is useful when multiple machines want to connect via NFS; they could both be clients as well as servers. The reason this method is preferable over the earlier one is that if the server is switched off, the client will not throw errors about being unable to find NFS shares. See [[autofs#NFS network mounts]] for details.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Performance tuning ===<br />
<br />
When using NFS on a network with a significant number of clients one may increase the default NFS threads from ''8'' to ''16'' or even a higher, depending on the server/network requirements:<br />
<br />
{{hc|/etc/nfs.conf|2=<br />
[nfsd]<br />
threads=16<br />
}}<br />
<br />
It may be necessary to tune the {{ic|rsize}} and {{ic|wsize}} mount options to meet the requirements of the network configuration.<br />
<br />
In recent linux kernels (>2.6.18) the size of I/O operations allowed by the NFS server (default max block size) varies depending on RAM size, with a maximum of 1M (1048576 bytes), the max block size of the server will be used even if nfs clients requires bigger {{ic|rsize}} and {{ic|wsize}}. See https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/5.8_Technical_Notes/Known_Issues-kernel.html<br />
It is possible to change the default max block size allowed by the server by writing to the {{ic|/proc/fs/nfsd/max_block_size}} before starting ''nfsd''. For example, the following command restores the previous default iosize of 32k:<br />
<br />
# echo 32768 > /proc/fs/nfsd/max_block_size<br />
<br />
To make the change permanent, create a [[systemd-tmpfile]]:<br />
<br />
{{hc|/etc/tmpfiles.d/nfsd-block-size.conf|<br />
w /proc/fs/nfsd/max_block_size - - - - 32768<br />
}}<br />
<br />
To mount with the increased {{ic|rsize}} and {{ic|wsize}} mount options:<br />
<br />
# mount -t nfs -o rsize=32768,wsize=32768,vers=4 servername:/srv/nfs/music /mountpoint/on/client<br />
<br />
Furthermore, despite the violation of NFS protocol, setting {{ic|async}} instead of {{ic|sync}} or {{ic|sync,no_wdelay}} may potentially achieve a significant performance gain especially on spinning disks. Configure exports with this option and then execute {{ic|exportfs -arv}} to apply.<br />
<br />
{{hc|/etc/exports|2=<br />
/srv/nfs 192.168.1.0/24(rw,async,crossmnt,fsid=0)<br />
/srv/nfs/music 192.168.1.0/24(rw,async)<br />
}}<br />
<br />
{{Warning|Using {{ic|async}} comes with a risk of possible data loss or corruption if the server crashes or restarts uncleanly.}}<br />
<br />
=== Automatic mount handling ===<br />
<br />
This trick is useful for NFS-shares on a [[wireless]] network and/or on a network that may be unreliable. If the NFS host becomes unreachable, the NFS share will be unmounted to hopefully prevent system hangs when using the {{ic|hard}} mount option [https://bbs.archlinux.org/viewtopic.php?pid=1260240#p1260240].<br />
<br />
Make sure that the NFS mount points are correctly indicated in [[fstab]]:<br />
<br />
{{hc|/etc/fstab|2=<br />
lithium:/mnt/data /mnt/data nfs noauto 0 0<br />
lithium:/var/cache/pacman /var/cache/pacman nfs noauto 0 0<br />
}}<br />
<br />
{{Note|<br />
* Use hostnames in [[fstab]] for this to work, not IP addresses.<br />
* In order to mount NFS shares with non-root users the {{ic|users}} option has to be added.<br />
* The {{ic|noauto}} mount option tells [[systemd]] to not automatically [[mount]] the shares at boot, otherwise this may cause the boot process to stall.<br />
}}<br />
<br />
Create the {{ic|auto_share}} script that will be used by [[cron]] or [[systemd/Timers]] to use ICMP ping to check if the NFS host is reachable:<br />
<br />
{{hc|/usr/local/bin/auto_share|<nowiki><br />
#!/bin/bash<br />
<br />
function net_umount {<br />
umount -l -f $1 &>/dev/null<br />
}<br />
<br />
function net_mount {<br />
mountpoint -q $1 || mount $1<br />
}<br />
<br />
NET_MOUNTS=$(sed -e '/^.*#/d' -e '/^.*:/!d' -e 's/\t/ /g' /etc/fstab | tr -s " ")$'\n'b<br />
<br />
printf %s "$NET_MOUNTS" | while IFS= read -r line<br />
do<br />
SERVER=$(echo $line | cut -f1 -d":")<br />
MOUNT_POINT=$(echo $line | cut -f2 -d" ")<br />
<br />
# Check if server already tested<br />
if [[ "${server_ok[@]}" =~ "${SERVER}" ]]; then<br />
# The server is up, make sure the share are mounted<br />
net_mount $MOUNT_POINT<br />
elif [[ "${server_notok[@]}" =~ "${SERVER}" ]]; then<br />
# The server could not be reached, unmount the share<br />
net_umount $MOUNT_POINT<br />
else<br />
# Check if the server is reachable<br />
ping -c 1 "${SERVER}" &>/dev/null<br />
<br />
if [ $? -ne 0 ]; then<br />
server_notok[${#server_notok[@]}]=$SERVER<br />
# The server could not be reached, unmount the share<br />
net_umount $MOUNT_POINT<br />
else<br />
server_ok[${#server_ok[@]}]=$SERVER<br />
# The server is up, make sure the share are mounted<br />
net_mount $MOUNT_POINT<br />
fi<br />
fi<br />
done<br />
</nowiki>}}<br />
<br />
{{Note|Test using a TCP probe instead of ICMP ping (default is tcp port 2049 in NFS4) then replace the line:<br />
<br />
# Check if the server is reachable<br />
ping -c 1 "${SERVER}" &>/dev/null<br />
<br />
with:<br />
<br />
# Check if the server is reachable<br />
timeout 1 bash -c ": < /dev/tcp/${SERVER}/2049"<br />
<br />
in the {{ic|auto_share}} script above.}}<br />
<br />
Make sure the script is [[executable]]:<br />
<br />
# chmod +x /usr/local/bin/auto_share<br />
<br />
Next check configure the script to run every X, in the examples below this is every minute.<br />
<br />
==== Cron ====<br />
<br />
{{hc|# crontab -e|<br />
* * * * * /usr/local/bin/auto_share<br />
}}<br />
<br />
==== systemd/Timers ====<br />
<br />
{{hc|/etc/systemd/system/auto_share.timer|2=<br />
[Unit]<br />
Description=Automount NFS shares every minute<br />
<br />
[Timer]<br />
OnCalendar=*-*-* *:*:00<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/auto_share.service|2=<br />
[Unit]<br />
Description=Automount NFS shares<br />
After=syslog.target network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/local/bin/auto_share<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
Finally, [[enable]] and [[start]] {{ic|auto_share.timer}}.<br />
<br />
==== Using a NetworkManager dispatcher ====<br />
<br />
[[NetworkManager#Network services with NetworkManager dispatcher|NetworkManager]] can also be configured to run a script on network status change.<br />
<br />
The easiest method for mount shares on network status change is to symlink the {{ic|auto_share}} script:<br />
<br />
# ln -s /usr/local/bin/auto_share /etc/NetworkManager/dispatcher.d/30-nfs.sh<br />
<br />
However, in that particular case unmounting will happen only after the network connection has already been disabled, which is unclean and may result in effects like freezing of KDE Plasma applets. <br />
<br />
The following script safely unmounts the NFS shares before the relevant network connection is disabled by listening for the {{ic|pre-down}} and {{ic|vpn-pre-down}} events, make the script is [[executable]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-nfs.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Find the connection UUID with "nmcli con show" in terminal.<br />
# All NetworkManager connection types are supported: wireless, VPN, wired...<br />
WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"<br />
<br />
if [[ "$CONNECTION_UUID" == "$WANTED_CON_UUID" ]]; then<br />
<br />
# Script parameter $1: NetworkManager connection name, not used<br />
# Script parameter $2: dispatched event<br />
<br />
case "$2" in<br />
"up")<br />
mount -a -t nfs4,nfs <br />
;;<br />
"pre-down");&<br />
"vpn-pre-down")<br />
umount -l -a -t nfs4,nfs -f >/dev/null<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|This script ignores mounts with the {{ic|noauto}} option, remove this mount option or use {{ic|auto}} to allow the dispatcher to manage these mounts.}}<br />
<br />
Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down}} to catch the {{ic|pre-down}} events:<br />
<br />
# ln -s /etc/NetworkManager/dispatcher.d/30-nfs.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-nfs.sh<br />
<br />
== Troubleshooting ==<br />
<br />
There is a dedicated article [[NFS/Troubleshooting]].<br />
<br />
== See also ==<br />
<br />
* See also [[Avahi]], a Zeroconf implementation which allows automatic discovery of NFS shares.<br />
* HOWTO: [[Diskless network boot NFS root]]<br />
* [http://blogs.msdn.com/sfu/archive/2008/04/14/all-well-almost-about-client-for-nfs-configuration-and-performance.aspx Microsoft Services for Unix NFS Client info]{{Dead link|2021|05|17|status=404}}<br />
* [https://web.archive.org/web/20151212160906/https://blogs.oracle.com/jag/entry/nfs_on_snow_leopard NFS on Snow Leopard]<br />
* http://chschneider.eu/linux/server/nfs.shtml<br />
* [https://www.slashroot.in/how-do-linux-nfs-performance-tuning-and-optimization How to do Linux NFS Performance Tuning and Optimization]<br />
* [https://www.cyberciti.biz/faq/linux-unix-tuning-nfs-server-client-performance/ Linux: Tune NFS Performance]</div>PXfhttps://wiki.archlinux.org/index.php?title=Diskless_system&diff=692056Diskless system2021-08-18T05:23:26Z<p>PXf: /* Directory setup */ if a note instructs you to skip a step, it should come _before_ that step</p>
<hr />
<div>[[Category:Installation process]]<br />
[[de:Diskless_Workstation]]<br />
[[ja:ディスクレスシステム]]<br />
[[ru:Diskless system]]<br />
[[zh-hans:Diskless system]]<br />
{{Related articles start}}<br />
{{Related|NFS}}<br />
{{Related|NFS Troubleshooting}}<br />
{{Related|PXE}}<br />
{{Related|Mkinitcpio#Using_net}}<br />
{{Related|iSCSI Boot}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Diskless node]]<br />
:''A diskless node (or diskless workstation) is a workstation or personal computer without disk drives, which employs network booting to load its operating system from a server.''<br />
<br />
== Server configuration ==<br />
<br />
First of all, we must install the following components:<br />
* A [[Dhcpd|DHCP]] server to assign IP addresses to our diskless nodes.<br />
* A [[TFTP]] server to transfer the boot image (a requirement of all PXE option roms).<br />
* A form of network storage ([[NFS]] or NBD) to export the Arch installation to the diskless node.<br />
<br />
{{Note|{{pkg|dnsmasq}} is capable of simultaneously acting as both DHCP and TFTP server. For more information, see the [[dnsmasq]] article.}}<br />
<br />
=== DHCP ===<br />
<br />
Install ISC {{Pkg|dhcp}} and configure it:<br />
<br />
{{hc|/etc/dhcpd.conf|2=<br />
allow booting;<br />
allow bootp;<br />
<br />
authoritative;<br />
<br />
option domain-name-servers 10.0.0.1;<br />
<br />
option architecture code 93 = unsigned integer 16;<br />
<br />
group {<br />
next-server 10.0.0.1;<br />
<br />
if option architecture = 00:07 {<br />
filename "/grub/x86_64-efi/core.efi";<br />
} else {<br />
filename "/grub/i386-pc/core.0";<br />
}<br />
<br />
subnet 10.0.0.0 netmask 255.255.255.0 {<br />
option routers 10.0.0.1;<br />
range 10.0.0.128 10.0.0.254;<br />
}<br />
}<br />
}}<br />
<br />
{{Note|{{ic|next-server}} should be the address of the TFTP server; everything else should be changed to match your network}}<br />
<br />
RFC 4578 defines the "Client System Architecture Type" dhcp option. In the above configuration, if the PXE client requests an x86_64-efi binary (type 0x7), we appropriately give them one, otherwise falling back to the legacy binary. This allows both UEFI and legacy BIOS clients to boot simultaneously on the same network segment.<br />
<br />
Start ISC DHCP [[systemd]] service.<br />
<br />
=== TFTP ===<br />
<br />
The TFTP server will be used to transfer the bootloader, kernel, and initramfs to the client.<br />
<br />
Set the TFTP root to {{ic|/srv/arch/boot}}. See [[TFTP]] for installation and configuration.<br />
<br />
=== Network storage ===<br />
<br />
The primary difference between using NFS and NBD is while with both you can in fact have multiple clients using the same installation, with NBD (by the nature of manipulating a filesystem directly) you will need to use the {{ic|copyonwrite}} mode to do so, which ends up discarding all writes on client disconnect. In some situations however, this might be highly desirable.<br />
<br />
==== NFS ====<br />
<br />
Install {{Pkg|nfs-utils}} on the server.<br />
<br />
You will need to add the root of your Arch installation to your [[NFS]] exports:<br />
<br />
{{hc|/etc/exports|2=<br />
/srv *(rw,fsid=0,no_root_squash,no_subtree_check)<br />
/srv/arch *(rw,no_root_squash,no_subtree_check)<br />
}}<br />
<br />
Next, start NFS services: {{ic|nfs-idmapd}} {{ic|nfs-mountd}}.<br />
<br />
==== NBD ====<br />
<br />
Install {{Pkg|nbd}} and configure it.<br />
<br />
{{hc|/etc/nbd-server/config|2=<br />
[generic]<br />
user = nbd<br />
group = nbd<br />
[arch]<br />
exportname = /srv/arch.img<br />
copyonwrite = false<br />
}}<br />
<br />
{{Note|Set {{ic|copyonwrite}} to true if you want to have multiple clients using the same NBD share simultaneously; refer to {{man|5|nbd-server}} for more details. Also use [[chown]] to change the ownership of the exportname directory to the user {{ic|nbd}}.}}<br />
<br />
Start {{ic|nbd}} systemd service.<br />
<br />
== Client installation ==<br />
<br />
Next we will create a full Arch Linux installation in a subdirectory on the server. During boot, the diskless client will get an IP address from the DHCP server, then boot from the host using PXE and mount this installation as its root.<br />
<br />
=== Directory setup ===<br />
<br />
{{Note|Creating a separate filesystem is required for NBD but optional for NFS and can be skipped/ignored.}}<br />
<br />
Create a [[Wikipedia: Sparse file|sparse file]] of at least 1 gigabyte, and create a btrfs filesystem on it (you can of course also use a real block device or [[LVM]] if you so desire).<br />
<br />
# truncate -s 1G /srv/arch.img<br />
# mkfs.btrfs /srv/arch.img<br />
# export root=/srv/arch<br />
# mkdir -p "$root"<br />
# mount -o loop,compress=lzo /srv/arch.img "$root"<br />
<br />
=== Bootstrapping installation ===<br />
<br />
Install {{Pkg|devtools}} and {{Pkg|arch-install-scripts}}, and run ''pacstrap'' to install the [[Installation guide#Install essential packages|essential packages]] for the client:<br />
<br />
# pacstrap -d "$root" base linux linux-firmware mkinitcpio-nfs-utils nfs-utils<br />
<br />
{{Note|In all cases {{Pkg|mkinitcpio-nfs-utils}} is still required. {{ic|ipconfig}} used in early-boot is provided only by the latter.}}<br />
<br />
Now the initramfs needs to be constructed.<br />
<br />
==== NFS ====<br />
<br />
Trivial modifications to the {{ic|net}} hook are required in order for NFSv4 mounting to work (not supported by {{ic|nfsmount}}--the default for the {{ic|net}} hook).<br />
<br />
# sed s/nfsmount/mount.nfs4/ "$root/usr/lib/initcpio/hooks/net" > "$root/usr/lib/initcpio/hooks/netnfs4"<br />
# cp $root/usr/lib/initcpio/install/net{,nfs4}<br />
<br />
The copy of {{ic|net}} is unfortunately needed so it does not get overwritten when {{pkg|mkinitcpio-nfs-utils}} is updated on the client installation.<br />
<br />
Edit {{ic|$root/etc/mkinitcpio.conf}} and add {{ic|nfsv4}} to {{ic|MODULES}}, {{ic|netnfs4}} to {{ic|HOOKS}}, and {{ic|/usr/bin/mount.nfs4}} to {{ic|BINARIES}}.<br />
<br />
Next, we [[chroot]] our installation and run ''mkinitcpio'':<br />
<br />
# arch-chroot "$root" mkinitcpio -p linux<br />
<br />
==== NBD ====<br />
<br />
The {{AUR|mkinitcpio-nbd}} package needs to be installed on the client. Build it with [[makepkg]] and install it:<br />
<br />
# pacman --root "$root" --dbpath "$root/var/lib/pacman" -U mkinitcpio-nbd-0.4-1-any.pkg.tar.xz<br />
<br />
You will then need to append {{ic|nbd}} to your {{ic|HOOKS}} array after {{ic|net}}; {{ic|net}} will configure your networking for you, but not attempt a NFS mount if {{ic|nfsroot}} is not specified in the kernel line.<br />
<br />
== Client configuration ==<br />
<br />
In addition to the setup mentioned here, you should also set up your [[hostname]], [[timezone]], [[Locale#Setting the system locale|locale]], and [[keymap]], and follow any other relevant parts of the [[Installation guide]].<br />
<br />
=== Bootloader ===<br />
<br />
==== GRUB ====<br />
<br />
{{Merge|GRUB|}}<br />
<br />
Though poorly documented, GRUB supports being loaded via PXE.<br />
<br />
# pacman --root "$root" --dbpath "$root/var/lib/pacman" -S grub<br />
<br />
Create a grub prefix on the target installation for both architectures using {{ic|grub-mknetdir}}.<br />
<br />
# arch-chroot "$root" grub-mknetdir --net-directory=/boot --subdir=grub<br />
<br />
Luckily for us, grub-mknetdir creates prefixes for all currently compiled/installed targets, and the {{Pkg|grub}} maintainers were nice enough to give us both in the same package, thus grub-mknetdir only needs to be run once.<br />
<br />
Now we create a trivial GRUB configuration:<br />
<br />
{{hc|# vim "$root/boot/grub/grub.cfg"|2=<br />
menuentry "Arch Linux" {<br />
linux /vmlinuz-linux quiet add_efi_memmap ip=:::::eth0:dhcp nfsroot=10.0.0.1:/arch<br />
initrd /initramfs-linux.img<br />
}<br />
}}<br />
<br />
[[GRUB]] dark-magic will {{ic|1=set root=(tftp,10.0.0.1)}} automatically, so that the kernel and initramfs are transferred via TFTP without any additional configuration, though you might want to set it explicitly if you have any other non-tftp menuentries.<br />
<br />
{{Note|Modify your kernel line as-necessary, refer to [[PXELINUX]] for NBD-related options}}<br />
<br />
==== PXELINUX ====<br />
<br />
PXELINUX is provided by {{Pkg|syslinux}}, see [[PXELINUX]] for details.<br />
<br />
=== Additional mountpoints ===<br />
<br />
==== NBD root ====<br />
<br />
In late boot, you will want to switch your root filesystem mount to both {{ic|rw}}, and enable {{ic|1=compress=lzo}}, for much improved disk performance in comparison to [[NFS]].<br />
<br />
{{hc|# vim "$root/etc/fstab"|2=<br />
/dev/nbd0 / btrfs rw,noatime,compress=lzo 0 0<br />
}}<br />
<br />
==== Program state directories ====<br />
<br />
{{Accuracy|systemd does not use persistent logging by default when /var/log/journal is in tmpfs and/or does not exist}}<br />
<br />
You could mount {{ic|/var/log}}, for example, as tmpfs so that logs from multiple hosts do not mix unpredictably, and do the same with {{ic|/var/spool/cups}}, so the 20 instances of cups using the same spool do not fight with each other and make 1,498 print jobs and eat an entire ream of paper (or worse: toner cartridge) overnight.<br />
<br />
{{hc|# vim "$root/etc/fstab"|2=<br />
tmpfs /var/log tmpfs nodev,nosuid 0 0<br />
tmpfs /var/spool/cups tmpfs nodev,nosuid 0 0}}<br />
<br />
It would be best to configure software that has some sort of state/database to use unique state/database storage directories for each host. If you wanted to run [http://puppetlabs.com/ puppet], for example, you could simply use the {{ic|%H}} specifier in the puppet unit file:<br />
<br />
{{hc|# vim "$root/etc/systemd/system/puppetagent.service"|2=<br />
[Unit]<br />
Description=Puppet agent<br />
Wants=basic.target<br />
After=basic.target network.target<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/run/puppet/agent.pid<br />
ExecStartPre=/usr/bin/install -d -o puppet -m 755 /run/puppet<br />
ExecStart=/usr/bin/puppet agent --vardir=/var/lib/puppet-%H --ssldir=/etc/puppet/ssl-%H<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
Puppet-agent creates vardir and ssldir if they do not exist.<br />
<br />
If neither of these approaches are appropriate, the last sane option would be to create a [https://www.freedesktop.org/wiki/Software/systemd/Generators systemd generator] that creates a mount unit specific to the current host (specifiers are not allowed in mount units, unfortunately).<br />
<br />
== Client boot ==<br />
<br />
=== NBD ===<br />
<br />
{{Accuracy|When using COW on the server, the clients all effectively have read-only mounts of the original filesystem; it should theoretically be safe to do a read-write mount on the NBD server}}<br />
<br />
If you are using NBD, you will need to umount the {{ic|arch.img}} before/while you boot your client.<br />
<br />
This makes things particularly interesting when it comes to kernel updates. You cannot have your client filesystem mounted while you are booting a client, but that also means you need to use a kernel separate from your client filesystem in order to build it.<br />
<br />
You will need to first copy {{ic|$root/boot}} from the client installation to your tftp root (i.e. {{ic|/srv/boot}}).<br />
<br />
# cp -r "$root/boot" /srv/boot<br />
<br />
You will then need to umount {{ic|$root}} before you start the client.<br />
<br />
# umount "$root"<br />
<br />
{{Note|To update the kernel in this setup, you either need to mount {{ic|/srv/boot}} using [[NFS]] in [[fstab]] on the client (prior to doing the kernel update) or mount your client filesystem after the client has disconnected from NBD}}<br />
<br />
== See also ==<br />
<br />
* [https://www.kernel.org/doc/html/latest/admin-guide/nfs/nfsroot.html kernel.org: Mounting the root filesystem via NFS (nfsroot)]<br />
* [https://wiki.syslinux.org/wiki/index.php/PXELINUX syslinux.org: pxelinux FAQ]</div>PXfhttps://wiki.archlinux.org/index.php?title=QEMU&diff=691998QEMU2021-08-17T08:32:55Z<p>PXf: /* Chrooting into arm/arm64 environment from x86_64 */ + wikilink systemd-nspawn</p>
<hr />
<div>[[Category:Emulation]]<br />
[[Category:Hypervisors]]<br />
[[de:QEMU]]<br />
[[es:QEMU]]<br />
[[fr:QEMU]]<br />
[[it:QEMU]]<br />
[[ja:QEMU]]<br />
[[zh-hans:QEMU]]<br />
[[zh-hant:QEMU]]<br />
{{Related articles start}}<br />
{{Related|:Category:Hypervisors}}<br />
{{Related|Libvirt}}<br />
{{Related|QEMU/Guest graphics acceleration}}<br />
{{Related|PCI passthrough via OVMF}}<br />
{{Related articles end}}<br />
<br />
According to the [https://wiki.qemu.org/Main_Page QEMU about page], "QEMU is a generic and open source machine emulator and virtualizer."<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|qemu}} package (or {{Pkg|qemu-headless}} for the version without GUI) and below optional packages for your needs:<br />
<br />
* {{Pkg|qemu-arch-extra}} - extra architectures support<br />
* {{Pkg|qemu-block-gluster}} - [[Glusterfs]] block support<br />
* {{Pkg|qemu-block-iscsi}} - [[iSCSI]] block support<br />
* {{Pkg|qemu-block-rbd}} - RBD block support <br />
* {{Pkg|samba}} - [[Samba|SMB/CIFS]] server support<br />
<br />
Alternatively, {{AUR|qemu-user-static}} exists as a usermode and static variant.<br />
<br />
=== QEMU variants ===<br />
<br />
QEMU is offered in several variants suited for different use cases.<br />
<br />
As a first classification, QEMU is offered in full-system and usermode emulation modes:<br />
<br />
; Full-system emulation<br />
: In this mode, QEMU emulates a full system, including one or several processors and various peripherals. It is more accurate but slower, and does not require the emulated OS to be Linux.<br />
: QEMU commands for full-system emulation are named {{ic|qemu-system-''target_architecture''}}, e.g. {{ic|qemu-system-x86_64}} for emulating intel 64-bit CPUs, {{ic|qemu-system-i386}} for intel 32 bits CPUs, {{ic|qemu-system-arm}} for ARM (32 bits), {{ic|qemu-system-aarch64}} for ARM64, etc.<br />
: If the target architecture matches the host CPU, this mode may still benefit from a significant speedup by using a hypervisor like [[#Enabling KVM|KVM]] or Xen.<br />
; [https://www.qemu.org/docs/master/user/main.html Usermode emulation]: In this mode, QEMU is able to invoke a Linux executable compiled for a (potentially) different architecture by leveraging the host system resources. There may be compatibility issues, e.g. some features may not be implemented, dynamically linked executables will not work out of the box (see [[#Chrooting into arm/arm64 environment from x86_64]] to address this) and only Linux is supported (although [https://wiki.winehq.org/Emulation Wine may be used] for running Windows executables).<br />
: QEMU commands for usermode emulation are named {{ic|qemu-''target_architecture''}}, e.g. {{ic|qemu-x86_64}} for emulating intel 64-bit CPUs.<br />
<br />
QEMU is offered in dynamically-linked and statically-linked variants:<br />
<br />
; Dynamically-linked (default): {{ic|qemu-*}} commands depend on the host OS libraries, so executables are smaller.<br />
; Statically-linked: {{ic|qemu-*}} commands can be copied to any Linux system with the same architecture.<br />
<br />
In the case of Arch Linux, full-system emulation is offered as:<br />
<br />
; Non-headless (default): This variant enables GUI features that require additional dependencies (like SDL or GTK).<br />
; Headless: This is a slimmer variant that does not require GUI (this is suitable e.g. for servers).<br />
<br />
Note that headless and non-headless versions install commands with the same name (e.g. {{ic|qemu-system-x86_64}}) and thus cannot be both installed at the same time.<br />
<br />
=== Details on packages offered in Arch Linux ===<br />
<br />
* The {{Pkg|qemu}} package provides the {{ic|x86_64}} architecture emulators for full-system emulation ({{ic|qemu-system-x86_64}}). The {{Pkg|qemu-arch-extra}} package provides the {{ic|x86_64}} usermode variant ({{ic|qemu-x86_64}}) and also for the rest of supported architectures it includes both full-system and usermode variants (e.g. {{ic|qemu-system-arm}} and {{ic|qemu-arm}}).<br />
* The headless versions of these packages (only applicable to full-system emulation) are {{Pkg|qemu-headless}} ({{ic|x86_64}}-only) and {{Pkg|qemu-headless-arch-extra}} (rest of architectures).<br />
* Full-system emulation can be expanded with some QEMU modules present in separate packages: {{Pkg|qemu-block-gluster}}, {{Pkg|qemu-block-iscsi}}, {{Pkg|qemu-block-rbd}} and {{Pkg|qemu-guest-agent}}.<br />
* The unofficial AUR package {{AUR|qemu-user-static}} provides a usermode and static variant for all target architectures supported by QEMU. A precompiled version of this package exists: {{AUR|qemu-user-static-bin}}. The installed QEMU commands are named {{ic|qemu-''target_architecture''-static}}, for example, {{ic|qemu-x86_64-static}} for intel 64-bit CPUs.<br />
<br />
{{Note|At present, Arch does not offer a full-system mode and statically linked variant (neither officially nor via AUR), as this is usually not needed.}}<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s).<br />
<br />
[[Libvirt]] provides a convenient way to manage QEMU virtual machines. See [[Libvirt#Client|list of libvirt clients]] for available front-ends.<br />
<br />
Other GUI front-ends for QEMU:<br />
<br />
* {{App|AQEMU|QEMU GUI written in Qt5.|https://github.com/tobimensch/aqemu|{{AUR|aqemu}}}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Accuracy|If I get the man page right the raw format only allocates the full size if the filesystem does not support "holes" or it is <br />
explicitly told to preallocate. See man qemu-img in section Notes.}} <br />
<br />
{{Tip|See [[Wikibooks:QEMU/Images]] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk.<br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. This image format also supports QEMU snapshotting functionality (see [[#Creating and managing snapshots via the monitor console]] for details). However, using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''qcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
{{Warning|If you store the hard disk images on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-on-Write (CoW)|Copy-on-Write]] for the directory before creating any images.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
<br />
$ qemu-img create -o backing_file=''img1.raw'',backing_fmt=''raw'' -f ''qcow2'' ''img1.cow''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
<br />
$ qemu-system-x86_64 ''img1.cow''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required.<br />
<br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like:<br />
<br />
$ qemu-img rebase -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked:<br />
<br />
$ qemu-img rebase -u -b ''/new/img1.raw'' ''/new/img1.cow''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the operating system installed on it unbootable. It is recommended to create a backup first.}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example, to increase image space by 10 GB, run:<br />
<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
After enlarging the disk image, you must use file system and partitioning tools inside the virtual machine to actually begin using the new space. When shrinking a disk image, you must '''first reduce the allocated file systems and partition sizes''' using the file system and partitioning tools inside the virtual machine and then shrink the disk image accordingly, otherwise shrinking the disk image will result in data loss! For a Windows guest, open the "create and format hard disk partitions" control panel.<br />
<br />
==== Converting an image ====<br />
<br />
You can convert an image to other formats using {{ic|qemu-img convert}}. This example shows how to convert a ''raw'' image to ''qcow2'':<br />
<br />
$ qemu-img convert -f raw -O qcow2 ''input''.img ''output''.qcow2<br />
<br />
This will not remove the original input file.<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly.<br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso'' bs=4k}}}}<br />
<br />
=== Installing the operating system ===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 guests, to install from a bootable ISO file as CD-ROM and a raw disk image:<br />
<br />
$ qemu-system-x86_64 -cdrom ''iso_image'' -boot order=d -drive file=''disk_image'',format=raw<br />
<br />
See {{man|1|qemu}} for more information about loading other media types (such as floppy, disk images or physical drives) and [[#Running virtualized system]] for other useful options.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Note|By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512M}} or {{ic|-m 2G}}.}}<br />
<br />
{{Tip|<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* When running QEMU in headless mode, it starts a local VNC server on port 5900 per default. You can use [[TigerVNC]] to connect to the guest OS: {{ic|vncviewer :5900}}<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.<br />
}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on guest's architecture) are used to run the virtualized guest. The usage is:<br />
<br />
$ qemu-system-x86_64 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{man|1|qemu}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt+g}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM (''Kernel-based Virtual Machine'') full virtualization must be supported by your Linux kernel and your hardware, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options. To check if KVM is enabled for a running VM, enter the [[#QEMU monitor]] and type {{ic|info kvm}}.<br />
<br />
{{Note|<br />
* The argument {{ic|1=accel=kvm}} of the {{ic|-machine}} option is equivalent to the {{ic|-enable-kvm}} or the {{ic|-accel kvm}} option.<br />
* CPU model {{ic|host}} requires KVM<br />
* If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.<br />
* KVM needs to be enabled in order to start Windows 7 and Windows 8 properly without a ''blue screen''.<br />
}}<br />
<br />
=== Enabling IOMMU (Intel VT-d/AMD-Vi) support ===<br />
<br />
First enable IOMMU, see [[PCI passthrough via OVMF#Setting up IOMMU]].<br />
<br />
Add {{ic|-device intel-iommu}} to create the IOMMU device:<br />
<br />
$ qemu-system-x86_64 '''-enable-kvm -machine q35 -device intel-iommu''' -cpu host ..<br />
<br />
{{Note|<br />
On Intel CPU based systems creating an IOMMU device in a QEMU guest with {{ic|-device intel-iommu}} will disable PCI passthrough with an error like: {{bc|Device at bus pcie.0 addr 09.0 requires iommu notifier which is currently not supported by intel-iommu emulation}} While adding the kernel parameter {{ic|1=intel_iommu=on}} is still needed for remapping IO (e.g. [[PCI passthrough via OVMF#Isolating the GPU|PCI passthrough with vfio-pci]]), {{ic|-device intel-iommu}} should not be set if PCI PCI passthrough is required.<br />
}}<br />
<br />
== Sharing data between host and guest ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[SMB]], [[Wikipedia:Network block device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[SMB]] or [[NFS]], or you can access the host's HTTP server, etc.<br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's port forwarding ===<br />
<br />
{{Note|QEMU's port forwarding is IPv4-only. IPv6 port forwarding is not implemented and the last patches were proposed in 2018.[https://lore.kernel.org/qemu-devel/1540512223-21199-1-git-send-email-max7255@yandex-team.ru/T/#u]}}<br />
<br />
QEMU can forward ports from the host to the guest to enable e.g. connecting from the host to an SSH server running on the guest.<br />
<br />
For example, to bind port 60022 on the host with port 22 (SSH) on the guest, start QEMU with a command like:<br />
<br />
$ qemu-system-x86_64 ''disk_image'' -nic user,hostfwd=tcp::60022-:22<br />
<br />
Make sure the sshd is running on the guest and connect with:<br />
<br />
$ ssh ''guest-user''@127.0.0.1 -p 60022<br />
<br />
You can use [[SSHFS]] to mount the guest's file system at the host for shared read and write access.<br />
<br />
To forward several ports, you just repeat the {{ic|hostfwd}} in the {{ic|-nic}} argument, e.g. for VNC's port:<br />
<br />
$ qemu-system-x86_64 ''disk_image'' -nic user,hostfwd=tcp::60022-:22,hostfwd=tcp::5900-:5900<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] on the host with an automatically generated {{ic|smb.conf}} file located in {{ic|/tmp/qemu-smb.''random_string''}} and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and is useful when you do not want to start the normal [[Samba]] service on the host, which the guest can also access if you have set up shares on it.<br />
<br />
Only a single directory can be set as shared with the option {{ic|1=smb=}}, but adding more directories (even while the virtual machine is running) could be as easy as creating symbolic links in the shared directory if QEMU configured SMB to follow symbolic links. It does not do so, but the configuration of the running SMB server can be changed as described below.<br />
<br />
''Samba'' must be installed on the host. To enable this feature, start QEMU with a command like:<br />
<br />
$ qemu-system-x86_64 -nic user,id=nic0,smb=''shared_dir_path'' ''disk_image''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
{{Note|<br />
* If you are using sharing options multiple times like {{ic|1=-net user,smb=''shared_dir_path1'' -net user,smb=''shared_dir_path2''}} or {{ic|1=-net user,smb=''shared_dir_path1'',smb=''shared_dir_path2''}} then it will share only the last defined one.<br />
* If you cannot access the shared folder and the guest system is Windows, check that the [http://ecross.mvps.org/howto/enable-netbios-over-tcp-ip-with-windows.htm NetBIOS protocol is enabled] and that a firewall does not block [https://technet.microsoft.com/en-us/library/cc940063.aspx ports] used by the NetBIOS protocol.<br />
* If you cannot access the shared folder and the guest system is Windows 10 Enterprise or Education or Windows Server 2016, [https://support.microsoft.com/en-us/help/4046019 enable guest access].<br />
}}<br />
<br />
One way to share multiple directories and to add or remove them while the virtual machine is running, is to share an empty directory and create/remove symbolic links to the directories in the shared directory. For this to work, the configuration of the running SMB server can be changed with the following script, which also allows the execution of files on the guest that are not set executable on the host:<br />
<br />
#!/bin/bash<br />
eval $(ps h -C smbd -o pid,args | grep /tmp/qemu-smb | gawk '{print "pid="$1";conf="$6}')<br />
echo "[global]<br />
allow insecure wide links = yes<br />
[qemu]<br />
follow symlinks = yes<br />
wide links = yes<br />
acl allow execute always = yes" >> $conf<br />
# in case the change is not detected automatically:<br />
smbcontrol --configfile=$conf $pid reload-config<br />
<br />
This can be applied to the running server started by qemu only after the guest has connected to the network drive the first time. An alternative to this method is to add additional shares to the configuration file like so:<br />
<br />
echo "[''myshare'']<br />
path=''another_path''<br />
read only=no<br />
guest ok=yes<br />
force user=''username''" >> $conf<br />
<br />
This share will be available on the guest as {{ic|\\10.0.2.4\''myshare''}}.<br />
<br />
=== Using filesystem passthrough and VirtFS ===<br />
<br />
See the [https://wiki.qemu.org/Documentation/9psetup QEMU documentation].<br />
<br />
=== Host file sharing with virtiofsd ===<br />
<br />
{{Style|See [[Help:Style/Formatting and punctuation]].}}<br />
<br />
virtiofsd is shipped with QEMU package. Documentation is available [https://qemu-stsquad.readthedocs.io/en/docs-next/tools/virtiofsd.html online] or "/usr/share/doc/qemu/tools/virtiofsd.html" on local file system with QEMU installed.<br />
<br />
Add user that runs qemu to 'kvm' group, because it needs to access virtiofsd socket. You might have to logout for change to take effect.<br />
<br />
{{Accuracy|Running services as root is not secure. Also the process should be wrapped in a systemd service.}}<br />
<br />
Start as virtiofsd as root:<br />
<br />
# /usr/lib/qemu/virtiofsd --socket-path=/var/run/qemu-vm-001.sock -o source=/tmp/vm-001 -o cache=always<br />
<br />
where<br />
<br />
* /var/run/qemu-vm-001.sock is a socket file,<br />
* /tmp/vm-001 is a shared directory between host and guest vm.<br />
<br />
The created socket file has root only access permission. Give group kvm access to it with:<br />
<br />
# chgrp kvm qemu-vm-001.sock; chmod g+rxw qemu-vm-001.sock<br />
<br />
Add the following configuration options when starting VM:<br />
<br />
-object memory-backend-memfd,id=mem,size=4G,share=on \<br />
-numa node,memdev=mem \<br />
-chardev socket,id=char0,path=/var/run/qemu-vm-001.sock \<br />
-device vhost-user-fs-pci,chardev=char0,tag=myfs<br />
<br />
where<br />
<br />
{{Expansion|Explain the remaining options (or remove them if they are not necessary).}}<br />
<br />
* size=4G shall match size specified with '-m 4G' option,<br />
* /var/run/qemu-vm-001.sock points to socket file started earlier,<br />
<br />
{{Style|The section should not be specific to Windows.}}<br />
<br />
Remember, that guest must be configured to enable sharing. For windows there are [https://virtio-fs.gitlab.io/howto-windows.html instructions]. Once configured, windows will have Z: drive mapped automatically with shared directory content. <br />
<br />
Your Windows 10 guest system is properly configured if it has:<br />
<br />
* VirtioFSSService windows service,<br />
* WinFsp.Launcher windows service,<br />
* VirtIO FS Device driver under "System devices" in Windows "Device Manager".<br />
<br />
If the above installed and Z: drive is still not listed, try repairing "Virtio-win-guest-tools" in Windows add/remove programs.<br />
<br />
=== Mounting a partition of the guest on the host ===<br />
<br />
It can be useful to mount a drive image under the host system, it can be a way to transfer files in and out of the guest. This should be done when the virtual machine is not running.<br />
<br />
The procedure to mount the drive on the host depends on the type of qemu image, ''raw'' or ''qcow2''. We detail thereafter the steps to mount a drive in the two formats in [[#Mounting a partition from a raw image]] and [[#Mounting a partition from a qcow2 image]]. For the full documentation see [[Wikibooks:QEMU/Images#Mounting an image on the host]].<br />
<br />
{{Warning|You must unmount the partitions before running the virtual machine again. Otherwise, data corruption is very likely to occur.}}<br />
<br />
==== Mounting a partition from a raw image ====<br />
<br />
It is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices.<br />
<br />
===== With manually specifying byte offset =====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
===== With loop module autodetecting partitions =====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* [[Kernel_modules#Manual_module_handling|Unload]] the {{ic|loop}} kernel module, and load it with the {{ic|1=max_part=15}} parameter set. Additionally, the maximum number of loop devices can be controlled with the {{ic|max_loop}} parameter.<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
<br />
# losetup -f -P ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
To mount the disk image with ''udisksctl'', see [[Udisks#Mount loop devices]].<br />
<br />
===== With kpartx =====<br />
<br />
''kpartx'' from the {{Pkg|multipath-tools}} package can read a partition table on a device and create a new device for each partition. For example:<br />
<br />
# kpartx -a ''disk_image''<br />
<br />
This will setup the loopback device and create the necessary partition(s) device(s) in {{ic|/dev/mapper/}}.<br />
<br />
==== Mounting a partition from a qcow2 image ====<br />
<br />
We will use {{ic|qemu-nbd}}, which lets use the NBD (''network block device'') protocol to share the disk image.<br />
<br />
First, we need the ''nbd'' module loaded:<br />
<br />
# modprobe nbd max_part=16<br />
<br />
Then, we can share the disk and create the device entries:<br />
<br />
# qemu-nbd -c /dev/nbd0 ''/path/to/image.qcow2''<br />
<br />
Discover the partitions:<br />
<br />
# partprobe /dev/nbd0<br />
<br />
''fdisk'' can be used to get information regarding the different partitions in {{{ic|''nbd0''}}:<br />
<br />
{{hc|# fdisk -l /dev/nbd0|2=<br />
Disk /dev/nbd0: 25.2 GiB, 27074281472 bytes, 52879456 sectors<br />
Units: sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disklabel type: dos<br />
Disk identifier: 0xa6a4d542<br />
<br />
Device Boot Start End Sectors Size Id Type<br />
/dev/nbd0p1 * 2048 1026047 1024000 500M 7 HPFS/NTFS/exFAT<br />
/dev/nbd0p2 1026048 52877311 51851264 24.7G 7 HPFS/NTFS/exFAT}}<br />
<br />
Then mount any partition of the drive image, for example the partition 2:<br />
<br />
# mount /dev/nbd0'''p2''' ''mountpoint''<br />
<br />
After the usage, it is important to unmount the image and reverse previous steps, i.e. unmount the partition and disconnect the nbd device:<br />
<br />
# umount ''mountpoint''<br />
# qemu-nbd -d /dev/nbd0<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you must either change the owner of the partition's device file to that user, add that user to the ''disk'' group, or use [[ACL]] for more fine-grained access control.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with an MBR. Such a virtual machine can be booted either by: [[#Specifying kernel and initrd manually]], [[#Simulating a virtual disk with MBR]], [[#Using the device-mapper]], [[#Using a linear RAID]] or [[#Using a Network Block Device]].<br />
<br />
==== Specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
<br />
{{Note|In this example, it is the '''host's''' images that are being used, not the guest's. If you wish to use the guest's images, either mount {{ic|/dev/sda3}} read-only (to protect the file system from the host) and specify the {{ic|/full/path/to/images}} or use some kexec hackery in the guest to reload the guest's kernel (extends boot time). }}<br />
<br />
$ qemu-system-x86_64 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
When there are multiple [[kernel parameters]] to be passed to the {{ic|-append}} option, they need to be quoted using single or double quotes. For example:<br />
<br />
... -append 'root=/dev/sda1 console=ttyS0'<br />
<br />
==== Simulating a virtual disk with MBR ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate an MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
For the following, suppose you have a plain, unmounted {{ic|/dev/hda''N''}} partition with some file system on it you wish to make part of a QEMU disk image. The trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image. More generally, the partition can be any part of a larger simulated disk, in particular a block device that simulates the original physical disk but only exposes {{ic|/dev/hda''N''}} to the virtual machine.<br />
<br />
A virtual disk of this type can be represented by a VMDK file that contains references to (a copy of) the MBR and the partition, but QEMU does not support this VMDK format. For instance, a virtual disk [https://www.virtualbox.org/manual/ch09.html#rawdisk created by]<br />
<br />
$ VBoxManage internalcommands createrawvmdk -filename ''/path/to/file.vmdk'' -rawdisk /dev/hda<br />
<br />
will be rejected by QEMU with the error message<br />
<br />
Unsupported image type 'partitionedDevice'<br />
<br />
Note that {{ic|VBoxManage}} creates two files, {{ic|''file.vmdk''}} and {{ic|''file-pt.vmdk''}}, the latter being a copy of the MBR, to which the text file {{ic|file.vmdk}} points. Read operations outside the target partition or the MBR would give zeros, while written data would be discarded.<br />
<br />
===== Using the device-mapper =====<br />
<br />
A method that is similar to the use of a VMDK descriptor file uses the [https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/index.html device-mapper] to prepend a loop device attached to the MBR file to the target partition. In case we do not need our virtual disk to have the same size as the original, we first create a file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=2048<br />
<br />
Here, a 1 MB (2048 * 512 bytes) file is created in accordance with partition alignment policies used by modern disk partitioning tools. For compatibility with older partitioning software, 63 sectors instead of 2048 might be required. The MBR only needs a single 512 bytes block, the additional free space can be used for a BIOS boot partition and, in the case of a hybrid partitioning scheme, for a GUID Partition Table. Then, we attach a loop device to the MBR file:<br />
<br />
# losetup --show -f ''/path/to/mbr''<br />
/dev/loop0<br />
<br />
In this example, the resulting device is {{ic|/dev/loop0}}. The device mapper is now used to join the MBR and the partition:<br />
<br />
# echo "0 2048 linear /dev/loop0 0<br />
2048 `blockdev --getsz /dev/hda''N''` linear /dev/hda''N'' 0" | dmsetup create qemu<br />
<br />
The resulting {{ic|/dev/mapper/qemu}} is what we will use as a QEMU raw disk image. Additional steps are required to create a partition table (see the section that describes the use of a linear RAID for an example) and boot loader code on the virtual disk (which will be stored in {{ic|''/path/to/mbr''}}).<br />
<br />
The following setup is an example where the position of {{ic|/dev/hda''N''}} on the virtual disk is to be the same as on the physical disk and the rest of the disk is hidden, except for the MBR, which is provided as a copy:<br />
<br />
# dd if=/dev/hda count=1 of=''/path/to/mbr''<br />
# loop=`losetup --show -f ''/path/to/mbr''`<br />
# start=`blockdev --report /dev/hda''N'' | tail -1 | awk '{print $5}'`<br />
# size=`blockdev --getsz /dev/hda''N''`<br />
# disksize=`blockdev --getsz /dev/hda`<br />
# echo "0 1 linear $loop 0<br />
1 $((start-1)) zero<br />
$start $size linear /dev/hda''N'' 0<br />
$((start+size)) $((disksize-start-size)) zero" | dmsetup create qemu<br />
<br />
The table provided as standard input to {{ic|dmsetup}} has a similar format as the table in a VDMK descriptor file produced by {{ic|VBoxManage}} and can alternatively be loaded from a file with {{ic|dmsetup create qemu --table ''table_file''}}. To the virtual machine, only {{ic|/dev/hda''N''}} is accessible, while the rest of the hard disk reads as zeros and discards written data, except for the first sector. We can print the table for {{ic|/dev/mapper/qemu}} with {{ic|dmsetup table qemu}} (use {{ic|udevadm info -rq name /sys/dev/block/''major'':''minor''}} to translate {{ic|''major'':''minor''}} to the corresponding {{ic|/dev/''blockdevice''}} name). Use {{ic|dmsetup remove qemu}} and {{ic|losetup -d $loop}} to delete the created devices.<br />
<br />
A situation where this example would be useful is an existing Windows XP installation in a multi-boot configuration and maybe a hybrid partitioning scheme (on the physical hardware, Windows XP could be the only operating system that uses the MBR partition table, while more modern operating systems installed on the same computer could use the GUID Partition Table). Windows XP supports hardware profiles, so that that the same installation can be used with different hardware configurations alternatingly (in this case bare metal vs. virtual) with Windows needing to install drivers for newly detected hardware only once for every profile. Note that in this example the boot loader code in the copied MBR needs to be updated to directly load Windows XP from {{ic|/dev/hda''N''}} instead of trying to start the multi-boot capable boot loader (like GRUB) present in the original system. Alternatively, a copy of the boot partition containing the boot loader installation can be included in the virtual disk the same way as the MBR.<br />
<br />
===== Using a linear RAID =====<br />
<br />
You can also do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: <br />
<br />
First, you create some small file to hold the MBR:<br />
<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hda''N''}} disk image using software RAID:<br />
<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu.<br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image:<br />
<br />
$ qemu-system-x86_64 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
===== Using a Network Block Device =====<br />
<br />
With [https://www.kernel.org/doc/html/latest/admin-guide/blockdev/nbd.html Network Block Device], Linux can use a remote server as one of its block device. You may use {{ic|nbd-server}} (from the {{pkg|nbd}} package) to create an MBR wrapper for QEMU.<br />
<br />
Assuming you have already set up your MBR wrapper file like above, rename it to {{ic|wrapper.img.0}}. Then create a symbolic link named {{ic|wrapper.img.1}} in the same directory, pointing to your partition. Then put the following script in the same directory:<br />
<br />
#!/bin/sh<br />
dir="$(realpath "$(dirname "$0")")"<br />
cat >wrapper.conf <<EOF<br />
[generic]<br />
allowlist = true<br />
listenaddr = 127.713705<br />
port = 10809<br />
<br />
[wrap]<br />
exportname = $dir/wrapper.img<br />
multifile = true<br />
EOF<br />
<br />
nbd-server \<br />
-C wrapper.conf \<br />
-p wrapper.pid \<br />
"$@"<br />
<br />
The {{ic|.0}} and {{ic|.1}} suffixes are essential; the rest can be changed. After running the above script (which you may need to do as root to make sure nbd-server is able to access the partition), you can launch QEMU with:<br />
<br />
qemu-system-x86_64 -drive file=nbd:127.713705:10809:exportname=wrap ''[...]''<br />
<br />
== Networking ==<br />
<br />
{{Style|Network topologies (sections [[#Host-only networking]], [[#Internal networking]] and info spread out across other sections) should not be described alongside the various virtual interfaces implementations, such as [[#User-mode networking]], [[#Tap networking with QEMU]], [[#Networking with VDE2]].}}<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [https://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-x86_64 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
* Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
* Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
{{bc|1=<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-x86_64 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
}}<br />
<br />
* Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|2=<br />
#!/usr/bin/env python<br />
# usage: qemu-mac-hasher.py <VMName><br />
<br />
import sys<br />
import zlib<br />
<br />
crc = str(hex(zlib.crc32(sys.argv[1].encode("utf-8"))))[-8:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-x86_64 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU.<br />
<br />
{{Note|ICMPv6 will not work, as support for it is not implemented: {{ic|Slirp: external icmpv6 not supported yet}}. [[Ping]]ing an IPv6 address will not work.}}<br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, redirecting host ports to the guest (for example to allow SSH connections to the guest) or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
{{Note|If the host system uses [[systemd-networkd]], make sure to symlink the {{ic|/etc/resolv.conf}} file as described in [[systemd-networkd#Required services and setup]], otherwise the DNS lookup in the guest system will not work.}}<br />
<br />
{{Tip|To use the virtio driver with user-mode networking, the option is: {{ic|1=-nic user,model=virtio-net-pci}}.}}<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the [[Firewalls|precautions]] you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, a better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
As indicated in the user-mode networking section, tap devices offer higher networking performance than user-mode. If the guest OS supports virtio network driver, then the networking performance will be increased considerably as well. Supposing the use of the tap0 device, that the virtio driver is used on the guest, and that no scripts are used to help start/stop networking, next is part of the qemu command one should see:<br />
<br />
-device virtio-net,netdev=network0 -netdev tap,id=network0,ifname=tap0,script=no,downscript=no<br />
<br />
But if already using a tap device with virtio networking driver, one can even boost the networking performance by enabling vhost, like:<br />
<br />
-device virtio-net,netdev=network0 -netdev tap,id=network0,ifname=tap0,script=no,downscript=no,vhost=on<br />
<br />
See [https://web.archive.org/web/20160222161955/http://www.linux-kvm.com:80/content/how-maximize-virtio-net-performance-vhost-net] for more information.<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet sharing#Enable NAT]] page.<br />
* See [[Network bridge]] for information on creating bridge.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
<br />
{{bc|1=<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface=br0 --bind-interfaces --dhcp-range=172.20.0.2,172.20.255.254<br />
}}<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
By default iptables would drop packets in the bridge network. You may need to use such iptables rule to allow packets in a bridged network:<br />
<br />
# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|<br />
* See [[Network bridge]] for information on creating bridge.<br />
* See https://wiki.qemu.org/Features/HelperNetworking for more information on QEMU's network helper.<br />
}}<br />
<br />
First, create a configuration file containing the names of all bridges to be used by QEMU:<br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''br0''<br />
allow ''br1''<br />
...}}<br />
<br />
Make sure {{ic|/etc/qemu/}} has {{ic|755}} [[permissions]]. [https://gitlab.com/qemu-project/qemu/-/issues/515 QEMU issues] and [https://www.gns3.com/community/discussions/gns3-cannot-work-with-qemu GNS3 issues] may arise if this is not the case.<br />
<br />
Now start the VM; the most basic usage to run QEMU with the default network helper and default bridge {{ic|br0}}:<br />
<br />
$ qemu-system-x86_64 -nic bridge ''[...]''<br />
<br />
Using the bridge {{ic|br1}} and the virtio driver:<br />
<br />
$ qemu-system-x86_64 -nic bridge,br=''br1'',model=virtio-net-pci ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Style|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [https://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-x86_64 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null<br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
<br />
$ run-qemu -hda ''myvm.img'' -m 512<br />
<br />
* It is recommended for performance and security reasons to disable the [http://ebtables.netfilter.org/documentation/bridge-nf.html firewall on the bridge]:<br />
<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [https://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Automatic module loading with systemd]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
==== Network sharing between physical device and a Tap device through iptables ====<br />
<br />
{{Merge|Internet_sharing|Duplication, not specific to QEMU.}}<br />
<br />
Bridged networking works fine between a wired interface (Eg. eth0), and it is easy to setup. However if the host gets connected to the network through a wireless device, then bridging is not possible.<br />
<br />
See [[Network bridge#Wireless interface on a bridge]] as a reference.<br />
<br />
One way to overcome that is to setup a tap device with a static IP, making linux automatically handle the routing for it, and then forward traffic between the tap interface and the device connected to the network through iptables rules.<br />
<br />
See [[Internet sharing]] as a reference.<br />
<br />
There you can find what is needed to share the network between devices, included tap and tun ones. The following just hints further on some of the host configurations required. As indicated in the reference above, the client needs to be configured for a static IP, using the IP assigned to the tap interface as the gateway. The caveat is that the DNS servers on the client might need to be manually edited if they change when changing from one host device connected to the network to another.<br />
<br />
To allow IP forwarding on every boot, one need to add the following lines to sysctl configuration file inside {{ic|/etc/sysctl.d}}:<br />
<br />
net.ipv4.ip_forward = 1<br />
net.ipv6.conf.default.forwarding = 1<br />
net.ipv6.conf.all.forwarding = 1<br />
<br />
The iptables rules can look like:<br />
<br />
# Forwarding from/to outside<br />
iptables -A FORWARD -i ${INT} -o ${EXT_0} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_1} -j ACCEPT<br />
iptables -A FORWARD -i ${INT} -o ${EXT_2} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_0} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_1} -o ${INT} -j ACCEPT<br />
iptables -A FORWARD -i ${EXT_2} -o ${INT} -j ACCEPT<br />
# NAT/Masquerade (network address translation)<br />
iptables -t nat -A POSTROUTING -o ${EXT_0} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_1} -j MASQUERADE<br />
iptables -t nat -A POSTROUTING -o ${EXT_2} -j MASQUERADE<br />
<br />
The prior supposes there are 3 devices connected to the network sharing traffic with one internal device, where for example:<br />
<br />
INT=tap0<br />
EXT_0=eth0<br />
EXT_1=wlan0<br />
EXT_2=tun0<br />
<br />
The prior shows a forwarding that would allow sharing wired and wireless connections with the tap device.<br />
<br />
The forwarding rules shown are stateless, and for pure forwarding. One could think of restricting specific traffic, putting a firewall in place to protect the guest and others. However those would decrease the networking performance, while a simple bridge does not include any of that.<br />
<br />
Bonus: Whether the connection is wired or wireless, if one gets connected through VPN to a remote site with a tun device, supposing the tun device opened for that connection is tun0, and the prior iptables rules are applied, then the remote connection gets also shared with the guest. This avoids the need for the guest to also open a VPN connection. Again, as the guest networking needs to be static, then if connecting the host remotely this way, one most probably will need to edit the DNS servers on the guest.<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Style|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [https://wiki.virtualsquare.org/ the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package.<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-x86_64 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here<br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep vde_switch | xargs kill -TERM<br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can [[start]] {{ic|qemu-network-env.service}} as usual.<br />
<br />
==== Alternative method ====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-x86_64 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [https://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|2=<br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
}}<br />
<br />
The following custom systemd service can be used to create and activate a VDE2 tap interface for users in the {{ic|users}} user group.<br />
<br />
{{hc|/etc/systemd/system/vde2@.service|2=<br />
[Unit]<br />
Description=Network Connectivity for %i<br />
Wants=network.target<br />
Before=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/vde_switch -tap %i -daemon -mod 660 -group users<br />
ExecStart=/usr/bin/ip link set dev %i up<br />
ExecStop=/usr/bin/ip addr flush dev %i<br />
ExecStop=/usr/bin/ip link set dev %i down<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
=== Shorthand configuration ===<br />
<br />
If you are using QEMU with various networking options a lot, you probably have created a lot of {{ic|-netdev}} and {{ic|-device}} argument pairs, which gets quite repetitive. You can instead use the {{ic|-nic}} argument to combine {{ic|-netdev}} and {{ic|-device}} together, so that, for example, these arguments:<br />
<br />
-netdev tap,id=network0,ifname=tap0,script=no,downscript=no,vhost=on -device virtio-net-pci,netdev=network0<br />
<br />
become:<br />
<br />
-nic tap,script=no,downscript=no,vhost=on,model=virtio-net-pci<br />
<br />
Notice the lack of network IDs, and that the device was created with {{ic|1=model=}}. The first half of the {{ic|-nic}} parameters are {{ic|-netdev}} parameters, whereas the second half (after {{ic|1=model=}}) are related with the device. The same parameters (for example, {{ic|1=smb=}}) are used. To completely disable the networking use {{ic|-nic none}}.<br />
<br />
See [https://qemu.weilnetz.de/doc/qemu-doc.html#Network-options QEMU networking documentation]{{Dead link|2021|05|17|status=404}} for more information on parameters you can use.<br />
<br />
== Graphic card ==<br />
<br />
QEMU can emulate a standard graphic card text mode using {{ic|-curses}} command line option. This allows to type text and see text output directly inside a text terminal. Alternatively, {{ic|-nographic}} serves a similar purpose.<br />
<br />
QEMU can emulate several types of VGA card. The card type is passed in the {{ic|-vga ''type''}} command line option and can be {{ic|std}}, {{ic|qxl}}, {{ic|vmware}}, {{ic|virtio}}, {{ic|cirrus}} or {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels without requiring guest drivers. This is the default since QEMU 2.2.<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, pass the {{ic|-vga qxl}} option and install drivers in the guest. You may want to use [[#SPICE]] for improved graphical performance when using QXL.<br />
<br />
On Linux guests, the {{ic|qxl}} and {{ic|bochs_drm}} kernel modules must be loaded in order to gain a decent performance.<br />
<br />
Default VGA memory size for QXL devices is 16M which is sufficient to drive resolutions approximately up to QHD (2560x1440). To enable higher resolutions, [[#Multi-monitor support|increase vga_memmb]].<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. Install the VMware drivers {{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests.<br />
<br />
=== virtio ===<br />
<br />
{{ic|virtio-vga}} / {{ic|virtio-gpu}} is a paravirtual 3D graphics driver based on [https://virgil3d.github.io/ virgl]. Currently a work in progress, supporting only very recent (>= 4.4) Linux guests with {{Pkg|mesa}} (>=11.2) compiled with the option {{ic|1=gallium-drivers=virgl}}.<br />
<br />
To enable 3D acceleration on the guest system select this vga with {{ic|-vga virtio}} and enable the opengl context in the display device with {{ic|1=-display sdl,gl=on}} or {{ic|1=-display gtk,gl=on}} for the sdl and gtk display output respectively. Successful configuration can be confirmed looking at the kernel log in the guest:<br />
<br />
{{hc|# dmesg {{!}} grep drm |<br />
[drm] pci: virtio-vga detected<br />
[drm] virgl 3d acceleration enabled<br />
}}<br />
<br />
=== cirrus ===<br />
<br />
The cirrus graphical adapter was the default [https://wiki.qemu.org/ChangeLog/2.2#VGA before 2.2]. It [https://www.kraxel.org/blog/2014/10/qemu-using-cirrus-considered-harmful/ should not] be used on modern systems.<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
== SPICE ==<br />
<br />
The [https://www.spice-space.org/ SPICE project] aims to provide a complete open source solution for remote access to virtual machines in a seamless way.<br />
<br />
=== Enabling SPICE support on the host ===<br />
<br />
The following is an example of booting with SPICE as the remote desktop protocol, including the support for copy and paste from host:<br />
<br />
$ qemu-system-x86_64 -vga qxl -device virtio-serial-pci -spice port=5930,disable-ticketing=on -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The parameters have the following meaning:<br />
<br />
# {{ic|-device virtio-serial-pci}} adds a virtio-serial device<br />
# {{ic|1=-spice port=5930,disable-ticketing=on}} set TCP port {{ic|5930}} for spice channels listening and allow client to connect without authentication{{Tip|Using [[wikipedia:Unix_socket|Unix sockets]] instead of TCP ports does not involve using network stack on the host system. It does not imply that packets are encapsulated and decapsulated to use the network and the related protocol. The sockets are identified solely by the inodes on the hard drive. It is therefore considered better for performance. Use instead {{ic|1=-spice unix=on,addr=/tmp/vm_spice.socket,disable-ticketing=on}}.}}<br />
# {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in the virtio-serial device,<br />
# {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port. It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Connecting to the guest with a SPICE client ===<br />
<br />
A SPICE client is necessary to connect to the guest. In Arch, the following clients are available:<br />
<br />
{{App|virt-viewer|SPICE client recommended by the protocol developers, a subset of the virt-manager project.|https://virt-manager.org/|{{Pkg|virt-viewer}}}}<br />
<br />
{{App|spice-gtk|SPICE GTK client, a subset of the SPICE project. Embedded into other applications as a widget.|https://www.spice-space.org/|{{Pkg|spice-gtk}}}}<br />
<br />
For clients that run on smartphone or on other platforms, refer to the ''Other clients'' section in [https://www.spice-space.org/download.html spice-space download].<br />
<br />
==== Manually running a SPICE client ====<br />
<br />
One way of connecting to a guest listening on Unix socket {{ic|/tmp/vm_spice.socket}} is to manually run the SPICE client using {{ic|$ remote-viewer spice+unix:///tmp/vm_spice.socket}} or {{ic|1=$ spicy --uri="spice+unix:///tmp/vm_spice.socket"}}, depending on the desired client. Since QEMU in SPICE mode acts similarly to a remote desktop server, it may be more convenient to run QEMU in daemon mode with the {{ic|-daemonize}} parameter.<br />
<br />
{{Tip|To connect to the guest through SSH tunelling, the following type of command can be used: {{bc|$ ssh -fL 5999:localhost:5930 ''my.domain.org'' sleep 10; spicy -h 127.0.0.1 -p 5999}}<br />
This example connects ''spicy'' to the local port {{ic|5999}} which is forwarded through SSH to the guest's SPICE server located at the address ''my.domain.org'', port {{ic|5930}}.<br />
Note the {{ic|-f}} option that requests ssh to execute the command {{ic|sleep 10}} in the background. This way, the ssh session runs while the client is active and auto-closes once the client ends.<br />
}}<br />
<br />
==== Running a SPICE client with QEMU ====<br />
<br />
QEMU can automatically start a SPICE client with an appropriate socket, if the display is set to SPICE with the {{ic|-display spice-app}} parameter. This will use the system's default SPICE client as the viewer, determined by your [[XDG_MIME_Applications#mimeapps.list|mimeapps.list]] files.<br />
<br />
=== Enabling SPICE support on the guest ===<br />
<br />
For '''Arch Linux guests''', for improved support for multiple monitors or clipboard sharing, the following packages should be installed:<br />
* {{Pkg|spice-vdagent}}: Spice agent xorg client that enables copy and paste between client and X-session and more.<br />
* {{Pkg|xf86-video-qxl}}: Xorg X11 qxl video driver<br />
For guests under '''other operating systems''', refer to the ''Guest'' section in [https://www.spice-space.org/download.html spice-space download].<br />
<br />
=== Password authentication with SPICE ===<br />
<br />
If you want to enable password authentication with SPICE you need to remove {{ic|disable-ticketing}} from the {{ic|-spice}} argument and instead add {{ic|1=password=''yourpassword''}}. For example:<br />
<br />
$ qemu-system-x86_64 -vga qxl -spice port=5900,password=''yourpassword'' -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
Your SPICE client should now ask for the password to be able to connect to the SPICE server.<br />
<br />
=== TLS encrypted communication with SPICE ===<br />
<br />
You can also configure TLS encryption for communicating with the SPICE server. First, you need to have a directory which contains the following files (the names must be exactly as indicated):<br />
<br />
* {{ic|ca-cert.pem}}: the CA master certificate.<br />
* {{ic|server-cert.pem}}: the server certificate signed with {{ic|ca-cert.pem}}.<br />
* {{ic|server-key.pem}}: the server private key.<br />
<br />
An example of generation of self-signed certificates with your own generated CA for your server is shown in the [https://www.spice-space.org/spice-user-manual.html#_generating_self_signed_certificates Spice User Manual].<br />
<br />
Afterwards, you can run QEMU with SPICE as explained above but using the following {{ic|-spice}} argument: {{ic|1=-spice tls-port=5901,password=''yourpassword'',x509-dir=''/path/to/pki_certs''}}, where {{ic|''/path/to/pki_certs''}} is the directory path that contains the three needed files shown earlier.<br />
<br />
It is now possible to connect to the server using {{pkg|virt-viewer}}:<br />
<br />
$ remote-viewer spice://''hostname''?tls-port=5901 --spice-ca-file=''/path/to/ca-cert.pem'' --spice-host-subject="C=''XX'',L=''city'',O=''organization'',CN=''hostname''" --spice-secure-channels=all<br />
<br />
Keep in mind that the {{ic|--spice-host-subject}} parameter needs to be set according to your {{ic|server-cert.pem}} subject. You also need to copy {{ic|ca-cert.pem}} to every client to verify the server certificate.<br />
<br />
{{Tip|You can get the subject line of the server certificate in the correct format for {{ic|--spice-host-subject}} (with entries separated by commas) using the following command: {{bc|<nowiki>$ openssl x509 -noout -subject -in server-cert.pem | cut -d' ' -f2- | sed 's/\///' | sed 's/\//,/g'</nowiki>}}<br />
}}<br />
<br />
The equivalent {{Pkg|spice-gtk}} command is:<br />
<br />
$ spicy -h ''hostname'' -s 5901 --spice-ca-file=ca-cert.pem --spice-host-subject="C=''XX'',L=''city'',O=''organization'',CN=''hostname''" --spice-secure-channels=all<br />
<br />
== VNC ==<br />
<br />
One can add the {{ic|-vnc :''X''}} option to have QEMU redirect the VGA display to the VNC session. Substitute {{ic|''X''}} for the number of the display (0 will then listen on 5900, 1 on 5901...).<br />
<br />
$ qemu-system-x86_64 -vnc :0<br />
<br />
An example is also provided in the [[#Starting QEMU virtual machines on boot]] section.<br />
{{Warning|The default VNC server setup does not use any form of authentication. Any user can connect from any host.}}<br />
<br />
=== Basic password authentication ===<br />
<br />
An access password can be setup easily by using the {{ic|password}} option. The password must be indicated in the QEMU monitor and connection is only possible once the password is provided.<br />
<br />
$ qemu-system-x86_64 -vnc :0,password -monitor stdio<br />
<br />
In the QEMU monitor, password is set using the command {{ic|change vnc password}} and then indicating the password.<br />
<br />
The following command line directly runs vnc with a password:<br />
<br />
$ printf "change vnc password\n%s\n" MYPASSWORD | qemu-system-x86_64 -vnc :0,password -monitor stdio<br />
<br />
{{Note|The password is limited to 8 characters and can be guessed through brute force attack. More elaborated protection is strongly recommended for public network.}}<br />
<br />
== Audio ==<br />
<br />
=== Host ===<br />
<br />
The {{ic|-audiodev}} flag sets the audio backend driver and its options. The list of available audio backend drivers and their optional settings is detailed in the {{man|1|qemu}}. man page.<br />
<br />
At the bare minimum, you need to choose a driver and set an id.<br />
<br />
-audiodev pa,id=snd0<br />
<br />
=== Guest ===<br />
<br />
==== With audiodev ====<br />
<br />
===== Intel HD Audio =====<br />
<br />
For Intel HD Audio emulation add both controller and codec devices. To list the available Intel HDA Audio devices:<br />
<br />
$ qemu-system-x86_64 -device help | grep hda<br />
<br />
Add the audio controller<br />
<br />
-device ich9-intel-hda<br />
<br />
Add the audio codec and map it to a host audio backend id<br />
<br />
-device hda-output,audiodev=snd0<br />
<br />
===== Intel 82801AA AC97 =====<br />
<br />
For AC97 emulation just add the audio card device and map it to a host audio backend id<br />
<br />
-device AC97,audiodev=snd0<br />
<br />
==== Without audiodev ====<br />
<br />
To get list of the supported emulation audio drivers:<br />
$ qemu-system-x86_64 -soundhw help<br />
<br />
To use e.g. {{ic|hda}} driver for the guest use the {{ic|-device intel-hda -device hda-duplex}} command with QEMU.<br />
<br />
{{Note|Video graphic card emulated drivers for the guest machine may also cause a problem with the sound quality. Test one by one to make it work. You can list possible options with {{ic|<nowiki>qemu-system-x86_64 -h | grep vga</nowiki>}}.}}<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [https://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} for passing a disk image, with parameter {{Ic|1=if=virtio}}:<br />
$ qemu-system-x86_64 -drive file=''disk_image'',if='''virtio'''<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-x86_64 -nic user,model='''virtio-net-pci'''<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an Arch Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must contain the necessary modules. By default, this is handled by [[mkinitcpio]]'s {{ic|autodetect}} hook. Otherwise use the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}} to include the necessary modules and rebuild the initial ramdisk.<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=(virtio virtio_blk virtio_pci virtio_net)}}<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing disks by [[UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [https://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
You might also want to install {{Pkg|qemu-guest-agent}} to implement support for QMP commands that will enhance the hypervisor management capabilities. After installing the package you can enable and start the {{ic|qemu-guest-agent.service}}.<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
==== Virtio drivers for Windows ====<br />
<br />
Windows does not come with the virtio drivers. The latest and stable versions of the drivers are regularly built by Fedora, details on downloading the drivers are given on [https://github.com/virtio-win/virtio-win-pkg-scripts/blob/master/README.md virtio-win on GitHub]. In the following sections we will mostly use the stable ISO file provided here: [https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso virtio-win.iso]. Alternatively, use {{AUR|virtio-win}}.<br />
<br />
==== Block device drivers ====<br />
<br />
===== New Install of Windows =====<br />
<br />
The drivers need to be loaded during installation, the procedure is to load the ISO image with the virtio drivers in a cdrom device along with the primary disk device and the Windows ISO install media:<br />
<br />
$ qemu-system-x86_64 ... \<br />
-drive file=''disk_image'',index=0,media=disk,if=virtio \<br />
-drive file=''windows.iso'',index=2,media=cdrom \<br />
-drive file=''virtio-win.iso'',index=3,media=cdrom \<br />
...<br />
<br />
During the installation, at some stage, the Windows installer will ask "Where do you want to install Windows?", it will give a warning that no disks are found. Follow the example instructions below (based on Windows Server 2012 R2 with Update).<br />
<br />
* Select the option ''Load Drivers''.<br />
* Uncheck the box for ''Hide drivers that are not compatible with this computer's hardware''.<br />
* Click the browse button and open the CDROM for the virtio iso, usually named "virtio-win-XX".<br />
* Now browse to {{ic|E:\viostor\[your-os]\amd64}}, select it, and confirm.<br />
<br />
You should now see your virtio disk(s) listed here, ready to be selected, formatted and installed to.<br />
<br />
===== Change existing Windows VM to use virtio =====<br />
<br />
Modifying an existing Windows guest for booting from virtio disk requires that the virtio driver is loaded by the guest at boot time.<br />
We will therefore need to teach Windows to load the virtio driver at boot time before being able to boot a disk image in virtio mode.<br />
<br />
To achieve that, first create a new disk image that will be attached in virtio mode and trigger the search for the driver:<br />
<br />
$ qemu-img create -f qcow2 ''dummy.qcow2'' 1G<br />
<br />
Run the original Windows guest with the boot disk still in IDE mode, the fake disk in virtio mode and the driver ISO image.<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''disk_image'',if=ide -drive file=''dummy.qcow2'',if=virtio -cdrom virtio-win.iso<br />
<br />
Windows will detect the fake disk and look for a suitable driver. If it fails, go to ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not navigate to the driver folder within the CD-ROM, simply select the CD-ROM drive and Windows will find the appropriate driver automatically (tested for Windows 7 SP1).<br />
<br />
Request Windows to boot in safe mode next time it starts up. This can be done using the ''msconfig.exe'' tool in Windows. In safe mode all the drivers will be loaded at boot time including the new virtio driver. Once Windows knows that the virtio driver is required at boot it will memorize it for future boot.<br />
<br />
Once instructed to boot in safe mode, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''disk_image'',if=virtio<br />
<br />
You should boot in safe mode with virtio driver loaded, you can now return to ''msconfig.exe'' disable safe mode boot and restart Windows.<br />
<br />
{{Note|If you encounter the blue screen of death using the {{ic|1=if=virtio}} parameter, it probably means the virtio disk driver is not installed or not loaded at boot time, reboot in safe mode and check your driver configuration.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-nic}} argument.<br />
<br />
$ qemu-system-x86_64 -m 4G -drive file=''windows_disk_image'',if=virtio -nic user,model=virtio-net-pci -cdrom virtio-win.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
==== Balloon driver ====<br />
<br />
If you want to track you guest memory state (for example via {{ic|virsh}} command {{ic|dommemstat}}) or change guest's memory size in runtime (you still will not be able to change memory size, but can limit memory usage via inflating balloon driver) you will need to install guest balloon driver.<br />
<br />
For this you will need to go to ''Device Manager'', locate ''PCI standard RAM Controller'' in ''System devices'' (or unrecognized PCI controller from ''Other devices'') and choose ''Update driver''. In opened window you will need to choose ''Browse my computer...'' and select the CD-ROM (and do not forget the ''Include subdirectories'' checkbox). Reboot after installation. This will install the driver and you will be able to inflate the balloon (for example via hmp command {{ic|balloon ''memory_size''}}, which will cause balloon to take as much memory as possible in order to shrink the guest's available memory size to ''memory_size''). However, you still will not be able to track guest memory state. In order to do this you will need to install ''Balloon'' service properly. For that open command line as administrator, go to the CD-ROM, ''Balloon'' directory and deeper, depending on your system and architecture. Once you are in ''amd64'' (''x86'') directory, run {{ic|blnsrv.exe -i}} which will do the installation. After that {{ic|virsh}} command {{ic|dommemstat}} should be outputting all supported values.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|1=<br />
virtio_load="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
# sed -ibak "s/ada/vtbd/g" /etc/fstab<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== QEMU monitor ==<br />
<br />
While QEMU is running, a monitor console is provided in order to provide several ways to interact with the virtual machine running. The QEMU monitor offers interesting capabilities such as obtaining information about the current virtual machine, hotplugging devices, creating snapshots of the current state of the virtual machine, etc. To see the list of all commands, run {{ic|help}} or {{ic|?}} in the QEMU monitor console or review the relevant section of the [https://www.qemu.org/docs/master/system/monitor.html official QEMU documentation].<br />
<br />
=== Accessing the monitor console ===<br />
<br />
==== Graphical view ====<br />
<br />
When using the {{ic|std}} default graphics option, one can access the QEMU monitor by pressing {{ic|Ctrl+Alt+2}} or by clicking ''View > compatmonitor0'' in the QEMU window. To return to the virtual machine graphical view either press {{ic|Ctrl+Alt+1}} or click ''View > VGA''.<br />
<br />
However, the standard method of accessing the monitor is not always convenient and does not work in all graphic outputs QEMU supports.<br />
<br />
==== Telnet ====<br />
<br />
To enable [[telnet]], run QEMU with the {{ic|-monitor telnet:127.0.0.1:''port'',server,nowait}} parameter. When the virtual machine is started you will be able to access the monitor via telnet:<br />
<br />
$ telnet 127.0.0.1 ''port''<br />
<br />
{{Note|If {{ic|127.0.0.1}} is specified as the IP to listen it will be only possible to connect to the monitor from the same host QEMU is running on. If connecting from remote hosts is desired, QEMU must be told to listen {{ic|0.0.0.0}} as follows: {{ic|-monitor telnet:0.0.0.0:''port'',server,nowait}}. Keep in mind that it is recommended to have a [[firewall]] configured in this case or make sure your local network is completely trustworthy since this connection is completely unauthenticated and unencrypted.}}<br />
<br />
==== UNIX socket ====<br />
<br />
Run QEMU with the {{ic|-monitor unix:''socketfile'',server,nowait}} parameter. Then you can connect with either {{pkg|socat}}, {{pkg|nmap}} or {{pkg|openbsd-netcat}}.<br />
<br />
For example, if QEMU is run via:<br />
<br />
$ qemu-system-x86_64 -monitor unix:/tmp/monitor.sock,server,nowait ''[...]''<br />
<br />
It is possible to connect to the monitor with:<br />
<br />
$ socat - UNIX-CONNECT:/tmp/monitor.sock<br />
<br />
Or with:<br />
<br />
$ nc -U /tmp/monitor.sock<br />
<br />
Alternatively with {{pkg|nmap}}:<br />
<br />
$ ncat -U /tmp/monitor.sock<br />
<br />
==== TCP ====<br />
<br />
You can expose the monitor over TCP with the argument {{ic|-monitor tcp:127.0.0.1:''port'',server,nowait}}. Then connect with netcat, either {{pkg|openbsd-netcat}} or {{pkg|gnu-netcat}} by running:<br />
<br />
$ nc 127.0.0.1 ''port''<br />
<br />
{{Note|In order to be able to connect to the tcp socket from other devices other than the same host QEMU is being run on you need to listen to {{ic|0.0.0.0}} like explained in the telnet case. The same security warnings apply in this case as well.}}<br />
<br />
==== Standard I/O ====<br />
<br />
It is possible to access the monitor automatically from the same terminal QEMU is being run by running it with the argument {{ic|-monitor stdio}}.<br />
<br />
=== Sending keyboard presses to the virtual machine using the monitor console ===<br />
<br />
Some combinations of keys may be difficult to perform on virtual machines due to the host intercepting them instead in some configurations (a notable example is the {{ic|Ctrl+Alt+F*}} key combinations, which change the active tty). To avoid this problem, the problematic combination of keys may be sent via the monitor console instead. Switch to the monitor and use the {{ic|sendkey}} command to forward the necessary keypresses to the virtual machine. For example:<br />
<br />
(qemu) sendkey ctrl-alt-f2<br />
<br />
=== Creating and managing snapshots via the monitor console ===<br />
<br />
{{Note|This feature will '''only''' work when the virtual machine disk image is in ''qcow2'' format. It will not work with ''raw'' images.}}<br />
<br />
It is sometimes desirable to save the current state of a virtual machine and having the possibility of reverting the state of the virtual machine to that of a previously saved snapshot at any time. The QEMU monitor console provides the user with the necessary utilities to create snapshots, manage them, and revert the machine state to a saved snapshot.<br />
<br />
* Use {{ic|savevm ''name''}} in order to create a snapshot with the tag ''name''.<br />
* Use {{ic|loadvm ''name''}} to revert the virtual machine to the state of the snapshot ''name''.<br />
* Use {{ic|delvm ''name''}} to delete the snapshot tagged as ''name''.<br />
* Use {{ic|info snapshots}} to see a list of saved snapshots. Snapshots are identified by both an auto-incremented ID number and a text tag (set by the user on snapshot creation).<br />
<br />
=== Running the virtual machine in immutable mode ===<br />
<br />
It is possible to run a virtual machine in a frozen state so that all changes will be discarded when the virtual machine is powered off just by running QEMU with the {{ic|-snapshot}} parameter. When the disk image is written by the guest, changes will be saved in a temporary file in {{ic|/tmp}} and will be discarded when QEMU halts.<br />
<br />
However, if a machine is running in frozen mode it is still possible to save the changes to the disk image if it is afterwards desired by using the monitor console and running the following command:<br />
<br />
(qemu) commit all<br />
<br />
If snapshots are created when running in frozen mode they will be discarded as soon as QEMU is exited unless changes are explicitly commited to disk, as well.<br />
<br />
=== Pause and power options via the monitor console ===<br />
<br />
Some operations of a physical machine can be emulated by QEMU using some monitor commands:<br />
<br />
* {{ic|system_powerdown}} will send an ACPI shutdown request to the virtual machine. This effect is similar to the power button in a physical machine.<br />
* {{ic|system_reset}} will reset the virtual machine similarly to a reset button in a physical machine. This operation can cause data loss and file system corruption since the virtual machine is not cleanly restarted.<br />
* {{ic|stop}} will pause the virtual machine.<br />
* {{ic|cont}} will resume a virtual machine previously paused.<br />
<br />
=== Taking screenshots of the virtual machine ===<br />
<br />
Screenshots of the virtual machine graphic display can be obtained in the PPM format by running the following command in the monitor console:<br />
<br />
(qemu) screendump ''file.ppm''<br />
<br />
== QEMU machine protocol ==<br />
<br />
The QEMU machine protocol (QMP) is a JSON-based protocol which allows applications to control a QEMU instance. Similarly to the [[#QEMU monitor]] it offers ways to interact with a running machine and the JSON protocol allows to do it programmatically. The description of all the QMP commands can be found in [https://raw.githubusercontent.com/coreos/qemu/master/qmp-commands.hx qmp-commands].<br />
<br />
=== Start QMP ===<br />
<br />
The usual way to control the guest using the QMP protocol, is to open a TCP socket when launching the machine using the {{ic|-qmp}} option. Here it is using for example the TCP port 4444:<br />
<br />
$ qemu-system-x86_64 ''[...]'' -qmp tcp:localhost:4444,server,nowait<br />
<br />
Then one way to communicate with the QMP agent is to use [[netcat]]:<br />
<br />
{{hc|nc localhost 4444|{"QMP": {"version": {"qemu": {"micro": 0, "minor": 1, "major": 3}, "package": ""}, "capabilities": []} } }}<br />
<br />
At this stage, the only command that can be recognized is {{ic|qmp_capabilities}}, so that QMP enters into command mode. Type:<br />
<br />
{"execute": "qmp_capabilities"}<br />
<br />
Now, QMP is ready to receive commands, to retrieve the list of recognized commands, use:<br />
<br />
{"execute": "query-commands"}<br />
<br />
=== Live merging of child image into parent image ===<br />
<br />
It is possible to merge a running snapshot into its parent by issuing a {{ic|block-commit}} command. In its simplest form the following line will commit the child into its parent:<br />
<br />
{"execute": "block-commit", "arguments": {"device": "''devicename''"}}<br />
<br />
Upon reception of this command, the handler looks for the base image and converts it from read only to read write mode and then runs the commit job.<br />
<br />
Once the ''block-commit'' operation has completed, the event {{ic|BLOCK_JOB_READY}} will be emitted, signalling that the synchronization has finished. The job can then be gracefully completed by issuing the command {{ic|block-job-complete}}:<br />
<br />
{"execute": "block-job-complete", "arguments": {"device": "''devicename''"}}<br />
<br />
Until such a command is issued, the ''commit'' operation remains active.<br />
After successful completion, the base image remains in read write mode and becomes the new active layer. On the other hand, the child image becomes invalid and it is the responsibility of the user to clean it up.<br />
<br />
{{Tip|The list of device and their names can be retrieved by executing the command {{ic|query-block}} and parsing the results. The device name is in the {{ic|device}} field, for example {{ic|ide0-hd0}} for the hard disk in this example: {{hc|{"execute": "query-block"}|{"return": [{"io-status": "ok", "device": "'''ide0-hd0'''", "locked": false, "removable": false, "inserted": {"iops_rd": 0, "detect_zeroes": "off", "image": {"backing-image": {"virtual-size": 27074281472, "filename": "parent.qcow2", ... } }} }}<br />
<br />
=== Live creation of a new snapshot ===<br />
<br />
To create a new snapshot out of a running image, run the command:<br />
<br />
{"execute": "blockdev-snapshot-sync", "arguments": {"device": "''devicename''","snapshot-file": "''new_snapshot_name''.qcow2"}}<br />
<br />
This creates an overlay file named {{ic|''new_snapshot_name''.qcow2}} which then becomes the new active layer.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Improve virtual machine performance ===<br />
<br />
There are a number of techniques that you can use to improve the performance of the virtual machine. For example:<br />
<br />
* Apply [[#Enabling KVM]] for full virtualization.<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU rather than a more generic CPU.<br />
* Especially for Windows guests, enable [https://blog.wikichoon.com/2014/07/enabling-hyper-v-enlightenments-with-kvm.html Hyper-V enlightenments]: {{ic|1=-cpu host,hv_relaxed,hv_spinlocks=0x1fff,hv_vapic,hv_time}}.<br />
* If the host machine has multiple cores, assign the guest more cores using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* If supported by drivers in the guest operating system, use virtio for network and/or block devices, see [[#Installing virtio drivers]].<br />
* Use TAP devices instead of user-mode networking, see [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, you may want to disable the cache:<br />
$ qemu-system-x86_64 -drive file=''disk_image'',if=virtio,'''cache=none'''<br />
* Use the native Linux AIO:<br />
$ qemu-system-x86_64 -drive file=''disk_image'',if=virtio''',aio=native,cache.direct=on'''<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]. See [[#Enabling KSM]].<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU using {{ic|-device virtio-balloon}}.<br />
* It is possible to use a emulation layer for an ICH-9 AHCI controller (although it may be unstable). The AHCI emulation supports [[Wikipedia:Native_Command_Queuing|NCQ]], so multiple read or write requests can be outstanding at the same time:<br />
$ qemu-system-x86_64 -drive id=disk,file=''disk_image'',if=none -device ich9-ahci,id=ahci -device ide-drive,drive=disk,bus=ahci.0<br />
<br />
See https://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured with {{ic|virsh autostart}} or through the ''virt-manager'' GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== With systemd service ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|2=<br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/qemu-system-x86_64 -name %i -enable-kvm -m 512 -nographic $args<br />
ExecStop=/usr/bin/bash -c ${haltcmd}<br />
ExecStop=/usr/bin/bash -c 'while nc localhost 7100; do sleep 1; done'<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{Note|This service will wait for the console port to be released, which means that the VM has been shutdown, to graciously end.}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the variables {{ic|args}} and {{ic|haltcmd}} set. Example configs:<br />
<br />
{{hc|/etc/conf.d/qemu.d/one|2=<br />
args="-hda /dev/vg0/vm1 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' {{!}} nc localhost 7100" # or netcat/ncat}}<br />
<br />
{{hc|/etc/conf.d/qemu.d/two|2=<br />
args="-hda /srv/kvm/vm2 -serial telnet:localhost:7001,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="ssh powermanager@vm2 sudo poweroff"}}<br />
<br />
The description of the variables is the following:<br />
<br />
* {{ic|args}} - QEMU command line arguments to be used.<br />
* {{ic|haltcmd}} - Command to shut down a VM safely. In the first example, the QEMU monitor is exposed via telnet using {{ic|-monitor telnet:..}} and the VMs are powered off via ACPI by sending {{ic|system_powerdown}} to monitor with the {{ic|nc}} command. In the other example, SSH is used.<br />
<br />
To set which virtual machines will start on boot-up, [[enable]] the {{ic|qemu@''vm_name''.service}} systemd unit.<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the options {{ic|-usb -device usb-tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
<br />
$ qemu-system-x86_64 -hda ''disk_image'' -m 512 -usb -device usb-tablet<br />
<br />
If that does not work, try using {{ic|-vga qxl}} parameter, also look at the instructions [[#Mouse cursor is jittery or erratic]].<br />
<br />
=== Pass-through host USB device ===<br />
<br />
It is possible to access the physical device connected to a USB port of the host from the guest. The first step is to identify where the device is connected, this can be found running the {{ic|lsusb}} command. For example:<br />
<br />
{{hc|$ lsusb|<br />
...<br />
Bus '''003''' Device '''007''': ID '''0781''':'''5406''' SanDisk Corp. Cruzer Micro U3<br />
}}<br />
<br />
The outputs in bold above will be useful to identify respectively the ''host_bus'' and ''host_addr'' or the ''vendor_id'' and ''product_id''.<br />
<br />
In qemu, the idea is to emulate an EHCI (USB 2) or XHCI (USB 3) controller with the option {{ic|1=-device usb-ehci,id=ehci}} or {{ic|1=-device qemu-xhci,id=xhci}} respectively and then attach the physical device to it with the option {{ic|1=-device usb-host,..}}. We will consider that ''controller_id'' is either {{ic|ehci}} or {{ic|xhci}} for the rest of this section.<br />
<br />
Then, there are two ways to connect to the USB of the host with qemu:<br />
<br />
# Identify the device and connect to it on any bus and address it is attached to on the host, the generic syntax is: {{bc|1=-device usb-host,bus=''controller_id''.0,vendorid=0x''vendor_id'',productid=0x''product_id''}}Applied to the device used in the example above, it becomes:{{bc|1=-device usb-ehci,id=ehci -device usb-host,bus=ehci.0,vendorid=0x'''0781''',productid=0x'''5406'''}}One can also add the {{ic|1=...,port=''port_number''}} setting to the previous option to specify in which physical port of the virtual controller the device should be attached, useful in the case one wants to add multiple usb devices to the VM. Another option is to use the new {{ic|hostdevice}} property of {{ic|usb-host}} which is available since QEMU 5.1.0, the syntax is: {{bc|1=-device qemu-xhci,id=xhci -device usb-host,bus=xhci.0,hostdevice=/dev/bus/usb/003/007}}<br />
# Attach whatever is connected to a given USB bus and address, the syntax is:{{bc|1=-device usb-host,bus=''controller_id''.0,hostbus=''host_bus'',host_addr=''host_addr''}}Applied to the bus and the address in the example above, it becomes:{{bc|1=-device usb-ehci,id=ehci -device usb-host,bus=ehci.0,hostbus='''3''',hostaddr='''7'''}}<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[udev#About udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== USB redirection with SPICE ===<br />
<br />
When using [[#SPICE]] it is possible to redirect USB devices from the client to the virtual machine without needing to specify them in the QEMU command. It is possible to configure the number of USB slots available for redirected devices (the number of slots will determine the maximum number of devices which can be redirected simultaneously). The main advantages of using SPICE for redirection compared to the previously-mentioned {{ic|-usbdevice}} method is the possibility of hot-swapping USB devices after the virtual machine has started, without needing to halt it in order to remove USB devices from the redirection or adding new ones. This method of USB redirection also allows us to redirect USB devices over the network, from the client to the server. In summary, it is the most flexible method of using USB devices in a QEMU virtual machine.<br />
<br />
We need to add one EHCI/UHCI controller per available USB redirection slot desired as well as one SPICE redirection channel per slot. For example, adding the following arguments to the QEMU command you use for starting the virtual machine in SPICE mode will start the virtual machine with three available USB slots for redirection:<br />
<br />
{{bc|1=<br />
-device ich9-usb-ehci1,id=usb \<br />
-device ich9-usb-uhci1,masterbus=usb.0,firstport=0,multifunction=on \<br />
-device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \<br />
-device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev1 -device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev2 -device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \<br />
-chardev spicevmc,name=usbredir,id=usbredirchardev3 -device usb-redir,chardev=usbredirchardev3,id=usbredirdev3<br />
}}<br />
<br />
See [https://www.spice-space.org/usbredir.html SPICE/usbredir] for more information.<br />
<br />
Both {{ic|spicy}} from {{Pkg|spice-gtk}} (''Input > Select USB Devices for redirection'') and {{ic|remote-viewer}} from {{pkg|virt-viewer}} (''File > USB device selection'') support this feature. Please make sure that you have installed the necessary SPICE Guest Tools on the virtual machine for this functionality to work as expected (see the [[#SPICE]] section for more information).<br />
<br />
{{Warning|Keep in mind that when a USB device is redirected from the client, it will not be usable from the client operating system itself until the redirection is stopped. It is specially important to never redirect the input devices (namely mouse and keyboard), since it will be then difficult to access the SPICE client menus to revert the situation, because the client will not respond to the input devices after being redirected to the virtual machine.}}<br />
<br />
==== Automatic USB forwarding with udev ====<br />
<br />
Normally, forwarded devices must be available at VM boot time to be forwarded. If that device is disconnected, it will not be forwarded anymore.<br />
<br />
You can use [[udev rule]]s to automatically attach a device when it comes online. Create a {{ic|hostdev}} entry somewhere on disk. [[chown]] it to root to prevent other users modifying it.<br />
<br />
{{hc|/usr/local/hostdev-mydevice.xml|2=<br />
<hostdev mode='subsystem' type='usb'><br />
<source><br />
<vendor id='0x03f0'/><br />
<product id='0x4217'/><br />
</source><br />
</hostdev><br />
}}<br />
<br />
Then create a ''udev'' rule which will attach/detach the device:<br />
<br />
{{hc|/usr/lib/udev/rules.d/90-libvirt-mydevice|2=<br />
ACTION=="add", \<br />
SUBSYSTEM=="usb", \<br />
ENV{ID_VENDOR_ID}=="03f0", \<br />
ENV{ID_MODEL_ID}=="4217", \<br />
RUN+="/usr/bin/virsh attach-device GUESTNAME /usr/local/hostdev-mydevice.xml"<br />
ACTION=="remove", \<br />
SUBSYSTEM=="usb", \<br />
ENV{ID_VENDOR_ID}=="03f0", \<br />
ENV{ID_MODEL_ID}=="4217", \<br />
RUN+="/usr/bin/virsh detach-device GUESTNAME /usr/local/hostdev-mydevice.xml"<br />
}}<br />
<br />
[https://rolandtapken.de/blog/2011-04/how-auto-hotplug-usb-devices-libvirt-vms-update-1 Source and further reading].<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
{{Note|Although KSM may reduce memory usage, it may increase CPU usage. Also note some security issues may occur, see [[Wikipedia:Kernel same-page merging]].}}<br />
<br />
To enable KSM:<br />
<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, use [[systemd#systemd-tmpfiles - temporary files|systemd's temporary files]]:<br />
<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/html/latest/admin-guide/mm/ksm.html for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory:<br />
<br />
$ grep -r . /sys/kernel/mm/ksm/<br />
<br />
}}<br />
<br />
=== Multi-monitor support ===<br />
<br />
The Linux QXL driver supports four heads (virtual screens) by default. This can be changed via the {{ic|1=qxl.heads=N}} kernel parameter.<br />
<br />
The default VGA memory size for QXL devices is 16M (VRAM size is 64M). This is not sufficient if you would like to enable two 1920x1200 monitors since that requires 2 × 1920 × 4 (color depth) × 1200 = 17.6 MiB VGA memory. This can be changed by replacing {{ic|-vga qxl}} by {{ic|<nowiki>-vga none -device qxl-vga,vgamem_mb=32</nowiki>}}. If you ever increase vgamem_mb beyond 64M, then you also have to increase the {{ic|vram_size_mb}} option.<br />
<br />
=== Custom display resolution ===<br />
<br />
A custom display resolution can be set with {{ic|1=-device VGA,edid=on,xres=1280,yres=720}} (see [[wikipedia:Extended_Display_Identification_Data|EDID]] and [[wikipedia:Display_resolution|display resolution]]).<br />
<br />
=== Copy and paste ===<br />
<br />
One way to share the clipboard between the host and the guest is to enable the SPICE remote desktop protocol and access the client with a SPICE client.<br />
One needs to follow the steps described in [[#SPICE]]. A guest run this way will support copy paste with the host.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 10.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Fast startup ====<br />
<br />
{{Note|An administrator account is required to change power settings.}}<br />
<br />
For Windows 8 (or later) guests it is better to disable "Turn on fast startup (recommended)" from the Power Options of the Control Panel as explained in the following [https://www.tenforums.com/tutorials/4189-turn-off-fast-startup-windows-10-a.html forum page], as it causes the guest to hang during every other boot.<br />
<br />
Fast Startup may also need to be disabled for changes to the {{ic|-smp}} option to be properly applied.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-x86_64 -nographic -nic user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either {{Pkg|rdesktop}} or {{Pkg|freerdp}} to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
=== Clone Linux system installed on physical equipment ===<br />
<br />
Linux system installed on physical equipment can be cloned for running on QEMU vm. See [https://coffeebirthday.wordpress.com/2018/09/14/clone-linux-system-for-qemu-virtual-machine/ Clone Linux system from hardware for QEMU virtual machine]<br />
<br />
=== Chrooting into arm/arm64 environment from x86_64 ===<br />
<br />
Sometimes it is easier to work directly on a disk image instead of the real ARM based device. This can be achieved by mounting an SD card/storage containing the ''root'' partition and chrooting into it.<br />
<br />
Another use case for an ARM chroot is building ARM packages on an x86_64 machine - {{AUR|armutils-git}} can be used for that. Here, the chroot environment can be created from an image tarball from [https://archlinuxarm.org Arch Linux ARM] - see [https://nerdstuff.org/posts/2020/2020-003_simplest_way_to_create_an_arm_chroot/] for a detailed description of this approach.<br />
<br />
Either way, from the chroot it should be possible to run ''pacman'' and install more packages, compile large libraries etc. Since the executables are for the ARM architecture, the translation to x86 needs to be performed by [[QEMU]].<br />
<br />
Install {{AUR|binfmt-qemu-static}} and {{AUR|qemu-user-static}} from the [[AUR]] on the x86_64 machine/host. ''binfmt-qemu-static'' will take care of registering the qemu binaries to binfmt service.<br />
<br />
[[Restart]] {{ic|systemd-binfmt.service}}<br />
<br />
{{AUR|qemu-user-static}} is needed to allow the execution of compiled programs from other architectures. This is similar to what is provided by {{Pkg|qemu-arch-extra}}, but the "static" variant is required for chroot. Examples:<br />
<br />
qemu-arm-static path_to_sdcard/usr/bin/ls<br />
qemu-aarch64-static path_to_sdcard/usr/bin/ls<br />
<br />
These two lines execute the {{ic|ls}} command compiled for 32-bit ARM and 64-bit ARM respectively. Note that this will not work without chrooting, because it will look for libraries not present in the host system.<br />
<br />
{{AUR|qemu-user-static}} allows automatically prefixing the ARM exectuable with {{ic|qemu-arm-static}} or {{ic|qemu-aarch64-static}}.<br />
<br />
Make sure that the ARM executable support is active:<br />
<br />
{{hc|$ ls /proc/sys/fs/binfmt_misc|<br />
qemu-aarch64 qemu-arm qemu-cris qemu-microblaze qemu-mipsel qemu-ppc64 qemu-riscv64 qemu-sh4 qemu-sparc qemu-sparc64 status<br />
qemu-alpha qemu-armeb qemu-m68k qemu-mips qemu-ppc qemu-ppc64abi32 qemu-s390x qemu-sh4eb qemu-sparc32plus register<br />
}}<br />
<br />
Each executable must be listed.<br />
<br />
If it is not active, [[reinstall]] {{AUR|binfmt-qemu-static}} and [[restart]] {{ic|systemd-binfmt.service}}.<br />
<br />
Mount the SD card to {{ic|/mnt/sdcard}} (the device name may be different).<br />
<br />
# mkdir -p /mnt/sdcard<br />
# mount /dev/mmcblk0p2 /mnt/sdcard<br />
<br />
Mount boot partition if needed (again, use the suitable device name):<br />
<br />
# mount /dev/mmcblk0p1 /mnt/sdcard/boot<br />
<br />
Finally ''chroot'' into the SD card root as described in [[Change root#Using chroot]]:<br />
<br />
# chroot /mnt/sdcard /bin/bash<br />
<br />
Alternatively, you can use ''arch-chroot'' from {{Pkg|arch-install-scripts}}, as it will provide an easier way to get network support:<br />
<br />
# arch-chroot /mnt/sdcard /bin/bash<br />
<br />
You can also use [[systemd-nspawn]] to chroot into the ARM environment:<br />
<br />
# systemd-nspawn -D /mnt/sdcard -M myARMMachine --bind-ro=/etc/resolv.conf<br />
<br />
{{ic|1=--bind-ro=/etc/resolv.conf}} is optional and gives a working network DNS inside the chroot<br />
<br />
=== Not grabbing mouse input ===<br />
<br />
{{Style|It is not explained what the option actually does. Is it causing or avoiding the side effect?}}<br />
<br />
Tablet mode has side effect of not grabbing mouse input in QEMU window:<br />
<br />
-usb -device usb-tablet<br />
<br />
It works with several -vga backends one of which is virtio.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|~/.bashrc}} file.<br />
<br />
=== No visible Cursor ===<br />
<br />
Add {{ic|1=-display default,show-cursor=on}} to QEMU's options to see a mouse cursor.<br />
<br />
If that still does not work, make sure you have set your display device appropriately, for example: {{ic|-vga qxl}}.<br />
<br />
Another option to try is {{ic|-usb -device usb-tablet}} as mentioned in [[#Mouse integration]]. This overrides the default PS/2 mouse emulation and synchronizes pointer location between host and guest as an added bonus.<br />
<br />
=== Two different mouse cursors are visible ===<br />
<br />
Apply the tip [[#Mouse integration]].<br />
<br />
=== Keyboard issues when using VNC ===<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [https://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps/}}.<br />
<br />
$ qemu-system-x86_64 -k ''keymap'' ''disk_image''<br />
<br />
=== Could not read keymap file ===<br />
<br />
qemu-system-x86_64: -display vnc=0.0.0.0:0: could not read keymap file: 'en'<br />
<br />
is caused by an invalid ''keymap'' passed to the {{ic|-k}} argument. For example, {{ic|en}} is invalid, but {{ic|en-us}} is valid - see {{ic|/usr/share/qemu/keymaps/}}.<br />
<br />
=== Guest display stretches on window resize ===<br />
<br />
To restore default window size, press {{ic|Ctrl+Alt+u}}.<br />
<br />
=== ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy ===<br />
<br />
If an error message like this is printed when starting QEMU with {{ic|-enable-kvm}} option:<br />
<br />
ioctl(KVM_CREATE_VM) failed: 16 Device or resource busy<br />
failed to initialize KVM: Device or resource busy<br />
<br />
that means another [[hypervisor]] is currently running. It is not recommended or possible to run several hypervisors in parallel.<br />
<br />
=== libgfapi error message ===<br />
<br />
The error message displayed at startup:<br />
<br />
Failed to open module: libgfapi.so.0: cannot open shared object file: No such file or directory<br />
<br />
[[Install]] {{pkg|glusterfs}} or ignore the error message as GlusterFS is a optional dependency.<br />
<br />
=== Kernel panic on LIVE-environments ===<br />
<br />
If you start a live-environment (or better: booting a system) you may encounter this:<br />
<br />
[ end Kernel panic - not syncing: VFS: Unable to mount root fs on unknown block(0,0)<br />
<br />
or some other boot hindering process (e.g. cannot unpack initramfs, cant start service foo).<br />
Try starting the VM with the {{ic|-m VALUE}} switch and an appropriate amount of RAM, if the ram is to low you will probably encounter similar issues as above/without the memory-switch.<br />
<br />
=== Windows 7 guest suffers low-quality sound ===<br />
<br />
Using the {{ic|hda}} audio driver for Windows 7 guest may result in low-quality sound. Changing the audio driver to {{ic|ac97}} by passing the {{ic|-soundhw ac97}} arguments to QEMU and installing the AC97 driver from [https://www.realtek.com/en/component/zoo/category/pc-audio-codecs-ac-97-audio-codecs-software Realtek AC'97 Audio Codecs] in the guest may solve the problem. See [https://bugzilla.redhat.com/show_bug.cgi?id=1176761#c16 Red Hat Bugzilla – Bug 1176761] for more information.<br />
<br />
=== Could not access KVM kernel module: Permission denied ===<br />
<br />
If you encounter the following error:<br />
<br />
libvirtError: internal error: process exited while connecting to monitor: Could not access KVM kernel module: Permission denied failed to initialize KVM: Permission denied<br />
<br />
Systemd 234 assigns a dynamic ID for the {{ic|kvm}} group (see {{Bug|54943}}). To avoid this error, you need edit the file {{ic|/etc/libvirt/qemu.conf}} and change the line with {{ic|1=group = "78"}} to {{ic|1=group = "kvm"}}.<br />
<br />
=== "System Thread Exception Not Handled" when booting a Windows VM ===<br />
<br />
Windows 8 or Windows 10 guests may raise a generic compatibility exception at boot, namely "System Thread Exception Not Handled", which tends to be caused by legacy drivers acting strangely on real machines. On KVM machines this issue can generally be solved by setting the CPU model to {{ic|core2duo}}.<br />
<br />
=== Certain Windows games/applications crashing/causing a bluescreen ===<br />
<br />
Occasionally, applications running in the VM may crash unexpectedly, whereas they would run normally on a physical machine. If, while running {{ic|dmesg -wH}} as root, you encounter an error mentioning {{ic|MSR}}, the reason for those crashes is that KVM injects a [[wikipedia:General protection fault|General protection fault]] (GPF) when the guest tries to access unsupported [[wikipedia:Model-specific register|Model-specific registers]] (MSRs) - this often results in guest applications/OS crashing. A number of those issues can be solved by passing the {{ic|1=ignore_msrs=1}} option to the KVM module, which will ignore unimplemented MSRs.<br />
<br />
{{hc|/etc/modprobe.d/kvm.conf|2=<br />
...<br />
options kvm ignore_msrs=1<br />
...<br />
}}<br />
<br />
Cases where adding this option might help:<br />
<br />
* GeForce Experience complaining about an unsupported CPU being present.<br />
* StarCraft 2 and L.A. Noire reliably blue-screening Windows 10 with {{ic|KMODE_EXCEPTION_NOT_HANDLED}}. The blue screen information does not identify a driver file in these cases.<br />
<br />
{{Warning|While this is normally safe and some applications might not work without this, silently ignoring unknown MSR accesses could potentially break other software within the VM or other VMs.}}<br />
<br />
=== Applications in the VM experience long delays or take a long time to start ===<br />
<br />
This may be caused by insufficient available entropy in the VM. Consider allowing the guest to access the hosts's entropy pool by adding a [https://wiki.qemu.org/Features/VirtIORNG VirtIO RNG device] to the VM, or by installing an entropy generating daemon such as [[Haveged]].<br />
<br />
Anecdotally, OpenSSH takes a while to start accepting connections under insufficient entropy, without the logs revealing why.<br />
<br />
=== High interrupt latency and microstuttering ===<br />
<br />
This problem manifests itself as small pauses (stutters) and is particularly noticeable in graphics-intensive applications, such as games.<br />
<br />
* One of the causes is CPU power saving features, which are controlled by [[CPU frequency scaling]]. Change this to {{ic|performance}} for all processor cores. <br />
* Another possible cause is PS/2 inputs. Switch from PS/2 to Virtio inputs, see [[PCI passthrough via OVMF#Passing keyboard/mouse via Evdev]].<br />
<br />
=== QXL video causes low resolution ===<br />
<br />
QEMU 4.1.0 introduced a regression where QXL video can fall back to low resolutions, when being displayed through spice. [https://bugs.launchpad.net/qemu/+bug/1843151] For example, when KMS starts, text resolution may become as low as 4x10 characters. When trying to increase GUI resolution, it may go to the lowest supported resolution.<br />
<br />
As a workaround, create your device in this form:<br />
<br />
-device qxl-vga,max_outputs=1...<br />
<br />
=== Hang during VM initramfs ===<br />
<br />
Linux 5.2.11 introduced a KVM regression where under some circumstances a VM may permanently hang during the early boot phase, when the initramfs is being loaded or ran. [https://www.spinics.net/lists/kvm/msg195171.html] Linux 5.3 fixed the regression. The host shows qemu using 100% CPU * number of virtual CPUs. Reported case is with a host using hyperthreading, and a VM being given more than host's {{ic|nproc}}/2 virtual CPUs. It is unknown what exact circumstances trigger one of the threads to delete a memory region to cause this. The workarounds are:<br />
<br />
* Upgrade to Linux 5.3.<br />
* Downgrade to Linux 5.2.10<br />
* Until fixed, try giving the VM no more than the host's {{ic|nproc}}/2 virtual CPUs<br />
* Custom compile linux, reverting commit 2ad350fb4c (note this re-introduces a regression triggered when removing a memslot)<br />
<br />
=== VM does not boot when using a Secure Boot enabled OVMF ===<br />
<br />
{{ic|/usr/share/edk2-ovmf/x64/OVMF_CODE.secboot.fd}} from {{Pkg|edk2-ovmf}} is built with [[Wikipedia:System Management Mode|SMM]] support. If S3 support is not disabled in the VM, then the VM might not boot at all.<br />
<br />
Add the {{ic|1=-global ICH9-LPC.disable_s3=1}} option to the ''qemu'' command.<br />
<br />
See {{Bug|59465}} and https://github.com/tianocore/edk2/blob/master/OvmfPkg/README for more details and the required options to use Secure Boot in QEMU.<br />
<br />
=== Guest CPU interrupts are not firing ===<br />
<br />
If you are writing your own operating system by following the [https://wiki.osdev.org/ OSDev wiki], or are simply getting stepping through the guest architecture assembly code using QEMU's {{ic|gdb}} interface using the {{ic|-s}} flag, it's useful to know that many emulators, QEMU included, usually implement some CPU interrupts leaving many hardware interrupts unimplemented. One way to know if your code if firing an interrupt, is by using:<br />
<br />
-d int<br />
<br />
to enable showing interrupts/exceptions on stdout.<br />
<br />
To see what other guest debugging features QEMU has to offer, see:<br />
<br />
qemu-system-x86_64 -d help<br />
<br />
or replace {{ic|x86_64}} for your chosen guest architecture.<br />
<br />
== See also ==<br />
<br />
* [https://qemu.org Official QEMU website]<br />
* [https://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]{{Dead link|2021|05|17|status=404}}<br />
* [[Wikibooks:QEMU|QEMU Wikibook]]<br />
* [http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU] by AlienBOB (last updated in 2008)<br />
* [http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army] by Falconindy<br />
* [https://git.qemu.org/?p=qemu.git;a=tree;f=docs Lastest docs]<br />
* [https://qemu.weilnetz.de/ QEMU on Windows]<br />
* [[wikipedia:Qemu|Wikipedia]]<br />
* [[debian:QEMU|Debian Wiki - QEMU]]<br />
* [https://people.gnome.org/~markmc/qemu-networking.html QEMU Networking on gnome.org]<br />
* [http://bsdwiki.reedmedia.net/wiki/networking_qemu_virtual_bsd_systems.html Networking QEMU Virtual BSD Systems]<br />
* [https://www.gnu.org/software/hurd/hurd/running/qemu.html QEMU on gnu.org]<br />
* [https://wiki.freebsd.org/qemu QEMU on FreeBSD as host]<br />
* [https://wiki.mikejung.biz/KVM_/_Xen KVM/QEMU Virtio Tuning and SSD VM Optimization Guide]<br />
* [https://doc.opensuse.org/documentation/leap/virtualization/html/book-virt/part-virt-qemu.html Managing Virtual Machines with QEMU - openSUSE documentation]<br />
* [https://www.ibm.com/support/knowledgecenter/en/linuxonibm/liaat/liaatkvm.htm KVM on IBM Knowledge Center]</div>PXfhttps://wiki.archlinux.org/index.php?title=Debugging&diff=691997Debugging2021-08-17T08:21:14Z<p>PXf: /* Readelf */ ld-lsb is picked up into [community]</p>
<hr />
<div>[[Category:Development]]<br />
[[Category:System administration]]<br />
[[ja:ステップバイステップデバッグガイド]]<br />
{{Related articles start}}<br />
{{Related|General troubleshooting}}<br />
{{Related|Reporting bug guidelines}}<br />
{{Related|Debugging/Getting traces}}<br />
{{Related|Boot debugging}}<br />
{{Related articles end}}<br />
{{Expansion|This article might as well be about debugging in general, so that other useful tools like {{Pkg|ltrace}} can be added here.}}<br />
This page is mainly about how to gather more information in connection with bug reports. Even though the word "debug" is used, it's not intended as a guide for how to debug programs while developing.<br />
<br />
== When an application fails ==<br />
<br />
=== Run it from the commandline ===<br />
<br />
{{Merge|General troubleshooting|Already covered there}}<br />
<br />
{{Style|There should be no need to check that files in {{ic|/usr/bin/}} are executable, the below command could just be {{ic|pacman -Ql ''packagename'' {{!}} grep ' /usr/bin/.'}}.}}<br />
<br />
If an application suddenly crashes, try running it from a [[terminal emulator]]. Type in the name of the application in lowercase letters. If you do not know the name of the executable, only the name of the package, the following command can find the name of the executable. Replace ''packagename'' with the name of the package:<br />
<br />
for f in $(pacman -Qlq ''packagename'' | grep /bin/); do file $f 2>/dev/null | grep -q executable && basename $f; done<br />
<br />
=== Check availability of a core dump ===<br />
<br />
A core dump is a file containing a process's address space (memory) when the process terminates unexpectedly. If the application is compiled in a debug-friendly way, the "core" file can be used to find out where things went wrong. <br />
<br />
The location of core dumps may vary depending on the operating system configuration. See [[core dump]] to find whether generation of core dump files is enabled on your system and where do they go.<br />
<br />
== Segmentation faults ==<br />
<br />
There are several techniques that can be used to figure out what went wrong. Put your detective hat on.<br />
<br />
=== Gdb ===<br />
<br />
{{Pkg|gdb}} is an ancient and well tested application for debugging applications. See [[Debugging/Getting traces#Getting the trace]] for more instructions how to use it to obtain a trace. While running from {{ic|gdb}} you might have to wait for the segfault. Afterwards, post the trace to a [[List of applications#Pastebin services|pastebin service]] and include the URL in your bug report.<br />
<br />
=== Improved gdb output ===<br />
<br />
{{Merge|Debugging/Getting traces|Same subject}}<br />
<br />
First [[Arch Build System|recompile]] the application in question with debug options. Make sure that {{ic|debug}} and {{ic|!strip}} are in the options array in the PKGBUILD, for example:<br />
<br />
options=(debug !strip)<br />
<br />
Then install the package and run it again with gdb, as above.<br />
<br />
If you have a "core" file, it can be used together with gdb to get a backtrace:<br />
<br />
$ gdb appname core<br />
bt full<br />
<br />
=== Valgrind ===<br />
<br />
Assuming you have an unstripped binary without inlined functions, it is usually a good idea to also run that program through {{Pkg|valgrind}}. ''valgrind'' is a tool that emulates a CPU and usually shows where things go wrong or provide additional info in addition to gdb.<br />
<br />
$ valgrind appname<br />
<br />
it will provide a lot of helpful debug output if there is a crash. Consider {{ic|-v}} and {{ic|1=--leak-check=full}} to get even more info.<br />
<br />
Alternatively, use:<br />
<br />
$ valgrind --tool=callgrind appname<br />
<br />
and run the output through {{Pkg|kcachegrind}} to graphically explore the functions the program uses. If a program hangs, this makes it easier to pinpoint the location of the error.<br />
<br />
== Missing files or libraries ==<br />
<br />
=== Strace ===<br />
<br />
{{Pkg|strace}} finds out in detail what an application is actually doing. If an application tries to open a file that is not there, it can be discovered by strace.<br />
<br />
For finding which files a program named ''appname'' tries to open:<br />
<br />
$ strace -eopen appname<br />
<br />
Save the output, post it to a [[List of applications#Pastebin services|pastebin service]] and keep the URL in handy.<br />
<br />
{{Tip|If you wish to grep the output from strace, you can try:<br />
{{ic|strace -o /dev/stdout appname {{!}} grep ''string''}}<br />
}}<br />
<br />
=== LD_DEBUG ===<br />
<br />
Setting {{ic|1=LD_DEBUG=files}} gives another overview of what files an application is looking for. For an application named ''appname'':<br />
<br />
LD_DEBUG=files appname > appname.log 2>&1<br />
<br />
The output will end up in {{ic|appname.log}}.<br />
<br />
For more information, see {{man|8|ld-linux}}.<br />
<br />
=== Readelf ===<br />
<br />
If you get "no such file or directory" when running an application, try the following command:<br />
<br />
$ readelf -a /usr/bin/appname | grep interp<br />
<br />
(replace /usr/bin/appname with the location of your executable)<br />
<br />
Make sure the interpreter in question (like /lib/ld-linux-x86-64.so.2) actually exists. Install {{Pkg|ld-lsb}} if need be.<br />
<br />
== If it is not written in C or C++, but perhaps in Python ==<br />
<br />
Use {{Pkg|file}} on the executable to get more information (replace "appname" with your executable):<br />
<br />
$ file /usr/bin/''appname''<br />
<br />
If it says "ELF" it is a binary executable and is usually written in C or C++. If it says "Python script" you know you are dealing with an application written in Python.<br />
<br />
If it is a shell script, open up the shell script in a text editor and see (usually at the bottom of the file) if you can find the name of the real application (ELF file). You can then temporarily put "gdb" right in the shellscript, before the name of the executable, for debugging purposes. See the sections about gdb further up. Prefix the command with {{ic|gdb --args}} if the executable in question needs arguments as well.<br />
<br />
For pure shell scripts, you can also use {{ic|bash -x ''script_name''}} or {{ic|bash -xv ''script_name''}}.<br />
<br />
For Python applications, the output will often say which file and line number the crash occured at. If you are proficient with Python, you can try to fix this and include the fix in the bug report.<br />
<br />
== Report the bug ==<br />
<br />
Please report a bug at https://bugs.archlinux.org and possibly also directly to the developers of the application in question, then include a link in the Arch Linux bug report. This helps us all.<br />
<br />
However, if you think there is something wrong with the application itself, and not with how it is packaged, report the bug directly to upstream (which means the developers of the application). Normally, software streams from developers, through packagers/maintainers and down to users. Upstream means the other way, so for this case: directly to the developers of an application.<br />
<br />
== See also ==<br />
<br />
* [[Gentoo:Project:Quality Assurance/Backtraces]]</div>PXfhttps://wiki.archlinux.org/index.php?title=User_talk:Lahwaacz&diff=691763User talk:Lahwaacz2021-08-15T05:23:43Z<p>PXf: /* DPMS: "\033[9;0]" */ new section</p>
<hr />
<div>== bot checking links after move ==<br />
<br />
Hi, re [[Talk:Touchpad Synaptics#adding libinput alternative]]. [[Touchpad Synaptics]] has 100+ backlinks and the more important ones - a bit tedious task. I was just glancing over your clever github bot scripts. It would be handy to have a script after such moves: walk over the backlinks of [[Touchpad Synaptics]] and just replace "[[Touchpad Synaptics" with "[[Synaptics" from the links. That would leave all links to subsections intact. Leaving out the translations to handle manually, there would not be much to go wrong, or? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:36, 26 September 2015 (UTC)<br />
<br />
:Hi, thanks for the suggestion. It would be indeed handy in this case, but most likely not generally. Imagine that there was a [[UUID]] page, which was later generalized and renamed to [[Persistent block device naming]] and content about UUID is now only a section on the page. In this case using the naive replacement would likely change the meaning of many sentences, and using shorter redirects for convenience is actually encouraged. There would have to be a list of whitelisted "harmless" replacements, which could even help to replace <nowiki>[[pacman|Install]]</nowiki> with <nowiki>[[Install]]</nowiki> etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:01, 26 September 2015 (UTC)<br />
<br />
::Yes, good examples, but you are thinking universal already :) I did not mean it could be that. For example, if you take the time when the bulk of the title case moves were done. With such a script one could avoid a lot of internal redirects as well. E.g. [https://wiki.archlinux.org/index.php/Special:WhatLinksHere/Beginners'_Guide]. But it's ok, just an idea. Please close this, if you think it's too singular cases with a simple enough replacement where it could be applied. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 10:02, 26 September 2015 (UTC)<br />
<br />
== mkosi ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=Systemd-nspawn&diff=0&oldid=491975 revert]: You can use mkosi also to create a container/directory tree (-t directory). So it can do the same and more. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 11:33, 1 October 2017 (UTC)<br />
<br />
:Alright, how is the "more" relevant to systemd-nspawn though? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:30, 3 October 2017 (UTC)<br />
<br />
::Hi, mkosi let's you create images (or directory trees) of various different distributions and allows you to do things like setting the root-password or installing additional packages. systemd-nspawn alows you to boot such images/directory trees. So I thought mentioning mkosi as alternative to manually creating a container with pacstrap or debootstrap would be worth it. -- [[User:Nudin|Nudin]] ([[User talk:Nudin|talk]]) 22:23, 5 October 2017 (UTC)<br />
<br />
== Waking from suspend with USB device ==<br />
<br />
Hi Lahwaacz, thanks for your input on this topic.<br />
Can you help me a bit further, I know the USB host controller and the USB device are different things but I thought that enabling the host controller was not necessary anymore, see [https://www.spinics.net/lists/linux-usb/msg53661.html].<br />
In my case all the {{ic|driver/*/power/wakeup}} are all enabled by default and the {{ic|/proc/acpi/wakeup}} as well.<br />
Anyway I have added a step in my explanations to identify the path awaiting for more clarity.<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 21:57, 16 January 2018 (UTC)<br />
<br />
:Hi, thanks for the link, it's entirely possible that something changed since the section was written. However, in my case only the keyboard device has wakeup enabled by default: {{bc|<nowiki><br />
$ for f in /sys/bus/usb/drivers/usb/*/power/wakeup; do echo "$f: $(cat $f)"; done<br />
/sys/bus/usb/drivers/usb/1-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/2-1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-11/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/3-12/power/wakeup: enabled<br />
/sys/bus/usb/drivers/usb/3-13/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/4-4/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb1/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb2/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb3/power/wakeup: disabled<br />
/sys/bus/usb/drivers/usb/usb4/power/wakeup: disabled<br />
</nowiki>}}<br />
:But in practice it seems to wake up the system even without the host controllers enabled for wakeup... It might also depend on some BIOS/firmware settings but if it works by default on most systems then I think the host controller settings could be removed again.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:14, 19 January 2018 (UTC)<br />
<br />
== Are supported local/remote destinations important for choosing a backup program? ==<br />
<br />
You [[Special:Diff/525550|reverted]] my edit adding supported backup destinations to [[Synchronization_and_backup_programs]]. This is puzzling to me. Here are some thoughts:<br />
* if choosing any backup program, the ability to send the backup off-site vs only on a local disk is a key feature consideration. Perhaps *the* key feature: one helps me recover in case my house gets burglarized or burns down, and the other does not. This is a much more important feature consideration than, say, whether the program is written in Go or Mono (something that has a full column). I think it's hard to disagree on that.<br />
* Given this, I am very puzzled you would use the term "useless" in the revert message.<br />
* I assume you didn't like that the table got even bigger (it didn't fit into the layout even before). I don't like it either, but perhaps the revert should have said "can you put this somewhere else, not in this already-too-big table?"<br />
* On a personal note, when I provide feedback or give opinion on somebody else's work, I'd like to be constructive and kind, instead of aggressive and putting people down. Just a thought. Thanks for listening.<br />
<br />
[[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 17:38, 11 June 2018 (UTC)<br />
<br />
:No because you can use any remote back-end with any backup application by just running one command / writing the backups to a [[FUSE]] (if available).--[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 04:39, 12 June 2018 (UTC)<br />
<br />
::Hmm, by that reasoning we don't need the Arch package repository, as long as we have source code and makepkg. Or Perl, if we have bash and awk. But even then, and if all the fuse backends existed (I doubt they do), and if it were easy to set all of them up (another thing I doubt), do you indeed believe that running something written to read/write local files will be just as efficient backing up gigabytes of data to a remote repository as something that is specifically optimized for that use case? Note that backing up, say, daily, a typical hard drive via tpyical consumer broadband is still quite a bandwidth challenge in many places today. What about we add this info, and remove (or merge) some other columns to make the table smaller? {{Unsigned|18:08, 12 June 2018|Jernst}}<br />
<br />
:::Your comparisons don't make sense. Mind the slash in my response, you do not need a FUSE implementation, a simple CLI suffices. You do not need to "set all of them up", you only need one. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 18:47, 12 June 2018 (UTC)<br />
<br />
::::If you ever attempt to help a normal user set up a reliably-working off-site backup strategy, think of this discussion. In the meantime, this is all the time I'm going to spend on a discussion that has such repeated gems in it as "makes no sense" without explaining why you think so. Have a nice day. [[User:Jernst|Jernst]] ([[User talk:Jernst|talk]]) 18:54, 12 June 2018 (UTC)<br />
<br />
== The pip section in [[Python package guidelines]] ==<br />
<br />
Hi, you wanted the warning about using pip or wheels restored but accidentally(?) reverted my whole set of changes. I redid them, leaving the warning in place. – [[User:Flying sheep|flying sheep]] 08:17, 8 March 2019 (UTC)<br />
<br />
:Full revert was intentional, because the "wheel" section is not a full replacement for "pip" because there are packages which don't provide wheel files. As I said in the edit summary, there is no reason to recommend one or the other due to the warning. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:21, 8 March 2019 (UTC)<br />
::That still doesn’t explain why you reverted the first part, that had nothing to do with the pip/wheel section and simple improves the files.pythonhosted.org URLs. I restored that one while we’re discussing the pip/wheel section. And about that: There’s no reason to use pip for anything else, and pip is only used because some people (me included) didn’t understand that you can install most wheels by just extracting them to the correct location. So what do you think is missing from my wheels section that the former pip section had? – [[User:Flying_sheep|flying sheep]] 11:41, 11 March 2019 (UTC)<br />
<br />
:::If you didn't notice, the page includes "guidelines" in the title. So the page should contain only common and recommended ways to do things, not everything that is possible to do. If you think that your way to install "wheels" should be followed by everybody, feel free to discuss it on the talk page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:26, 11 March 2019 (UTC)<br />
::::Well, extracting static archives sounds much more recommended than running pip with like 7 options to make it behave. I added a talk item: [[Talk:Python package guidelines#Remove_pip_section_in_favor_of_wheels_section?]] – [[User:Flying_sheep|flying sheep]]<br />
<br />
== wpa_supplicant ==<br />
<br />
Regarding https://wiki.archlinux.org/index.php?title=WPA_supplicant&diff=577215&oldid=577167, one person ran into this problem in March of this year and spent too much time diagnosing it:<br />
<br />
https://bbs.archlinux.org/viewtopic.php?id=244950<br />
<br />
It took me a few days to find the problem. I want to make sure the next time someone encounters it, they easily find relevant information about what the cause is. Since you've reverted my edits to both netctl and wpa_supplicant, what do you suggest?<br />
<br />
--<br />
<br />
[[User:Pooryorick|Pooryorick]] ([[User talk:Pooryorick|talk]]) 08:24, 18 July 2019 (UTC)<br />
<br />
== F2FS and GRUB ==<br />
<br />
Hello. :) I'm here to address a recent disagreement. I noticed a reversion of my edit regarding the F2FS filesystem, in particular regarding the configuration file to edit (with you representing /boot/grub/grub.cfg and me representing /etc/default/grub). I run F2FS on my daily driver with an encrypted root filesystem and encrypted boot on a separate partition, and have never had to touch grub.cfg. I only automatically generate it. It's possible to use either, but /etc/default/grub would make more sense as a recommendation in my mind because grub.cfg has the potential to be overwritten during updates, whereas /etc/default/grub doesn't. <br />
<br />
If there's a compelling reason to use grub.cfg over /etc/default/grub, please let me know. ^^ I'm always eager to learn more about Arch. I don't want to get in a reversion war so I've left your change untouched for the time being.<br />
<br />
[[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 00:17, 8 September 2019 (UTC)<br />
<br />
:The reason is explained in the section: "If GRUB is used with an unsupported filesystem it is not able to extract the UUID of your drive so it uses classic non-persistent /dev/sdXx names instead." If it does not apply to F2FS, it should be made clear. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:29, 8 September 2019 (UTC)<br />
<br />
::You can specify UUID's in GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, so my proposed solution would work for F2FS and other unsupported filesystems, without the burden of manually editing grub.cfg. If there's anything I need to clarify or something else I'm missing, just let me know. :) [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 19:37, 8 September 2019 (UTC)<br />
<br />
:::The {{ic|1=root=}} parameter is not supposed to be in GRUB_CMDLINE_LINUX_DEFAULT, regardless if UUID is used or not. ''grub-mkconfig'' automatically detects the root filesystem and adds the appropriate {{ic|1=root=}} parameter based on GRUB_DISABLE_LINUX_UUID. In any case, your change to the paragraph does not make sense. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:02, 8 September 2019 (UTC)<br />
<br />
::::It could simply be because I use full disk encryption, and adding a kernel parameter for the encrypted disk's UUID is correct in that situation. You're more experienced with contributing to the wiki, so I guess I'll defer to your judgment. It felt like a reasonable edit and solution to me and I don't see the downside to including it in GRUB_CMDLINE_LINUX_DEFAULT. [[User:Eurydice|Eurydice]] ([[User talk:Eurydice|talk]]) 05:38, 9 September 2019 (UTC)<br />
<br />
== dracut executable link ==<br />
<br />
Hello, your last edit on the dracut page (https://wiki.archlinux.org/index.php?title=Dracut&oldid=596388) that undid my 'Link to direct "make executable" section for executable link' commit states: "the redirect executable points exactly to that section", but it doesn't. Following the [[executable]] link just points to the top of the Help:Reading page.<br />
<br />
{{unsigned|17:06, 28 January 2020|Krathalan}}<br />
<br />
:In that case your browser probably does not work correctly, because the redirect [https://wiki.archlinux.org/index.php?title=Executable&redirect=no really points to the section]. Or MediaWiki, there was a bug several years ago... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 28 January 2020 (UTC)<br />
<br />
:: How strange... thanks for pointing that out. It does indeed appear to be some issue with my Firefox configuration. [[User:Krathalan|Krathalan]] ([[User talk:Krathalan|talk]]) 19:51, 28 January 2020 (UTC)<br />
<br />
== Getting install.php work in DokuWiki ==<br />
<br />
Hi, than you for having undone my contribution and pointed to the right solution on [[Dokuwiki#Configuration]]. Indeed I had read this solution before, but I was misled by the condition "if you are using lighttpd or nginx and your PHP version is lower than 7": as I use Apache with php v. 7.4.3 I didn't take it into account. Do you know what a correct rephrasing could be? Maybe it should be deleted?<br />
<br />
Also, I think that, at the end of this same section, one should add something like "verify that {{Pkg|php-gd}} is installed and restart {{ic|php-fpm.service}}".<br />
<br />
Naturally I can do it myself, but I prefer to ask before.<br />
[[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 17:31, 19 February 2020 (UTC)<br />
<br />
:Hi, apparently it depends on whether you had {{ic|open_basedir}} set previously or not. I've changed the page, feel free to update the gd extension. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:16, 19 February 2020 (UTC)<br />
<br />
::Thank you! However, while, I didn't have {{ic|open_basedir}} set previously, I couldn't access ''install.php''. I suspect there is another thing to do, since the configuration editor in DokuWiki complains that it cannot modify the configuration files although ownership and permissions are correctly set for the relevant symlinks, directories and files, and so is {{ic|open_basedir}}. However I can edit my pages. Maybe a return from a new user with a fresh installation would be more useful, though. [[User:BDumont|BDumont]] ([[User talk:BDumont|talk]]) 08:20, 20 February 2020 (UTC)<br />
<br />
== Dead link in Simple stateful firewall#See Also ==<br />
<br />
Hi, Jakub. I am about [https://wiki.archlinux.org/index.php?title=Simple_stateful_firewall&diff=599725&oldid=599717 this] edit. I tried to follow that link one more time and it is not require entering captcha. I am not see any content limitations and my colleague (he uses Tor) does not see them too. I am not sure how it works, so I leave it on your descision. -- [[User:Duodai|Duodai]] ([[User talk:Duodai|talk]]) 14:29, 1 March 2020 (UTC)<br />
<br />
:Well, maybe it depends on the location from which the request comes. But I don't know how it works either... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:33, 1 March 2020 (UTC)<br />
<br />
::my guess is it returns captcha for crawlers only -- [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 01:59, 2 March 2020 (UTC)<br />
<br />
:::I'm getting it in my browser... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:14, 2 March 2020 (UTC)<br />
<br />
== SystemD user units depending on graphical session ==<br />
Hi,<br />
regarding reverting my addition to [[Systemd/User]], could you please explain why? I referenced [[https://www.freedesktop.org/software/systemd/man/systemd.special.html]] which directly contradicts what you said in your summary.<br />
<br />
{{unsigned|19:53, 5 May 2020|Fuero}}<br />
<br />
:The note in [[Systemd/User#How it works]] still applies - systemd services are never per-session, but per-user. The service does not magically get the correct DISPLAY or WAYLAND_DISPLAY variable, it does not work if you have multiple sessions per user, etc. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:45, 6 May 2020 (UTC)<br />
<br />
== Plymouth ==<br />
<br />
Actually with just Plymouth it does not work properly. Even 0dd17y had the same issue in https://bbs.archlinux.org/viewtopic.php?id=220900.<br />
<br />
The reason I did not file a bug report is that it is anyway fixed in the git version and the latest release (0.9.4) is around 2 years behind master<br />
<br />
{{unsigned|09:50, 6 May 2020|M.Srikanth}}<br />
<br />
:So if you don't have to file a bug report, add a full troubleshooting entry or at least properly reference your inline note instead of resorting to plain "if that does not work, try this instead". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:15, 6 May 2020 (UTC)<br />
<br />
== [Bitcoin core] build the code and run the test suites ==<br />
<br />
Hello,<br />
<br />
This week, I managed to build the Bitcoin code and run all the test suites with the help of this page: https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests<br />
<br />
Archlinux has two particularities:<br />
* being in rolling release, it takes to manually use the library {{ic|Berkeley DB (BDB) v4.8}}<br />
* the {{ic|/tmp}} directory is by default limited to half the size of the Ram<br />
<br />
For these reason, maybe it could be interesting to have a page in the wiki to explain how to build the Bitcoin core?<br />
<br />
Cheers,<br />
<br />
Thomas<br />
<br />
[[User:Thomasb|Thomasb]] ([[User talk:Thomasb|talk]]) 20:29, 9 May 2020 (UTC)<br />
<br />
:I don't think that this is useful. There is the {{AUR|bitcoin-core-git}} package and nothing more should be needed. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:53, 26 May 2020 (UTC)<br />
<br />
== Double linefeed results in extra line ==<br />
<br />
If you look at templates that end with double linefeed before noinclude this would result in extra line in resulting page.<br />
<br />
It may be a minor point but since you are perfectionist about wikitext I should mention this is a tradeoff and it results in slightly worse result.<br />
<br />
Removing just one linefeed removes the problem while still allowing it to not jumble all the tags into same line.<br />
<br />
-- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 16:30, 11 May 2020 (UTC)<br />
<br />
:If this is about [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=next&oldid=612179], the spaces I added back are not included when the template is used elsewhere, because the spaces are inside the noinclude tags. The extra space is only on the template page itself, but it does not result from template inclusion. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:41, 11 May 2020 (UTC)<br />
<br />
::OFC, I mean the template page render has extra line. -- [[User:Svito|Svito]] ([[User talk:Svito|talk]]) 21:21, 11 May 2020 (UTC)<br />
<br />
:::I agree with [[User:Svito|Svito]], isn't it good to delete the extra blank lines? -- [[User:Blackteahamburger|Blackteahamburger]] ([[User talk:Blackteahamburger|talk]]) 05:39, 12 May 2020 (UTC)<br />
<br />
::::OK, let's do it. [https://wiki.archlinux.org/index.php?title=Template:Cat_main&diff=616382&oldid=612181] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:47, 26 May 2020 (UTC)<br />
<br />
== Re: lighttpd: remove python2 version ==<br />
<br />
Instead of removing the example we could as well add an example using a Python3 library like https://pypi.org/project/flup6/.<br />
<br />
{{unsigned|15:23, 18 May 2020|Gruentee}}<br />
<br />
:Feel free to add it if you find it useful. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:56, 18 May 2020 (UTC)<br />
<br />
== Xbindkeys removal ==<br />
<br />
Hi, just wondering why you [https://wiki.archlinux.org/index.php?title=Xbindkeys&diff=617675&oldid=617670 removed my edit] from [[Xbindkeys]]? The xbindkeys page has a number of quick tips but no mention of how to bind anything to the Print Screen key so I thought it would be useful to add. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:27, 3 June 2020 (UTC)<br />
<br />
:Giving examples for all keys on the keyboard is useless, there is [[Xbindkeys#Identifying keycodes]] which teaches how to find the keycodes and keysyms of any key. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 3 June 2020 (UTC)<br />
<br />
:: So how come you left the examples for the volume up/down and brightness? What is different between those examples and a screenshot example? Aren't more examples better to save people from hunting all over the place trying to piece things together themselves? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 14:03, 4 June 2020 (UTC)<br />
<br />
:::The difference is that when it comes to volume control, there are 1 or 2 options for the 99% most common cases, but for screenshot taking there are dozens of different options. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:15, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for edit to XDG Base Directory page regarding python_history ==<br />
<br />
I understand the justification for reverting the change I made, however I would like to point out that similar entries on the page (such as Maven) also have instructions for what contents to put in files (even though there is native documentation for those settings). Additionally, it took me a bit of re-reading on the linked Python documentation to reason out how the documentation's example needed to be modified, since it's not clear from the Python documentation whether placing such code in the PYTHONSTARTUP file will actually ''override'' the default behavior. [[User:Varriount|Varriount]] ([[User talk:Varriount|talk]]) 20:44, 20 June 2020 (UTC)<br />
<br />
:Even maven's note can be [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=631704&oldid=631630 shortened]. The notes in the table must be as short as possible, there is no place for extended explanations or long code snippets like in the upstream documentation. If the Python's documentation is not clear enough, I don't think any note in a massive convoluted table will ever be better. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:47, 12 August 2020 (UTC)<br />
<br />
== Re: Revert for Backlight page ==<br />
<br />
Hi, you reverted my change to [[Backlight]] page that mentioned WIP patches for controlling OLED panel brightness. I don't really understand justification for reverting it since currently the page says that OLED brightness can be controlled only by changing gamma ramp. That is wrong - since it's not the only way - these panels can control brightness with a PWM. Moreover controlling brightness with gamma ramp is not optimal - it essentially reduces dynamic range, i.e. at 50% you have 7 bits per pixel, at 25% - 6 bit per pixel, etc. That results in banding artifacts at lower brightness level.<br />
<br />
As far waiting for the patches to be merged before mentioning it there - it'll take ~3-6 months (yes, that's the process) and I haven't found *any* reference to these changes on the internet - everyone recommends using gamma ramp instead of fixing it properly. I'm absolutely sure that having information about these patches would not hurt [[User:Anarsoul|Anarsoul]] ([[User talk:Anarsoul|talk]]) 15:56, 30 June 2020 (UTC)<br />
<br />
:Linking to a repo which which has 2 custom commits on top of some arbitrary development version of the Linux kernel tree is not helpful for users. Nobody will compile directly from this repo which is already significantly outdated compared to recent kernel versions and there is no indication if the patches actually work with newer (or older) kernels. We can mention the PWM control as a general concept though. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:32, 12 August 2020 (UTC)<br />
<br />
== Automatic template correction ==<br />
<br />
Per [[Help:Template#Style]], templates should be used with the capitalization shown in the examples in their pages, so {{ic|&#123;{AUR&#124;...}} is correct, while {{ic|&#123;{aur&#124;...}} is not.<br />
<br />
However, there are pages that don't respect that rule (e.g. [[Android_Debug_Bridge]] until recently).<br />
<br />
I beleive this correction should be easy to implement using a bot. What do you think?<br />
<br />
{{unsigned|07:24, 25 August 2020|Relrel}}<br />
<br />
:Yes, this should be easy, but the bot should not make a huge amount of simple style-only changes - they should be combined with corrections for more complex rules. Anyway, there is an idea to create a [https://github.com/lahwaacz/wiki-scripts/issues/22 style linter] for the ArchWiki rules. Would you like to help? ;-) – [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:21, 25 August 2020 (UTC)<br />
<br />
== Failed to create tun device ==<br />
<br />
I don't understand your reason for [[https://wiki.archlinux.org/index.php?title=NetworkManager&diff=0&oldid=634880 removing my section in NetworkManager]]. Could you elaborate?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 07:40, 11 September 2020 (UTC)<br />
<br />
:You can't use [[systemd-networkd]] and [[NetworkManager]] at the same time. Even if you don't have any ''.network'' file for systemd-networkd, you can't solve NetworkManager's problems with systemd-networkd. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:43, 11 September 2020 (UTC)<br />
<br />
::Ok, thanks, in this case it solved the error I got. Now the VPN works. Do you have an idea about how to solve it without systemd-networkd?--[[User:Egils|Egils]] ([[User talk:Egils|talk]]) 22:27, 11 September 2020 (UTC)<br />
<br />
:::You should really fix the permission problem for {{Pkg|networkmanager-openvpn}}. The tun interface should be managed by OpenVPN which needs rights to create it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:37, 12 September 2020 (UTC)<br />
<br />
::I don't think this statement is entirely correct. [[systemd-networkd]] and [[NetworkManager]] can happily co-exist together if they are managing different interfaces. I unfortunately don't have a reference to point to this, but I came across this being mentioned a couple of times on forums. I personally use [[NetworkManager]] on my laptop to handle wifi, while [[systemd-networkd]] is in control of virtual ethernet and bridges for all my [[systemd-nspawn]] instances. [[User:Romstor|Romstor]] ([[User talk:Romstor|talk]]) 03:24, 12 September 2020 (UTC)<br />
<br />
== [https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&oldid=636526/ XDG Base Directory]: Undo revision 636525 ==<br />
<br />
Dear Lahwaacz,<br />
<br />
maybe my changes were to rushed and from my point of view only. But I have two points to consider:<br />
<br />
# If I put the quotes around my vimrc and source it from my .bash_profile, I get the vim-error E471 (Argument required). Without quotes, this doesn't happen. So this change based on experience.<br />
# The rtp should includes directories, which are needed at runtime. (in plain vim e.g. ~/.vim). This is not a typical configuration directory. My mistake was, that I supposed that everyone put their vim plug-ins in $XDG_DATA_HOME and not in $XDG_CONFIG_HOME, because from my point of view a plug-in doesn't belong to the configuration. Maybe it is a good idea to add a remark, which explains the addition of $XDG_CONFIG_HOME to the rtp.<br />
<br />
[[User:Grrr|Grrr]] ([[User talk:Grrr|talk]]) 13:53, 26 September 2020 (UTC)<br />
<br />
# Quotes are there because $XDG_CONFIG_HOME may contain spaces.<br />
# It's not only about quotes - the runtimepath has subdirectories for color schemes, keymaps, autoload scripts etc.<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 26 September 2020 (UTC)<br />
<br />
== Readability in Wiki ==<br />
<br />
I noticed that you and the other admins and moderators often want sentences to continue endlessly, without line breaks.<br />
For example in the introduction of [[Wayland]].<br />
<br />
I think it would be better to have more seperated sentences, so it is easier to read and "important" information is easier visible for people.<br />
I don't know who is responsible, but maybe some options in MediaWiki (or whatever this wiki software is) could be changed as well, to make make line breaks etc. easier and reduce the height-space (if you know what I mean) between sentences, so it looks better, even though line breaks are used.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:38, 15 October 2020 (UTC) G3ro<br />
<br />
:I don't know exactly what you mean. Is it about the readability of the rendered HTML or the "source code" of the page? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:15, 15 October 2020 (UTC)<br />
<br />
:: Well I guess it can be about both. But mainly it is about what people see on the page.<br />
:: There are three seperate topics I mentioned:<br />
<br />
:: 1. Use line breaks: I would like to use more line breaks, because if you have long sentences that are written after each other without line breaks, it gets "harder" to recognize when the next sentence starts.<br />
:: While I agree to what you said somewhere, that sentences that belong directly together, should be written in one "paragraph", it would be useful for sentences that cover (slightly) different "topics" to be visibly parted.<br />
<br />
:: 2. Adjust margin options: I notice that when line breaks are used, there is a vertical space added between two sentences. Just like in this post. If you would use line breaks more often, this is a little too much spacing in my oppinion.<br />
<br />
:: 3. Potential options to make line breaks easier: It would be very convenient if a line break in the source code would lead to a line break in displayed text as well, instead of needing to add an empty line.<br />
<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:33, 15 October 2020 (UTC) G3ro<br />
<br />
:::OK, now I understand. I agree that splitting different topics usually improves legibility, but they should be split into separate paragraphs and not just by line breaks (e.g. using the &lt;br> tags). Paragraphs are semantic units whereas line breaks inside a paragraph are usually typographic errors.<br />
:::Also note that such splitting alone may not be enough to improve the text flow. For example, if we consider the intro for [[Wayland]], the second sentence about XWayland would not constitute a good paragraph - it is just a plain statement and the new topic is not nicely introduced. Ideally, you'd split the topic and make some wording changes for the second paragraph.<br />
:::As for the margin options, that is the difference between paragraph splitting and non-semantic line breaks. In my opinion, the styling is correct in this respect, as paragraphs should be discernible. You mentioned that you like line breaks to easily recognize where a sentence ends - but reading should be based on whole paragraphs, not sentences. There should be no reason to skip anything in the middle of a paragraph, otherwise it should be probably split into multiple paragraphs or otherwise rephrased.<br />
:::If you find it hard to follow a long sentence horizontally on a wide screen, we might consider enforcing some maximum width for the whole content. I think the readability would be better, since there would be more top-to-bottom eye movement at the cost of left-to-right-and-back.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:59, 15 October 2020 (UTC)<br />
<br />
== Xorg parentheses ==<br />
<br />
I actually think that X(org) is very useful to imply that it is one and the same thing.<br />
<br />
It might even be more confusing now, as we use both Xorg and X, because the wiki title and the package titles are Xorg.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:30, 17 October 2020 (UTC) G3ro<br />
<br />
:Well the conventions should be established on the [[Xorg]] page, not anywhere else... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:36, 17 October 2020 (UTC)<br />
<br />
:: Imo the conventions are established by upstream and they use a wide variety of X, X.org, X(org), Xorg etc.<br />
:: As I said I always prefer X(org) because then it is clear, that both are same thing.<br />
:: But ultimately it's your decision. <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 13:43, 17 October 2020 (UTC) G3ro<br />
<br />
:::When upstream is not capable of making a unambiguous decision, it makes sense that other projects pick some option and stick with it wherever they can to keep at least some consistency. So for this wiki, pages should use the same style as the [[Xorg]] page. But feel free to start a discussion about this in [[Talk:Xorg]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:56, 17 October 2020 (UTC)<br />
<br />
== SSHFS - systemd edit ==<br />
<br />
The edit was removed because "there is no advantage over using fstab entries".<br />
<br />
Is not only about the dis/advantages of the systemd option, is about that it is another possibility to achieve the task, that is why it was created in another level and the fstab section was left alone.<br />
<br />
Reconsider the edit as it presents another option which people can use.<br />
<br />
[[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 16:22, 22 October 2020 (UTC)<br />
<br />
:There is no need to use anything else, fstab just works well enough. Configuring mounts with systemd services is not a good idea - it is much more bloated than fstab and not the right tool for it. If anything, a different type of systemd units should be used: {{man|5|systemd.mount}}. But creating the mount units manually is still pretty useless since everything can be configured in fstab and systemd will generate the unit for you. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:22, 22 October 2020 (UTC)<br />
<br />
:: It is about the ability to use the user's .config file and all the proper options that are saved there. Also systemd gives the possibility to use different targets, so the user could mount it when an specific user logs in or when a graphical session starts. I could argue that bad a modification of fstab could lead to a system that doesnt boot, but such poorly configured systemd unit file just fails and the system is fine. Just give the user the information and let it decide what they can use depending on their use case. [[User:Garnica|Garnica]] ([[User talk:Garnica|talk]]) 08:08, 24 October 2020 (UTC)<br />
<br />
:::You can configure systemd targets in fstab using the {{ic|x-systemd.wanted-by}} and {{ic|x-systemd.required-by}} options, there are also {{ic|nofail}} and {{ic|noauto}} options. Please read the {{man|5|systemd.mount}} manual.<br />
:::Using hosts from the user's {{ic|.ssh/config}} is the only thing which is not possible with fstab, but this does not warrant using the wrong tool for the task. Simple copy the full {{ic|user@hostname}} into fstab and you're done.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:47, 24 October 2020 (UTC)<br />
<br />
== [[Self-encrypting drives]] ==<br />
<br />
Hi, I'd like to respectfully disagree with the rollback. It's specific to sedutil that with most commands you need to input /dev/nvme0 (when encrypting the device) but for the sleep commands it requires /dev/nvme0n1 or it fails with a very unspecific error (Error saving the password to the kernel errno = 25), as found out in the discussion https://github.com/Drive-Trust-Alliance/sedutil/issues/90<br />
<br />
All in all I believe that it is important to keep this piece of information which was found out in a long discussion between the reporter and the developers. I ran into it and I believe many people may run into it, considering most of the new SSD will be NVMe. Best, [[User:Przemub|Przemub]] ([[User talk:Przemub|talk]]) 13:34, 28 October 2020 (UTC)<br />
<br />
:OK, then it makes sense. But it should be probably explained before, not in the section about the sleep command. Also please add the link to the note as a reference. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:27, 28 October 2020 (UTC)<br />
<br />
== Nvidia Installation ==<br />
<br />
The whole guide is unnecessary long and overcomplicated formulated.<br />
Shorter is better, most people will know their graphic card for example, so the determination etc. is only optional.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:21, 10 November 2020 (UTC) G3ro<br />
<br />
:Moving some info to some other page and leaving a tip behind does not make it shorter, but harder to follow. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:36, 10 November 2020 (UTC)<br />
<br />
== Btrfs layout ==<br />
<br />
Hi, Lahwaacz<br />
<br />
Thanks for maintaining [[Snapper]]! However I think the layout is not openSUSE specific and beneficial to all btrfs users. Can you elaborate your reason of undoing the edits? IMO the previous 'simple layout' complicates the rollback procedure.<br />
<br />
Cheers,<br />
[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 07:26, 3 December 2020 (UTC)<br />
<br />
:It is not overcomplicated, it is just doing things right. You can read about that in the forum thread, see the first note in [[Snapper#Suggested filesystem layout]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:24, 3 December 2020 (UTC)<br />
<br />
::Anyway I've moved the guides to my user page. It's not that I haven't read the 5-year-old forum post, it's that before the current layout I followed that post and resulted in a not fully rolled-back system. That post also sourced (then current) information from openSUSE. openSUSE has since massively overhauled the layout, as I pointed out in an edit you undid earlier.[[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 09:02, 3 December 2020 (UTC)<br />
<br />
::Since last message I've extensively documented the new layout at [[User:I2Oc9/Btrfs_subvolumes]] and [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption]]. Have a look for yourself. Nothing new really, but IMO [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my take]] is much more simpler and complete than the supposedly [[Snapper#Restoring_/_to_a_previous_snapshot_of_@|simpler one]]. That one does not leverage native {{ic|snapper rollback}} or {{Pkg|grub-btrfs}}, among other things. I strongly suggest you try if you have time. [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 11:55, 3 December 2020 (UTC)<br />
<br />
::Actually if you look closely, none of [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Rollback_/_&_system_recovery|my recovery methods]] is specific to [[User:I2Oc9/Btrfs_subvolumes#A_new_kind_of_layout|the new 'complex' layout]], it will work totally fine with the old one. I just don't think moving @ around in live environment is appropriate.<br />
<br />
::On the other hand, the layout recommendation has been updated by openSUSE [https://en.opensuse.org/SDB:BTRFS], why stick with the old one? [[User:I2Oc9|I2Oc9]] ([[User talk:I2Oc9|talk]]) 12:37, 3 December 2020 (UTC)<br />
<br />
:::The main reasons why I reverted your edits on the [[Snapper]] page are: 1) it was a huge change which was not discussed previously as required by [[ArchWiki:Contributing#The 3 fundamental rules]], and 2) it has some elements which do not apply to Arch (see below). If you wish to propose a better layout of the subvolumes, it should be discussed in [[Talk:Snapper]] first. Your user pages would serve as great drafts.<br />
:::Note that the current suggested layout is not ''flat'' in the sense of [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|your section]] - it has a separate subvolume for {{ic|.snapshots}} so it does not lead to the recursive mess. So your proposed layout seemed very similar to the current suggested layout. The real difference is which subvolume gets mounted at {{ic|/}}, but I did not find it explained anywhere on the Snapper page before I reverted the changes (I get it now from your user page). I also did not find a proper documentation of the openSUSE's layout - it seems to be just the product of their installer and the documentation only deals with the result, saying at most that [https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha-snapper.html#sec-snapper-snapshot-boot the subvolume configuration must not be changed] for rollbacks to work.<br />
:::Now the openSUSE-specific elements: some Arch packages actually install software into {{ic|/opt}}, so the recommended layout should not suggest a separate subvolume for this path. Even more importantly, the pacman database is located at {{ic|/var/lib/pacman/local/}} and it must be rolled back along with the system, so there should be no separate subvolume for {{ic|/var}}. Instead, users should be encouraged to create (even nested) subvolumes for specific data directories under {{ic|/var}}, such as {{ic|/var/log}}, {{ic|/var/tmp}}, {{ic|/var/cache/pacman}}, {{ic|/var/lib/machines}}, etc.<br />
:::Finally, the suggested layout should not be GRUB-specific, there should be no recommendations regarding a boot loader. Sure it is useful to include non-trivial tips, but people may actually use a different boot loader.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:31, 4 December 2020 (UTC)<br />
<br />
::::Thanks for your detailed reply. I admit that I'm not knowledgeable on the intricate differences between distributions and shouldn't have made the changes without properly discussing them first.<br />
::::Yes, I get that the current layout is not [[User:I2Oc9/Btrfs subvolumes#Snapper on flatly-installed system subvolume|the one described in this section]] and indeed properly separates {{ic|/.snapshot}} and {{ic|/}}. The layout I proposed attempts to add some "niceties" such as supporting multi-distribution installations (complex and unnecessary, I agree) and bring the openSUSE layout here, which is a mistake, as you've pointed out.<br />
::::As for GRUB, since I use LUKS all the time and it's the only bootloader supporting encrypted {{ic|/boot}} on Btrfs on LUKS1, I really didn't think of any other possibilities.<br />
::::I will incorporate your recommendations to my user page and add a new section in [[Talk:Snapper]] pointing to those pages.<br />
::::Cheers -- [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:09, 4 December 2020 (UTC)<br />
<br />
:::::I've adopted [[Install_Arch_Linux_on_ZFS#System_datasets|Archlinux Root on ZFS layout]] to [[User:I2Oc9/Root_on_Btrfs_with_LUKS_full_disk_encryption#Create_subvolumes|my proposal]]. [[User:S0x9v|S0x9v]] ([[User talk:S0x9v|talk]]) 10:56, 4 December 2020 (UTC)<br />
<br />
== Reflector Revert ==<br />
<br />
Hi Lahwaacz, about your [https://wiki.archlinux.org/index.php?title=Reflector&oldid=643749 revert], it seems like there's precedence for including AUR packages that replicate the code on the wiki. For example, in [[dash#Relinking /bin/sh]].<br />
<br />
In addition, I believe that there's value for linking the AUR package because it allows a simpler user experience where the AUR package is maintained for them. That way, if it is ever updated, they can easily fetch the update instead of religiously checking the wiki page (which most users probably don't do).<br />
<br />
Thanks!<br />
<br />
[[User:Denton-l|Denton-l]] ([[User talk:Denton-l|talk]]) 01:52, 7 December 2020 (UTC)<br />
<br />
:That precedence was only created by [https://wiki.archlinux.org/index.php?title=Dash&type=revision&diff=561587&oldid=518398 yourself]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:35, 5 May 2021 (UTC)<br />
<br />
== firefox zoom ==<br />
<br />
"no reason to zoom manually, see HiDPI)" - fractional scaling doesn't work [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 02:38, 26 December 2020 (UTC)<br />
<br />
:That should be explained in [[HiDPI#Firefox]] anyway. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:48, 26 December 2020 (UTC)<br />
<br />
::it's good to have this mentioned somewhere clearly so people know about it before they say "fonts on linux suck" [[User:Ubone|Ubone]] ([[User talk:Ubone|talk]]) 15:51, 29 December 2020 (UTC)<br />
<br />
== Intel GVT-g edits ==<br />
<br />
Hello Lahwaacz,<br />
<br />
I have noticed that you reverted one of the edits I have performed on [[Intel_GVT-g]].<br />
<br />
About this revert: [https://wiki.archlinux.org/index.php?title=Intel_GVT-g&oldid=648062 Windows problems are out of scope]<br />
<br />
While I understand that the ArchWiki is about ArchLinux, this article in particular mentions Windows in the introduction, and already includes another troubleshooting point about Windows. The issue I have encountered with the black bars is somewhat common, as I have found other people discussing it online, and I really fail to see why not including this piece of information in this article would be better than including it.<br />
<br />
Please, let me know your thoughts. If you think that the point can be improved, I will be happy to do that.<br />
<br />
Ciao,<br />
<br />
[[User:Wilcomir|Wilcomir]] ([[User talk:Wilcomir|talk]]) 09:14, 3 January 2021 (UTC)<br />
<br />
:Well, the existing section about a Windows problem is actually solved by configuring the Linux host. I think anything involving configuration or installation of programs in Windows is not appropriate for long troubleshooting sections. At most, they could be mentioned in a short reference to other sites which describe the problem in detail. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:34, 3 January 2021 (UTC)<br />
<br />
== XDG configuration for Vim ==<br />
<br />
Hi Lahwaacz,<br />
<br />
You have reverted the updated Notes for Vim on [[XDG Base Directory]], because "copy-pasted from a blog post".<br />
<br />
The problem is, not only is the configuration presented currently also copied from a blog post too, but is already 10 years old.<br />
<br />
Would it be OK, if we bring back the more up to date version? Or at least remove the obsolete one and leave link to newer?<br><br />
(Although I think a copy on wiki would be beneficial in case my blog ceases to exist)<br />
<br />
[[User:Jorengarenar|Jorengarenar]] ([[User talk:Jorengarenar|talk]]) 02:05, 12 January 2021 (UTC)<br />
<br />
== Root on ZFS draft ==<br />
<br />
Hi, I submitted [https://github.com/openzfs/openzfs-docs/pull/104 a Root on ZFS draft] to official doc repo.<br />
<br />
In the draft, the following directories are separated from root filesystem:<br />
home,root,srv,usr/local,var/log,var/spool,var/tmp<br />
<br />
Is this appropriate for Arch Linux? Or do you have any suggestion on the draft?<br />
Any comment is appreciated.<br />
[[User:M0p|M0p]] ([[User talk:M0p|talk]]) 01:28, 23 January 2021 (UTC)<br />
<br />
== Re: undo GRUB - Common installation errors ==<br />
<br />
Concerning your undo of [https://wiki.archlinux.org/index.php?title=GRUB&diff=next&oldid=649799 Add the error message `Could not prepare Boot variable: No space left on device`)]<br />
Is there a better place to for this Information? One can find the solution in various forums, but I thought it could be helpful to have it in this wiki somewhere. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 12:51, 25 January 2021 (UTC)<br />
<br />
:The error message is not specific to the {{ic|/sys/fs/pstore/}} filesystem (which does not even seem to be used by default on Arch...) Where did you find that? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:16, 25 January 2021 (UTC)<br />
<br />
::I did not find anything Arch specific, but this post about Debian helped: [https://donjajo.com/fix-grub-efibootmgr-not-set-variable-no-space-left-device/ Post]. I also found something about [https://askubuntu.com/questions/1072618/could-not-prepare-boot-variable-no-space-left-on-device-grub-install-error-ef /sys/fs/efi/efivars/dump-*] The problem is that the actual efi-partition does not seam to be the problem, there is more than 70% space left. If there is better information to guide the user in the right direction that wuld be more helpful. This is what I found worked, but I admit that I don't know much about how grub operates. [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 16:20, 25 January 2021 (UTC)<br />
<br />
:::This wiki ''is'' Arch specific so old posts about Debian or Ubuntu do not apply. Even if they did, this is hardly a ''common'' installation problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:29, 26 January 2021 (UTC)<br />
<br />
::::I know that, and would not have put it there if it didn't occur on my Arch Linux installation. If this is something that should not be documented in this wiki, I understand that. Is there any other place you would recommend? An issue for grub-install maybe? [[User:ModProg|ModProg]] ([[User talk:ModProg|talk]]) 22:24, 26 January 2021 (UTC)<br />
<br />
== Kernel Compilation time ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Kernel&diff=next&oldid=650896 link]<br />
<br />
I don't think we should judge information by what is obvious to experts.<br />
People might have experience with compilation of other programs, which mostly is fast, and then there is the kernel which takes forever to compile.<br />
I think it does not hurt anyone to make people aware of it.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:03, 6 February 2021 (UTC)<br />
<br />
:It is an unnecessary information without a definite answer which can even be [https://html.duckduckgo.com/html?q=how%20long%20does%20it%20take%20to%20compile%20Linux%20kernel searched elsewhere]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:23, 6 February 2021 (UTC)<br />
<br />
:: I disagree, with that argument nearly any tip and note is unnecessary. These things are intended to inform users about things that should be taken into consideration and that are different from the norm.<br />
:: Also do you search for the compilation time for every program you intend to compile? I don't.<br />
:: Furthermore this info is included, why not tell it to people directly on the start, so they don't read over it? <br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:36, 6 February 2021 (UTC)<br />
<br />
:::If someone wants to compile the Linux kernel, they should obviously expect that it will take ''some time''. Stating that it "can take up to several hours" does not make sense without referring to a specific hardware. Obviously, it will take much longer on a poor laptop than on a powerful workstation with a many-core processor, but people can assume that themselves. Without a reference to a specific hardware, the note is unnecessarily discouraging because the compilation can be as fast as some tens of minutes - it is by far not the most expensive package to compile...<br />
:::As you said, people can find better notes later along with advices to enable parallel build etc. which is all that's needed IMO.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:03, 6 February 2021 (UTC)<br />
<br />
== Wayland style ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Wayland&diff=prev&oldid=650979 link]<br />
<br />
I think in the old version it was much easier to read the "source code", so I don't see why there can't be spaces between it.<br />
Things shouldn't be complicated more than necessary.<br />
<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 14:11, 6 February 2021 (UTC)<br />
<br />
:Most templates on the wiki are written without spaces around the |. When we [https://github.com/archlinux/archwiki/pull/32 switch the editor], there will even be syntax highlighting. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:25, 6 February 2021 (UTC)<br />
<br />
== Bluetooth keyboard ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php/Bluetooth_keyboard link]<br />
<br />
On your last change you said "not specific to keyboards, all of this is already mentioned on the Bluetooth page", the point is that this is extremely relevant for bluetooth keyboard since it is required to perform the login! If this little piece cannot be duplicated I would suggest at least to leave a link saying "If you want to autoconnect at boot please refer to...". I'm new here and I would not touch it further, but please evaluate the suggestion (this is because after reading bluetooth keyboard page and not finding the solution I had to look for it on forums)<br />
<br />
{{unsigned|21:17, 20 February 2021|Stevexyz}}<br />
<br />
:Well, basically the whole page is flagged to be merged with the main [[Bluetooth]] page, so it's expected to be incomplete. Other tips may always be found on a more general page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:40, 21 February 2021 (UTC)<br />
<br />
== Re: Steam Needs to be online error ==<br />
<br />
Reference: [https://wiki.archlinux.org/index.php?title=Steam/Troubleshooting&diff=next&oldid=653073 link]<br />
<br />
The problem here is that DNS resolution in general works already (yes even outside browsers), i.e. <br />
<br />
dig media.steampowered.com<br />
<br />
would run successfully, but the Steam client couldn’t resolve it. The DNS request from 'dig' shows up in my nameserver’s log, the one Steam should send doesn’t. This indicates it might indeed a problem specific to Steam, and it’s not as easy as just say "go fix your DNS resolution", as it already may work correctly for everything but Steam.<br />
<br />
Additionally, at no point does [[Domain name resolution]] even mention nscd, so you effectively removed a fix/workaround for the problem from the Wiki. So I was definitely not "duplicating an article" here. [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 08:12, 22 February 2021 (UTC)<br />
<br />
:Could I please hear your opinion on this? I’d be happy to just add something along the lines of "if you made sure DNS resolution works but Steam still can’t resolve it, try additionally enabling the nscd service" to the Steam troubleshooting page. Unfortounately I don’t know why running the service helps, but I’d still like to give others an easier time finding this solution than I had myself. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 09:15, 28 February 2021 (UTC)<br />
<br />
::Hi, I'm sorry for the delay. Could you test if using a different program for DNS caching (e.g. [[systemd-resolved]]) instead of {{ic|nscd.service}} fixes the problem? If not, then it's probably not due to DNS - {{man|8|nscd}} actually caches more than just DNS. Also if you have a reference to some website where you found about nscd, it would be nice to add it. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:22, 28 February 2021 (UTC)<br />
<br />
:::No worries. Using [[systemd-resolved]] for DNS resolution (and caching I guess, I wasn’t aware it does that, too) was a thing I did try, but that didn’t fix it for me. The place I found out about nscd fixing it was actually the [https://bbs.archlinux.org/viewtopic.php?id=263356 Arch forums]. When I search the web for Steam in combination with nscd, all I can seem to find are more forum entries of people that don’t know why that fixes it either. I can try a bit to find out what nscd does to make it work, but I’m not too confident I will be successful. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 14:51, 28 February 2021 (UTC)<br />
<br />
::::Okay, so {{ic|nscd}} allows to [https://man7.org/linux/man-pages/man5/nscd.conf.5.html dis-/enable caching per service], and it’s indeed enabling it for {{ic|hosts}} that makes it work. That’s weird though, since [[systemd-resolved]] has caching enabled by default, and using it for resolution didn’t make {{ic|steam}} work for me. Leads me to think that I didn’t set it up correctly, although resolving via {{ic|dig}} *did* work. Since [[steam]] depends on [[Name Service Switch]], I tried resolving using {{ic|getent}} manually with nscd disabled, but that worked while steam did not. I’m not really sure what to make of this, since I have no idea how this low level networking/resolving stuff works really. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 15:39, 28 February 2021 (UTC)<br />
<br />
:::::Hmm, I don't know the details either. Steam needs the multilib packages so maybe that's part of the problem. Could you add your findings to the section and use [[Template:Expansion]] for the missing details? Maybe someone can figure it out. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:44, 28 February 2021 (UTC)<br />
<br />
::::::Sure, I can do that. I’ll probably need a minute to figure out how to use the template though, but I should have the time later today. Thanks for your input on this. -- [[User:Irimi1|Irimi1]] ([[User talk:Irimi1|talk]]) 17:56, 28 February 2021 (UTC)<br />
<br />
== Removal of website link ==<br />
<br />
Refers to this: https://wiki.archlinux.org/index.php?title=PipeWire&diff=next&oldid=653701<br />
<br />
I don't understand why that has to be removed. The official website should be always worth a mention, even if it is somehow mentioned in the text already.<br />
[[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:02, 28 February 2021 (UTC)<br />
<br />
:The "See also" section is for additional links, it is not intended as a collection of all links used on a page. Adding links which are clearly mentioned in the appropriate place only clutters the list. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:24, 28 February 2021 (UTC)<br />
<br />
:: There are just three links and only one of them is really useful, the others could maybe even be removed as they link to old blog posts.<br />
:: I can only repeat myself, that things don't always have to be made more complicated than necessary.<br />
:: The official website is a central point which links to many more useful ressources, so it's one link for much information.<br />
:: [[User:G3ro|G3ro]] ([[User talk:G3ro|talk]]) 20:34, 28 February 2021 (UTC)<br />
<br />
== Removal of bootia32.efi generation procedure from X205TA install page. ==<br />
<br />
Those [https://wiki.archlinux.org/index.php?title=ASUS_x205ta&diff=596239&oldid=562734 instructions] were really straightforward and useful, imho in comparison present ones require too much material to be confident with. I think it's (paradoxically) way easier to generate the file than to configure a `grub.cfg` from zero to boot a live cd. Can we undo the edit? Otherwise we could put them in a new page or section in the GRUB page and link to them maybe. [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 05:07, 4 March 2021 (UTC)<br />
<br />
:If there is something wrong with the information on the [https://wiki.archlinux.org/index.php/Unified_Extensible_Firmware_Interface#Booting_64-bit_kernel_on_32-bit_UEFI general page], it should be improved instead of describing the same procedure in a different way on a completely unrelated page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:16, 6 March 2021 (UTC)<br />
<br />
:: I didn't know we had that info in the UEFI article. I think it could be appropriate to insert the [https://en.wikipedia.org/wiki/Template:See_also#Examples See also] archwiki equivalent (which I couldn't find) for UEFI page on top of the aforementioned section, what do you think? [[User:Tallero|Tallero]] ([[User talk:Tallero|talk]]) 13:28, 7 March 2021 (UTC)<br />
<br />
:::Well, the removed section was previously flagged with "Duplicates [[Unified Extensible Firmware Interface#Booting 64-bit kernel on 32-bit UEFI]]"...<br />
:::Also the laptops pages are usually related to most of the general pages on this wiki, adding all of them would be pretty useless. Users should not expect to find everything on a single laptop page, they should always check if there is a general page for their topic with more details.<br />
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 7 March 2021 (UTC)<br />
<br />
== Re: Show how to use systemd/Timers with wg-quick@.service ==<br />
<br />
I don't think using service is the appropriate when you want to start Wireguard at boot. For most people connecting to a VPN is not exactly part system startup.<br />
A timer should more appropriate.<br />
[[User:ENV25|ENV25]] ([[User talk:ENV25|talk]]) 10:03, 11 April 2021 (UTC)<br />
<br />
:I don't see how OnBootSec=1min is more appropriate than an automatically starting service. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:19, 11 April 2021 (UTC)<br />
<br />
== USB flash installation medium (BIOS bootable) ==<br />
<br />
Hi, about your [https://wiki.archlinux.org/index.php?title=USB_flash_installation_medium&diff=next&oldid=673926 revert]: "making the partition bootable is discussed below"<br />
Do you mean installing syslinux and `dd` the [gpt]mbr with "discussed below"? This was not enought for my setup (Sandisk Ultra 64GB, Dell XPS 9370) to make the partition BIOS bootable. It did work right after I checked "Legacy BIOS Bootable" checkbox using gnome-disks.<br />
<br />
{{Unsigned|13:42, 30 May 2021 (UTC)|Auipga}}<br />
<br />
:Yes, that's what I meant. If it does not work, it should be fixed rather than providing a duplicate instruction without a reason. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:16, 30 May 2021 (UTC)<br />
<br />
== Systemd-networkd systemd-networkd-wait-online.service discussion modifications ==<br />
<br />
I'm not sure why you're reverting my edits.<br />
<br />
You said: "''empty ExecStart is explained in Systemd#Examples''"<br />
<br />
Exactly: Systemd#Examples clearly states "''As another example, in order to replace the ExecStart directive for a unit that is '''not of type oneshot'''''"<br />
<br />
'''systemd-networkd-wait-online''' is a oneshot service. By having the superfluous empty ExecStart you're just confusing people.<br />
<br />
Regarding the file naming, yes the name is irrelevant, but it's generally helpful to non-expert users to stick to canonical naming conventions.<br />
<br />
Please make sure you're on solid ground before reverting edits; you're just discouraging people from engaging with the Wiki. Thanks. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 16:51, 9 June 2021 (UTC)<br />
<br />
:{{man|5|systemd.service}} says: "Unless Type= is oneshot, exactly one command must be given. When Type=oneshot is used, zero or more commands may be specified."<br />
:So when a service is not oneshot, users ''must'' clear ExecStart before adding a modified command in the drop-in file. If a service is oneshot, they ''may or may not'' clear ExecStart, since the service may have multiple ExecStart commands.<br />
:In case of systemd-networkd-wait-online, I don't see why you would want to run multiple instances with different options: one to wait for ''all'' links (which is the default command) and another one to wait for ''any'' link (which is the command in the drop-in example). So clearing ExecStart really makes sense for systemd-networkd-wait-online.<br />
:— [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:44, 9 June 2021 (UTC)<br />
<br />
== Pacman: Install missing dependencies ==<br />
<br />
Hi. [https://wiki.archlinux.org/index.php?title=Pacman&type=revision&diff=690774&oldid=690762 "Pacman" Revision as of 21:50, 4 August 2021 (undo)] - maybe at least put that into [[System_maintenance#Avoid_certain_pacman_commands]]?<br />
<br />
[[User:Galeksandrp|Galeksandrp]] ([[User talk:Galeksandrp|talk]])<br />
<br />
:[[System_maintenance#Avoid_certain_pacman_commands]] already mentions {{ic|-Rdd}}. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:12, 14 August 2021 (UTC)<br />
<br />
== DPMS: "\033[9;0]" ==<br />
<br />
Hi. It seems that you removed {{ic|echo -ne "\033[9;0]"}} from [[Display Power Management Signaling|DPMS]]<br />
<br />
https://wiki.archlinux.org/index.php?title=Display_Power_Management_Signaling&diff=629705&oldid=625073<br />
<br />
[https://www.denx.de/wiki/view/DULG/SwitchOffScreenSaverAndBlinkingCursor A DULG page] and [https://unix.stackexchange.com/a/23636 a U&L post] brought me here.<br />
<br />
May I ask (1) if this method is still working; and (2) where is this escape sequence documented? [not found in {{man|4|console_codes}}]<br />
<br />
Thanks.</div>PXf